前面我们已经使用 Python 编写过函数,也使用 asyncio 执行过异步任务。但网页不能直接导入电脑里的 Python 文件,更不能像调用普通函数一样跨越浏览器和 Python 进程。
如果希望网页把用户问题交给 Python,再取得模型回复,就需要在二者之间建立一组可以通过网络调用的接口,也就是 API,如上案例所示,你可以在本地电脑启动本专栏的案例服务,然后体验接口请求
一次最简单的调用过程如下:
网页发送 HTTP 请求,FastAPI 找到匹配的 Python 函数,函数完成处理后,由 FastAPI 返回 HTTP 响应。
FLOW / RELATIONSHIP
网页
发送 HTTP 请求
FastAPI
匹配对应的 Python 函数
Python 函数
处理请求数据
HTTP 响应
FastAPI 返回处理结果
HTTP 规定请求和响应如何在网络中传输,JSON 负责表达其中的结构化数据,FastAPI 则负责把 HTTP 世界与 Python 函数连接起来。
例如,网页不能直接执行下面的函数:
1def greeting(name: str) -> str: 2 return f"你好,{name}"
使用 FastAPI 后,可以为它增加一个 HTTP 入口:
1GET /greeting/小微
收到这个请求时,FastAPI 会提取路径中的名字、调用 Python 函数,再把结果转换成 HTTP 响应。后面的文章会逐步实现这些能力。
FastAPI 是一个 Python Web 框架。它主要负责:
在后续项目中,网页只与 FastAPI 通信,FastAPI 再把经过校验的数据交给 LangChain
我们继续使用前面文章创建的 uv 项目。如果项目中还没有 FastAPI,可以安装标准依赖:
1uv add "fastapi[standard]"
standard 会安装 FastAPI 常用的标准依赖,其中包括 FastAPI CLI 和 Uvicorn。依赖声明会写入 pyproject.toml,解析出的具体版本会记录在 uv.lock 中。
standard
pyproject.toml
uv.lock
在项目根目录创建 main.py:
main.py
01from fastapi import FastAPI 02 03app = FastAPI( 04 title="Local Agent API", 05 description="供网页调用的本地 AI 助手服务", 06 version="0.1.0", 07) 08 09@app.get("/") 10async def root() -> dict[str, str]: 11 return {"message": "Hello FastAPI"}
启动开发服务:
1uv run fastapi dev main.py
FastAPI CLI 会导入 main.py,寻找其中的 FastAPI 应用对象,再使用 Uvicorn 启动开发服务器。默认访问地址是:
1http://127.0.0.1:8000
127.0.0.1 表示当前电脑,8000 是服务监听的端口。http://localhost:8000 通常也会指向同一台电脑。
127.0.0.1
8000
http://localhost:8000
开发模式会监听代码变化并自动重启。终端需要保持运行,按 Ctrl+C 可以停止服务。
Ctrl+C
现在打开浏览器,访问:
1http://127.0.0.1:8000/
页面会显示:
1{"message":"Hello FastAPI"}
也可以打开另一个终端,通过 curl 发送同一个请求:
1curl http://127.0.0.1:8000/
如果希望同时查看状态码和响应头,可以添加 -i:
-i
1curl -i http://127.0.0.1:8000/
你会看到类似下面的结果:
1HTTP/1.1 200 OK 2content-type: application/json 3 4{"message":"Hello FastAPI"}
至此,我们已经完成了一次完整调用:客户端发送 HTTP 请求,FastAPI 执行 Python 函数,然后返回 JSON 响应。
下面逐行拆解第一个接口。
1from fastapi import FastAPI
这行代码从 fastapi 包中导入 FastAPI 类。它提供了创建应用、注册路由、声明依赖和处理异常等能力。
fastapi
1app = FastAPI( 2 title="Local Agent API", 3 description="供网页调用的本地 AI 助手服务", 4 version="0.1.0", 5)
FastAPI() 调用类并创建实例,变量 app 保存这个实例。它是整个 Web 应用的入口,后续路由、中间件和异常处理器都会注册到这个对象上。
FastAPI()
app
title、description 和 version 是接口文档元数据,也会进入 OpenAPI 描述。这里的 version 表示当前 API 应用版本,不是 Python、FastAPI 或模型版本。
title
description
version
1@app.get("/") 2async def root() -> dict[str, str]: 3 return {"message": "Hello FastAPI"}
@app.get("/") 是路径操作装饰器。它告诉 FastAPI:收到路径为 / 的 GET 请求时,调用下面的 root() 函数。
@app.get("/")
/
root()
这几部分分别表示:
get
root
dict[str, str]
return
函数名不决定 URL,URL 由装饰器中的路径决定。不过函数名会成为路由名称,并参与默认 OpenAPI operationId 的生成,因此应该清晰、唯一并尽量保持稳定。
operationId
初学 FastAPI 时,很容易混淆「启动服务时执行的代码」和「每次请求时执行的代码」。
启动服务时,Python 会导入 main.py:
服务启动时导入 FastAPI,创建 app 实例和 root 函数,装饰器把 root 注册到 app,然后服务器开始等待请求。注册函数不等于执行函数体。
导入 FastAPI
导入 main.py 时执行
创建 app 实例
建立 ASGI 应用对象
创建 root 函数
此时不运行函数体
注册路径函数
装饰器关联 GET / 与 root
等待请求
由 ASGI 服务器监听
收到 GET / 后,FastAPI 才会执行 root():
GET /
请求到来后匹配 GET 方法与根路径,调用 root 函数,对返回值进行校验和序列化,最后发送 HTTP 响应。
收到请求
匹配 GET /
方法与路径同时匹配
调用 root()
执行路径函数体
校验与序列化
Python 返回值转换为响应数据
发送 HTTP 响应
因此,模块顶部的代码通常在导入时执行,路径函数内部的代码则在请求到来时执行。
下面这种写法会在应用导入时运行一次,而不是每次请求运行:
1print("正在导入 main.py") 2 3app = FastAPI()
开发服务器自动重载后会重新导入模块,所以开发过程中可能看到它打印多次。昂贵模型初始化、连接池和需要清理的资源不应该随意散落在模块顶部,后面的「工程」文章会使用 lifespan 管理它们。
一次 HTTP 交互分为请求和响应。
客户端发送的请求可以简化为:
1GET / HTTP/1.1 2Host: 127.0.0.1:8000
其中:
GET
Host
服务端返回的响应可以简化为:
1HTTP/1.1 200 OK 2Content-Type: application/json 3 4{"message":"Hello FastAPI"}
200
Content-Type
路径函数返回的是 Python 字典:
1{"message": "Hello FastAPI"}
FastAPI 会根据响应类型校验数据,再把它序列化成 JSON 字节并交给服务器发送。客户端最终收到的是 HTTP 响应,而不是 Python 对象。
FastAPI 会读取函数参数和返回值的类型提示,并把它们用于运行时处理。
在 main.py 中增加一个路径参数接口:
01from fastapi import FastAPI 02 03app = FastAPI(title="Local Agent API") 04 05@app.get("/") 06async def root() -> dict[str, str]: 07 return {"message": "Hello FastAPI"} 08 09@app.get("/users/{user_id}") 10async def get_user(user_id: int) -> dict[str, int]: 11 return {"user_id": user_id}
访问:
1http://127.0.0.1:8000/users/42
路径中的 42 原本来自 URL 文本。FastAPI 根据 user_id: int 把它转换成整数,再传给 get_user()。
42
user_id: int
get_user()
返回类型 dict[str, int] 也不只是编辑器提示。FastAPI 会使用它校验和序列化响应,并为 OpenAPI 生成响应 Schema。
dict[str, int]
如果访问:
1http://127.0.0.1:8000/users/hello
hello 无法转换成整数,FastAPI 会在执行 get_user() 之前返回 422 校验错误。也就是说,路径函数拿到的已经是通过声明规则解析的数据。
hello
422
简单类型可以直接写在函数签名中。字段较多或存在嵌套结构时,后面会使用 Pydantic 模型描述请求和响应。
服务运行后,可以访问三个文档地址:
/docs
/redoc
/openapi.json
这三个概念的关系是:
路径、参数、类型和响应声明生成 OpenAPI Schema。Swagger UI 和 ReDoc 分别读取同一份 Schema,渲染各自的接口文档界面。
接口声明
路径、参数、类型和响应
OpenAPI Schema
Swagger UI
ReDoc
OpenAPI 是描述 HTTP API 的标准,/openapi.json 是当前应用按照该标准生成的数据。Swagger UI 和 ReDoc 是读取这份数据后展示出来的文档界面。
打开 /docs,找到 /users/{user_id},点击 Try it out,输入 42 并执行。你可以直接看到最终请求 URL、响应状态码和响应体。
/users/{user_id}
Try it out
再输入 hello,观察 422 响应。这个实验能直观看到类型提示不仅用于编辑器,也参与真实 HTTP 请求处理。
自动文档不是额外维护的一份说明。类型、默认值和响应结构越准确,生成的接口契约就越可信。
FastAPI 应用并不是独自完成网络监听、数据校验和异步调度。当前项目中的主要组件可以这样理解:
浏览器发送请求后,完整调用关系可以简化为:
浏览器或 curl 通过 HTTP 把请求发送给 Uvicorn。Uvicorn 通过 ASGI 把请求交给 FastAPI;路由匹配与校验后执行路径函数。Python 返回值经 FastAPI 序列化,再由 Uvicorn 通过 HTTP 返回客户端。此图描述本机服务模式。
浏览器 / curl
HTTP 请求
Uvicorn
接收请求,调用 ASGI 应用
路由匹配与数据校验
路径函数
执行业务,返回 Python 数据
校验并序列化响应
读取响应数据
ASGI 规定 Uvicorn 如何把请求事件交给 Python 应用,以及应用如何把响应事件交还给服务器。它是一套接口规范,不是另一个需要单独编写的业务框架。
app = FastAPI() 创建的是 ASGI 应用对象,不是一个已经监听端口的服务器。只有运行 fastapi dev 或其他 ASGI 服务器命令后,程序才会开始监听网络请求。
app = FastAPI()
fastapi dev
路径函数可以使用 async def,也可以使用普通 def:
async def
def
1@app.get("/async") 2async def async_route(): 3 result = await async_service() 4 return result 5 6@app.get("/sync") 7def sync_route(): 8 return sync_service()
这里只需要回顾选择原则:
await
asyncio.run()
上一大章已经解释了事件循环、线程池、超时和 worker。FastAPI 大章会重点学习 HTTP 接口设计,不再重复 asyncio 的内部原理。
第一次运行时,常见问题可以根据状态码或终端信息判断:
404 Not Found
405 Method Not Allowed
Address already in use
终端中的 Uvicorn 日志会显示请求方法、路径和状态码。排查时先判断请求有没有到达服务,再判断是路由、校验还是函数内部执行失败。
第一个接口很短,但已经形成了一条完整链路:
HTTP 请求经 ASGI 服务器交给 FastAPI,FastAPI 调用 Python 路径函数,处理结果最终转换成 HTTP 响应。
ASGI 服务器
网络与应用之间的接口
路由与数据契约
处理具体业务
学习后续内容时,要始终区分三个层次:
用最小接口观察路径参数、查询参数和 JSON 响应,先建立请求与路径函数之间的对应关系。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from fastapi import FastAPI 2 3from greetings import router 4 5app = FastAPI(title="认识 FastAPI") 6app.include_router(router) 7
01from fastapi import APIRouter, Query 02 03router = APIRouter() 04 05@router.get("/") 06async def root() -> dict[str, str]: 07 return {"message": "Hello FastAPI"} 08 09@router.get("/greeting/{name}") 10async def greeting( 11 name: str, 12 language: str = Query(default="zh", pattern="^(zh|en)$"), 13) -> dict[str, str]: 14 prefix = "你好" if language == "zh" else "Hello" 15 return {"message": f"{prefix},{name}", "language": language} 16 17@router.get("/users/{user_id}") 18async def user(user_id: int) -> dict[str, int]: 19 return {"user_id": user_id} 20
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /greeting/小微?language=zh。本篇不需要模型密钥或外部服务。
GET /greeting/小微?language=zh
默认响应的 message 为 "你好,小微"。把 language 改为 en,结果变成 "Hello,小微";请求 /users/42 得到整数 42,请求 /users/abc 得到 422,而未定义的 /missing 得到 404。
message
"你好,小微"
"Hello,小微"
/users/42
/users/abc
/missing
浏览器把请求交给当前 Python 应用的 ASGI 接口,既没有启动监听端口,也没有调用远程后端。原文中的 Uvicorn、网络端口和访问地址属于本机服务模式。在线接口不保存用户数据。
下载项目后,在项目目录执行:
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. API
前面我们已经使用 Python 编写过函数,也使用 asyncio 执行过异步任务。但网页不能直接导入电脑里的 Python 文件,更不能像调用普通函数一样跨越浏览器和 Python 进程。
如果希望网页把用户问题交给 Python,再取得模型回复,就需要在二者之间建立一组可以通过网络调用的接口,也就是 API,如上案例所示,你可以在本地电脑启动本专栏的案例服务,然后体验接口请求
一次最简单的调用过程如下:
网页发送 HTTP 请求,FastAPI 找到匹配的 Python 函数,函数完成处理后,由 FastAPI 返回 HTTP 响应。
FLOW / RELATIONSHIP
网页
发送 HTTP 请求
FastAPI
匹配对应的 Python 函数
Python 函数
处理请求数据
HTTP 响应
FastAPI 返回处理结果
HTTP 规定请求和响应如何在网络中传输,JSON 负责表达其中的结构化数据,FastAPI 则负责把 HTTP 世界与 Python 函数连接起来。
例如,网页不能直接执行下面的函数:
使用 FastAPI 后,可以为它增加一个 HTTP 入口:
收到这个请求时,FastAPI 会提取路径中的名字、调用 Python 函数,再把结果转换成 HTTP 响应。后面的文章会逐步实现这些能力。
2. FastAPI
FastAPI 是一个 Python Web 框架。它主要负责:
在后续项目中,网页只与 FastAPI 通信,FastAPI 再把经过校验的数据交给 LangChain
3. 接口
我们继续使用前面文章创建的 uv 项目。如果项目中还没有 FastAPI,可以安装标准依赖:
standard会安装 FastAPI 常用的标准依赖,其中包括 FastAPI CLI 和 Uvicorn。依赖声明会写入pyproject.toml,解析出的具体版本会记录在uv.lock中。在项目根目录创建
main.py:启动开发服务:
FastAPI CLI 会导入
main.py,寻找其中的 FastAPI 应用对象,再使用 Uvicorn 启动开发服务器。默认访问地址是:127.0.0.1表示当前电脑,8000是服务监听的端口。http://localhost:8000通常也会指向同一台电脑。开发模式会监听代码变化并自动重启。终端需要保持运行,按
Ctrl+C可以停止服务。4. 请求
现在打开浏览器,访问:
页面会显示:
也可以打开另一个终端,通过 curl 发送同一个请求:
如果希望同时查看状态码和响应头,可以添加
-i:你会看到类似下面的结果:
至此,我们已经完成了一次完整调用:客户端发送 HTTP 请求,FastAPI 执行 Python 函数,然后返回 JSON 响应。
5. 语法
下面逐行拆解第一个接口。
这行代码从
fastapi包中导入FastAPI类。它提供了创建应用、注册路由、声明依赖和处理异常等能力。FastAPI()调用类并创建实例,变量app保存这个实例。它是整个 Web 应用的入口,后续路由、中间件和异常处理器都会注册到这个对象上。title、description和version是接口文档元数据,也会进入 OpenAPI 描述。这里的version表示当前 API 应用版本,不是 Python、FastAPI 或模型版本。@app.get("/")是路径操作装饰器。它告诉 FastAPI:收到路径为/的 GET 请求时,调用下面的root()函数。这几部分分别表示:
appget/rootdict[str, str]return函数名不决定 URL,URL 由装饰器中的路径决定。不过函数名会成为路由名称,并参与默认 OpenAPI
operationId的生成,因此应该清晰、唯一并尽量保持稳定。6. 时机
初学 FastAPI 时,很容易混淆「启动服务时执行的代码」和「每次请求时执行的代码」。
启动服务时,Python 会导入
main.py:服务启动时导入 FastAPI,创建 app 实例和 root 函数,装饰器把 root 注册到 app,然后服务器开始等待请求。注册函数不等于执行函数体。
FLOW / RELATIONSHIP
导入 FastAPI
导入 main.py 时执行
创建 app 实例
建立 ASGI 应用对象
创建 root 函数
此时不运行函数体
注册路径函数
装饰器关联 GET / 与 root
等待请求
由 ASGI 服务器监听
收到
GET /后,FastAPI 才会执行root():请求到来后匹配 GET 方法与根路径,调用 root 函数,对返回值进行校验和序列化,最后发送 HTTP 响应。
FLOW / RELATIONSHIP
收到请求
匹配 GET /
方法与路径同时匹配
调用 root()
执行路径函数体
校验与序列化
Python 返回值转换为响应数据
发送 HTTP 响应
因此,模块顶部的代码通常在导入时执行,路径函数内部的代码则在请求到来时执行。
下面这种写法会在应用导入时运行一次,而不是每次请求运行:
开发服务器自动重载后会重新导入模块,所以开发过程中可能看到它打印多次。昂贵模型初始化、连接池和需要清理的资源不应该随意散落在模块顶部,后面的「工程」文章会使用 lifespan 管理它们。
7. HTTP
一次 HTTP 交互分为请求和响应。
客户端发送的请求可以简化为:
其中:
GET是 HTTP 方法,表示读取数据;/是路径,表示当前站点根路径;Host表示目标主机和端口。服务端返回的响应可以简化为:
其中:
200是状态码,表示请求成功;Content-Type表示响应正文采用 JSON;路径函数返回的是 Python 字典:
FastAPI 会根据响应类型校验数据,再把它序列化成 JSON 字节并交给服务器发送。客户端最终收到的是 HTTP 响应,而不是 Python 对象。
8. 类型
FastAPI 会读取函数参数和返回值的类型提示,并把它们用于运行时处理。
在
main.py中增加一个路径参数接口:访问:
路径中的
42原本来自 URL 文本。FastAPI 根据user_id: int把它转换成整数,再传给get_user()。返回类型
dict[str, int]也不只是编辑器提示。FastAPI 会使用它校验和序列化响应,并为 OpenAPI 生成响应 Schema。如果访问:
hello无法转换成整数,FastAPI 会在执行get_user()之前返回422校验错误。也就是说,路径函数拿到的已经是通过声明规则解析的数据。简单类型可以直接写在函数签名中。字段较多或存在嵌套结构时,后面会使用 Pydantic 模型描述请求和响应。
9. 文档
服务运行后,可以访问三个文档地址:
/docs/redoc/openapi.json这三个概念的关系是:
路径、参数、类型和响应声明生成 OpenAPI Schema。Swagger UI 和 ReDoc 分别读取同一份 Schema,渲染各自的接口文档界面。
FLOW / RELATIONSHIP
接口声明
路径、参数、类型和响应
OpenAPI Schema
/openapi.json
Swagger UI
/docs
ReDoc
/redoc
OpenAPI 是描述 HTTP API 的标准,
/openapi.json是当前应用按照该标准生成的数据。Swagger UI 和 ReDoc 是读取这份数据后展示出来的文档界面。打开
/docs,找到/users/{user_id},点击Try it out,输入42并执行。你可以直接看到最终请求 URL、响应状态码和响应体。再输入
hello,观察 422 响应。这个实验能直观看到类型提示不仅用于编辑器,也参与真实 HTTP 请求处理。自动文档不是额外维护的一份说明。类型、默认值和响应结构越准确,生成的接口契约就越可信。
10. 原理
FastAPI 应用并不是独自完成网络监听、数据校验和异步调度。当前项目中的主要组件可以这样理解:
浏览器发送请求后,完整调用关系可以简化为:
浏览器或 curl 通过 HTTP 把请求发送给 Uvicorn。Uvicorn 通过 ASGI 把请求交给 FastAPI;路由匹配与校验后执行路径函数。Python 返回值经 FastAPI 序列化,再由 Uvicorn 通过 HTTP 返回客户端。此图描述本机服务模式。
FLOW / RELATIONSHIP
浏览器 / curl
HTTP 请求
Uvicorn
接收请求,调用 ASGI 应用
FastAPI
路由匹配与数据校验
路径函数
执行业务,返回 Python 数据
FastAPI
校验并序列化响应
Uvicorn
发送 HTTP 响应
浏览器 / curl
读取响应数据
ASGI 规定 Uvicorn 如何把请求事件交给 Python 应用,以及应用如何把响应事件交还给服务器。它是一套接口规范,不是另一个需要单独编写的业务框架。
app = FastAPI()创建的是 ASGI 应用对象,不是一个已经监听端口的服务器。只有运行fastapi dev或其他 ASGI 服务器命令后,程序才会开始监听网络请求。11. 异步
路径函数可以使用
async def,也可以使用普通def:这里只需要回顾选择原则:
async def并await;def路径函数;async def中直接执行耗时同步 IO;asyncio.run()。上一大章已经解释了事件循环、线程池、超时和 worker。FastAPI 大章会重点学习 HTTP 接口设计,不再重复 asyncio 的内部原理。
12. 错误
第一次运行时,常见问题可以根据状态码或终端信息判断:
404 Not Found405 Method Not Allowed422Address already in useapp定位失败fastapi dev终端中的 Uvicorn 日志会显示请求方法、路径和状态码。排查时先判断请求有没有到达服务,再判断是路由、校验还是函数内部执行失败。
13. 边界
第一个接口很短,但已经形成了一条完整链路:
HTTP 请求经 ASGI 服务器交给 FastAPI,FastAPI 调用 Python 路径函数,处理结果最终转换成 HTTP 响应。
FLOW / RELATIONSHIP
HTTP 请求
ASGI 服务器
网络与应用之间的接口
FastAPI
路由与数据契约
Python 函数
处理具体业务
HTTP 响应
学习后续内容时,要始终区分三个层次:
14. 在线实验
用最小接口观察路径参数、查询参数和 JSON 响应,先建立请求与路径函数之间的对应关系。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /greeting/小微?language=zh。本篇不需要模型密钥或外部服务。默认响应的
message为"你好,小微"。把 language 改为 en,结果变成"Hello,小微";请求/users/42得到整数 42,请求/users/abc得到 422,而未定义的/missing得到 404。浏览器把请求交给当前 Python 应用的 ASGI 接口,既没有启动监听端口,也没有调用远程后端。原文中的 Uvicorn、网络端口和访问地址属于本机服务模式。在线接口不保存用户数据。
下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。