跳到主内容

LangChain Python

最后更新: 2026-10-11

1. 入口

FastAPI 配置分为两层。pyproject.toml 中的 [tool.fastapi] 配置 CLI 如何找到应用;应用 Settings 则配置创建出来的服务如何运行。

当前项目使用:

pyproject.toml
1
[tool.fastapi]
2
entrypoint = "app.main:app"

冒号左侧是模块路径,右侧是模块中的对象名:

FastAPI CLI / app.main:app 入口定位

入口 app.main:app 的冒号左侧是模块路径:app 表示 Python 包,main 表示包内的 app/main.py 模块。冒号右侧 app 表示该模块导出的 FastAPI 对象;CLI 导入模块并取得该对象。

对应代码是:

app/main.py
1
from app.factory import create_app
2
3
app = create_app()

FastAPI CLI 执行的效果相当于:

import-entrypoint.py
1
from app.main import app

配置入口后,本地开发不必重复传文件路径:

fastapi-commands.bash
1
uv run fastapi dev
2
uv run fastapi run

fastapi dev 面向开发,会启用自动重载;fastapi run 面向生产启动。[tool.fastapi] 不会决定监听端口、worker 数量或环境变量,这些仍由 CLI 参数和运行环境控制。

需要特别注意,fastapi dev 会在导入应用前尝试设置 FASTAPI_ENV=development,而 fastapi run 不会自动设置生产值。上一篇的 Settings 读取的是 APP__ENVIRONMENT,并不会把 FASTAPI_ENV 自动转换成 settings.app.environment,因此部署时仍应显式设置 APP__ENVIRONMENT=production。

两条命令的默认监听地址也不同:fastapi dev 使用 127.0.0.1,只供本机访问;fastapi run 使用 0.0.0.0,可能被网络中的其他设备访问。生产部署还需要结合反向代理、HTTPS、防火墙和进程管理,不能把执行一条 fastapi run 当作完整的部署方案。

如果项目改成 src 布局,例如应用位于 src/agent_api/main.py,入口也必须同步调整:

src-entrypoint.toml
1
[tool.fastapi]
2
entrypoint = "agent_api.main:app"

这个写法要求 agent_api 已经按照 src 布局安装到当前 Python 环境中。只是在仓库里创建 src/agent_api 目录,却没有正确配置并安装项目时,Python 仍然可能找不到这个包。

入口配置错误时,FastAPI CLI 会在启动阶段报告模块无法导入或找不到 app,它与请求路由返回 404 是不同问题。

2. 应用工厂

不要在 main.py 中读取几十个环境变量,再逐个创建中间件、数据库和模型。应用工厂可以把组装过程集中起来:

app/factory.py
01
from collections.abc import Callable
02
from contextlib import AbstractAsyncContextManager
03
04
from fastapi import FastAPI
05
06
from app.api.router import router as api_router
07
from app.core.settings import Settings, get_settings
08
from app.middleware import register_middleware
09
10
11
def create_app(settings: Settings | None = None) -> FastAPI:
12
current_settings = settings if settings is not None else get_settings()
13
14
app = FastAPI(
15
title=current_settings.app.name,
16
version="0.1.0",
17
debug=current_settings.app.environment == "development",
18
)
19
app.state.settings = current_settings
20
21
register_middleware(app, current_settings)
22
app.include_router(api_router)
23
return app

settings 参数允许测试显式传入配置;正常启动则调用 get_settings()。这比在测试中修改全局环境变量后重新导入整个模块更可控。

app.state.settings 把当前配置挂在应用实例上,适合需要从 Request 找到应用资源的依赖。它不是让所有业务代码直接访问全局状态的理由,业务服务仍应通过构造参数接收自己需要的配置。

Settings 可以在进程中缓存:

app/core/settings.py
1
from functools import lru_cache
2
3
4
@lru_cache(maxsize=1)
5
def get_settings() -> Settings:
6
return Settings()

