← 返回知识目录

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、首次输出很慢、中途断流、用户取消、截断、拒答、备用模型能力不足、最后用量缺失,以及多实例配额争抢。端到端任务质量与错误传播的分析继续看评估、反馈与可观测性。

来源与延伸阅读

返回 Agent 系统设计总览