在项目中,我们通过 langchain-openai 调用 DeepSeek 的 OpenAI 兼容接口。模型配置可以拆成连接信息、默认生成参数和允许使用的模型:
langchain-openai
我们之前选择了在 .env 中配置模型参数,具体使用时,可以根据个人喜好选择
01[model] 02provider = "openai" 03name = "deepseek-v4-flash" 04base_url = "https://api.deepseek.com" 05temperature = 0.2 06max_tokens = 2048 07timeout_seconds = 30 08max_retries = 2 09allowed_models = [ 10 "deepseek-v4-flash", 11 "deepseek-v4-pro", 12]
这些字段的含义如下:
provider
name
base_url
temperature
max_tokens
timeout_seconds
max_retries
allowed_models
provider 与模型名称不是一回事。使用 OpenAI 兼容接口时,LangChain 仍然需要 OpenAI 集成来组织请求,但 name 会原样交给实际服务商:
01from langchain_openai import ChatOpenAI 02 03from app.core.settings import Settings 04 05 06def create_model(settings: Settings) -> ChatOpenAI: 07 api_key = settings.model.api_key 08 if api_key is None: 09 raise RuntimeError("模型 API Key 未配置") 10 11 return ChatOpenAI( 12 model=settings.model.name, 13 api_key=api_key.get_secret_value(), 14 base_url=str(settings.model.base_url), 15 temperature=settings.model.temperature, 16 max_tokens=settings.model.max_tokens, 17 timeout=settings.model.timeout_seconds, 18 max_retries=settings.model.max_retries, 19 )
ChatOpenAI 封装的是消息转换、HTTP 调用、流式输出、重试和响应对象构造等客户端逻辑。base_url 指向 DeepSeek 后,请求实际发送给 DeepSeek,不会因为类名中有 OpenAI 就改成调用 OpenAI 官方服务。
ChatOpenAI
不同服务商对兼容参数的支持并不完全一致。TOML 能成功解析、LangChain 构造函数能接收参数,不代表上游一定会按相同方式执行。模型是否支持温度、工具调用、结构化输出、推理参数和流式 usage,需要以当前服务商文档与真实测试为准。
LangChain 也提供了专门的 langchain-deepseek 集成。只需要兼容接口中的基础文本能力时,可以继续使用 ChatOpenAI;如果要读取 reasoning_content 等 DeepSeek 扩展字段,或者使用供应商特有能力,应优先选择 ChatDeepSeek。此时还要安装 langchain-deepseek,并把 provider、模型工厂和依赖声明一起调整,不能只替换类名。
langchain-deepseek
reasoning_content
ChatDeepSeek
模型 Settings 可以使用 Pydantic 校验范围:
01from typing import Literal 02 03from pydantic import BaseModel, Field, HttpUrl, SecretStr, model_validator 04 05 06class ModelSettings(BaseModel): 07 provider: Literal["openai"] = "openai" 08 name: str = Field(min_length=1) 09 base_url: HttpUrl 10 api_key: SecretStr | None = None 11 temperature: float = Field(default=0.2, ge=0, le=2) 12 max_tokens: int = Field(default=2048, gt=0, le=100_000) 13 timeout_seconds: float = Field(default=30, gt=0, le=300) 14 max_retries: int = Field(default=2, ge=0, le=10) 15 allowed_models: list[str] = Field(min_length=1) 16 17 @model_validator(mode="after") 18 def validate_default_model(self) -> "ModelSettings": 19 if self.name not in self.allowed_models: 20 raise ValueError("默认模型必须位于 allowed_models 中") 21 return self
这里把 provider 限制为当前项目真正接入的 openai,这样拼写错误会在启动时暴露。max_tokens 的 100_000 也是项目为了控制成本和响应时间设定的上限,不代表 DeepSeek 接口本身的最大输出能力。
openai
100_000
API Key 仍然通过环境提供:
1MODEL__API_KEY=your-api-key
不要在 config.toml 中写真实密钥:
config.toml
1# 不要提交这种配置 2[model] 3api_key = "sk-real-secret"
配置中的 name 是默认模型,allowed_models 是服务端允许列表。用户可以请求切换模型,但不能把任意字符串直接传给供应商:
1[model] 2name = "deepseek-v4-flash" 3allowed_models = [ 4 "deepseek-v4-flash", 5 "deepseek-v4-pro", 6]
1from app.core.settings import Settings 2 3 4def resolve_model(requested: str | None, settings: Settings) -> str: 5 model = requested or settings.model.name 6 if model not in settings.model.allowed_models: 7 raise ValueError(f"不支持的模型:{model}") 8 return model
如果不同模型使用不同 base_url 或 API Key,仅切换模型名不够。此时应配置完整模型档案,并在服务端按受控 ID 选择,不能让客户端提交任意 URL 和密钥。
配置要区分进程级配置、业务输入、运行上下文和生成参数:
thread_id
进程级配置适合在应用启动时创建模型客户端。其余内容随请求变化,不应通过修改全局 Settings 实现,否则两个并发请求可能互相覆盖。
LangChain 模型可以通过 bind() 派生本次调用参数:
bind()
01from collections.abc import Sequence 02 03from langchain_core.messages import BaseMessage 04from langchain_openai import ChatOpenAI 05 06 07async def reply( 08 model: ChatOpenAI, 09 messages: Sequence[BaseMessage], 10 temperature: float, 11) -> str: 12 request_model = model.bind(temperature=temperature) 13 response = await request_model.ainvoke(messages) 14 return response.text
bind() 返回一个带有本次调用参数的新 Runnable,不会修改 TOML,也不会改写共享模型实例。请求参数仍需通过 Pydantic Schema 限制范围。
LangChain 的 init_chat_model() 还支持 configurable fields,让调用时通过 Runnable config 切换受控字段。它适合一个图中需要声明式切换模型的场景,但不要把所有字段都暴露为 configurable:
init_chat_model()
01from langchain.chat_models import init_chat_model 02 03from app.core.settings import Settings 04 05 06def create_configurable_model(settings: Settings): 07 api_key = settings.model.api_key 08 if api_key is None: 09 raise RuntimeError("模型 API Key 未配置") 10 11 return init_chat_model( 12 model=settings.model.name, 13 model_provider=settings.model.provider, 14 base_url=str(settings.model.base_url), 15 api_key=api_key.get_secret_value(), 16 configurable_fields=("model", "temperature", "max_tokens"), 17 config_prefix="chat", 18 )
调用时传入的字段仍应由服务端白名单生成:
01response = await model.ainvoke( 02 messages, 03 config={ 04 "configurable": { 05 "chat_model": selected_model, 06 "chat_temperature": temperature, 07 "chat_max_tokens": max_tokens, 08 }, 09 }, 10)
Runnable config 是一次调用的上下文,不等于应用 TOML。前者随请求变化,后者在进程启动时确定默认策略。
LangGraph 配置可以分为图构建参数、持久化参数和每次运行参数:
1[langgraph] 2recursion_limit = 50 3checkpointer = "memory" 4store = "memory" 5 6[langgraph.postgres] 7pool_size = 10 8pool_timeout_seconds = 30
各字段职责:
recursion_limit
checkpointer
store
pool_size
pool_timeout_seconds
checkpointer 与 Store 不相同:
checkpointer 保存一次会话 thread 内的图状态、步骤和恢复点。Store 保存跨 thread 使用的长期记忆或共享数据。两者可以同时使用,职责不同。
THREAD / 会话内
CROSS-THREAD / 跨会话
状态、步骤和恢复点
Store
长期记忆与共享数据
开发和测试可以使用内存实现。下面的示例同时补全了最小图结构,model 会在节点中真正参与调用:
model
01from langchain_core.language_models import BaseChatModel 02from langgraph.checkpoint.memory import InMemorySaver 03from langgraph.graph import END, START, MessagesState, StateGraph 04from langgraph.store.memory import InMemoryStore 05 06 07def create_memory_graph(model: BaseChatModel): 08 async def call_model(state: MessagesState): 09 response = await model.ainvoke(state["messages"]) 10 return {"messages": [response]} 11 12 builder = StateGraph(MessagesState) 13 builder.add_node("model", call_model) 14 builder.add_edge(START, "model") 15 builder.add_edge("model", END) 16 17 checkpointer = InMemorySaver() 18 store = InMemoryStore() 19 20 return builder.compile( 21 checkpointer=checkpointer, 22 store=store, 23 )
内存状态只存在于当前进程。重启会丢失,多 worker 之间也不共享,因此不适合需要可靠恢复的生产服务。这段函数固定创建内存实现,不会读取 TOML;在完整项目中,还需要由资源工厂读取 settings.langgraph.checkpointer 和 settings.langgraph.store,再选择对应实现。只修改配置字段,并不会自动切换后端。
settings.langgraph.checkpointer
settings.langgraph.store
生产环境可以在 TOML 中选择 PostgreSQL 后端,但连接 URL 仍通过敏感环境变量提供。双下划线表示嵌套层级,因此下面的变量对应 settings.langgraph.postgres.url:
settings.langgraph.postgres.url
1LANGGRAPH__POSTGRES__URL=postgresql://user:password@db/agent
图编译时注入 checkpointer。每次调用时提供 thread_id 和递归限制:
1result = await graph.ainvoke( 2 {"messages": messages}, 3 config={ 4 "configurable": { 5 "thread_id": conversation_id, 6 }, 7 "recursion_limit": settings.langgraph.recursion_limit, 8 }, 9)
thread_id 是业务会话标识,必须来自当前已授权用户可访问的会话。不能让攻击者猜一个 ID 就读取其他用户的图状态。配置文件只能提供命名规则或默认策略,不能代替数据库授权检查。
LangSmith tracing 常通过环境变量启用:
1LANGSMITH_TRACING=true 2LANGSMITH_API_KEY=your-langsmith-key 3LANGSMITH_PROJECT=fastapi-langchain-development 4LANGSMITH_TRACING_SAMPLING_RATE=0.1
TOML 可以保存非敏感策略:
1[observability] 2tracing_enabled = false 3project = "fastapi-langchain-development" 4sampling_rate = 0.1
但是,仅写 TOML 不会自动启用 LangSmith。sampling_rate 也不是 LangSmith 会自动查找的 TOML 字段。部署平台可以直接提供上面的 LangSmith 环境变量;如果项目把非敏感策略统一放在 TOML 中,就要在创建模型、Agent 或图之前完成一次显式映射:
sampling_rate
01import os 02 03from app.core.settings import Settings 04 05 06def configure_langsmith(settings: Settings) -> None: 07 observability = settings.observability 08 os.environ["LANGSMITH_TRACING"] = str( 09 observability.tracing_enabled, 10 ).lower() 11 os.environ["LANGSMITH_PROJECT"] = observability.project 12 os.environ["LANGSMITH_TRACING_SAMPLING_RATE"] = str( 13 observability.sampling_rate, 14 )
这段代码只映射公开策略,LANGSMITH_API_KEY 仍由运行环境提供。若项目改为手动创建 LangSmith Client,也可以把采样率传给 tracing_sampling_rate,再通过 tracing context 使用该 Client;两种接入方式选择一种即可。
LANGSMITH_API_KEY
Client
tracing_sampling_rate
追踪配置需要按环境管理:
LangSmith API Key 必须由环境提供。项目名称可以进入 TOML,但生产环境仍可覆盖。
追踪可能包含提示词、工具输入输出、模型回答和用户数据。启用前要确认脱敏、访问控制、保留时间与隐私策略。SecretStr 只保护配置对象打印,不会自动从 tracing 中移除用户内容。
SecretStr
本章讲的是 Python 应用如何使用 TOML 管理自己的运行配置。LangGraph CLI 和 LangSmith Deployment 还有独立的 langgraph.json:
langgraph.json
1{ 2 "dependencies": ["."], 3 "graphs": { 4 "assistant": "./app/graph.py:graph" 5 }, 6 "env": "./.env" 7}
它告诉 LangGraph 工具:
langgraph.json 与 pyproject.toml 可以同时存在:
pyproject.toml
pyproject.toml 保存 Python 依赖和工具配置,config.toml 保存应用默认策略,.env 保存本地密钥和环境覆盖,langgraph.json 保存 LangGraph CLI 或部署的图入口。只通过 FastAPI 托管图而不使用 LangGraph CLI 时,不必创建 langgraph.json。
CONTEXT
Python 依赖与开发工具
应用默认运行策略
.env
本地密钥与环境覆盖
LangGraph CLI / 部署的图入口
不能因为喜欢 TOML 就把 langgraph.json 改成 langgraph.toml,LangGraph CLI 默认不会识别自创格式。也不要在 langgraph.json 的 env 字段中写密钥值,它应指向环境文件或由部署平台提供环境变量。
langgraph.toml
env
如果当前项目只通过 FastAPI 自己托管编译图,不使用 LangGraph CLI/Agent Server,就不必提前创建 langgraph.json。是否需要它取决于部署方式。
AI 配置不仅要检查类型,还要检查组合关系:
01from typing import Literal 02 03from pydantic import BaseModel, Field, SecretStr, model_validator 04 05 06class PostgresSettings(BaseModel): 07 url: SecretStr | None = None 08 pool_size: int = Field(default=10, gt=0) 09 pool_timeout_seconds: float = Field(default=30, gt=0) 10 11 12class LangGraphSettings(BaseModel): 13 checkpointer: Literal["memory", "postgres"] = "memory" 14 store: Literal["memory", "postgres"] = "memory" 15 recursion_limit: int = Field(default=50, gt=0, le=500) 16 postgres: PostgresSettings = Field(default_factory=PostgresSettings) 17 18 @model_validator(mode="after") 19 def validate_backend(self) -> "LangGraphSettings": 20 uses_postgres = ( 21 self.checkpointer == "postgres" or self.store == "postgres" 22 ) 23 if uses_postgres and self.postgres.url is None: 24 raise ValueError("PostgreSQL 后端需要数据库 URL") 25 return self
生产启动还应执行有超时的连通性检查,但不要让检查产生昂贵模型回答。可以验证:
失败信息应指出哪个组件不可用,但不能包含 API Key、数据库密码或完整 Authorization 头。
重试也要有边界。配置 max_retries = 10 可能把一次不可恢复的配置错误拖成很长超时。认证失败、模型不存在等客户端错误通常不应反复重试;网络抖动和限流才可能适合退避重试。
max_retries = 10
实际校验模型允许列表与生成参数,组合本次运行上下文,先观察公开默认配置与请求覆盖之间的关系。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from fastapi import FastAPI 2 3from model_policy import router 4 5app = FastAPI(title="AI 运行配置") 6app.include_router(router) 7
01from pathlib import Path 02import tomllib 03 04from fastapi import APIRouter, HTTPException 05from pydantic import BaseModel, ConfigDict, Field, model_validator 06 07router = APIRouter() 08 09class ModelPolicy(BaseModel): 10 model_config = ConfigDict(extra="forbid") 11 name: str = Field(min_length=1, max_length=80) 12 temperature: float = Field(ge=0, le=2) 13 max_tokens: int = Field(gt=0, le=4096) 14 timeout_seconds: float = Field(gt=0, le=120) 15 allowed_models: list[str] = Field(min_length=1, max_length=5) 16 17 @model_validator(mode="after") 18 def allowed_default(self) -> "ModelPolicy": 19 if self.name not in self.allowed_models: 20 raise ValueError("默认模型不在允许列表中") 21 return self 22 23class GenerationRequest(BaseModel): 24 model_config = ConfigDict(extra="forbid") 25 model: str | None = Field(default=None, max_length=80) 26 temperature: float | None = Field(default=None, ge=0, le=2) 27 max_tokens: int | None = Field(default=None, gt=0, le=4096) 28 thread_id: str = Field(default="lesson-thread", min_length=1, max_length=80) 29 30@router.post("/model-policy") 31async def model_policy(payload: GenerationRequest) -> dict[str, object]: 32 with Path(__file__).with_name("config.toml").open("rb") as file: 33 config = tomllib.load(file) 34 policy = ModelPolicy.model_validate(config["model"]) 35 selected = payload.model or policy.name 36 if selected not in policy.allowed_models: 37 raise HTTPException(status_code=400, detail="请求模型不在允许列表中") 38 return {"model": selected, 39 "temperature": payload.temperature if payload.temperature is not None else policy.temperature, 40 "max_tokens": payload.max_tokens if payload.max_tokens is not None else policy.max_tokens, 41 "timeout_seconds": policy.timeout_seconds, 42 "runnable_config": {"configurable": {"thread_id": payload.thread_id}, 43 "recursion_limit": config["langgraph"]["recursion_limit"]}, 44 "tracing_enabled": config["observability"]["tracing_enabled"], 45 "model_called": False} 46
01[model] 02name = "teaching-model-a" 03temperature = 0.2 04max_tokens = 512 05timeout_seconds = 30 06allowed_models = ["teaching-model-a", "teaching-model-b"] 07 08[langgraph] 09recursion_limit = 50 10 11[observability] 12tracing_enabled = false 13
打开在线案例,点击运行,等待环境就绪,再发送默认 POST /model-policy。本篇不需要模型密钥或外部服务。
POST /model-policy
默认请求体:
1{"thread_id":"lesson-thread","temperature":0.2}
默认 model=teaching-model-a、temperature=0.2、max_tokens=512;runnable_config 中保留本次 thread_id 和递归上限。改成 temperature=0 时仍得到 0,而不会因布尔判断意外回到默认温度。
请求未知模型返回 400,温度和输出上限越界返回 422。每次请求加载并组合独立数据,不修改共享模型设置。teaching-model-a/b 只是离线策略的示例 ID,不是供应商真实模型名;model_called=false 明确表示没有调用 LLM、创建 LangGraph 或上传 tracing。真实模型、图持久化和部署仍按原文接入,thread_id 的权限校验不能由字符串格式替代。
下载项目后,在项目目录执行:
1uv run fastapi dev main.py
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 模型
在项目中,我们通过
langchain-openai调用 DeepSeek 的 OpenAI 兼容接口。模型配置可以拆成连接信息、默认生成参数和允许使用的模型:我们之前选择了在 .env 中配置模型参数,具体使用时,可以根据个人喜好选择
这些字段的含义如下:
providernamebase_urltemperaturemax_tokenstimeout_secondsmax_retriesallowed_modelsprovider与模型名称不是一回事。使用 OpenAI 兼容接口时,LangChain 仍然需要 OpenAI 集成来组织请求,但name会原样交给实际服务商:ChatOpenAI封装的是消息转换、HTTP 调用、流式输出、重试和响应对象构造等客户端逻辑。base_url指向 DeepSeek 后,请求实际发送给 DeepSeek,不会因为类名中有 OpenAI 就改成调用 OpenAI 官方服务。不同服务商对兼容参数的支持并不完全一致。TOML 能成功解析、LangChain 构造函数能接收参数,不代表上游一定会按相同方式执行。模型是否支持温度、工具调用、结构化输出、推理参数和流式 usage,需要以当前服务商文档与真实测试为准。
LangChain 也提供了专门的
langchain-deepseek集成。只需要兼容接口中的基础文本能力时,可以继续使用ChatOpenAI;如果要读取reasoning_content等 DeepSeek 扩展字段,或者使用供应商特有能力,应优先选择ChatDeepSeek。此时还要安装langchain-deepseek,并把provider、模型工厂和依赖声明一起调整,不能只替换类名。2. Settings
模型 Settings 可以使用 Pydantic 校验范围:
这里把
provider限制为当前项目真正接入的openai,这样拼写错误会在启动时暴露。max_tokens的100_000也是项目为了控制成本和响应时间设定的上限,不代表 DeepSeek 接口本身的最大输出能力。API Key 仍然通过环境提供:
不要在
config.toml中写真实密钥:配置中的
name是默认模型,allowed_models是服务端允许列表。用户可以请求切换模型,但不能把任意字符串直接传给供应商:如果不同模型使用不同
base_url或 API Key,仅切换模型名不够。此时应配置完整模型档案,并在服务端按受控 ID 选择,不能让客户端提交任意 URL 和密钥。3. 动态参数
配置要区分进程级配置、业务输入、运行上下文和生成参数:
base_url、API Key、HTTP 超时、最大重试、连接池thread_id、用户身份和请求 ID进程级配置适合在应用启动时创建模型客户端。其余内容随请求变化,不应通过修改全局 Settings 实现,否则两个并发请求可能互相覆盖。
LangChain 模型可以通过
bind()派生本次调用参数:bind()返回一个带有本次调用参数的新 Runnable,不会修改 TOML,也不会改写共享模型实例。请求参数仍需通过 Pydantic Schema 限制范围。LangChain 的
init_chat_model()还支持 configurable fields,让调用时通过 Runnable config 切换受控字段。它适合一个图中需要声明式切换模型的场景,但不要把所有字段都暴露为 configurable:调用时传入的字段仍应由服务端白名单生成:
Runnable config 是一次调用的上下文,不等于应用 TOML。前者随请求变化,后者在进程启动时确定默认策略。
4. LangGraph
LangGraph 配置可以分为图构建参数、持久化参数和每次运行参数:
各字段职责:
recursion_limitcheckpointerstorepool_sizepool_timeout_secondscheckpointer 与 Store 不相同:
checkpointer 保存一次会话 thread 内的图状态、步骤和恢复点。Store 保存跨 thread 使用的长期记忆或共享数据。两者可以同时使用,职责不同。
THREAD / 会话内
CROSS-THREAD / 跨会话
checkpointer
状态、步骤和恢复点
Store
长期记忆与共享数据
开发和测试可以使用内存实现。下面的示例同时补全了最小图结构,
model会在节点中真正参与调用:内存状态只存在于当前进程。重启会丢失,多 worker 之间也不共享,因此不适合需要可靠恢复的生产服务。这段函数固定创建内存实现,不会读取 TOML;在完整项目中,还需要由资源工厂读取
settings.langgraph.checkpointer和settings.langgraph.store,再选择对应实现。只修改配置字段,并不会自动切换后端。生产环境可以在 TOML 中选择 PostgreSQL 后端,但连接 URL 仍通过敏感环境变量提供。双下划线表示嵌套层级,因此下面的变量对应
settings.langgraph.postgres.url:图编译时注入 checkpointer。每次调用时提供
thread_id和递归限制:thread_id是业务会话标识,必须来自当前已授权用户可访问的会话。不能让攻击者猜一个 ID 就读取其他用户的图状态。配置文件只能提供命名规则或默认策略,不能代替数据库授权检查。5. 追踪
LangSmith tracing 常通过环境变量启用:
TOML 可以保存非敏感策略:
但是,仅写 TOML 不会自动启用 LangSmith。
sampling_rate也不是 LangSmith 会自动查找的 TOML 字段。部署平台可以直接提供上面的 LangSmith 环境变量;如果项目把非敏感策略统一放在 TOML 中,就要在创建模型、Agent 或图之前完成一次显式映射:这段代码只映射公开策略,
LANGSMITH_API_KEY仍由运行环境提供。若项目改为手动创建 LangSmithClient,也可以把采样率传给tracing_sampling_rate,再通过 tracing context 使用该 Client;两种接入方式选择一种即可。追踪配置需要按环境管理:
LangSmith API Key 必须由环境提供。项目名称可以进入 TOML,但生产环境仍可覆盖。
追踪可能包含提示词、工具输入输出、模型回答和用户数据。启用前要确认脱敏、访问控制、保留时间与隐私策略。
SecretStr只保护配置对象打印,不会自动从 tracing 中移除用户内容。6. 部署
本章讲的是 Python 应用如何使用 TOML 管理自己的运行配置。LangGraph CLI 和 LangSmith Deployment 还有独立的
langgraph.json:它告诉 LangGraph 工具:
langgraph.json与pyproject.toml可以同时存在:pyproject.toml 保存 Python 依赖和工具配置,config.toml 保存应用默认策略,.env 保存本地密钥和环境覆盖,langgraph.json 保存 LangGraph CLI 或部署的图入口。只通过 FastAPI 托管图而不使用 LangGraph CLI 时,不必创建 langgraph.json。
CONTEXT
pyproject.toml
Python 依赖与开发工具
config.toml
应用默认运行策略
.env
本地密钥与环境覆盖
langgraph.json
LangGraph CLI / 部署的图入口
不能因为喜欢 TOML 就把
langgraph.json改成langgraph.toml,LangGraph CLI 默认不会识别自创格式。也不要在langgraph.json的env字段中写密钥值,它应指向环境文件或由部署平台提供环境变量。如果当前项目只通过 FastAPI 自己托管编译图,不使用 LangGraph CLI/Agent Server,就不必提前创建
langgraph.json。是否需要它取决于部署方式。启动校验
AI 配置不仅要检查类型,还要检查组合关系:
生产启动还应执行有超时的连通性检查,但不要让检查产生昂贵模型回答。可以验证:
失败信息应指出哪个组件不可用,但不能包含 API Key、数据库密码或完整 Authorization 头。
重试也要有边界。配置
max_retries = 10可能把一次不可恢复的配置错误拖成很长超时。认证失败、模型不存在等客户端错误通常不应反复重试;网络抖动和限流才可能适合退避重试。7. 在线实验
实际校验模型允许列表与生成参数,组合本次运行上下文,先观察公开默认配置与请求覆盖之间的关系。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
POST /model-policy。本篇不需要模型密钥或外部服务。默认请求体:
默认 model=teaching-model-a、temperature=0.2、max_tokens=512;runnable_config 中保留本次 thread_id 和递归上限。改成 temperature=0 时仍得到 0,而不会因布尔判断意外回到默认温度。
请求未知模型返回 400,温度和输出上限越界返回 422。每次请求加载并组合独立数据,不修改共享模型设置。teaching-model-a/b 只是离线策略的示例 ID,不是供应商真实模型名;model_called=false 明确表示没有调用 LLM、创建 LangGraph 或上传 tracing。真实模型、图持久化和部署仍按原文接入,thread_id 的权限校验不能由字符串格式替代。
下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。