缓存后,同一 worker 进程只读取和校验一次配置。部署多个 worker 时,每个进程都有自己的 Settings 和资源,Python 内存不会跨进程共享。

修改 .env 或 TOML 后,缓存对象不会自行变化。生产环境应重启或滚动更新应用,而不是尝试在请求中清除缓存。

3. 依赖

FastAPI 依赖可以把 Settings 提供给路由:

app/api/dependencies.py
01
from typing import Annotated
02
03
from fastapi import Depends, Request
04
05
from app.core.settings import Settings
06
07
08
def get_current_settings(request: Request) -> Settings:
09
return request.app.state.settings
10
11
12
SettingsDep = Annotated[Settings, Depends(get_current_settings)]

get_settings() 负责在创建应用时读取配置,get_current_settings() 则负责把这个已经确定的对象交给路由。名称看起来相近,但职责不同。这样测试向应用工厂传入 Settings 后,路由、中间件和 lifespan 都会看到同一个实例。

路由只声明需要配置,不负责读取配置文件:

app/api/routes/info.py
01
from fastapi import APIRouter
02
03
from app.api.dependencies import SettingsDep
04
05
router = APIRouter()
06
07
08
@router.get("/runtime-info")
09
async def runtime_info(settings: SettingsDep) -> dict[str, str]:
10
return {
11
"app_name": settings.app.name,
12
"environment": settings.app.environment,
13
"model": settings.model.name,
14
}

真实接口不一定应该公开模型名称和环境信息。这里用于演示依赖传递;生产健康检查只返回排障所需的非敏感字段。

依赖注入的价值不是少写一行导入,而是让对象来源明确且可以替换。对于 Settings,应用工厂参数就是最直接的替换入口:

tests/test_info.py
1
from app.factory import create_app
2
3
4
def test_factory_uses_injected_settings(test_settings):
5
app = create_app(test_settings)
6
7
assert app.state.settings is test_settings

这里的 test_settings fixture 会在第 6 节定义。模型客户端等资源依赖仍然可以使用 app.dependency_overrides 替换,但覆盖完成后应及时清空,避免影响其他测试。

如果路由自己调用 Settings(),测试就很难替换来源,还可能在每次请求中重复读取文件。

4. 生命周期

Settings 是轻量配置对象,数据库连接池、异步 HTTP 客户端和 LangGraph checkpointer 则是需要创建与关闭的长期资源。它们适合放进 FastAPI lifespan,也就是从应用启动到应用停止的这段生命周期:

app/core/lifespan.py
01
from collections.abc import AsyncIterator
02
from contextlib import asynccontextmanager
03
04
from fastapi import FastAPI
05
from httpx import AsyncClient, Timeout
06
07
from app.agent.graph import create_graph
08
from app.agent.model import create_model
09
from app.core.checkpointer import open_checkpointer
10
from app.core.settings import Settings
11
12
13
def create_lifespan(settings: Settings):
14
@asynccontextmanager
15
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
16
async with AsyncClient(
17
timeout=Timeout(settings.model.timeout_seconds),
18
) as http_client:
19
async with open_checkpointer(settings) as checkpointer:
20
model = create_model(settings)
21
graph = create_graph(
22
model=model,
23
checkpointer=checkpointer,
24
)
25
26
app.state.http_client = http_client
27
app.state.model = model
28
app.state.checkpointer = checkpointer
29
app.state.graph = graph
30
31
yield
32
33
return lifespan

create_lifespan() 是一个工厂:外层函数先接收 Settings,内层 lifespan() 再由 FastAPI 调用。yield 之前负责创建资源,yield 之后会按照 async with 的逆序自动关闭资源。

如果某个资源在 yield 之前创建失败,应用不会开始接收请求,已经进入的 async with 也会负责清理。这比先启动服务、等到请求到来后才发现核心资源不可用更容易排查。

