Agent 模型调用:接口、流式与可靠性
Agent 的规划、检索和工具决策,都要经过模型调用。一次请求在本地返回了文字,只证明接口能通;要让它进入业务链路,还需要处理输出截断、连接中断、配额、重复请求、模型切换和追踪。
本文把原生 API 与 Spring AI、LangChain 放在同一条调用链里理解:先定义应用需要的契约,再决定哪些工作由 SDK 或框架完成。结构化数据的生成与校验见结构化输出与数据校验,历史消息与记忆管理见上下文编排与记忆召回。
整理来源:CodeCrush《大模型应用开发基础》第 05、07、09、10、21、22 篇。本文按主题合并原稿,删去重复入门解释,补充接口边界与失败处理。代码为教学示例;模型 ID、支持参数和依赖版本需要在自己的环境中确认,不构成已完成真实 API 联调的声明。官方资料复核日期:2026-09-22。
1. 把模型服务、协议与业务接口分开
模型服务可以来自厂商 API、第三方托管或本地推理服务。个人设备也能运行合适大小的模型;是否适合生产,取决于硬件、模型质量、并发与维护成本。SDK 是 HTTP 等协议的封装,不是运行模型的必要条件。
一个实用的分层是:
业务:抽取工单、回答制度问题、决定下一步工具
↓
应用调用层:权限、预算、路由、截止时间、统一结果
↓
SDK / 框架 provider:协议映射、认证、流式事件、部分重试
↓
远程或本地模型服务
常见接口不能只按“都能聊天”来替换:
| 接口 | 请求形态 | 响应读取 | 需要保留的差异 |
|---|---|---|---|
| Chat Completions | messages 消息数组 |
choices、finish_reason、usage |
工具调用、拒答、空内容与厂商扩展字段 |
| OpenAI Responses | input,可含多种输入项 |
output 项与事件;SDK 可提供文本聚合 |
完成状态、工具结果、不同类型的内容项 |
| Anthropic Messages | messages,系统说明在顶层 system |
content 块、stop_reason |
原生内容块与工具协议 |
| 其他原生协议 | 各家请求结构 | 各家响应结构 | 模态、文件、推理、异步任务等能力 |
“OpenAI 兼容”通常能减少基础文本对话的迁移工作,但不是全功能一致的承诺。换 base_url、密钥和模型名之后,还要逐项验证工具调用、结构化输出、流式用量、推理参数及错误格式。基础 SDK 用法可对照 OpenAI Python SDK。
先跑通一次完整的文本调用
下面选择 Chat Completions 说明最小过程。LLM_MODEL 必须设为目标服务实际支持的模型 ID;LLM_BASE_URL 必须与密钥所属服务匹配。密钥只由服务端读取,.env 应排除在版本控制之外;写了 .env 文件并不代表程序会自动加载它。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ["LLM_BASE_URL"],
timeout=60.0,
max_retries=2,
)
response = client.chat.completions.create(
model=os.environ["LLM_MODEL"],
messages=[{"role": "user", "content": "用一句话解释什么是 API。"}],
)
if not response.choices:
raise RuntimeError("响应没有候选结果")
choice = response.choices[0]
if choice.finish_reason != "stop":
raise RuntimeError(f"本例要求完整文本,实际结束状态:{choice.finish_reason}")
if getattr(choice.message, "refusal", None):
raise RuntimeError("模型拒绝了当前请求")
if choice.message.content is None:
raise RuntimeError("响应没有文本内容")
print(choice.message.content)
if response.usage is not None:
print(response.usage.model_dump())
这个例子有意只接受完整文本。真实 Agent 还应识别工具调用结束状态,交给执行循环处理;不能把 tool_calls 当作普通失败,也不能因为 HTTP 200 就认定任务完成。Responses 的结束状态也不能硬套 finish_reason。
2. 控制输出时,先检查模型支持什么
Temperature 改变候选 Token 的相对概率;正温度的普通缩放不会改变同一组 logits 的排序。Top P 按累计概率保留候选集合,再从集合中采样。它们调整生成分布,不直接保证事实正确、格式合法或工具安全。
| 设置 | 适用问题 | 常见误用 |
|---|---|---|
temperature |
控制表达多样性 | 认为设为 0 就能在所有服务环境中严格复现 |
top_p |
控制采样候选范围 | 把低概率候选都当成乱码,认为它能消除幻觉 |
| 输出 Token 上限 | 控制一次生成的资源边界 | 把上限当成模型必须达到的目标长度 |
| 推理强度或预算 | 在支持的模型上调整推理资源 | 将某厂商的档位和默认值套给所有模型 |
调参先使用模型推荐默认值,一次只改变一个采样因素,用同一组任务比较。不同模型可能限制或不接受采样参数;不能把一个 temperature=0.2, top_p=0.9 组合当成通用生产配置。
输出长度字段也不同:某些 Chat Completions 模型使用 max_completion_tokens,Responses 使用 max_output_tokens,其他接口可能使用 max_tokens。是否包含推理 Token、具体上限以及截断标记,要按目标模型核对。LangChain 的 OpenAI 集成也记录了相关参数转换,见集成说明。
输出被截断时,要保留“未完成”状态。对于长文,可以增加预算或拆成有边界的小任务;对于 JSON,要拒绝解析不完整对象。直接原样重试通常不会解决输出配额不足。
3. 非流式、流式与异步不是同一条分类轴
原稿把“同步”“流式”“异步 Batch”依次介绍,容易让人误以为三者互斥。实际要分别看两件事:结果怎样交付,以及客户端怎样等待。
| 维度 | 选择 | 说明 |
|---|---|---|
| 结果交付 | 非流式 / 流式 | 一次拿完整结果,或持续接收增量事件 |
| 客户端调度 | 阻塞 / async |
当前线程等待,或由事件循环调度等待 |
| 服务端任务 | 在线请求 / 后台任务 / Batch | 当前连接返回结果,或提交任务后凭 ID 查询 |
await client... 可以请求非流式结果;同步客户端也可以消费流。Batch 是服务端离线任务接口,和 Python 的 async 不是同一种能力。
流式需要管理两段连接
浏览器 ← SSE / WebSocket → 应用服务 ← 厂商事件流 → 模型服务
鉴权、限流、取消、聚合、记录状态
持续输出能改善首屏等待,并降低部分空闲读取超时的概率;它不能消除所有超时。代理仍可能缓冲内容,网关可能有连接总时长上限,推理阶段也可能长时间没有文本。停止生成可以通过取消请求或独立控制接口实现,并不必然要求 WebSocket。
以下示例消费 Chat Completions 文本流。仅在目标服务支持时启用 include_usage;最后一块可能只有用量,没有 choices。中断时用量可能拿不到,应记录“未知”,不能记成零。
pieces = []
finish_reason = None
usage = None
stream = client.chat.completions.create(
model=os.environ["LLM_MODEL"],
messages=[{"role": "user", "content": "用三百字介绍杭州。"}],
stream=True,
stream_options={"include_usage": True},
)
try:
for chunk in stream:
if chunk.usage is not None:
usage = chunk.usage
if not chunk.choices:
continue
choice = chunk.choices[0]
if choice.delta.content:
pieces.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
if choice.finish_reason is not None:
finish_reason = choice.finish_reason
finally:
stream.close()
if finish_reason != "stop":
raise RuntimeError(f"文本流未完整结束:{finish_reason}")
full_text = "".join(pieces)
这里仍是文本专用例子。工具调用的名称和参数也可能分块返回,需要按调用 ID 聚合,全部接收并通过校验后才能执行。推理摘要、文本、工具、音频等内容应保留类型,不应全部串成一段普通文字。也不能假定厂商会暴露完整内部思考过程。
Batch 保留请求与结果的对应关系
适合容忍延迟的离线任务时,可以把请求写成 JSONL,提交批次,保存 batch_id,然后查询完成状态并下载结果。结果可能不按输入顺序返回,用自己的 custom_id 关联,不用行号关联。
import json
items = [("comment-1", "物流很快,包装严实。"), ("comment-2", "等了一周还没发货。")]
with open("batch.jsonl", "w", encoding="utf-8") as file:
for item_id, text in items:
request = {
"custom_id": item_id,
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": os.environ["LLM_MODEL"],
"messages": [{"role": "user", "content": f"判断评论情感:{text}"}],
},
}
file.write(json.dumps(request, ensure_ascii=False) + "\n")
with open("batch.jsonl", "rb") as file:
uploaded = client.files.create(file=file, purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(batch.id) # 持久化此 ID;恢复任务时先查状态,避免重新提交整批
这段使用 OpenAI Batch 的调用形态,不能只改域名就假定另一家也支持。提交成功不等于所有条目成功;需要检查错误文件、过期或取消状态、每条结果及计费。价格、容量和完成窗口以官方 Batch 文档为准。
4. 超时、重试、限流共同服从一次任务的预算
连接超时限制建立连接的等待;读取超时限制下一块数据的等待;总截止时间限制整个业务请求。它们不是一个数值的三种名称。HTTPX 还区分写入与连接池等待,见超时说明。SDK 的实际传输实现会随版本变化,应在锁定版本上检查配置方法。
非流式请求的读取等待要覆盖生成时间;流式读取等待要考虑首块延迟和块间停顿。只在 for chunk in stream 内比较时间,不足以实现严格总截止:当循环正阻塞等待下一块时,检查语句根本不会运行。异步调用可以用外层取消机制限定整个消费过程:
import asyncio
from openai import AsyncOpenAI
async def read_with_deadline(messages, seconds=90):
# Python 3.11+;SDK 的网络超时与业务总截止分别配置。
async with AsyncOpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ["LLM_BASE_URL"],
timeout=30.0,
max_retries=0,
) as async_client:
async with asyncio.timeout(seconds):
stream = await async_client.chat.completions.create(
model=os.environ["LLM_MODEL"], messages=messages, stream=True,
)
try:
async for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
finally:
await stream.close()
这段只演示截止和关闭连接;业务仍要像上一例一样验证完整结束。断开本地连接也不保证服务端立即停止计算或不再计费。
先分类失败,再决定是否重试
| 失败 | 优先处理 | 需要防止的问题 |
|---|---|---|
| 连接中断、部分 5xx | 有界指数退避,加抖动 | 重试风暴、总延迟失控 |
| 429 | 区分速率限制与余额/配额,读取 Retry-After |
对不会自行恢复的错误反复重试 |
| 参数错误、无效模型、鉴权失败 | 修正配置或请求 | 重试浪费费用 |
| 截断、拒答、业务校验失败 | 各自进入专门分支 | 当成普通网络故障 |
| 已输出部分内容后中断 | 标记部分结果,明确重新生成或续接策略 | 把第二次回答直接追加到第一次尾部 |
不能把“除 429 外的全部 4xx 都不可重试”写成统一规则;例如具体 SDK 可能把 408、409 纳入重试。也不能把 SDK、框架、网关三层默认重试叠起来:每层 3 次尝试,最坏可放大到 27 次。让一个层级管理预算,其他层明确禁用或计入同一预算。
模型生成的重试与工具副作用的重试要分开。发送消息、创建订单等工具动作必须先检查幂等键或已执行记录,避免模型调用重试间接造成重复操作。恢复策略见动态重规划与长任务恢复。
限流与排队有不同计量单位
RPM、TPM、并发数可能同时约束一个账号、项目、地域或模型。配额应从当前控制台和响应头读取,不把课程中的固定数值写死。按请求速率用令牌桶,按在途数量用信号量;估计 Token 时考虑输入、预留输出与厂商实际计量规则。
多实例服务需要共享限流状态,单进程 limiter 只能约束自己。队列还要有容量、等待上限、取消和背压:无界排队只会把 429 换成长时间卡住。Batch 可能有独立配额,但“独立配额”不等于没有限制。
5. 统一接口保留能力差异,降级必须重新验收
调用层应统一应用需要的结果,而不是把所有厂商压成一个字符串:
ModelResult
content_blocks 文本、工具调用、可见推理摘要等类型化内容
finish_state complete / truncated / tool_call / refusal / error
usage 输入、输出、缓存与推理用量;缺失值为 unknown
provider_request_id 关联服务端排障
model_version 实际返回版本与配置版本
attempts / fallback 尝试次数与路由变化
请求侧则应有能力要求,例如“必须支持图像输入”“必须提供 Schema 约束”“数据必须留在指定区域”。路由先筛掉不满足硬约束的候选,再在剩余模型中比较成本、延迟和任务质量。
跨厂商备用能降低部分共同故障,但也可能改变数据处理边界、引用习惯与格式能力。切换后仍需通过同一校验;无法保持关键约束时,返回明确的不可用结果比伪造成功更合适。缓存回答也必须检查用户权限、内容版本和时效,不能任意拿历史答案兜底。
6. 框架负责复用,应用仍负责契约
框架的主要价值是组件复用、接口抽象和编排。复用文档读取器、模型 provider、向量库适配器能减少样板代码;替换组件仍要检查语义差异,例如距离函数、元数据过滤、维度和错误处理,不保证换依赖后业务完全不用改。
| 任务 | Spring AI | LangChain |
|---|---|---|
| 模型调用 | ChatModel / ChatClient |
聊天模型与 provider 集成 |
| 类型化消息 | UserMessage、AssistantMessage 等 |
HumanMessage、AIMessage 等 |
| 结构化结果 | .entity() 与转换器 |
with_structured_output() |
| 调用编排 | Advisor 链 | Runnable / LCEL,复杂状态流程可用 LangGraph |
| 生产治理 | 对接现有 Spring 监控与韧性组件 | 回调、追踪、限流与部署设施组合 |
SDK 已经够用的短链路无需为了“完整”而引框架。已有 Spring 服务通常优先评估 Spring AI;Python 数据处理和已有 LangChain 生态可以延用 LangChain;Java 项目也有 LangChain4j 等独立选择。LangChain4j 不是 LangChain 的官方 Java 移植。选择时同时检查团队栈、必要集成、状态恢复和维护成本,不把“某生态唯一选择”“所有新方法都先到某框架”当成事实。
同一动作,只保留一组并列例子
LangChain 的 provider 是负责协议适配的集成。下面明确使用 OpenAI provider;换成兼容服务时,仍要检查它是否保留你需要的扩展字段:
from langchain.chat_models import init_chat_model
from langchain.messages import SystemMessage, HumanMessage
model = init_chat_model(
model=os.environ["LLM_MODEL"],
model_provider="openai",
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ["LLM_BASE_URL"],
timeout=60,
max_retries=2,
)
messages = [
SystemMessage("你是简洁的技术助手。"),
HumanMessage("解释模型调用层的作用。"),
]
response = model.invoke(messages)
print(response.text)
print(response.usage_metadata)
full = None
for chunk in model.stream(messages):
full = chunk if full is None else full + chunk
print(chunk.text, end="", flush=True)
保留完整消息有助于保留工具调用与元数据;只拼文本后再作为历史消息使用,会丢失这些信息。框架消息本身也不是自动持久化,记忆组件需要显式接入。
Spring AI 则在项目锁定的 BOM、模型 starter 和配置下构建 ChatClient。下面假设 chatClient 已由服务配置完成:
ChatResponse response = chatClient.prompt()
.user("解释模型调用层的作用。")
.call()
.chatResponse();
// 将 Flux 返回给响应式 HTTP 层;由应用处理取消、异常和终止状态。
Flux<String> fragments = chatClient.prompt()
.user("解释模型调用层的作用。")
.stream()
.content();
需要响应元数据时,不要只取 .content()。在响应式请求路径里也不要为方便而 .block();链路的消费、取消和错误传播应由应用统一控制。框架的默认重试、限流作用域和监控开关应按版本与 provider 核查,不能假定“装了框架”就完成生产治理。
7. 记录足够的证据,才能解释一次失败
最少记录任务 ID、调用 ID、模型与版本、Prompt/Schema 版本、尝试次数、结束状态、降级路径、Token 用量、总延迟以及流式 TTFT。汇总同时看 P50、P95、P99,避免平均值掩盖长尾;用量缺失单独计数,不能污染成本统计。
请求日志默认做脱敏和访问控制,密钥不进入日志,原文是否留存由业务数据政策决定。调试可用抽样或受控存储,不必把所有用户输入永久写到公共追踪平台。
验证调用层时至少覆盖:正常文本、无权限、429、持续 5xx、首次输出很慢、中途断流、用户取消、截断、拒答、备用模型能力不足、最后用量缺失,以及多实例配额争抢。端到端任务质量与错误传播的分析继续看评估、反馈与可观测性。
来源与延伸阅读
- CodeCrush 原始笔记:05 第一次调用大模型、07 控制模型输出的关键参数、09 同步、流式与异步调用、10 构建可靠的模型调用层。
- 框架原始笔记:21 为什么需要引入开发框架、22 统一模型调用与消息处理。提示词模板细节与记忆策略在知识库对应主题中集中讲解。
- 官方接口:OpenAI Python SDK、OpenAI Batch、HTTPX 超时。
- 框架参考:LangChain 模型、LangChain OpenAI 集成、Spring AI ChatClient。