跳转到主要内容

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 递材料

GETPOST
语义问 / 读,不改变什么交材料 / 触发执行
数据放哪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 看谁占着。

小练习

  1. 给 §3 的应用加 GET /bmi/{name}:从 bmi_table 查 BMI;查不到时返回 404 和提示(提示:from fastapi import HTTPException,raise HTTPException(status_code=404, detail=...))。
  2. 写 POST /bmi:请求体含 weight、height(pydantic 模型),返回 BMI 数值和分类(逻辑复用第 8 章)。用 /docs 的 Try it out 测试。
  3. 把 §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 下逐字出现,顺序与产生顺序一致