示例中的 create_model()、create_graph() 和 open_checkpointer() 是项目自己的工厂函数,后续 LangChain/LangGraph 文章会实现。其中,open_checkpointer() 应返回异步上下文管理器,让内存和 PostgreSQL 两种实现拥有统一的打开、关闭方式。不能只把 checkpointer 传给编译图后,再假设可以从图对象中取回并关闭它。

最后,把这个 lifespan 工厂交给应用工厂:

app/factory.py
01
from fastapi import FastAPI
02
03
from app.api.router import router as api_router
04
from app.core.lifespan import create_lifespan
05
from app.core.settings import Settings, get_settings
06
from app.middleware import register_middleware
07
08
AppLifespan = Callable[[FastAPI], AbstractAsyncContextManager[None]]
09
10
11
def create_app(
12
settings: Settings | None = None,
13
*,
14
lifespan: AppLifespan | None = None,
15
) -> FastAPI:
16
current = settings if settings is not None else get_settings()
17
is_production = current.app.environment == "production"
18
current_lifespan = (
19
lifespan if lifespan is not None else create_lifespan(current)
20
)
21
22
app = FastAPI(
23
title=current.app.name,
24
version="0.1.0",
25
debug=current.app.environment == "development",
26
openapi_url=None if is_production else "/openapi.json",
27
docs_url=None if is_production else "/docs",
28
redoc_url=None if is_production else "/redoc",
29
lifespan=current_lifespan,
30
)
31
app.state.settings = current
32
33
register_middleware(app, current)
34
app.include_router(api_router)
35
return app

正常启动没有传入 lifespan 时,工厂会调用 create_lifespan(current);测试则可以传入不连接外部服务的生命周期。这样应用工厂、路由依赖、中间件和 lifespan 始终使用同一份 Settings。这里选择在生产环境关闭 OpenAPI Schema 和两个文档页面,但这属于产品策略,不是固定答案。即使关闭这些入口,接口本身仍需认证、授权和输入校验,不能把隐藏文档当作安全措施。

5. 资源依赖

请求需要使用生命周期资源时,可以通过依赖从 request.app.state 读取:

app/api/dependencies.py
01
from typing import Annotated
02
03
from fastapi import Depends, Request
04
from langchain_core.language_models import BaseChatModel
05
06
07
def get_chat_model(request: Request) -> BaseChatModel:
08
return request.app.state.model
09
10
11
ChatModelDep = Annotated[BaseChatModel, Depends(get_chat_model)]

路由获得的是抽象模型接口:

app/api/routes/chat.py
01
from fastapi import APIRouter
02
from pydantic import BaseModel, Field
03
04
from app.api.dependencies import ChatModelDep
05
06
router = APIRouter()
07
08
09
class ChatRequest(BaseModel):
10
question: str = Field(min_length=1, max_length=4_000)
11
12
13
class ChatResponse(BaseModel):
14
answer: str
15
16
17
@router.post("/chat")
18
async def chat(payload: ChatRequest, model: ChatModelDep) -> ChatResponse:
19
response = await model.ainvoke(payload.question)
20
return ChatResponse(answer=response.text)

ChatRequest 继承 BaseModel,所以 FastAPI 会把 JSON 请求体解析到 payload,并在调用模型前检查问题是否为空、长度是否超出当前项目限制。如果直接把 question: str 写在函数参数中,它默认会被当作查询参数,而不是 JSON 请求体。

资源范围需要区分:

对象典型范围
Settings每进程一份
数据库 Engine/Pool每进程一份
HTTP Client每进程复用
LangChain 模型客户端通常每进程复用
LangGraph 编译图通常每进程复用
数据库 Session每请求一份
当前用户身份每请求解析
thread_id每个对话线程一个,由每次图调用显式携带

不能因为数据库 Engine 可以复用,就把一个可变的数据库 Session 也放到全局。thread_id 也不能设置成全进程共享值,否则不同用户的对话状态可能混在一起。配置决定如何创建资源,资源自身还要遵守正确生命周期。

