【Agent开发速成笔记】一、从0到1基础Python学习

文章目录

前言
AI生成的学习路线
[一、Python 工程基础](#一、Python 工程基础)
- [1.1 venv、pip机制](#1.1 venv、pip机制)
- - [1.1.1 venv 的核心机制（虚拟环境）](#1.1.1 venv 的核心机制（虚拟环境）)
  - [1.1.2 pip 的核心机制（包管理）](#1.1.2 pip 的核心机制（包管理）)
  - [1.1.3 总结](#1.1.3 总结)
- [1.2 包管理（requirements.txt、pip 源配置）](#1.2 包管理（requirements.txt、pip 源配置）)
- - [1.2.1 requirements.txt 环境清单](#1.2.1 requirements.txt 环境清单)
  - [1.2.2 pip 源配置 ------ 解决下载慢、被墙的问题](#1.2.2 pip 源配置 —— 解决下载慢、被墙的问题)
- [1.3 Python项目实践方案](#1.3 Python项目实践方案)
- - [1.3.1 Python项目结构](#1.3.1 Python项目结构)
  - [1.3.2 模块、包](#1.3.2 模块、包)
  - [1.3.3 导入规则最佳实践](#1.3.3 导入规则最佳实践)
[二、Web 开发核心(FastAPI)](#二、Web 开发核心(FastAPI))
- [2.1📋 什么是 FastAPI？](#2.1📋 什么是 FastAPI？)
- [2.2 基础运行](#2.2 基础运行)
- [2.3 fastAPI关键点](#2.3 fastAPI关键点)
- - 1.路由路径定义
  - [2.Pydantic 模型（数据校验与序列化）](#2.Pydantic 模型（数据校验与序列化）)
  - [3、依赖注入（Dependency Injection）](#3、依赖注入（Dependency Injection）)
  - 4、中间件与异常处理
写到最后

前言

AI冲击太快，作为一个web前端，公司业务也在进行Agent开发，从此小小web前端转Agent工程师开发，要开发Agent就得先学习python。这篇笔记用于记录从0到1入门学习过程以及关键点，方便后续复盘学习，业务不等人挑简单的先学习，深入原理和规则的这些事边开发边补吧。

AI生成的学习路线

AI的学习计划很详细，时长也很长，但是实际业务不等人，按这个计划，挑关键点去学习，先入门实践再深入。

阶段1：Python 工程基础（1-2周）

主题	学习内容	推荐资源
虚拟环境	venv、pip 机制	Python官方文档 - venv
包管理	requirements.txt、pip 源配置	pip 用户指南
项目结构	模块、包、导入规则	Python项目最佳实践
类型提示	Type hints、Pydantic 模型	FastAPI 官方教程 - Python类型

阶段2：Web 开发核心（2-3周）

主题	为什么学	推荐资源
FastAPI	你项目用的框架	FastAPI 官方教程（中英双语）
异步编程	async/await、事件循环	Real Python - Async IO
REST API 设计	路由、请求响应、状态码	RESTful API 设计指南

阶段3：AI/Agent 工程化（3-4周）

主题	与你项目的关联	学习资源
LangChain	项目依赖的基础	LangChain 官方文档
LangGraph	agent-supervisor 核心框架	LangGraph 教程
SSE 流式	项目中的实时对话	FastAPI Streaming Response

阶段4：工程部署（1-2周）

主题	解决你遇到的问题	推荐资源
Docker 基础	端口映射、容器网络	Docker 官方教程
Nginx 反向代理	前后端分离部署	Nginx 入门指南
环境变量管理	.env、配置分离	python-dotenv

其他

中文学习资源（更易上手）
fastApi官方示例项目：https://github.com/tiangolo/full-stack-fastapi-template

一、Python 工程基础

1.1 venv、pip机制

venv 负责创建隔离的 Python 运行环境。
pip 负责在该环境中安装、升级、删除第三方包。

1.1.1 venv 的核心机制（虚拟环境）

作用：解决不同项目依赖同一个包的不同版本时的冲突问题。

工作原理：

执行 python -m venv myenv 后，会在当前目录生成一个 myenv 文件夹，内部复制或链接了系统 Python 解释器的可执行文件，并创建了独立的 Lib/site-packages 目录。
当你激活环境（Windows 运行 myenv\Scripts\activate，Linux/Mac 运行 source myenv/bin/activate）时，它仅仅是临时修改了终端会话的 PATH 环境变量，把 myenv/bin 或 myenv\Scripts 放到了最前面。
结果：终端输入 python 指向虚拟环境里的解释器，输入 pip 指向虚拟环境里的包管理器。安装的任何包都会落入 myenv/Lib/site-packages，与系统全局环境完全隔绝。

1.1.2 pip 的核心机制（包管理）

作用：从 Python Package Index 或其他源下载、解压、安装 .whl 或 .tar.gz 格式的包。

工作流程：

解析依赖：读取包名和版本约束，计算需要安装的依赖树。
下载：从配置的镜像源下载 .whl（预编译的二进制包，安装快）或源代码包。
安装：将包内的文件解压/复制到当前激活环境的 site-packages 目录下。
生成元数据：在 site-packages 同级目录写入 dist-info 文件夹，记录版本和文件清单，供 pip uninstall 使用。

1.1.3 总结

venv 决定了你把包"装在哪里"，pip 决定了"装什么"以及"怎么装"。

1.2 包管理（requirements.txt、pip 源配置）

1.2.1 requirements.txt 环境清单

作用：将当前虚拟环境中安装的所有包及精确版本冻结成一个文本文件，方便在其他机器或服务器上一键还原完全相同的依赖环境。
生成与使用：

bash 复制代码

# 冻结当前环境，生成文件
 pip freeze > requirements.txt
# 根据文件批量安装依赖
pip install -r requirements.txt

requirements.txt示例

bash 复制代码

# LangGraph & LangChain
langgraph>=1.1.0
langchain>=1.2.0
langchain-openai>=1.1.0
langchain-core>=1.2.0

# API Framework
fastapi>=0.115.0
uvicorn[standard]>=0.32.0
pydantic>=2.0.0

# NLP
jieba>=0.42.0

手动维护时，通常只写顶层依赖（直接 import 的包），由 pip 自动解析子依赖，避免文件臃肿；pip freeze 会包含所有间接依赖，适合追求绝对一致性的生产部署。

1.2.2 pip 源配置 ------ 解决下载慢、被墙的问题

默认源：https://pypi.org/simple/，国内访问可能很慢。更换为国内镜像源能显著提升下载速度。

常用国内镜像源地址:

阿里云：https://mirrors.aliyun.com/pypi/simple/
清华：https://pypi.tuna.tsinghua.edu.cn/simple/
中科大：https://pypi.mirrors.ustc.edu.cn/simple/

常用命令

bash 复制代码

# 查看版本
pip --version
# 安装
pip install 包名
pip install 包名==版本号
# 从 requirements.txt 安装多个包
pip install -r requirements.txt
# 使用国内镜像源加速
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名

# 卸载
pip uninstall 包名
# 批量卸载
pip uninstall -r requirements.txt -y

# 查看搜索
# 列出已安装的包
pip list
# 查看包的详细信息
pip show 包名
# 导出当前环境的所有依赖到文件
pip freeze > requirements.txt

# 升级pip自身
python -m pip install --upgrade pip
# 升级某个包
pip install -U 包名
# 配置镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

1.3 Python项目实践方案

1.3.1 Python项目结构

典型的项目结构如下：

text 复制代码

my_project/
├── pyproject.toml           # 现代构建配置（替代 setup.py）
├── README.md
├── requirements.txt         # 开发依赖（可选，若使用 Poetry/Flit 可省略）
├── setup.py                # 打包和发布管理
├── src/
│   └── my_package/          # 主包目录（避免顶层直接放模块）
│       ├── __init__.py
│       ├── core/
│       │   ├── __init__.py
│       │   └── engine.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/                   # 测试目录（与 src 同级）
│   ├── __init__.py
│   └── test_core.py
└── scripts/                 # 运行脚本（如启动脚本）
    └── run.py

1.3.2 模块、包

模块（Module）：单个 .py 文件。
包（Package）：包含__init__.py的目录（Python 3.3+ 支持无 init .py 的命名空间包，但显式声明更清晰）。
- init .py 作用：标识目录为包；控制 from package import * 的行为（通过 all ）；可用于简化导入路径（如 from .core import Engine）。

1.3.3 导入规则最佳实践

python 复制代码

# 优先使用绝对导入
from my_pkg.core.engin import Engine

# 谨慎使用相对导入(适用于包内模块间引用；)
from .engine import Engine
from ..utils.helpers import helper_func

避免import * ，除非在_init_.py中明确定义_all_，否则容易命名冲突

二、Web 开发核心(FastAPI)

2.1📋 什么是 FastAPI？

FastAPI 是一个现代、快速（高性能）的 Python Web 框架，专为构建 API 而设计。

核心优势：

✅ 基于 Python 类型提示（Type Hints）：用 pydantic 自动校验请求/响应数据；

✅ 自动生成交互式 API 文档：支持 Swagger UI（/docs）和 ReDoc（/redoc）；

✅ 原生异步支持（async/await）：高性能，适合 I/O 密集型任务（如数据库、HTTP 请求）；

✅ 依赖注入系统：灵活管理共享逻辑（如数据库连接、认证）；

✅ 与 Starlette + Pydantic 深度集成：底层高性能，上层易用。

2.2 基础运行

1、安装

bash 复制代码

pip install fastapi uvicorn[standard]

fastapi:用于创建 API 应用，提供装饰器、类型提示、路由等功能
uvicorn： ASGI 服务器，用于运行 FastAPI 应用，将 FastAPI 应用部署到服务器上。 [standard]代表标准安装

2、运行

main.py基础代码

python 复制代码

from fastapi  import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

运行

bash 复制代码

uvicorn main:app --reload

访问 http://localhost:8000 和 http://localhost:8000/docs 查看文档。
localhost:8000效果
localhost:8000/docs效果

2.3 fastAPI关键点

1.路由路径定义

使用装饰器定义HTTP方法
@app.get(...):
- @符号是 Python 的装饰器语法，它的作用是把下面紧跟着的函数"注册"到 app 的路由表中。
- app 是你通过 app = FastAPI() 创建的 FastAPI 应用实例。
- .get() 是 FastAPI 实例上的方法，表示这个接口只接受 HTTP GET 请求。

python 复制代码

@app.get("/items/{item_id}")
def read_item(item_id: int,q:str=None):
    return {"item_id": item_id,"q":q}

2.Pydantic 模型（数据校验与序列化）

Pydantic 是 FastAPI 背后的数据校验与序列化引擎。功能：自动数据校验；序列化（.model_dump()）；自动生成 JSON Schema 与文档；一句话总结：用类型注解来自动校验和转换原始数据，确保数据格式完全符合预期，并支持零代码生成 API 文档。

自动校验类型、必填字段、默认值；
自动生成 JSON Schema（用于文档和前端对接）。

python 复制代码

from fastapi import FastAPI
from pydantic import BaseModel

# 创建 FastAPI 应用实例
app = FastAPI()
# 定义 Item模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False
# 定义创建 Item的路由
@app.post("/items/")
def create_item(item: Item):
    return item

测试接口：访问http://localhost:8000/docs#/对应的swaggerUI文档，try_it运行对应接口，修改参数看返回值。

3、依赖注入（Dependency Injection）

依赖注入（Dependency Injection，简称 DI）是一种设计模式，核心思想是：函数或类不要自己"创建"依赖的资源，而是由外部"注入"进来。这样做最大的好处是解耦和方便测试。

用于数据库连接、认证、权限检查等共享逻辑。

python 复制代码

from fastapi import FastAPI,Depends
from pydantic import BaseModel
# 定义依赖函数
def common_parameters(q: str = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

# 使用依赖注入的路由
@app.get("/users/")
def read_users(commons: dict = Depends(common_parameters)):
    return {"users": [], "params": commons}

4、中间件与异常处理

添加 CORS、日志、认证中间件；
自定义错误响应：

python 复制代码

from fastapi import FastAPI,HTTPException

app = FastAPI()
# 模拟数据库
fake_items_db = {"1": "苹果", "2": "香蕉"}

@app.get("/items/{item_id}")
def read_item(item_id: str):
     # 尝试从"数据库"中查找
    item = fake_items_db.get(item_id)
     # 如果没找到，直接返回 404 错误
    if not item:
        raise HTTPException(status_code=404, detail=f"ID为 {item_id} 的商品不存在")
        # 找到了，正常返回
    return {"item_id": item_id, "item_name": item}

HTTPException 是 FastAPI 内置的异常类。当你的业务逻辑发现"出了问题"，可以主动抛出这个异常，FastAPI 会自动把它转换成标准的 HTTP 错误响应返回给客户端。
在swagger UI中调用，传入id:3示例：

写到最后

以上只是基础中的基础内容，目前看真实项目中还有很多关于python中间件，数据库集成，测试，部署等功能，后面看实操代码继续记录。