大模型 API 调用工程
一次生产级 LLM 调用包含哪些阶段
调用大模型似乎只是构造请求、发送 HTTP 请求,再读取模型返回的结果。但在实际的生产环境中,一次 LLM 调用实际上是一条由业务服务、模型调用组件和模型提供商共同完成的。
一般情况下,我们说一次模型 API 请求就是指的是向模型服务发起的一次推理调用。一次完整的业务请求指的是更完整的部分,包括可能不止一次的模型调用,上下文处理,工具执行,结果处理等内容。
整体上,大概上
flowchart TD
A["用户或业务系统发起请求"] --> B["接入处理:鉴权、校验、链路标识"]
B --> C["上下文组装:系统指令、历史、业务数据"]
C --> D["调用决策:模型、参数、Token 预算"]
D --> E["通过 SDK / HTTP 发送 API 请求"]
E --> F["模型服务:排队、Prefill、Decode"]
F --> G["接收响应:文本、结构化内容或工具调用"]
G --> H{"是否需要应用执行工具?"}
H -- "是" --> I["执行工具、取得结果并加入上下文"]
I --> C
H -- "否" --> J["解析、校验并转换为业务结果"]
J --> K["返回客户端并记录调用指标"]
请求进入与参数的校验
- 请求首先进入业务后端。此时后端并不会立即把用户输入原样转发给模型,而是会做一些判断和处理。一般会完成身份鉴权、租户或用户权限校验、输入长度与参数检查,并生成
requestId或traceId,用于关联后续的检索、模型调用和工具执行日志。
构建模型输入上下文
- 通过校验后,后端需要把业务请求转换成模型能够理解的输入。大模型 API 接收的通常不只是用户输入的一句话,还可能包含:系统与开发者指令、历史消息、业务上下文、工具与输出约束。
- 这一步还需要考虑上下文窗口与 Token 预算。除了当前问题,历史消息、检索结果和工具定义也会占用输入空间;同时还必须为模型的输出预留足够的容量。通常需要对历史记录和上下文进行截取、摘要,或筛选相关性较高的资料,而不是无限追加内容。
模型选择与调用前调度
- 上下文准备完成后,系统需要决定把请求交给哪个模型,以及怎样执行,以实现动态模型调用。与此同时,调用组件会确定模型参数、最大输出长度、请求超时和成本预算等内容。
发送 API 请求与模型推理
- 后端通过 SDK 或 HTTP 客户端将请求发送到模型提供商,通常需要携带鉴权信息、模型标识、消息内容以及相应的生成参数。对于业务后端来说,这本质上是一次远程服务调用
- LLM 调用的耗时不仅有网络开销,还包括模型侧的等待、输入处理和输出生成。任务复杂情况、输入上下文的长度、模型规模以及最终生成的 Token 数量,都会影响实际延迟。
接收响应并识别模型的结束状态
- 模型开始产生输出后,可以同步返回和流式返回。而且一个模型响应往往不仅包含文本,还可能带有输出类型、结束原因、Token 用量,以及提供商返回的请求标识等信息。
- 对于这里,请求成功和业务结果完整完成是两码事。因此,后端不能只判断 HTTP 状态码,还需要识别模型输出的内容与结束状态,决定下一步应该继续执行还是交付结果。
按需执行工具并形成多轮调用
- 如果模型返回了工具调用请求,业务后端需要根据工具名称与参数,找到对应的业务实现,执行实际操作,再把执行结果提供给模型。
- 这样,一次用户请求就可能变成以下形式:模型调用 → 工具执行 → 模型再次调用 → 最终答复*。
结果校验与业务交付
- 模型返回最终内容后,业务后端需要将其转换成当前业务真正需要的结果。一般要进行格式解析与业务校验后,才能用于数据库更新、接口响应或后续任务。
调用收尾与可观测性记录
- 用户拿到答案,并不意味着后端的工作已经全部结束。生产环境还需要记录本次调用的执行情况用于观测。
- 在这里多说一嘴,可观测性的目标是让系统知道请求经历了什么、花费多少、在哪里出现问题。
总之,
- 业务后端负责:身份与权限、业务数据、上下文组装、结果校验及业务状态管理。
- 模型调用层负责:模型与参数选择、请求发送、响应适配、预算控制和调用观测。
- 模型提供商负责:模型侧请求调度、推理执行、内容生成和模型原始响应。
同步返回和流式返回
等待模型生成完毕后一次性获取完整响应,或者在模型生成过程中持续接收增量结果,分别称为同步返回和流式返回。
现代大模型几乎都使用流式返回
非流式调用中,业务后端发送请求后,需要等模型完成本次生成,才能拿到完整响应。模型服务最终返回一个完整的 JSON 对象,其中可能包含生成内容、结束原因和 Token 用量等信息。这种方式的主要优势是处理简单、结果边界明确。后端拿到的通常已经是完整内容,可以直接开始处理
同步调用要等模型生成完全部内容,再一次性返回完整结果。而当系统更关心最终结构化结果的时候,一般会使用非流式调用,因为不需要向用户实时展示生成过程,整个的输出梗完整,能省去很多额外的校验
流式输出则是边生成边返回,模型每产生一段文本或一个事件,供应商就通过长连接把增量推给调用方。而且这个模式也更符合模型输出的情况,从模型侧看,输出是逐步生成的,那么我跟用户交互的时候,为什么也不逐段的生成呢?
因此,流失返回能减低
TTFT(Time to First Token),即从发起模型请求到收到第一个输出
Token 的时间,不用等整段回答完成,大幅的增强用户的体验
sequenceDiagram
participant U as 客户端
participant B as 业务后端
participant M as 模型 API
U->>B: 发送问题
B->>M: 发起流式请求 stream=true
M-->>B: 增量事件 1
B-->>U: 转发增量内容
M-->>B: 增量事件 2
B-->>U: 追加显示
M-->>B: 后续增量事件
B-->>U: 持续追加
M-->>B: 完成事件 / 最终状态
B-->>U: 发送结束标记
流式输出的一段通常由流式协议来控制,而模型的逐个输出通常是逐个 Token 进行的
流式返回还需要处理哪些问题
- 明确结束状态。 接收流式内容时,连接建立成功或 HTTP
状态为
200,只能说明响应已经开始,应当识别提供商定义的完成事件、失败事件或中断状态。 - 处理客户端取消。用户点击“停止生成”或关闭页面时,后端应尽可能把取消信号向上游传播,结束不再需要的模型请求
- 检查代理和网关的缓冲。 即使模型服务持续输出,如果 Nginx 或其他中间层进行了相应缓冲,会把内容缓存到一定大小才转发。因此,部署时要关注响应缓冲、空闲超时和连接保持策略。
- 区分中间结果和最终结果。 流式生成的文本或 JSON 片段可能尚未闭合,尤其是结构化输出和工具调用参数。通常需要等对应的完成事件或完整参数组装完成后,再进行校验与业务处理。
SSE、WebSocket 和 HTTP chunked 这三种流式协议怎么选
讨论 LLM 流式传输时,经常会同时提到 SSE、WebSocket 和 HTTP chunked,但它们严格来说并不是三个处于同一层级的协议。
- SSE(Server-Sent Events):浏览器原生
EventSource,基于 HTTP 的服务端单向事件推送机制 - WebSocket:建立持久连接后的双向通信协议,客户端与服务端都可以主动发送消息。
- HTTP chunked:HTTP/1.1 的分块传输编码,解决响应体长度未知时如何逐块传输的问题;它本身不定义业务语义。
一般情况下,LLM 的流式返回中,SSE 是最常见的选择,因为符合 LLM 的业务情况,尤其适合“用户提交一次问题,服务端持续返回生成内容”的场景,因为在一次 LLM 请求中,大多数情况下是服务端向你发送事件。
而且 SSE
适合文本流,它的实现和使用还很简单,浏览器端几行代码就能接收事件,服务端按
data: 一段段写出去即可。对于普通的 AI
聊天、文本续写、内容生成,SSE
通常是默认优先考虑的方案。
客户端发起一次 HTTP 请求,服务端在同一个响应中持续推送事件。SSE
通常通过 HTTP 响应承载,媒体类型是
text/event-stream,消息格式是一份 UTF-8
文本事件流。每个事件由若干行字段组成,事件使用 event: 和
data:
等字段描述,两个换行符用于分隔事件。例如,业务后端可以定义如下事件格式:
1 | event: delta |
Java 侧常见做法是
Content-Type: text/event-stream,再用响应式流往外推。Spring 提供了ServerSentEvent<T>
1
2
3
4
5
6
7
8
9
10
public Flux<ServerSentEvent<String>> stream() {
return Flux.interval(Duration.ofMillis(500))
.map(seq -> ServerSentEvent.<String>builder()
.id(Long.toString(seq))
.event("token")
.data("片段-" + seq)
.retry(Duration.ofSeconds(3))
.build());
}
WebSocket 适合更实时、更复杂的交互。比如语音 Agent 里,客户端要不断上传音频,服务端要不断返回 ASR、LLM、TTS 状态,还要支持用户中途打断。这种复杂场景用 WebSocket 更自然。
它的优势是建立连接后不必为每条消息重新完成一次 HTTP 请求,也能更自然地处理双向消息;但相应地,需要管理连接生命周期、心跳、状态和异常关闭等问题。
HTTP chunked 是底层分块机制,作为流式 HTTP
响应的底层传输机制,完全没有做任何的业务事件协议,需要你自行实现;Transfer-Encoding: chunked
解决的是 HTTP/1.1
如何传输未知长度的响应体。在这种模式下,服务端可以持续写入数据块,而不必提前计算完整响应的
Content-Length。
一个 chunk 可能只是某个 SSE 事件的一部分,也可能包含多个 SSE 事件;应用如果选择自定义 HTTP 流式格式,仍然需要设计明确的消息分隔、完成标记与错误事件。
错误处理、超时、重试和幂等
这一部分内容都是大模型的高可用的一个方向,就是针对于服务端的高可用方向
大模型 API 仍然是远程服务调用,因此网络中断、请求超时、服务端异常、资源限额等问题都会出现。但它比普通接口多了几项需要特别注意的事情:请求是连续且昂贵的;生成过程可能持续很久;而且一次业务请求可能包含多次模型调用和具有副作用的工具操作;输出是不确定的;请求超时并不代表模型没有执行
很明显,对于大模型的重试更加危险,一次业务请求可能涉及多轮模型调用和工具执行,盲目重试可能产生额外的推理费用,甚至重复执行真实业务操作。因此,这一部分实际上需要解决三个问题:如何判断错误、哪些错误可以重试,以及重试后如何保证业务结果不会重复产生。
我们先来了解一下,哪些错误能重试,哪些不能重试,那么思路还是一样的,如果重试是有用的,那么它就有必要,如果重试就算再多次也没作用,那么就不应该重试。如果你是网络断了,供应商有点小问题5xx但不是过载,这种的就可以进行重试。重试是只针对有可能自行恢复的错误
一个比较合理的判断过程如下:
flowchart TD
A["一次 LLM 调用失败"] --> B{"是否为可恢复的故障?"}
B -- 否 --> C["终止并返回明确错误"]
B -- 是 --> D{"是否已输出部分结果或执行过副作用?"}
D -- 是 --> E["核对执行状态、已产生的副作用和部分输出"]
E --> E2{"是否可以安全地重新执行?"}
E2 -- 否 --> H["停止重试,保留失败或待恢复状态"]
E2 -- 是 --> F["检查剩余时间和重试次数"]
D -- 否 --> F
F --> G{"仍有重试预算?"}
G -- 否 --> H
G -- 是 --> I["等待退避时间,再次请求"]
I --> J["返回结果或继续按策略处理错误"]
具体的重试的内容,例如重试间隔,这倒是和普通的业务大差不差,通常使用指数退避与随机抖动。例如,第一次失败后等待约 0.5 秒,第二次约 1 秒,第三次约 2 秒,并设置最大等待时间。随机抖动是为了避免大量客户端同时失败后,又在同一个时间点一起重试,把原本已经繁忙的模型服务压得更重。
如果服务端提供了
Retry-After,通常应优先遵守它指示的最低等待时间;避免多重重试导致重试爆炸
对于错误处理就需要理解,失败发生在哪一层,不能把所有异常统一捕获后都执行一次重试。一般需要根据错误发生的位置和原因,判断它是暂时性故障,还是必须修改请求或业务状态才能解决的问题。
另外,对于流式响应,HTTP 200
只代表响应已经成功开始。后续仍然可能出现模型错误事件或连接中断,所以HTTP
请求成功与模型生成成功,需要分别判断。
超时可能没有收到结果,不等于请求没有成功
假设后端向模型服务发送请求,设置了 30 秒超时。模型实际上在第 31 秒完成,但后端在第 30 秒已经放弃等待,那么对后端来说,请求是超时的;对模型服务来说,请求却可能已经执行甚至完成,产生了 Token 费用。
从调用方视角,可以将情况分成三类:
- 请求尚未发送成功:例如连接建立前就失败,通常不存在已经执行该请求的风险。
- 请求已经发出,但没有收到完整响应:无法仅凭客户端超时判断服务端是否执行完毕,属于结果未知。
- 已经收到部分流式输出后中断:可以确认请求至少开始生成,但不能把已收到的片段视为完整结果。
因此,生产环境通常要分别配置连接超时、读取或流空闲超时,以及整个业务调用的总截止时间。前两者控制单次通信,后者则决定整个业务最大能等待多久,包括可能发生的重试。重试不能无限延长一次用户请求的生命周期。
但是一般情况下,关于大模型的超时,会设计的很保守。如果很长时间,模型没有任何相应,推理没有任何新的内容,网络长时间无法与大模型联通,这种情况下会超时失败,而例如调用的工具没有给出任何处理这种情况,通常会做显式的处理,而不会直接超时放弃。
只要有重试,就必须讨论幂等。
幂等就是防止一次业务操作被执行多次,在大模型里也一样同一个逻辑操作被重复提交,最终产生的业务效果与只执行一次相同。
例如,Agent 调用 createOrder
创建订单。工具已经成功把订单写进数据库,但网络恰好中断,Agent
没有收到成功响应。如果恢复时直接重新执行
createOrder,就可能创建两张订单。
大模型中幂等分两个层面:
- 模型调用的重复执行:同一个 Prompt 再请求一次模型,不保证得到完全一样的文本;也可能再次消耗 Token 和产生费用。除非模型服务明确提供相应的去重能力,否则不能假设传入相同参数就天然幂等。
- 业务工具的重复执行:例如创建订单、扣款、发送消息、修改数据库。这里需要应用自己保证同一业务操作不会产生重复副作用。
没错大模型的幂等我们也是用幂等键来做,用于标识同一次逻辑业务操作,然后就是非常公式的使用数据库唯一约束配合事务,实现幂等键的原子占用,并持久化执行状态。
大模型本身的幂等并不是结果一致,只追求的是不重复花钱说白了,那么,大模型本身的调用幂等,就可以使用编排层生成的一个稳定的
run_id。这个 run_id
是后续所有模型调用和工具调用的根标识,然后组合其他稳定的 id
形成大模型调用的幂等键。在模型调用层中, 在每次准备调用模型前,再以
run_id + step_name
等的具体步骤的键,去查本地存储,若已有该步骤的模型响应就直接使用。不仅能够做幂等,还能保证中断恢复
但是呢,主要是涉及的问题就是工具调用,对于涉及外部内容的操作,单靠本地记录仍然不太能保证完整的一致性,这时需要查询外部执行结果。一般情况下,我们会对大模型调用的工具本身做好幂等化,确保大模型调用工具的时候不会有幂等的负担。
如果工具调用需要额外的幂等呢,这时候用
run_id + tool_call_id 做副作用去重。模型返回
tool_call 时,tool_call_id
是额外传入的一个稳定值。你以 run_id + tool_call_id
作为幂等键,先查本地执行记录,若已完成,直接返回存储结果,不调用工具。若未完成,调用工具,并将该幂等键作为参数传给工具,由工具在调用外部系统时使用
限流、排队和降级
收到供应商 429 才开始限流,说明系统缺少自己的容量管理。导致给模型提供商整不会了。对于生产级 LLM 应用来说,我们不能只考虑请求能不能发出去,还要考虑当前还有多少模型额度、后端能同时承担多少推理请求,以及资源不足时应该优先保障哪些业务。
限流负责控制进入模型调用链路的请求量;降级则是在原有调用方案不可用、太慢或成本过高时,主动选择一个能力有所取舍、但仍然可接受的服务方案。它们的共同目标是让系统在容量有限或依赖异常时,仍然保持可控的服务质量。
传统接口经常按 QPS(每秒请求数)或者 RPM(每分钟请求数)限流,因为多数接口的资源开销相对稳定。但 LLM 请求之间的成本差异非常大,一次请求消耗的推理资源完全不同。
因此,模型供应商通常会组合多种额度指标:
| 指标 | 含义 | 主要限制什么 |
|---|---|---|
| RPM(Requests Per Minute) | 每分钟允许的请求数 | 请求频率 |
| TPM(Tokens Per Minute) | 每分钟允许消耗的 Token 数 | Token 吞吐量 |
| ITPM / OTPM | 分别限制输入、输出 Token 的速率 | 需要分别管理输入和输出负载的模型服务 |
| 并发数(Concurrency) | 同一时间正在执行的请求数量 | 后端连接、内存、执行槽位等资源 |
| 使用量 / 成本预算 | 日、月使用额度或费用上限 | 长周期资源消耗和成本 |
举个例子,假设某个模型的额度为 60 RPM 和
120,000 TPM。如果每次请求平均消耗
8,000 Token,即使一分钟只发出 15
次请求,也可能已经用完这一分钟的 Token 预算;
而且,并发数和 RPM 并不是一回事。即使一分钟请求数没有超标,如果每个请求都执行得很久,大量流式连接也可能同时占据后端的连接与内存资源。反过来,一个瞬间涌入的大量请求,也可能触发供应商的短时间突发限制,即使按整分钟统计还没有超额。所以说,大模型的限流一般会从很多个角度综合设计,来保证服务的可靠性。
因此,通常会采用分层限流
- 用户 / 租户层:限制单个用户或租户的调用频率、Token 用量与预算,避免少数用户占满公共资源。
- 业务功能层:为聊天、文档分析、后台批处理、Agent 执行等设置不同配额与优先级。交互式请求一般更重视响应延迟,批处理任务则可以适当等待。
- 模型 / 供应商层:根据具体模型、项目、账号或共享配额池,统一控制向上游发送的请求量和 Token 消耗。
- 实例资源层:约束当前 Java 服务可以同时持有的上游调用数量,保护线程、连接池、内存和流式响应资源。
另外,多个 Spring Boot 实例共同使用同一个 API 配额时,每个实例只是自己在本地做单独的限流是不够的。假设上游总配额是 100 RPM,三个实例都认为自己可以发 100 RPM,那么整体流量就可能达到 300 RPM。共享配额需要通过 Redis 等集中式机制协调,或在统一的模型网关中管理,这个涉及到的内容更加复杂
对于大模型,最常见的限流算法还是令牌桶,系统按照一定速率向桶中补充令牌,请求进入时先取得令牌;没有足够令牌,就等待或拒绝。它可以在控制长期平均速率的同时,允许一定范围内的短时突发。
Token 限流有一个实际问题,请求发送前,我们通常不知道最终会输出多少 Token。所以工程上会先根据 Prompt 和输出上限做估算,预占一部分预算,请求完成后,再依据供应商返回的实际用量进行调整。
当请求暂时超过可用容量时,系统并不一定要直接失败,可以按业务情况选择短暂排队、延迟执行或者快速拒绝。
排队必须是有界的:限制最大队列长度、最大等待时间,并支持任务取消和超时淘汰等等管理内容。否则请求虽然没有立刻触发上游
429,却在本地越积越多,最后把系统内存和连接资源耗尽。对于响应式流,还要注意下游消费速度和客户端断开连接的问题。
这里也可以引入舱壁隔离(Bulkhead),为不同模型或业务设置独立的并发槽位。这样,长时间运行的 Agent 任务不会把普通聊天的所有执行资源都占满。限流控制进入速率,舱壁控制同时执行的数量,队列则吸收有限的流量波动,三者通常要配合使用。
降级主要是当原来的模型调用方案不可用时,主动调整服务方案,优先保住核心业务能力
切换模型或供应商
哪个可用选择哪个,切换到能够完成同类任务的备用模型
降低单次请求的资源消耗
说白了,降智,减少检索片段,工具调用,缩短输出,减少 ReAct 循环次数等等
将非实时任务转为异步处理
对于长文档分析、批量内容生成等任务,如果当前额度不足,可以先接受任务,再在容量恢复后执行,前提是用户能够感知上述流程吗,否则容易白干
提供明确的兜底
总的来说,LLM 限流不是简单地加一个 QPS 拦截器,而是把请求次数、Token 吞吐、并发资源和费用预算统一纳入容量管理;降级也不是出错后随便换个模型,而是在明确能力约束的前提下,有计划地牺牲一部分性能、成本或功能,以保证核心服务仍然可用。
Java 后端怎么落地 LLM 调用
如果使用 Spring Boot,可以把这些能力放在统一的 LLM 调用组件或模型网关中,而不是散落在每一个业务 Service 中。
从 Java 后端的角度来说,调用模型本质上还是一次 RPC / HTTP 远程服务调用。只不过相比调用传统的业务微服务,LLM 的请求内容更复杂,耗时更不稳定,输出也具有一定的不确定性。因此,我们不仅需要完成 HTTP 通信,还需要通过合理的软件架构,将模型访问、业务上下文和调用治理分离。
在 Java 生态中,主要有三种常见方案。
| 方案 | 核心特点 | 适用场景 |
|---|---|---|
| 原生 SDK / HTTP Client | 直接对接供应商 API,拥有较高的控制自由度 | 自建模型网关、特殊协议、需要精确控制请求和响应 |
| Spring AI | 与 Spring 生态集成,提供统一的模型接口、ChatClient 和 Advisor 等抽象 | Spring Boot AI 应用、RAG、模型集成 |
| LangChain4j | 面向 Java 的 LLM 应用框架,提供 AI Services、Tools、Memory、RAG 等能力 | AI 应用开发、Agent、复杂工具调用与业务编排 |
统一模型调用层应该如何设计?比较合理的做法是,在业务 Service 与具体模型 SDK 之间建立一层统一的模型调用抽象,那么具体架构就是这样的
flowchart TD
A["Controller / API"] --> B["业务 Application Service"]
B --> C["统一 LLM Client / Gateway"]
C --> D["模型路由与参数配置"]
D --> E["调用治理:配额、并发、超时、重试"]
E --> F["Provider Adapter"]
F --> G["OpenAI SDK"]
F --> H["Anthropic SDK"]
F --> I["其他兼容模型 API"]
G --> J["统一响应转换"]
H --> J
I --> J
J --> K["文本 / 结构化结果 / 流式事件"]
K --> B
我们可以在 Java 中定义一组与具体模型供应商无关的数据结构:
1 | public record LlmRequest( |
然后定义统一调用接口
1 | public interface LlmClient { |
这样,业务层只依赖
LlmClient,而不需要关心底层到底使用哪个
SDK。实际的供应商适配器负责将统一请求转换成供应商要求的格式,再把原始响应转换成统一的业务模型。
最后提一下会话管理与业务事务应该如何处理,首先,会话状态不应该完全依赖模型框架的内存对象,这种内容一般持久化到数据库,而且尤其是对于需要长期保存和涉及到跨会话使用的内容。
其次,不要在长时间运行的数据库事务中写等待模型生成的这种内容。例如一个 Agent 需要先读取数据库中的任务信息,再调用 LLM 分析,最后将执行结果写回数据库。这是很常见的内容,但是很容易设计出问题来,更合理的方式是,拆分,这样可以避免模型长时间推理期间持续占有数据库连接、事务锁等资源。
总体而言,可以按照职责把 Java 后端中的 LLM 能力划分为三层:
- 业务 Application Service:处理用户请求、业务规则、会话上下文和任务状态。
- 统一模型调用层:负责模型路由、参数规范化、配额控制、调用追踪和统一响应。
- Provider Adapter:负责具体供应商的 SDK / HTTP 通信、响应解析以及模型特有功能。
大模型结构化输出
为什么需要结构化输出
大模型天然擅长生成自然语言,但是在实际的工程应用中,我们并不总是希望它返回一段普通文本。输出 JSON 是有必要的,如果我们希望根据模型的输出直接调用业务接口、操作数据库或者执行后续工作流,就必须将这些自然语言转换为明确的数据结构。
而通常情况下,依靠这种”请返回 JSON”的提示词模式是不可靠的,先看一个非常常见的 Prompt:
1 | 请判断下面用户反馈属于哪类工单,返回 JSON。 |
模型可能返回:
1 | { |
这份结果能否落库,还取决于后端的字段约定,我们都知道,JSON 是需要严格的格式解析和字段解析的。自然语言 Prompt 很难把这些边界稳定地传递到每一次调用,格式、字段、类型、追加文本和边界条件都可能失守。因此,会带来格式飘逸,字段缺失,类型错误,额外文本,边界崩溃等问题。
这就是结构化输出(Structured Output)要解决的核心问题:让模型按照预先定义的数据结构生成结果,使自然语言推理能力能够可靠地接入传统软件系统。
怎样把 JSON 从格式要求变成契约就十分重要
JSON Mode、JSON Schema 和 Structured Outputs 分别负责输出模式、结构定义和生成约束
- JSON Mode 是一种输出模式,靠提示词等约束模型返回合法 JSON。
- JSON Schema 是一种结构描述规范,用来定义 JSON 应该包含哪些字段、字段类型是什么、哪些必填、枚举值有哪些、是否允许额外字段。
- Structured Outputs 是模型供应商提供的结构化生成能力,它接收 JSON Schema 或类似 Schema,让模型在生成阶段尽量或严格贴合这份结构。
之后,结构化输出主要解决的是输出格式、字段组织和类型约束的问题,在此之上,语义检查与业务校验依旧是必要的。
对于 AI Agent、信息抽取、自动化工作流以及需要调用真实业务接口的应用,结构化输出通常是连接 LLM 推理能力与传统后端业务逻辑的重要基础。
基于 JSON Schema 的约束生成
JSON Schema 是一种描述 JSON 文档结构的规范。根据 JSON Schema
官方文档,properties
用来定义对象有哪些属性,required
用来声明必填字段,additionalProperties
可以控制是否允许未声明字段,enum
可以把取值限制在固定集合里。
一个工单分类 Schema 可以这样写:
1 | { |
这样,Schema 把后端可接受的数据形状写清了。调用支持结构化输出的 API 时,需要把它随请求传入,让大模型阅读这个规范契约,然后服务端也要用同一份规则或等价校验器检查模型输出
所以说,Structured Outputs 能生效且效果更稳定的原因就是,它前移了必要的约束,但是同时,Structured Outputs 通常指供应商提供的结构化输出能力。它会把 JSON Schema 或类似 Schema 传入模型调用,在生成阶段约束输出结构。
结构化输出在工程中有两类常见用途:
- 响应结构化输出:模型的最终回答就是一份符合 Schema 的 JSON,比如工单分类、信息抽取、情感打分。后续拿到了可以直接反序列化消费,一般是工作流中的一步。
- 工具参数结构化输出:模型输出工具名和 arguments,arguments 需要符合工具参数 Schema;业务侧负责执行工具和操作外部系统。
后面要讲的 Function Calling,就属于第二类
Function Calling 到底调用了什么
模型生成的是调用意图
Function Calling 这个名字很容易误导新人。很多人以为“模型调用函数”,好像模型真的执行了你的 Java 方法。但是实际上,模型是只是根据用户问题和工具描述生成结构化调用意图。一般是 Agent 的环境,也就是 Harness 来在受管理的环境中执行这个工具。
大模型本身并不会真正执行函数或者调用外部 API,它只是根据用户需求和可用工具的定义,生成一个结构化的工具调用请求。
例如,我们开发了一个 AI 项目管理助手,用户输入:
帮我查询一下项目 A 当前有哪些未完成的任务。
假设 Java 后端已经向模型注册了一个工具,当模型收到用户请求以及可用工具的描述以后,它可以判断当前任务需要查询业务系统中的真实数据,而不是依靠自己的知识直接生成答案。于是,模型可能返回类似下面的结构化内容:
1 | { |
其中:
name:模型希望调用的工具名称。arguments:模型根据用户需求生成的调用参数。id:本次工具调用的标识,用于将工具执行结果与对应的调用请求关联起来。
而这段 JSON
就是模型要表达的调用意图。模型只是告诉后端:“我认为应该使用
queryTasks,并传入这些参数。
至于这个工具的情况,是否真实存在、调用参数是否合法、当前用户有没有权限,以及工具最终能否执行成功等等内容,都需要由应用程序负责处理,一般是 Agent 的运行环境 Harness
Function Calling 可以理解为一种由模型参与决策的工具调用机制:
Function Calling 不是模型获得了执行代码的能力
模型不会直接连接 MySQL,也不会自己向业务系统发送 HTTP 请求。真正访问数据库、调用接口或者修改文件的,仍然是 Java 后端中的工具实现。
所以说,工具调用的权限边界仍然由应用程序控制,模型生成的参数也应该被视为需要校验的输入,而不是可以直接信任的业务指令。
模型生成工具调用请求本身也需要校验
另外,模型并不一定每次都需要调用工具。对于能够直接回答的问题,它可以生成普通文本;对于需要访问外部数据或执行操作的任务,则可以选择一个或多个可用工具。
这也是 Function Calling 和普通结构化输出的重要区别:
- 普通结构化输出:让模型按照指定的数据结构生成结果,供业务系统解析和使用。
- Function Calling:让模型按照工具定义生成调用请求,由应用程序执行工具,并可能将执行结果重新交给模型继续处理。
实际上,Function Calling 可以看作结构化输出在工具调用场景下的一种特殊应用。它不仅要求模型生成符合工具参数约束的数据,还赋予了这些数据明确的调用语义。
总的来说,模型负责理解任务并生成调用意图,应用程序负责验证和执行真实操作。这种职责分离,使得 LLM 能够参与传统后端业务流程,同时让工具执行、权限控制和业务状态管理仍然处于应用程序的控制之下。
工具调用是如何实现的
前面已经知道,Function Calling 的本质是模型根据用户需求生成工具调用意图,而真正的工具执行由应用程序负责。
那么,应用程序是如何将模型生成的调用意图,转换成一次真实的 Java 方法调用,并且让模型获得执行结果的?
实际上,这个过程可以分为两个部分:
- 模型侧:根据开发者提供的工具定义,决定是否调用工具,以及使用什么参数。
- 应用侧:管理工具注册、参数解析、工具分发、真实执行和结果回传,并根据模型的后续响应决定是否继续调用。
整个执行流程如下:
sequenceDiagram
participant U as 用户
participant A as Java 应用 / Agent
participant M as LLM API
participant T as Tool Executor
participant B as 业务服务
U->>A: 提交任务
A->>M: 发送消息与可用工具定义
M-->>A: 返回 tool_calls(名称、参数、ID)
A->>A: 参数解析、权限与业务校验
A->>T: 根据工具名称分发执行
T->>B: 调用 Java 方法 / HTTP API
B-->>T: 返回业务执行结果
T-->>A: 返回工具执行结果
A->>M: 追加工具调用结果并继续推理
M-->>A: 最终回答 / 新的工具调用
A-->>U: 返回最终结果
这里实际上包含了一套相对标准的工具执行机制。
工具注册与描述生成
首先,应用程序需要将允许模型调用的工具注册到模型调用组件中。
例如,在 LangChain4j 中,可以通过
@Tool声明 Java 方法,也可以使用底层的ToolSpecification手动描述工具。框架会将工具名称、功能描述、参数类型等信息转换为模型 API 能够识别的工具定义,并在请求时传给模型。
这里需要注意,发送给模型的是工具的描述信息,而不是方法本身,更不是把代码交给模型执行。
接收工具调用并分发执行
模型返回工具调用请求后,应用程序需要解析其中的工具名称和参数。
例如,模型希望调用
queryTasks,并提供项目 ID 和任务状态。应用程序需要通过工具注册表找到对应的
Tool Executor,然后把模型生成的 JSON 参数转换成真实的方法参数。然后,会有一个内容,作为连接模型调用请求与真实业务执行能力的适配层。并且它还会在执行前需要校验工具是否允许当前用户调用,以及参数是否满足基本约束,不能因为模型选择了某个工具,就默认该操作获得了授权。将工具执行结果返回给模型
工具执行完成以后,通常还需要将返回值序列化成模型能够理解的内容,再发送给 LLM。
例如,
queryTasks查询得到两条未完成任务,应用程序会将结果转换为工具响应,并与原先的工具调用关联。通常需要保留工具调用 ID,使模型服务能够知道这个结果对应哪一次工具调用。
如果工具执行失败,也应该由应用程序按照预先定义的策略处理异常。对于允许模型自行恢复的错误,可以向模型返回明确、经过处理的错误结果,让它调整参数或选择其他工具;对于权限违规、不可恢复的故障,则可以直接终止本次执行。
在实际的 Agent 系统中,一次模型调用往往是多轮工具调用,这个工具不一定就调用一次,工具调用通常存在一个循环
每一轮模型都会根据当前上下文、已经执行的工具结果,以及剩余的可用能力,决定下一步操作。
flowchart TD
A["调用 LLM"] --> B{"模型返回什么?"}
B -- "最终回答" --> C["结束并返回结果"]
B -- "工具调用请求" --> D["解析、校验和分发工具"]
D --> E["执行工具并获取结果"]
E --> F["追加工具结果到上下文"]
F --> G{"是否允许继续执行?"}
G -- "是" --> A
G -- "否" --> H["终止并返回执行状态"]
Tools 注册与调用遵循什么标准格式
Function Calling 的工具执行过程,是由模型生成调用请求,再交给应用程序执行。
那么这里还有一个问题:我们是如何告诉模型有哪些工具可以使用的?模型又是按照什么格式生成工具调用请求的?
实际上,目前主流大模型 API 都有类似的工具调用协议,通常使用 JSON 描述工具,并使用 JSON Schema 定义工具的输入参数。
一般来说,一套完整的 Tool Calling 协议需要解决三个问题:
- Tool Definition(工具定义):告诉模型有哪些工具、分别能做什么、需要什么参数。
- Tool Call(工具调用请求):模型按照约定的结构,返回希望执行的工具及其参数。
- Tool Result(工具执行结果):应用程序执行工具后,按照协议将结果返回给模型。
对于工具注册格式,我们先以 OpenAI 的 Chat Completions API 为例
假设我们的 Java 后端提供了一个 queryTasks
工具,负责查询指定项目下的任务。那么,在请求模型时,可以通过
tools 字段提供工具定义:
1 | { |
这里展示的是请求中的 tools
部分,实际请求还需要包含模型名称、用户消息等信息。
这份定义中几个关键字段的作用如下:
| 字段 | 含义 |
|---|---|
type |
工具类型,这里使用 function |
name |
工具名称,模型通过它指定需要调用哪个工具 |
description |
工具功能描述,帮助模型理解什么时候应该使用该工具 |
parameters |
工具的参数定义,通常采用 JSON Schema |
properties |
定义每个参数的名称、数据类型及描述 |
required |
指定必须提供的参数 |
enum |
限制参数只能从给定值中选择 |
additionalProperties |
控制是否允许出现未定义的额外字段 |
strict |
OpenAI 提供的严格模式配置,要求模型生成符合受支持 Schema 约束的参数 |
其中,最核心的是 name、description 和
parameters。工具名称用于定位工具,描述信息帮助模型选择工具,JSON
Schema 用于约束工具调用参数。
对于工具调用请求的格式
当模型决定调用工具时,通常不会返回普通的自然语言回答,而是返回结构化的工具调用信息。对于 OpenAI Chat Completions,典型的模型响应包含:
1 | { |
首先,tool_calls
是一个数组,意味着模型可能一次提出多个工具调用请求,而不只是一个。其次,arguments
在这一协议中是一个包含 JSON 内容的字符串,应用程序通常需要先将其解析为
JSON 对象,再转换成实际方法参数。最后,id
是本次工具调用的关联标识,后续返回工具执行结果时,需要通过这个标识建立对应关系。
对于工具结果的回传
1 | { |
其中:
role: "tool":说明这条消息来自工具执行结果。tool_call_id:关联模型之前提出的工具调用请求。content:工具执行返回的数据,这里将 JSON 数据序列化为字符串。
将原先的 Assistant 工具调用消息和相应的 Tool Result 一起保留在对话历史中,模型就能根据实际查询结果继续回答用户。
此外,除了工具定义以外,实际 API
通常还提供一些工具选择和调用控制能力。例如,OpenAI 的
tool_choice 可以控制模型是否允许使用工具
总的来说,目前 Function Calling 没有一套所有供应商完全统一的 API 消息格式,但是已经形成了以工具描述、JSON Schema 参数约束、结构化调用请求和工具结果回传为核心的通用设计模式。
Function Calling、MCP Tool、HTTP API、Agent Skill 是什么关系
它们解决不同问题,而且层级也不一样,因此,现实使用中经常组合使用。
| 能力 | 定位 | 解决的问题 | 谁来执行 |
|---|---|---|---|
| JSON Mode | 输出格式开关 | 让模型输出合法 JSON | 模型侧生成 |
| JSON Schema | 结构描述规范 | 定义字段、类型、枚举、必填等契约 | 本身不参与生成,只描述结构 |
| Structured Outputs | 模型 API 结构化生成能力 | 把 Schema 接入生成,让输出贴合结构 | 模型侧生成 + 服务端校验 |
| Function Calling / Tool Calling | 模型到工具的调用意图生成机制 | 自然语言转工具名和参数 | 通常由业务侧或供应商执行 |
| MCP | 工具和上下文接入协议 | 标准化工具发现、调用、资源访问 | MCP Client / Server 协作 |
| 普通 HTTP API | 业务服务接口 | 确定性业务读写 | 后端服务 |
| Agent Skill | 可复用任务说明和执行 SOP | 复杂任务的流程编排和上下文注入 | Agent 按说明执行 |
那么 Function Calling 到 HTTP API 的调用,两者之间通常需要一个工具执行层做映射
1 | 模型工具调用 query_order → 服务端校验参数 → 调用 GET /api/orders/{orderId} |
所以,Function Calling 可以包一层 HTTP API,但 HTTP API 本身不是 Function Calling。
而 Function Calling 是模型供应商侧的工具调用机制,各家的请求和响应格式会有差异。
MCP Tool 是 MCP 协议里的工具能力。根据 MCP 官方规范,MCP 允许 Server 暴露可由语言模型调用的工具,工具包含名称和描述其 Schema 的元数据。
Function Calling 负责让模型表达“调用哪个工具、参数是什么”;MCP 负责 Client 与 Server 之间的工具发现、调用和结果返回。
一个支持 MCP 的 Agent Runtime,可以先通过 MCP
发现工具,再把这些工具定义转换成某个模型供应商的 Function Calling
格式传给模型。模型选择工具后,Runtime 再把调用转成 MCP 的
tools/call 请求。
Skill 记录任务需要的上下文、执行步骤和处理规则,可以理解为一份可复用的“任务说明书”。Skill 一般是约束 Agent 对固定任务的一个流程说明。
结构化输出如何在实践中实现
工程中落地结构化输出
落地结构化输出,主要是
- 怎样让模型稳定生成符合业务要求的数据,并正确转换成 Java 对象?
- 当模型的结构化结果涉及真实业务操作时,如何确保这些操作是合法、安全且可控的?
首先,需要根据业务场景选择合适的结构化输出方案。
实际工程中,优先考虑模型供应商原生支持的 JSON Schema 约束生成。如果模型或 API 不支持,再使用 JSON Mode 配合 Prompt 进行格式约束,自己定义 JSON Schema。而且对于 Java 开发者来说,也不一定需要自己手动编写完整的 JSON Schema。LangChain4j、Spring AI 等框架已经能够根据 Java 类型或相关定义,辅助生成结构化输出约束。
例如,我们仍然使用前面介绍的工单分类业务。
用户输入:
我付款成功了,但是订单一直显示待支付。
我们希望模型生成分类结果,并交给工单系统进一步处理。
首先定义业务需要的数据结构:
1 | public enum TicketCategory { |
接着,使用 LangChain4j 的 AI Service 定义结构化输出接口:
1 | interface TicketClassifier { |
然后配置支持 JSON Schema 约束生成的模型:
1 | ChatModel model = OpenAiChatModel.builder() |
在这个例子中,LangChain4j 会根据返回类型生成相应的 JSON Schema,将它作为模型调用的结构化输出约束,并在收到响应后转换为 Java 对象。因此,业务代码不需要手动从自然语言中提取字段,也不需要自己拼接 JSON。
但是,只有模型支持该能力、框架正确启用对应配置、返回类型得到支持时,才会真正采用 Schema 约束生成。否则,部分框架可能退回到 Prompt 引导与结果解析的实现方式。
然后,模型输出可以被成功反序列化,只代表它能够转换成 Java 对象,还需要进行业务校验等内容。
总的来说,结构化输出应该被设计成一个明确的数据转换与校验环节,而不是让模型生成 JSON 后就直接进入数据库操作。
保证工具调用的安全
工具权限与最小权限原则
模型能够看到或者选择某个工具,不代表当前用户有权限调用它。
例如,普通项目成员可以查询版本信息,但是只有具备发布权限的成员才能执行发布操作。
因此,工具执行前必须根据真实用户身份、租户、角色和资源权限进行校验。
而且,不应该让模型决定当前用户的身份。例如
tenantId、operatorId
等可信身份信息,应该从服务端认证上下文获取。对于高权限操作,还可以根据当前任务动态控制工具可见范围,避免向模型暴露完全不需要的危险工具。
参数校验与业务规则验证
即使工具名称和参数都符合 JSON Schema,也不能直接执行。
例如调用 deleteVersion 时,需要检查:
- 当前用户是否具备目标项目的操作权限。
- 指定项目和版本是否真实存在。
- 版本是否属于当前项目。
- 当前版本状态是否允许删除。
- 是否存在其他项目对该版本的引用。
这些规则都应该放在实际业务 Service 或领域层中实现。
换句话说,Tool Executor 可以负责工具适配和参数校验,但真正的业务不变量仍然应该由业务系统保证。
高风险操作需要额外的执行控制
对于删除数据、发送消息、执行系统命令、生产环境发布等具有明显副作用的工具,应该根据操作风险设置额外限制。
例如:
- 对只读查询,可以允许 Agent 在授权范围内自动执行。
- 对普通写入,需要进行完整的业务校验与幂等控制。
- 对删除、支付、生产部署等高风险操作,可以要求用户显式确认,或者通过审批流程后再执行。
对于具有不可逆副作用的操作,还可以采用“预览与执行分离”的设计:先让 Agent 生成待执行操作和影响范围,经过用户确认后,再使用服务端保存的操作计划执行。
这样能够避免模型在用户没有明确授权的情况下,直接完成高风险操作。
防止 Prompt Injection 影响工具执行
工具执行还存在一种比较特殊的风险:外部数据可能包含试图诱导模型改变行为的恶意指令。
因此,应该将工具返回内容视为不可信数据,对于可能影响实际业务状态的操作,仍然要经过权限、参数及业务规则校验。
对于允许执行代码或系统命令的 Agent,还需要结合沙箱隔离、文件访问范围、网络访问限制和执行资源限制,避免模型生成的操作获得超出任务需要的系统权限。
最后,生产环境还应该限制工具的执行时间、调用次数和并发资源,避免 Agent 因为错误规划而反复执行工具。
对于重要的业务操作,需要保留工具调用记录,包括任务标识、真实操作人、工具名称、关键参数、执行状态及业务结果等信息,并对敏感内容进行脱敏。
AI 应用评测
前面讨论的是如何把模型调用稳定地接入业务系统。但是 LLM 应用和传统软件不同,LLM 的输出并不总是固定,同样的输入可能得到不同措辞、不同推理过程,甚至不同质量的结果,模型也成功返回了内容,也不代表它真正完成了用户的任务。
因此,我们需要 AI 应用评测,针对明确的任务和评价标准,持续测量模型或整个 AI 系统的实际表现。一般区分三个层次:
- 模型级评测:模型本身的知识、推理、指令遵循、代码等能力怎么样。
- 组件级评测:检索器、重排器、Prompt、工具选择、结构化解析等单个环节是否工作正确。
- 应用级 / 端到端评测:用户交给系统的事情到底有没有办成,以及整个执行过程的质量、成本与稳定性。
理解公开 benchmark
最容易接触到的评测,就是各类大模型排行榜。某个模型在推理、代码或者数学榜单上得分更高,我们往往就认为它更强。公开 Benchmark 主要回答模型在特定任务集上表现如何,但是它是广泛化的衡量,测评不能当饭吃。
Benchmark 本质上是标准化测试:组织一批固定或周期更新的题目,规定输入方式、允许使用的工具、输出格式与评分规则,再让不同模型在尽可能一致的条件下作答。
按测试对象,可以大致分成几类:
- 知识与推理能力:例如 MMLU、MMLU-Pro、GPQA,关注多学科知识、复杂问题理解和推理。它们能反映能力的一部分,但不等于真实工作中能够调用工具解决问题。
- 指令遵循与综合能力:例如 IFEval、LiveBench。前者可检查明确的格式或指令约束,后者通过持续更新题目、使用可验证答案等方式,尽量减小题目泄露与纯主观打分的影响。
- 软件工程能力:例如 SWE-bench 系列,让系统面对真实仓库中的 Issue,修改代码并通过测试。它评测的已经不只是“模型会不会写一段代码”,还包括仓库理解、编辑和验证流程。
- 通用 Agent 能力:例如 GAIA、τ-bench。前者涉及检索、推理和工具使用;后者通过模拟用户与工具交互,检查 Agent 能否遵守业务规则并使最终数据库状态满足目标。
不同 Benchmark 测量的能力并不相同,例如:
| Benchmark | 主要考察什么 | 应该如何理解 |
|---|---|---|
| MMLU / MMLU-Pro | 多学科知识与推理题 | 观察一般知识和答题能力,但不等于实际业务完成率 |
| GPQA | 高难度专业科学问答 | 观察复杂专业问题上的推理与知识能力 |
| IFEval | 指令遵循 | 检查模型能否满足明确、可验证的输出约束 |
| SWE-bench | 真实软件仓库中的问题修复 | 通过补丁及测试执行,衡量代码修复任务的完成情况 |
| GAIA | 搜索、推理、工具使用等综合任务 | 更接近通用 AI 助手处理多步骤问题的场景 |
| AgentBench / τ-bench | 交互环境中的 Agent 决策与工具执行 | 观察多步骤交互、规则遵守和最终状态是否正确 |
阅读榜单时至少要弄清楚,测试的能力和你业务需求的能力对的上吗?
为什么评测数据集需要时刻的维护才有作用,因为你模型都在快速发展你的测评肯定也需要啊
- 数据污染导致模型高分低能。公开题目和答案可能进入模型训练数据,使得模型答对并非真正具备泛化能力
- 基准饱和与评分缺陷
但是,公开 Benchmark 做模型选型的初筛依旧是快速了解模型情况的好选择,了解哪些模型擅长长上下文、工具调用、代码修改或结构化输出,之后使用自己业务中的测试集,对候选模型在同一套工作流下进行实验。
它帮助我们缩小选择范围,但最终的生产效果还需要依赖我们项目中真实的业务完成能力、独立的任务指标等等结合实践的内容。
理解 LLMOps
大模型运维
LLMOps 代表大型语言模型运维。它的简短定义是 LLMOps 是 LLM 的 MLOps。这意味着 LLMOps 是一组工具和最佳实践,用于管理 LLM 支持的应用程序的生命周期,包括开发、部署和维护。其中,MLOps 就是机器学习运维
随着 2022 年底 OpenAI 的一顿乱折腾,从那时起,出现了许多其他 LLM 支持的应用程序。将 LLM 驱动的应用程序引入生产带来了自身的挑战。这就是为什么 LLMOps 会出现新的工具和最佳实践。
随着许多人开发 LLM 支持的应用程序并将其投入生产,和那些非 AI 的应用没有区别,投入生产就会面临生产中的问题,而且问题还往往不能一概而论。为了应对这些挑战,我们需要开发新的工具和最佳实践来管理 LLM 应用程序生命周期。因此,LLMOps 就这样产生了。
LLMOps 并不是只指监控模型 API,而是围绕整个应用生命周期管理 LLM 和 Agent 的运行质量和运行状态。传统系统主要观察服务是否正常运行,LLM 应用还必须观察结果质量,而且还要把Prompt 管理、模型配置、数据集、评测、发布、调用追踪和反馈改进组织成完整的工程生命周期。
LLMOps 通常需要:首先明确业务目标,构建评测数据;然后比较模型、Prompt、检索策略或 Agent 工作流;上线后收集 Trace、用户反馈和成本指标;最后再把典型失败案例沉淀到测试集中,继续迭代。
可观测性Observability 告诉我们系统发生了什么,评测Evaluation 帮助判断发生的事情是否足够好
因此,一个比较完整的 LLMOps 平台,通常需要把 Prompt 版本、模型版本、数据集版本、评测规则和每一次实验结果关联起来。否则今天调整了检索策略,明天换了模型,最后分数提高还是下降,我们甚至不知道是哪次变更造成的。
一个比较全面的评测指标体系
AI 应用的质量不是单一维度。
因此,生产系统需要根据业务目标建立多维度指标体系。常见指标大概可以分成以下几类。
| 维度 | 指标 | 计算方式 | 适用场景 |
|---|---|---|---|
| 检索质量 | Recall@k | 相关文档召回比例 | RAG 知识库 |
| Hit Rate@k | 是否至少命中一条 | RAG 快速验证 | |
| MRR | 第一条相关结果的排名 | 强依赖 Top-1 的 RAG | |
| Precision@k | 结果精准率 | Token 预算紧张场景 | |
| Context Precision | 相关上下文是否排在前面 | RAGAS 类 LLM 检索评测 | |
| Context Recall | 参考答案是否被上下文覆盖 | 缺少文档 ID 标注的早期 RAG 评测 | |
| 生成质量 | Faithfulness | 答案是否忠于上下文 | RAG、事实型问答 |
| Answer Relevance / Response Relevancy | 答案是否回答了问题 | 通用问答、客服 | |
| Completeness | 答案是否覆盖关键要点 | 政策解读、合规问答 | |
| Context Usage | 生成是否有效使用检索上下文 | 检索好但回答仍不好的 RAG 诊断 | |
| Noise Sensitivity | 错误声明受检索上下文影响的比例(越低越好) | Top-k 较大、上下文混杂的 RAG | |
| 动态信息 | 目标时点事实正确率(自定义) | 事实在任务目标时间点是否成立 | Web Search、行情、新闻、版本查询 |
| 证据时效合格率(自定义) | 引证是否满足任务定义的有效时间段 | 强时效信息检索 | |
| 引证支持率(自定义) | 引证是否支持对应的事实声明 | 带来源回答、研究型 Agent | |
| 必要来源覆盖率(自定义) | 关键结论是否覆盖任务要求的必要来源 | 多来源核验、合规研究 | |
| 工具调用 | 工具选择精确率 | 必要且正确的工具调用 / 总工具调用数 | Agent |
| 工具选择召回率 | 已覆盖的必要工具调用 / 标注的必要工具调用数 | Agent | |
| 工具集合完全匹配率 | 选择工具集合与期望集合完全一致的任务 / 总任务数 | Agent | |
| 参数准确率 | 正确参数 / 总参数数 | Agent | |
| 不必要调用率 | 多余调用 / 总调用次数 | Agent 效率优化 | |
| 任务完成率 | 完成任务 / 总任务数 | Agent E2E | |
| 错误恢复率 | 进入预定义恢复结果 / 工具失败总数 | Agent 鲁棒性 | |
| Agent 稳定性 | 至少一次成功率(pass@k) | k 次运行中至少成功 1 次的比例 | 观察能力上限 |
| 连续成功率(pass^k) | k 次运行全部成功的比例 | 高风险生产任务 | |
| 平均轮次 / 工具次数 | 总轮次或工具调用数均值 | 成本、效率和过度探索诊断 | |
| Skill 质量 | 触发召回率 | 正确触发 / 应触发样本数 | Skill 路由 |
| 误触发率 | 错误触发 / 不应触发样本数 | Skill 路由 | |
| 产物合格率 | 合格产物 / 总产物数 | PR 总结、报告生成、代码审查 | |
| 异常稳态率 | 异常输入下安全收敛的比例 | 工具失败、缺参、越权请求 | |
| 格式合规 | JSON 格式合法率 | 合法 JSON / 总输出数 | 结构化输出 |
| Schema 通过率 | 通过校验 / 合法 JSON 数 | 结构化输出 | |
| 枚举准确率 | 正确枚举 / 含枚举字段总数 | 分类、状态输出 | |
| 成本与延迟 | TTFT | 首 token 等待时间 | 流式输出体验 |
| E2E Latency | 从请求到最终结果的耗时 | 整体性能 | |
| Input / Output Tokens | 输入和输出 token 数 | 成本控制 | |
| 重试率 | 触发重试的请求比例 | 稳定性诊断 | |
| 安全与合规 | 违规请求拦截召回率 | 被拦截的应拒答样本 / 应拒答样本数 | 内容安全 |
| 正常请求误拒率 | 被错误拒绝的正常样本 / 正常样本数 | 内容安全 | |
| 越权操作率 | 未授权或超范围操作 / 总操作次数 | 任务执行型 Agent | |
| 幻觉率 | 无依据事实断言的比例 | 事实型问答 | |
| 格式遵循率 | 满足格式约束的输出比例 | Prompt 质量 | |
| 用户体验 | 满意反馈率 | 正向反馈 / 有效反馈数 | 客服、助手类应用 |
| 追问率 | 需要再次澄清或纠正的会话 / 总会话数 | 对话型 Agent | |
| 转人工率 | 转人工会话 / 总会话数 | 客服 Agent,需结合转人工策略解读 |
构建评测用例和 Golden Set
有了评测指标,下一步就是准备数据。Golden Set 可以理解成 AI 应用自己的标准测试集,每条样本都要有明确输入,以及判断输出好坏的标准。
那么,对于一条评测用例,它要落到可验证的问题上,给定一个输入,系统应该完成什么,完成标准是什么。不管单轮问答还是 Agent,一条可用的评测用例至少要回答三件事,给什么输入、在什么环境里跑、怎样算完成。答案可以不唯一,但判定条件必须明确。
单轮问答场景比较简单。输入是一段用户问题,输出是一段模型回答,评分器检查它是否准确、完整、相关。
Agent 场景会复杂很多,因为系统的符合的。它可能多轮思考、调用工具、修改外部状态,最后还会留下完整执行过程。几个对象会反复出现,进行评测和排查问题的时候,这些内容都要分开看,而且出问题其实很难精确判断问题发生在哪一层。
| 概念 | 含义 | 例子 |
|---|---|---|
| Task | 一条评测任务,包含输入和成功标准 | “修复空密码绕过登录校验的问题” |
| Trial | 同一条任务的一次运行 | 同一个 Agent 对同一条任务跑第 3 次 |
| Grader | 对输出或过程打分的评分器 | 单元测试、JSON Schema、LLM-as-Judge、人工复核 |
| Transcript / Trace | 一次运行的完整记录 | 用户输入、模型回复、工具调用、参数、返回值、耗时 |
| Outcome | 任务结束后的真实状态 | 代码测试通过、退款单创建成功、数据库状态更新 |
| Eval Harness | 负责跑任务、记录过程、调用评分器、汇总结果的工程骨架 | 本地脚本、评测平台、Claude Code 搭出来的评测流程 |
因为输出非确定,一条 Task 天然要跑 k 次。于是“这条用例通过了吗”这个问题本身就是不合适的,正确的问法是“这条用例的通过率是多少、方差多大”。对应到指标上就是原文里已经出现的两个量:
pass@k:k 次里至少成功 1 次 → 衡量能力上限;pass^k:k 次全部成功 → 衡量稳定性。
同样重要的是 Outcome 与 Transcript 的分离。因为,结果和过程,必须都要对。
那么,测试的数据从哪来?
可用从生产日志分层采样。先从日志里找用户反馈不满意,或者没有得到解决的内容,再检查失败前的输入和上下文,但是一般情况下,对于这个来源需要进行归因去重,同一个 bug 记十条肯定是不合适的。
测试数据的最边界的来源就是需求和规则,如果你连你的需求都满足不了这个肯定是不可用的,从验收标准、SOP 反推,用例能够覆盖 必须做对 的底线内容,然后再根据此,进行边界与对抗,构造一些边界内容,防止高估能力。
对于覆盖怎么设计,应该是满足场景的矩阵,按维度组合设计覆盖
| 维度 | 取值示例 |
|---|---|
| 任务类型 | 问答、总结、抽取、分类、多步 Agent |
| 难度 | 单跳、多跳、需工具、需澄清 |
| 输入形态 | 正常、超长、空、歧义、多语言、含注入 |
| 风险等级 | 一般、涉及资金/权限/合规 |
| 期望行为 | 应回答、应拒答、应调用工具、应追问 |
判定标准一般就是这四种,总之,能用代码判的,绝不用模型判
| 类型 | 例子 | 成本 | 稳定性 | 适用 |
|---|---|---|---|---|
| 确定性断言 | 单测、JSON Schema、正则、SQL 查状态、工具序列 | 低 | 高 | 结果/格式/状态可程序化判定 |
| 参考答案比对 | 精确匹配、编辑距离、嵌入相似度 | 低 | 中 | 短答案、分类、字段抽取 |
| LLM-as-Judge | 按 rubric 打分 | 中 | 中,需校准 | 开放文本、语义质量、语气合规 |
| 人工复核 | 专家标注 | 高 | 高 | 校准集、争议样本、高风险场 |
总之,公开 Benchmark 不能直接当 Golden Set 用。而且,Golden Set 不是一次性资产,需要根据产品的情况不断地进行维护和支持。
几种评测方法和评测工具
一条用例运行结束以后,究竟由谁判断它做得对不对?判断完成以后,又应该怎么比较不同版本的系统?
评测方法的核心就是,能用程序确定的,就不要让模型猜
- 确定性评测:是最容易理解,也最应该优先采用的方式。它不要求另一个模型解释答案,而是直接使用程序检查某个条件是否成立。例如 JSON Schema 是否通过、SQL 查询是否得到目标状态、代码能不能通过测试、Agent 是否调用了禁止使用的工具。
- 参考答案评测:把实际输出与标准答案或标注事实进行比较。短文本分类、实体抽取和固定知识问答比较适合这种方式。
- LLM-as-Judge:适用于无法简单写成代码规则的开放式输出,例如摘要是否完整、回答是否切题、表达是否符合要求。我们给评委模型输入问题、实际回答、必要的参考事实和评分标准,Judge 模型返回评分与理由,最后人工标记情况。
- 人工评测:主要用于有争议的内容和模型评委的校准。
目前相关工具非常多,但可以按照主要职责分类:有些是偏测试框架的,负责写断言、批量执行;有些偏 RAG / Agent 指标;还有一些是评测与可观测平台,擅长关联数据集、实验和线上 Trace。
| 工具 | 主要定位 | 更适合的使用场景 |
|---|---|---|
| Promptfoo | 配置驱动的 Prompt / LLM 测试框架,支持断言、模型对比与安全测试 | 快速对比 Prompt、模型或一个 HTTP AI 接口,接入 CI |
| DeepEval | Python 生态中的 LLM 测试与指标框架,支持单轮、多轮、Agent 等评测 | 编写自动化语义质量测试、组件及端到端回归 |
| Ragas | 面向 RAG 和 AI 工作流的指标、实验与测试数据工具 | 检索、回答质量以及 RAG 方案对比 |
| LangSmith | Trace、数据集、实验对比和在线 / 离线评测平台 | 需要查看复杂调用链并管理长期评测的系统 |
| Langfuse | 可观测、数据集、实验、评分和 Prompt 管理平台,支持自托管 | 希望把线上 Trace 与回归评测连接起来的团队 |
| Arize Phoenix | 开源可观测与评测平台,支持 Trace、实验和数据集 | 需要本地部署、排查 RAG / Agent 执行过程的系统 |
| Spring AI Evaluator | Spring AI 内置的响应评测接口及相关实现 | Java / Spring Boot 内部的集成测试和质量检查 |
不展开细说了,感兴趣的可以自己搜搜。
LLM-as-Judge
大模型的输出很多时候是开放性的,根本没有唯一的标准答案,那么应该如何自动判断一个回答的质量?
例如,我们开发了一个企业知识库问答系统,用户询问某项业务规则,模型给出了几段自然语言解释。我们希望知道它是否准确、是否完整、有没有错误理解用户意图。
这种情况下,传统的字符串匹配、规则断言等方法很难充分评估回答的语义质量。如果全部交给人工检查,成本又会很高。于是就有了 LLM-as-Judge(大模型充当评审员)。
很明显,就是使用一个 LLM 作为评测器,让它按照预先制定的评价标准,对另一个模型或 AI 应用的输出进行评价。
让模型 A 负责回答业务问题,模型 B 负责检查模型 A 的回答是否符合业务要求,并给出分数、评价理由或者通过与否的判断。通常情况下,Judge 要使用另一个模型。而且,LLM-as-Judge 是把评价任务转换成一次相对规范的模型推理过程,使其能够按照指定标准完成自动化评测,而不是打个分给个建议就完事了。
一次典型的 LLM-as-Judge 评测,一般需要提供以下信息:
- 评测输入(Input):原始用户问题或任务要求,让评审模型知道被测系统到底应该做什么。
- 待评测结果(Candidate Response):被测模型实际生成的回答。
- 评价标准(Rubric):规定应该从哪些维度评价,以及什么情况算合格。
- 参考依据(Reference,可选):可以是标准答案、知识库原文、业务规则或专家标注,用于辅助判断事实正确性。
例如,企业研发助手需要回答:
已经发布,并且被其他项目引用的版本,可以直接删除吗?
假设实际业务规则规定:已经被其他项目引用的版本不能直接删除,需要先解除引用关系。
那么,Judge 可以接收用户问题、实际业务规则以及被测模型的回答,对回答进行判断和测评。
Judge 判断的依据应该来自我们定义的业务规则,而不是仅仅依靠评审模型自身记忆中的知识。
几种常见的 Judge 评分方式。
| 评测方式 | 工作原理 | 适用场景 |
|---|---|---|
| Pointwise(单回答评分) | 对一个回答按照 Rubric 独立评分 | 质量检查、批量评测、上线质量门禁 |
| Pairwise(成对比较) | 同时提供两个回答,让 Judge 判断哪个更好 | 模型选型、Prompt 优化、版本对比 |
| Listwise(列表排序) | 同时比较多个候选结果并排序 | 多模型比较、候选答案排序 |
LLM-as-Judge 的核心是把什么叫作一个好的回答给定义清楚。这种明确的评价规则就叫作 Rubric(评分细则)。
例如,对于上面的企业研发助手,可以制定如下准确性评分标准:
| 分数 | 评价标准 |
|---|---|
| 4 | 准确回答问题,完整说明关键业务规则与限制条件 |
| 3 | 关键结论正确,但遗漏了不影响主要判断的次要信息 |
| 2 | 包含部分正确内容,但遗漏了重要业务条件 |
| 1 | 存在关键事实错误,或者给出了违反业务规则的建议 |
| 0 | 没有回答实际问题,或回答与任务完全无关 |
随后,我们就可以直接编写 Judge Prompt。
最后,LLM-as-Judge 更擅长评价语义质量,而业务完成的可能其实还是需要自己来判断,虽然现在的 Agent 已经能够全方位的完成对一个 Agent 的评价和测试。它最大的价值,是将原本需要大量人工参与的开放式语义评价转化为一个的自动化过程。
一些具体内容的评测方式
RAG 如何评测
RAG 的的评测,相比普通 LLM 应用有一个很明显的不同
RAG 的回答质量不仅取决于生成模型本身,还取决于检索系统有没有找到正确的知识,以及这些知识有没有被模型正确使用。
所以,RAG 评测的核心不仅是判断最后回答得好不好,还需要拆分检索质量、生成质量和端到端评测,来分别判断
- 检索评测:应该找到的知识有没有找到?找到的内容是否相关?排序是否合理?
- 生成评测:模型有没有正确使用检索上下文?回答有没有依据、是否正确完整?
- 端到端评测:从用户提出问题到系统交付答案,最终有没有解决问题,以及耗费了多少时间和资源?
检索阶段怎么评测
检索评测主要关注一个问题:检索系统能否从知识库中找到足以回答问题的有效证据,并把真正有价值的内容放在前面。
首先,我们评测的对象不一定只是向量数据库返回的结果。因为 RAG 不是直接从向量数据库中拿到向量就做比对的,可能经过查询改写、向量检索、关键词检索、混合召回、重排序、过滤以及上下文截取等多个步骤。这些步骤,如果有必要,每一步都需要看看。
前面已经列出了
Recall@k、Precision@k、MRR
等指标,这里主要解释它们在实际 RAG 中应该如何使用。
假设我们的用户问题是:
项目版本发布后,如果已经被其他项目引用,还可以删除吗?
知识库中存在相关业务文档:
- 文档 A:项目版本删除规则,明确指出被引用的版本不能直接删除。
- 文档 B:项目引用关系管理,说明如何解除版本引用。
- 文档 C:项目版本发布流程。
- 文档 D:平台账户权限管理,与当前问题无关。
假设系统最终检索到的 Top-3 是 C、D、A。
这时我们可以发现:
- Recall@3:如果把 A、B 标注为该问题需要覆盖的两个相关知识片段,那么目前只找到了 A,召回率为 50%。
- Precision@3:返回的三个片段中,只有 A 属于这次标注的相关内容,精确率约为 33.3%。
- MRR:如果 A
是第一个被标注为相关的结果,且出现在第三位,那么该问题的倒数排名是
1/3。
实际上,RAG 中的相关性并不是简单的主题相似。
例如,一篇文档标题叫“版本管理”,虽然与用户问题的主题高度相关,但是内容只介绍版本创建,完全没有提到删除规则,那么它对当前问题可能没有任何帮助。
这也是为什么在 RAG 评测中,除了普通检索指标,还会出现 Context Precision、Context Recall 等以回答任务为中心的指标。
它们和传统检索指标的关注点类似,但评测依据可以更加贴近自然语言语义:
- Context Precision:不仅关注检索内容是否有用,还关注有用内容是否排在前面。Ragas 中的典型实现会根据片段相关性及其排名计算评分。
- Context Recall:关注检索上下文是否覆盖参考答案需要的关键信息。例如参考答案包含三个关键事实,而检索内容只能支持其中两个,那么说明检索提供的证据不够完整。
所以,检索阶段需要综合考虑知识覆盖率、结果精确度、排序质量和上下文成本,而不是单独优化某一个指标。
生成阶段怎么评测
假设我们已经把正确的知识交给了 LLM,那么接下来就要判断模型有没有正确地使用这些知识。
生成阶段最重要的几个评价维度是:
| 评价维度 | 核心问题 |
|---|---|
| Faithfulness(忠实度) | 回答中的事实是否能够被检索上下文支持,也就是有没有依据 |
| Answer Relevance(回答相关性) | 回答是否真正回应了用户问题 |
| Answer Correctness(回答正确性) | 回答是否符合参考答案或可信的事实依据,也就是对不对 |
| Completeness(完整性) | 用户问题要求的关键内容是否得到覆盖 |
| Noise Sensitivity(噪声敏感性) | 模型是否容易受到无关或错误信息的干扰 |
例如,知识库中存在一份已经过期的业务文档,规定“已发布版本可以直接删除”,但是当前最新业务规则已经禁止这种操作。
RAG 检索到了旧文档,模型严格根据旧文档作答:
已发布的项目版本可以直接删除。
这个回答完全符合检索上下文,所以它的 Faithfulness 可能很高。但是根据当前有效业务规则,回答实际上是错误的,因此 Answer Correctness 应该很低。
Faithfulness 一般怎么计算和估定?一般是利用 LLM-as-Judge,把生成回答拆解成多个可以独立判断的事实声明,再逐个检查它们是否能够从检索上下文中推导出来。这种评测方式能够帮助我们识别回答中缺乏上下文依据的事实断言。
RAG 的引用与来源评测
对于企业知识库、技术文档问答和研究型助手,RAG 往往需要给出参考文档或者引用来源。
此时引用也应该单独检查,一般是引用的有效性是否可以,支持性如何,来源是否正确。
端到端评测与问题定位
检索和生成都完成以后,最终还需要观察整个 RAG 系统有没有真正解决用户问题。
端到端评测主要关注:
- 任务成功率:用户的问题是否得到准确、完整、符合业务要求的解答。
- 有效拒答能力:知识库没有足够证据时,系统能否承认信息不足,而不是凭空编造答案。
- 响应效率:检索、重排序、生成各自花费多少时间,整体延迟是否可以接受。
- 资源消耗:一次问答涉及多少检索请求、上下文 Token、生成 Token 以及推理费用。
但是,这些内容评价起来会很复杂,因此,生产环境中最好保留完整的 RAG Trace,包括查询改写、原始召回、重排序、最终上下文、模型输出与引用关系,这样才能对错误进行归因。
Agent 应用怎么评测
对于普通的 LLM 问答应用,我们通常只需要关注模型生成的回答质量。但是对于 Agent,情况就要复杂很多。
Agent 不仅需要生成回答,还需要自主规划任务、选择工具、执行操作、处理工具返回结果,并最终完成用户交代的任务。
例如,我们开发了一个软件研发 Agent,用户要求:
修复项目发布接口中重复请求可能导致重复创建发布记录的问题,并运行相关测试。
这个 Agent 可能需要读取项目代码、搜索相关接口、分析事务和幂等机制、修改文件、执行测试,最后向用户汇报修改情况。
在这个过程中,很多问题并不能通过检查最终回答发现。
例如,Agent 最后告诉用户“问题已经修复”,但是实际上并没有修改正确的代码;或者它确实修复了问题,却顺便删除了不应该修改的文件。
因此,Agent 评测的关键是同时关注任务最终结果、执行过程,以及在不同条件下完成任务的可靠性。
Agent 评测的核心:Outcome 与 Trajectory
- Outcome Evaluation(结果评测):检查任务执行结束后,真实环境是否达到了预期状态。
- Trajectory Evaluation(执行轨迹评测):检查 Agent 在执行过程中做出了哪些决策、调用了哪些工具、是否遵循了必要的业务约束。
这两个评测依据引申出了一个很重要的评测原则,Agent 评测不应该强制要求它按照唯一的预设步骤执行,而应该允许不同的有效执行路径,重点验证结果和必须遵守的约束。
但是肯定的,结果正确也不可以忽略执行过程。比较合理的评测方式,是将结果评测与轨迹评测结合起来。
| 评测对象 | 主要关注什么 | 典型检查方式 |
|---|---|---|
| 最终状态(Outcome) | 任务是否真正完成 | 数据库状态断言、自动化测试、文件内容检查 |
| 执行轨迹(Trajectory) | 工具调用和决策是否合理 | 工具调用记录、参数检查、过程规则校验 |
| 最终回复(Final Response) | 是否准确汇报执行结果 | 内容检查、LLM-as-Judge |
| 执行效率 | 是否存在不必要的探索与调用 | 工具次数、模型轮次、Token、执行耗时 |
如何评测 Agent 的工具调用和执行决策
工具调用是 Agent 实现实际业务能力的主要方式,因此也是非常重要的评测对象。
Agent 有没有调用工具,它为什么调用、参数是否正确、执行结果有没有被合理处理。都是很重要的评测标准。
具体方向
- 工具选择是否正确
- 工具参数是否正确
- 工具调用是否满足前置条件
- 是否存在不必要的工具调用
可以看到这些指标其实都非常灵活,所以评测工具调用时,会区分两种情况:
- 必须满足的执行约束:比如必须先获得授权、不得修改无关数据、不能重复执行不可逆操作,这些通常属于硬性检查。
- 可优化的执行行为:比如工具调用次数、探索顺序、是否存在重复检索等,通常属于效率和质量评价。
使用实际业务任务进行 Agent 评测
对于 Agent 来说,用那些测试用例就会显得过于死板,构造一个能够真实执行任务、并且能够验证任务结果的测试环境会好得多。
例如,我们针对软件研发 Agent 设计一条测试用例:
修复项目发布接口重复提交可能产生重复发布记录的问题,不允许破坏已有发布流程,并通过相关测试。
这条用例应该有一个预先准备的项目代码仓库,其中存在我们故意保留的幂等性缺陷。这就是不少 benchmark 的操作
所以,Agent 的任务成功标准并不一定是一个固定答案,而可以是一组最终状态和必须满足的业务约束。
多轮交互和动态环境下,Agent 的测试又会引入很多新的问题,
例如,用户提出的任务可能并不完整,Agent 需要主动追问;工具可能返回错误,Agent 需要调整执行方案;或者执行到一半,用户又提出新的限制条件。
因此,只使用完全固定、一次性提供全部信息的测试用例,可能无法充分反映 Agent 的实际表现。
一种常见方法是引入 用户模拟器,通过预先设置的角色、目标和隐藏信息,模拟真实用户与 Agent 进行多轮交互。除了模拟用户,还可以控制工具和外部环境的返回结果,用来测试 Agent 的异常处理能力。
当然,评测目标不是要求 Agent 永远能从错误中恢复。对于权限不足、业务条件不满足、危险操作缺少授权等情况,正确的行为可能就是停止操作,并向用户明确说明原因。这种测试也是非常有必要的。
最后,前面介绍 Golden Set 时已经提到了 pass@k 和
pass^k,它们在 Agent 评测中尤其重要。
因为 Agent 一次任务可能包含多轮模型推理、工具调用和决策,每一个步骤都存在一定的不确定性,而且前面的错误还可能影响后面的操作。
实际评测时,应当对每条任务执行多次独立 Trial,并重置初始状态,避免前一次执行产生的文件或数据库变更影响后续结果。来多次任务的拷打下,看看 Agent 的一次成功能否扩展到能够稳定的掌握和理解这个任务。
如何在工程中落地 Agent 评测
如果在后端中开发 Agent,评测执行可以划分为以下过程:
- 初始化测试环境:为每次 Trial 准备独立的数据库数据、文件系统或代码仓库状态。
- 执行 Agent 任务:提供任务描述、可用工具和必要的业务上下文,并设置明确的执行预算。
- 记录执行过程:保存模型调用、工具名称、调用参数、工具返回值、执行轮次和最终输出。
- 检查最终状态:通过独立的测试、数据库断言或产物验证判断任务是否真正完成。
- 执行轨迹评价:检查工具选择、参数、业务约束和异常处理过程;必要时使用 LLM-as-Judge 辅助评价。
- 汇总实验结果:按任务类型、难度、失败原因和执行成本汇总,比较不同 Agent 版本的表现。
结构化输出怎么评测
结构化输出的评测相比普通自然语言生成要直接得多,因为我们通常已经提前定义好了 JSON Schema、字段类型以及业务约束,很多内容可以通过程序自动判断。
只不过需要注意,结构化输出的主要目的是,结构化信息提取或业务决策
例如,我们让模型从用户需求中提取项目任务信息:
用户输入:
帮我创建一个高优先级任务,明天下午之前完成登录接口的修复,负责人是张三。
模型返回:
1 | { |
这个 JSON 可能完全符合我们规定的 Schema,但优先级和截止日期却与用户要求不一致。
因此,结构化输出的评测应该分层进行,从格式合法性、Schema 合规性,到字段语义准确性、业务约束正确性,最后检查是否能够真正用于下游业务。
| 评测层次 | 检查内容 | 常见方法 |
|---|---|---|
| 格式合法性 | 是否为合法 JSON,能否正常解析 | JSON Parser |
| Schema 合规性 | 字段类型、必填项、枚举、数组结构、额外字段等是否符合约束 | JSON Schema Validator |
| 字段准确性 | 提取的字段值是否符合用户输入及参考答案 | Exact Match、字段级比较 |
| 语义一致性 | 字段之间是否存在逻辑冲突,是否正确理解用户意图 | 规则断言、LLM-as-Judge |
| 业务约束 | 是否满足时间范围、状态流转、权限和其他业务规则 | 业务校验器 |
| 异常输入处理 | 信息缺失、歧义、非法输入时是否合理处理 | 边界用例、拒绝或澄清检查 |
其中,格式和 Schema 层面的判断比较容易实现,直接使用确定性校验即可。
而字段准确性则需要区分情况:
- 确定性字段:例如 ID、枚举值、金额、布尔值等,通常可以直接与参考答案比较。
- 可规范化字段:例如日期、时间、电话号码,可以先统一格式后再比较。
- 语义型字段:例如任务描述、文本摘要、问题分类理由,可以使用语义评价或者 LLM-as-Judge。
对于后端,结构化输出评测可以直接结合已有的数据解析和校验组件完成,例如:
- 解析检查:使用 Jackson 解析 JSON,检查语法是否正确。
- 结构检查:使用 JSON Schema 校验器,检查字段类型、必填项、枚举与结构约束。
- 字段检查:与 Golden Set 中的参考结果比较,计算字段准确率及整体匹配率。
- 业务检查:通过 Jakarta Validation、自定义校验器或领域业务规则,检查时间范围、状态流转等约束。
- 语义检查:对于无法直接用程序判断的描述性字段,再使用 LLM-as-Judge 辅助评价。
因此,结构化输出评测可以遵循一个比较简单的原则:先使用确定性程序验证格式和约束,再通过参考答案检查字段准确性,最后检查结果能否真正满足业务要求。
Harness 怎么评测
注意区分 Agent 与 Harness 的问题。
Agent 评测主要关注它能否正确理解任务、作出决策并完成任务;而 Harness 评测更关注底层运行环境、状态管理、执行控制和故障恢复机制是否可靠。
Harness 更偏向支撑 Agent 运行的执行环境与控制机制:它负责组织模型调用、执行工具、管理状态、隔离环境、限制资源,并在失败以后尽可能恢复任务。
Agent 的运行还依赖于 Harness。所以说,脱离 LLM 的内容,Harness 主要测试这些内容,主要是测试底层运行时够不够可靠。
Harness 应该重点评测的能力
| 评测维度 | 主要检查内容 | 典型验证方式 |
|---|---|---|
| 执行控制 | 任务状态流转、暂停、恢复、取消和超时是否正确 | 状态机断言、任务生命周期测试 |
| 状态持久化 | 对话上下文、执行进度、工具结果是否正确保存 | Checkpoint 完整性检查 |
| 故障恢复 | 服务重启、进程崩溃后能否从有效状态继续执行 | 故障注入、恢复成功率 |
| 幂等与一致性 | 重试和恢复过程中是否重复产生业务副作用 | 数据库状态、工具执行记录检查 |
| 沙箱与资源隔离 | 文件、网络、权限、CPU、内存等限制是否生效 | 隔离测试、资源压力测试 |
| 并发与调度 | 多任务并行时是否出现状态污染、资源争抢或任务丢失 | 并发压力测试、租户隔离检查 |
| 可观测性 | 是否能够还原任务的模型调用、工具执行和状态变更 | Trace 完整性、事件关联检查 |
其中,最值得重点关注的是状态持久化、故障恢复、幂等性和执行隔离,因为它们决定了长时间运行的 Agent 是否真正具备生产可用性。
故障注入,主动制造可控故障,观察系统的实际行为。是 Harness 的常用测试
例如:
- 模型 API 故障:模拟限流、超时或响应中断,检查重试策略、执行预算及最终状态。
- 工具执行故障:模拟工具调用失败、返回异常或结果未知,检查是否能够正确恢复或停止。
- 进程故障:在 Checkpoint 前后终止进程,检查任务状态能否正确恢复。
- 资源故障:模拟内存不足、磁盘空间不足、沙箱超时,检查资源控制和清理机制。
- 并发冲突:让多个任务同时修改共享资源,检查执行隔离、锁和状态一致性。
通过这些内容来量化 Harness 的可靠性,而且Harness 的很多能力可以直接使用确定性测试
对于后端,可以围绕 Harness 的任务状态机、持久化层、工具执行器和沙箱管理器建立自动化测试。
一个比较合理的分层方案是:
- 组件测试:检查 Checkpoint 读写、任务状态流转、执行预算、幂等记录和资源清理等基础功能。
- 集成测试:在真实数据库、消息队列或隔离沙箱中执行任务,验证跨组件状态一致性。
- 故障恢复测试:主动终止进程、模拟超时或断开依赖,重新启动后检查任务状态和实际副作用。
- 端到端回归测试:使用固定的 Agent 任务集,在正常和故障条件下比较最终任务成功率、恢复能力以及执行成本。
例如,使用 Spring Boot 构建 Harness 时,可以通过 Testcontainers 或独立的测试环境准备数据库和依赖服务,通过故障注入脚本控制进程及外部依赖,再由 JUnit 执行数据库断言、状态检查和资源检查。
同时,应当为每次 Trial 准备独立环境,确保前一次执行留下的文件、缓存、数据库记录不会影响后续评测,否则容易把测试环境的问题误认为 Harness 的可靠性问题。
最终,Harness 评测应该同时回答两个问题:正常情况下能否正确执行,以及异常情况下能否安全地停止、恢复或继续执行。
Agent 决定任务应该怎样完成,而 Harness 要保证这个执行过程在现实工程环境中足够可靠、可控、可观测。
