6. 服务与测试

第 4 节的完整应用工厂已经根据 settings.app.environment 设置标题、调试模式和文档地址。debug 只在 development 环境开启,不能简单写成 not is_production,否则 test 和 staging 也会意外进入调试模式。

CORS 同样要把 Settings 中的值真正传给中间件:

app/middleware/cors.py
01
from fastapi import FastAPI
02
from fastapi.middleware.cors import CORSMiddleware
03
04
from app.core.settings import Settings
05
06
07
def add_cors(app: FastAPI, settings: Settings) -> None:
08
app.add_middleware(
09
CORSMiddleware,
10
allow_origins=settings.server.cors.allow_origins,
11
allow_methods=settings.server.cors.allow_methods,
12
allow_headers=["Authorization", "Content-Type"],
13
allow_credentials=False,
14
)

上一篇的 CorsSettings 只声明了来源和请求方法,因此这里为请求头和凭据使用明确的安全值。如果项目需要让这两项随环境变化,应先把 allow_headers、allow_credentials 同时加入 Settings 模型和 TOML,再从 settings.server.cors 读取。配置项只有传入真实组件才会生效,仅在 TOML 中写下 allow_origins 不会自动改变浏览器跨域行为。

测试与排查

应用工厂允许测试直接构造 Settings:

tests/conftest.py
01
from collections.abc import AsyncIterator
02
from contextlib import asynccontextmanager
03
04
import pytest
05
from fastapi import FastAPI
06
07
from app.core.settings import Settings
08
from app.factory import create_app
09
10
11
@asynccontextmanager
12
async def empty_lifespan(_app: FastAPI) -> AsyncIterator[None]:
13
yield
14
15
16
@pytest.fixture
17
def test_settings() -> Settings:
18
return Settings(
19
_env_file=None,
20
app={
21
"name": "FastAPI LangChain Test",
22
"environment": "test",
23
"log_level": "WARNING",
24
},
25
server={
26
"host": "127.0.0.1",
27
"port": 8000,
28
"cors": {
29
"allow_origins": ["http://testserver"],
30
"allow_methods": ["GET", "POST", "OPTIONS"],
31
},
32
},
33
model={
34
"provider": "fake",
35
"name": "fake-model",
36
"base_url": "https://example.test",
37
"api_key": None,
38
"temperature": 0,
39
"timeout_seconds": 5,
40
"max_retries": 0,
41
},
42
langgraph={
43
"recursion_limit": 10,
44
"checkpoint_backend": "memory",
45
},
46
database={
47
"url": None,
48
"pool_size": 1,
49
"pool_timeout_seconds": 5,
50
},
51
langsmith_tracing=False,
52
langsmith_api_key=None,
53
)
54
55
56
@pytest.fixture
57
def app(test_settings: Settings) -> FastAPI:
58
return create_app(test_settings, lifespan=empty_lifespan)

_env_file=None 会关闭 .env 读取;各个必填分组也都显式提供测试值,因此不会只覆盖两个字段却意外沿用生产密钥。第 42 篇自定义的 TOML 来源仍会参与收集,但初始化参数优先级最高。若配置测试需要完全隔离 TOML,应为测试定义专用 Settings 子类或测试配置文件,这部分会在后续测试章节展开。

empty_lifespan 让只测试应用元数据或普通路由的用例不连接真实模型和数据库。需要验证资源型路由时,应改用能够写入 app.state.model 等假资源的测试 lifespan,或覆盖对应的 FastAPI 依赖。

创建 TestClient 时,如果要让 lifespan 真正运行,应把它作为上下文管理器使用。下面运行的是 fixture 中注入的 empty_lifespan,不会连接外部服务:

test-client-lifespan.py
1
from fastapi.testclient import TestClient
2
3
4
def test_runtime_info(app):
5
with TestClient(app) as client:
6
response = client.get("/runtime-info")
7
8
assert response.status_code == 200

