Python
FastAPI 速成:把程序变成 API
把 Python 函数变成 HTTP 接口的速成课——安装启动、路由、三种参数来路、GET/POST、流式响应,示例全部实测。
- Python
- FastAPI
目标:会装、会跑、会写路由和请求体——把任意 Python 函数变成 HTTP 接口,会用自动生成的 /docs 调试;学完能无障碍读懂 LangChain 书第 10 章(1.x 重写版:18 · 流式 API 与部署)的 FastAPI 部署代码。 定位:补充章,不占 13–22 主线。建议学完 13 类型注解、14 装饰器、21 pydantic 之后、开读部署章之前学;第 5、6 节用到 20 异步。 与 LangChain 的关系:把 chain/agent 部署成 Web 服务供网页、App 调用,社区的事实标准就是 FastAPI——部署章的 server.py 每一行都在本章有原型。
1. 为什么需要:让「别的程序」调用你的函数
第 8 章的函数调用,是同一个程序里喊名字。但真实产品长这样:网页上的对话框、手机 App、另一个服务,想用你写的 calc_bmi——它们跟你的代码不在一个进程、甚至不在一台机器上,怎么喊?
靠 HTTP:对方朝你机器的某个网址(URL)发一个请求,你的程序收到、执行函数、把结果发回去。这套「用 URL 暴露功能」的约定就叫 API。你的函数是技能,API 是把技能挂牌到网上。
FastAPI 就是干这个的框架(同类还有 12 章提过的 flask)。它的主张:你只写普通的 Python 函数,HTTP 那一层——解析请求、转 JSON、校验参数、生成文档——全部由框架代劳。
2. 五分钟跑起来
安装(第 17 章的 uv 环境;uvicorn 是跑 FastAPI 的服务器):
pip install fastapi uvicorn
最小应用,三行核心:
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def hello():
return {"message": "你好,API"}
启动:
uvicorn main:app --reload
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
逐个解读:
app = FastAPI():服务对象,后面的功能全部注册在它身上。@app.get("/"):装饰器(14 章第 7 节)——把hello登记为「收到 GET 请求/时执行的那个函数」。注意函数只是被登记,没有执行;每个请求到达时框架才调用它一次。return {"message": "你好,API"}:返回的 dict/list/pydantic 模型自动转成 JSON——API 世界的数据通用语。uvicorn main:app:文件 main.py 里的变量 app,交给 uvicorn 跑起来。第 20 章说过:uvicorn 启动时建好事件循环,你的代码只是被它调度。--reload改代码自动重启,开发期专用。
浏览器开 http://127.0.0.1:8000/,看到 {"message":"你好,API"}。再开 http://127.0.0.1:8000/docs——一份可交互的接口文档凭空出现了:每个接口一条,点开有 Try it out 按钮能当场填参数试。这是 FastAPI 的招牌,材料全靠读你函数身上的类型注解,你一行文档代码都没写。
3. 参数的三种来路
调用方传数据给接口,入口只有三个:URL 路径、URL 问号后面、请求体。FastAPI 看函数签名自动分发,你不需要写任何解析代码:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
users = {1: "小明", 2: "小红"}
bmi_table = {"小明": 22.0, "小红": 19.5}
class ChatRequest(BaseModel): # ③ 请求体的形状:pydantic 模型(第 21 章)
question: str
session_id: str
@app.get("/users/{user_id}") # ① 路径参数:URL 路径里挖一个洞
def get_user(user_id: int):
return {"user_id": user_id, "name": users.get(user_id)}
@app.get("/bmi/search") # ② 查询参数:?min_bmi=20&limit=1
def search_bmi(min_bmi: float = 0, limit: int = 10):
found = [(n, b) for n, b in bmi_table.items() if b >= min_bmi]
return {"count": len(found), "items": found[:limit]}
@app.post("/chat") # ③ 请求体:POST 的 JSON → 模型实例
def chat(req: ChatRequest):
return {"session": req.session_id, "echo": req.question}
| 来路 | 请求长什么样 | 写在哪 | 谁校验 |
|---|---|---|---|
| ① 路径参数 | /users/1 | 路径里 {user_id} + 同名形参 | 类型注解 |
| ② 查询参数 | /bmi/search?min_bmi=20&limit=1 | 函数形参,有默认值就可选 | 类型注解 |
| ③ 请求体 | POST 的 JSON 数据 | pydantic 模型形参 | pydantic(第 21 章) |
实测(uvicorn 起服务后 curl):
GET /users/1 → {"user_id":1,"name":"小明"}
GET /bmi/search → {"count":2,"items":[["小明",22.0],["小红",19.5]]}
GET /bmi/search?min_bmi=20&limit=1
→ {"count":1,"items":[["小明",22.0]]}
POST /chat + JSON → {"session":"s1","echo":"你好"}
查询参数的 min_bmi: float = 0, limit: int = 10 就是第 8 章的默认参数——不传就用默认值,/docs 里还会自动生成可填的表单。
注解在这里真的在干活。第 13 章说过注解「运行时不校验」——FastAPI 正是头号例外:它运行时读你的注解干活。传错类型,不是悄悄出错,而是一份明明白白的 422 报错:
GET /users/abc
→ 422
{"detail":[{"type":"int_parsing","loc":["path","user_id"],
"msg":"Input should be a valid integer, unable to parse string as an integer",
"input":"abc"}]}
哪个参数(loc)、错在哪(msg)、收到的是什么(input)一应俱全。POST 缺字段同理:/chat 少传 session_id 直接 422,错误信息指名道姓。看到 422 不是出了 bug,是框架替你挡住了脏数据——调试接口的第一神器就是它加 /docs。
4. GET 与 POST:取东西 vs 递材料
| GET | POST | |
|---|---|---|
| 语义 | 问 / 读,不改变什么 | 交材料 / 触发执行 |
| 数据放哪 | URL(路径 + 查询参数) | 请求体 |
| 适合 | 查询、搜索 | 表单、下单、对话 |
判断口诀:这次调用会改变什么吗? 只是问 → GET;要提交材料、触发动作 → POST。
LLM 的 chat 接口全是 POST,两个原因:问题文本可能很长,URL 塞不下也不该塞(URL 会被浏览器历史、服务器日志记下来);而且每次提问都要「递材料进去、等结果回来」,正是 POST 的形状。
curl 两种都试一遍(部署章 client.py 里的 requests.post 是同一件事的 Python 版):
curl "http://127.0.0.1:8000/bmi/search?min_bmi=20"
curl -X POST http://127.0.0.1:8000/chat \
-H "Content-Type: application/json" \
-d '{"question": "你好", "session_id": "s1"}'
5. async def:什么时候写、什么时候千万别写
规则一句话:函数体里要 await 才写 async def;其余情况老实写普通 def。
- 普通
def端点:FastAPI 自动丢进线程池跑,不会挡住别人。 async def端点:跑在事件循环上(20 章)——好处是能await异步库,代价是绝不能就地干等。
最危险的写法:async def 里调同步阻塞函数(requests、time.sleep)——它占着事件循环干等,整个服务的所有请求一起卡死。要么改回 def,要么换异步版(httpx、agent.astream)。
部署章的 async def chat(...) 里要 await agent.astream(...)——所以 async,正确形状。没有 await 的端点,写成 def 就好。
6. 流式响应:StreamingResponse
部署章最核心的形状,先用纯 FastAPI 看一遍。async def + yield = 异步生成器(20 章 §7、生成器原型见16 章):
import asyncio
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
@app.get("/count")
async def count():
async def numbers():
for i in range(5):
await asyncio.sleep(0.5) # 模拟「等 LLM 吐下一个字」
yield f"第 {i} 个\n"
return StreamingResponse(numbers(), media_type="text/plain; charset=utf-8")
实测 curl -N http://127.0.0.1:8000/count(-N 关掉 curl 自己的攒够再显示):每 0.5 秒蹦一行,不是干等 2.5 秒后一次性出——token 级流式的全部秘密就这么多。三件套拆开:
numbers():调用只是造出异步生成器,一行都不执行(16 章的生成器语义);StreamingResponse(numbers(), ...):把它接到 HTTP 上,产出一个、网络写一个;asyncio.sleep是「等待」的替身——真实场景换成async for message, metadata in agent.astream(...),token 到达即yield,浏览器实时蹦字。
7. 总装:LangChain 部署代码你现在全能读懂
部署章(1.x 重写版:18 · 流式 API 与部署)的 server.py 骨架(摘编),每个零件后面标出处:
# server.py(摘编)
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from rag_agent import get_agent
app = FastAPI()
class ChatRequest(BaseModel): # 请求体模型 —— 本章 §3③ + 第 21 章
question: str
session_id: str
agent = get_agent() # 贵的初始化:启动时做一次,
# 别塞进每个请求(每次都重新加载 FAISS)
@app.post("/chat") # POST —— 本章 §4:递材料、等回答
async def chat(req: ChatRequest): # async —— 本章 §5:里面要 await
async def token_stream(): # async def + yield —— 本章 §6
async for message, metadata in agent.astream(
{"messages": [{"role": "user", "content": req.question}]},
{"configurable": {"thread_id": req.session_id}},
stream_mode="messages",
):
if message.content:
yield message.content # token 到达即转手
return StreamingResponse(token_stream(), media_type="text/plain; charset=utf-8")
读完骨架,去书里看完整版(含异常要在生成器内部捕获的原因、client.py 怎么读流)——那里的每行代码在本章或 13–21 章都有出处,没有新语法。
8. 常见坑
- 改了代码没生效:忘了
--reload,或 uvicorn 跑的不是你正在编辑的文件。 - async def 里调 requests / time.sleep:整个服务卡死(§5)。同步逻辑就写 def,或换 httpx / asyncio.sleep。
- 看到 422 先别慌:读 body 里的
loc和msg,哪个字段什么错一目了然;再配合 /docs 的 Try it out 构造正确请求对照。 - 别的机器访问不到:默认只监听 127.0.0.1,局域网要
uvicorn main:app --host 0.0.0.0。 - 端口被占:报
address already in use,--port 8001换一个;先lsof -i :8000看谁占着。
小练习
- 给 §3 的应用加
GET /bmi/{name}:从bmi_table查 BMI;查不到时返回 404 和提示(提示:from fastapi import HTTPException,raise HTTPException(status_code=404, detail=...))。 - 写
POST /bmi:请求体含 weight、height(pydantic 模型),返回 BMI 数值和分类(逻辑复用第 8 章)。用 /docs 的 Try it out 测试。 - 把 §6 的 /count 改成
/typewriter:把一句话逐字流式输出,每个字间隔 0.1 秒。
练习答案
# 练习 1
from fastapi import HTTPException
@app.get("/bmi/{name}")
def bmi_of(name: str):
if name not in bmi_table:
raise HTTPException(status_code=404, detail=f"没有 {name} 的记录")
return {"name": name, "bmi": bmi_table[name]}
# 实测:GET /bmi/小刚 → 404 {"detail":"没有 小刚 的记录"}
# GET /bmi/小明 → {"name":"小明","bmi":22.0}
# 练习 2
class BmiRequest(BaseModel):
weight: float
height: float
@app.post("/bmi")
def calc_bmi(req: BmiRequest):
bmi = req.weight / req.height**2
label = "偏重" if bmi > 24 else ("正常" if bmi >= 18.5 else "偏轻")
return {"bmi": round(bmi, 1), "label": label}
# 实测:POST {"weight": 65, "height": 1.72} → {"bmi":22.0,"label":"正常"}
# 练习 3
@app.get("/typewriter")
async def typewriter():
async def chars():
for ch in "你好,FastAPI":
await asyncio.sleep(0.1)
yield ch
return StreamingResponse(chars(), media_type="text/plain; charset=utf-8")
# 实测:curl -N 下逐字出现,顺序与产生顺序一致