如果测试必须修改环境变量,应在修改后清除缓存,并在测试结束时恢复环境。pytest 的 monkeypatch 可以管理这个过程:

tests/test_settings.py
01
from app.core.settings import get_settings
02
03
04
def test_model_override(monkeypatch):
05
monkeypatch.setenv("MODEL__NAME", "test-model")
06
get_settings.cache_clear()
07
08
try:
09
settings = get_settings()
10
assert settings.model.name == "test-model"
11
finally:
12
get_settings.cache_clear()

monkeypatch 会在测试结束时恢复环境变量,finally 则保证即使断言失败也会清除 Settings 缓存。

7. 在线实验

让公开配置真正控制应用标题、调试模式、文档地址与 lifespan,观察同一 Settings 如何被工厂和路由共同使用。

目录结构
使用上下方向键浏览目录,左右方向键展开或收起,Enter 或空格切换展开状态。
    • main.pyFastAPI 入口
    • configured_app.py本篇实验逻辑
    • config.toml本篇附加文件
    • pyproject.toml基础依赖与项目元数据
    • .python-version本机 Python 版本
    • .gitignore
    • README.md操作与运行边界

下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:

main.py
1
from configured_app import create_app, load_settings
2
3
app = create_app(load_settings())
4
configured_app.py
01
from collections.abc import AsyncIterator
02
from contextlib import asynccontextmanager
03
from pathlib import Path
04
from typing import Literal
05
import tomllib
06
07
from fastapi import FastAPI, Request
08
from pydantic import BaseModel, ConfigDict, Field
09
10
class Settings(BaseModel):
11
model_config = ConfigDict(extra="forbid")
12
name: str = Field(min_length=1, max_length=80)
13
environment: Literal["development", "test", "production"]
14
15
def load_settings() -> Settings:
16
with Path(__file__).with_name("config.toml").open("rb") as file:
17
return Settings.model_validate(tomllib.load(file)["app"])
18
19
@asynccontextmanager
20
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
21
app.state.ready = True
22
print("应用生命周期启动")
23
try:
24
yield
25
finally:
26
app.state.ready = False
27
print("应用生命周期关闭")
28
29
def create_app(settings: Settings) -> FastAPI:
30
production = settings.environment == "production"
31
app = FastAPI(title=settings.name, debug=settings.environment == "development",
32
docs_url=None if production else "/docs",
33
redoc_url=None if production else "/redoc",
34
openapi_url=None if production else "/openapi.json", lifespan=lifespan)
35
app.state.settings = settings
36
37
@app.get("/runtime-info")
38
async def runtime_info(request: Request) -> dict[str, object]:
39
current = request.app.state.settings
40
return {"title": request.app.title, "environment": current.environment,
41
"debug": request.app.debug, "docs_url": request.app.docs_url,
42
"ready": request.app.state.ready}
43
44
return app
45
config.toml
1
[app]
2
name = "配置驱动的 FastAPI"
3
environment = "development"
4

打开在线案例,点击运行,等待环境就绪,再发送默认 GET /runtime-info。本篇不需要模型密钥或外部服务。

默认 title 为配置驱动的 FastAPI,environment=development、debug=true、docs_url="/docs"、ready=true。日志先记录生命周期启动,请求时读取的是应用已保存的 Settings。

把 environment 改为 production 并重新运行,debug 变为 false,docs_url 变为 null;此时用在线请求面板直接访问 /runtime-info,或者本机 curl 请求,不能继续依赖 /docs。配置在创建应用时读取,不随每次请求改写;本篇生命周期只管理本地状态,不创建模型、数据库或后台线程。

下载项目后,在项目目录执行:

code.ts
1
uv run fastapi dev main.py

再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。

正在验证登录状态
请稍候,验证完成后将继续显示文章内容

此段落已有评论,按 Enter 查看评论及回复列表。

评论-

文章反应
评论与回复

连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。

添加评论
    即时渲染