知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 测试与质量门禁 > 导读:本文从"我写了 200 个单测全绿,Agent(智能体,能自主调用工具完成多步任务的 LLM 应用)一上线还是答非所问、乱调工具,测试到底该怎么写?"这个实际开发中的疑问出发,把"传统单测为什么对 Agent 失效、测试金字塔怎么在 Agent 场景重构、怎么把不确定性变可控(录制回放 / mock 模型与工具 / 固定随机性 / 约束式断言)、评测集与回归门禁怎么建、关键指标怎么定、工具与 LLM 调用怎么打桩、一个可运行的节点单测 + 轨迹评测示例"逐项讲透,最后给出工程实践与踩坑清单。适合正在把 LLM(Large Language Model,大语言模型)Agent 送上生产、需要对它做质量把关的后端 / 测试 / 算法工程师。 ## 一、先建立全局认知 ### Q:为什么传统单元测试对 Agent 失效? A:结论先行——**传统单测建立在两个隐含假设上:被测函数的输出是确定的、被测函数不依赖外部不可控系统;而 Agent 同时把这两条都打破了。** 先看传统单测为什么好写:`assertEquals(3, add(1, 2))`。它能成立,是因为 `add` 是纯函数——同样的输入永远得到同样的输出,也不依赖网络、数据库、时间。测试的"红 / 绿"完全由你的代码决定,所以绿灯等于代码正确。 Agent 把这两条全推翻了: 1. **输出不确定。** 大模型是概率采样器(逐 token 采样下一个词),`temperature`(温度,控制采样随机性的解码参数)大于 0 时,同一个 Prompt 两次调用会得到不同措辞。即使把 `temperature` 设为 0,很多推理后端也不保证逐 token 可复现——并发批处理、浮点运算顺序、GPU 核函数的非确定性、模型版本被悄悄热更新,都会让"同样的输入"产生"不同的输出"。**是否严格可复现需结合具体供应商与推理框架的版本确认**,工程上不要假设它可复现。 2. **依赖外部系统。** Agent 的核心动作是"调模型 + 调工具":模型 API、搜索、数据库、HTTP 接口、向量库、缓存。任何一个抖动(限流、超时、返回格式变了、数据变了)都会让测试变红,而变红的根因并不在你的代码里。这就构成了**"偶发红 / 偶发绿"的测试**——它既不告诉你代码有没有坏,也无法被信任。 3. **断言无从下手。** 传统断言比"值相等";Agent 的输出是自然语言,同一语义可以有无数种措辞。"北京今天多云,26 度"和"今天北京天气为多云,气温 26℃"都对,但字符串不相等。 4. **执行路径也不唯一。** 同一个任务,Agent 可能先查天气再查空气质量,也可能反过来;可能 3 步完成,也可能因为一次工具报错重试变成 6 步。断言"路径"会极度脆弱,而只看"最终答案"又会漏掉过程里的问题(比如它先去删了条数据才想起要问用户)。 5. **成本与时间不可忽视。** 一条真实端到端轨迹要调用模型若干次、工具若干次;在 CI 里跑几百条轨迹,就是几分钟到几十分钟、几块到几十块钱一次。这让"每次提交都全量跑真实模型"在经济上不成立。 把差异摆成一张表: | 维度 | 传统单测 | Agent 测试 | | --- | --- | --- | | 输出形态 | 确定值 | 自然语言 / 结构化对象的概率分布 | | 依赖 | 无(或可打桩的轻依赖) | 模型、工具、向量库、外部 API | | 断言 | 等值 / 近似 | 约束 + 过程 + 评分 | | 路径 | 唯一 | 多解、可变步数 | | 单次成本 | 微秒级 | 秒级到分钟级、有真金白银 | | 稳定性 | 稳定可复现 | 天然波动 | | "绿灯"含义 | 代码正确 | 当前这批样本这次没出问题 | 所以第一件要接受的事是:**Agent 测试的目标不是"证明它对",而是"约束它别错得太离谱,并持续度量它的表现"。** 这是一次思维方式的切换。 ### Q:Agent 的"不确定性"到底来自哪几层? A:结论先行——**不确定性有四个来源:①模型采样与推理非确定性、②外部工具与数据、③编排逻辑(你自己写的分支、重试、并发、状态机)、④输入分布(用户会问什么)。前两层是"环境噪声",后两层才是"被测对象",测试设计的核心就是——把噪声固定或桩化,只让被测对象变化。** | 来源 | 典型表现 | 是"被测对象"吗 | 处理方式 | | --- | --- | --- | --- | | 模型采样 / 推理非确定 | 措辞变、偶尔不按格式 | 否 | 固定 `temperature`、锁模型版本、录制回放或桩化 | | 外部工具 / 数据 | 超时、返回值变、字段漂移 | 否 | 工具桩化 + 契约测试 + 固定数据快照 | | 编排逻辑 | 该调工具没调、循环不收敛、重试逻辑错 | **是** | 单测 / 轨迹测试重点覆盖 | | 输入分布 | 线上用户问法千奇百怪 | **是(评测集覆盖)** | 评测集分层、失败样本回流 | 这张表最重要的一列是"是否被测对象"。**绝大多数团队把力气花在了"怪模型不稳定"上,而没有意识到:真正你该负责、也只有你能负责的,是第 3 层编排逻辑和第 4 层的输入覆盖。** 模型的措辞波动不该成为你的测试失败原因——它应该被录制、被桩化、被隔离在测试范围之外;而"当模型返回一个畸形 JSON 时,你的代码会不会 500"才是你要测的东西。 ## 二、测试金字塔在 Agent 场景的重构 ### Q:传统测试金字塔为什么不适用? A:结论先行——**传统金字塔(大量快单测 + 少量慢集成 + 极少 E2E)是"单轴"结构,它假设质量可以靠确定性的层层叠加来保证;Agent 的不确定性不会因为测试层级叠加而消失,所以要在金字塔旁边再立一条"评测轴":一条轴是确定性的测试(快、便宜、要求必过),另一条轴是概率性的评测(慢、贵、看通过率与评分)。**  *图:测试金字塔:单轴必过 vs 双轴通过率与评分* ```text 传统金字塔(单轴) Agent 重构(双轴) /\ /\ /E2E\ / \ /------\ 线上监控/ \端到端评测 / 集成测试 \ /------\ (评分+阈值) /------------\ /轨迹集成\ (录制回放,必过) / 单元测试 \ /----------\ /----------------\ /节点/工具单测\(打桩,必过) /--------------\ / 纯函数单测 \(必过) 确定性轴(快、便宜) ◀──┤ 概率性轴(慢、贵) ◀──┘ 靠"通过率 + 评分"而非"必过" ``` 关键差异:**确定性轴上的用例(纯函数、打桩后的节点)可以要求"100% 必过";概率性轴上的用例(真实模型跑完整任务)只能要求"通过率阈值 + 相对基线不退化"。** 把两者混在一起,是门禁反复误报或形同虚设的根源。 ### Q:重构后的分层各测什么? A:结论先行——**五层,从下到上依次是:①纯函数单测 → ②节点 / 工具单测 → ③轨迹集成测试 → ④端到端评测 → ⑤线上监控。越往上越接近真实、越贵、越不做"必过"断言。** | 层级 | 测什么 | 是否调真实模型 | 断言方式 | 运行频率 | 典型工具 | | --- | --- | --- | --- | --- | --- | | ① 纯函数单测 | 解析器、校验器、状态归约、Prompt 拼装、路由规则 | 否 | 等值 / 精确 | 每次提交 | pytest / JUnit | | ② 节点 / 工具单测 | 单个节点"给定状态 → 产出状态增量与副作用";工具的参数校验、错误处理 | 否(桩化) | 等值 + 调用断言 | 每次提交 | pytest + fake | | ③ 轨迹集成测试 | 多节点编排:分支、重试、循环、工具编排、HITL(Human-in-the-loop,人在回路)暂停 | 否(录制回放) | 过程约束 + 约束式 | 每次合并 | 回放框架 | | ④ 端到端评测 | 完整任务在真实 / 近似真实环境下能否完成 | 是 | 评分 + 通过率 | 发版前 / 夜间 | 评测流水线 | | ⑤ 线上监控 | 真实流量的成功率、成本、越权、幻觉 | 是(真实流量) | 指标阈值 + 人工抽检 | 持续 | 可观测平台 | 逐层要点: - **① 纯函数单测**:这是唯一能享受"传统单测红利"的地方。把 Agent 里所有能做成纯函数的部分(JSON 解析、schema 校验、状态合并、工具参数校验、上下文裁剪、路由判定)都抽出来,给它们写密集的单测。**这一层做得越厚,上层越省心。** - **② 节点 / 工具单测**:节点是"状态进、状态出"的纯逻辑单元,把模型和工具桩化后,它同样是确定性的。这里重点测**异常分支**:模型返回非法 JSON、返回了未注册的工具名、工具超时、工具返回空、状态字段缺失。 - **③ 轨迹集成测试**:用录制回放(见第三节)把多节点串起来跑,断言"过程":该调的工具调了、不该调的没调、步数在预算内、HITL 在关键动作前确实暂停了。**这一层是 Agent 特有的价值最大的一层**——它能在不花模型钱的前提下,稳定复现"编排 bug"。 - **④ 端到端评测**:真实模型 + 真实(或高保真)工具,跑评测集,输出通过率与维度分。**这一层不做"必过",它产出的是一个分布统计。** - **⑤ 线上监控**:前面四层都只能覆盖"你想得到的场景",线上才有"你想不到的"。失败的线上样本要回流成 ③ / ④ 的用例(见第四节)。 一条实践原则:**能用下层解决的问题,绝不放到上层。** "JSON 解析失败"是 ① 的事,不该等 ④ 的评测通过率掉了才发现。 ## 三、把"不确定"变可控:录制回放、打桩与断言 ### Q:录制回放(Record & Replay)怎么做? A:结论先行——**核心思路是:把外部世界的一次真实交互序列"录"下来(模型的响应、工具的返回),之后测试时用录制的响应做替身来"放",从而把一个概率性系统在测试期变成确定性系统。关键是录制键要用"语义等价的规范化请求指纹",而不是原始字节。** 原理示意:  *图:录制与回放:cassette 的写入与命中* ```text 录制阶段(真跑一次) 请求A(模型) ──▶ 真实模型 ──▶ 响应A ┐ 请求B(工具) ──▶ 真实工具 ──▶ 响应B ├─▶ 落盘为 cassette(按请求指纹索引) 请求C(模型) ──▶ 真实模型 ──▶ 响应C ┘ 回放阶段(跑 N 次,不联网) 请求A ──▶ 查 cassette[A] ──▶ 命中,返回响应A (确定性,免费,快) 请求B ──▶ 查 cassette[B] ──▶ 命中,返回响应B 请求C ──▶ 查 cassette[C] ──▶ 命中,返回响应C ``` **录制键(fingerprint)怎么算**,是整个方案成败的关键: ```text fp = hash( model_id + model_version + normalize(messages) # 去掉 traceId/时间戳/空白/字段顺序 + tools_fingerprint # 工具定义的规范化序列化 + decoding_params ) # temperature/top_p/max_tokens 等 ``` 如果直接对原始请求体做哈希,命中率会趋近于零,因为每次调用都会带上不同的 `traceId`、时间戳、甚至消息列表里的动态内容。所以规范化和上一节"把噪声排除在外"的思路一致:**把每次必然不同的东西从键里剔除,只保留决定语义的部分。** 几条必须注意的边界: 1. **录制会过期。** 模型升级、工具接口变更、底层数据变了之后,旧录制就不再代表真实行为。做法是给 cassette 打上 `model_version / tool_version / schema_version`,版本一变即失效并重新录制。**把"录制版本"纳入 CI,否则测试会"在旧世界上全绿"。** 2. **一个键可能对应多个合法响应。** 因为模型是概率的,同一个请求在不同次录制里可能返回措辞不同但都合法的结果。稳妥做法是允许一个键下存多个候选响应:要么固定回放第一个以保证确定性,要么逐一回放、要求"每一个都通过约束断言"。 3. **录制要脱敏。** cassette 里会有真实用户输入、工具返回的敏感数据。**落盘前必须脱敏,并且 cassette 不能进公开仓库。** 4. **回放要有显式的"未命中"策略。** 是直接报错(推荐,避免静默走真实网络),还是允许 fallback 到真实调用(仅限少数"契约探测"用例)。 下面是一个最小可用的录制回放装饰器,解决的问题是:**让任意"模型 / 工具客户端"在录制模式下落盘、在回放模式下走本地 cassette,从而让上层编排代码完全无感。** ```python # record_replay.py —— 最小可用录制回放(示意,非生产级) import hashlib import json import os from pathlib import Path CASSETTE_DIR = Path(os.environ.get("CASSETTE_DIR", "cassettes")) def fingerprint(payload: dict) -> str: """把请求规范化后取指纹;剔除每次必然不同的字段。""" normalized = { "model": payload.get("model"), "version": payload.get("model_version"), "messages": _norm_messages(payload.get("messages", [])), "tools": _norm_tools(payload.get("tools", [])), "decoding": payload.get("decoding", {}), } blob = json.dumps(normalized, sort_keys=True, ensure_ascii=False) return hashlib.sha256(blob.encode("utf-8")).hexdigest() def _norm_messages(messages): # 去掉动态字段,只保留语义内容;具体字段按你的消息结构裁剪 out = [] for m in messages: out.append({"role": m.get("role"), "content": m.get("content")}) return out def _norm_tools(tools): # 工具定义按名字排序,避免顺序抖动导致指纹变化 return sorted(tools, key=lambda t: t.get("function", {}).get("name", "")) def recorded_call(mode: str, namespace: str, payload: dict, real_fn): """mode: 'record' | 'replay'。real_fn 是真实调用(模型或工具)。""" fp = fingerprint(payload) path = CASSETTE_DIR / namespace / f"{fp}.json" if mode == "replay": if not path.exists(): raise LookupError(f"cassette miss: {namespace}/{fp}") # 显式失败,禁止静默联网 return json.loads(path.read_text(encoding="utf-8"))["response"] # record 模式:真调一次并落盘 response = real_fn(payload) path.parent.mkdir(parents=True, exist_ok=True) path.write_text( json.dumps({"request": payload, "response": response}, ensure_ascii=False, indent=2), encoding="utf-8", ) return response ``` 适用边界:这个示例适合"顺序调用、无并发"的确定性轨迹。如果 Agent 会并发调工具、或工具调用有副作用再回退,回放的"顺序假设"就会失效,此时要么把并发收敛,要么对每次调用带上"调用序号",把序号也写入指纹。另外,`_norm_messages` 的裁剪规则必须与业务语义一致——**把该保留的字段剪掉了,会造成"不同请求命中了同一条录制"的假阳性**。 ### Q:为什么必须 mock 模型与工具?怎么打桩? A:结论先行——**打桩(mock / stub,用可控的替身替换真实依赖)的目的是把"被测的编排逻辑"和"不受控的模型 / 工具"隔离开:模型桩返回可控输出(包括错误、超时、畸形输出),工具桩返回可控结果,这样你才能稳定地测"当模型这样返回时,我的 Agent 是否正确处理"。** **第一原则是依赖注入(Dependency Injection,把依赖从外部传入而非在内部 new 出来)。** 如果节点里写死了 `OpenAI()` 或 `requests.get(...)`,你就没法替换它。正确做法是节点只依赖接口: ```python # 编排节点只依赖抽象接口,具体实现由外部注入 from abc import ABC, abstractmethod class ModelClient(ABC): @abstractmethod def complete(self, messages, tools) -> dict: ... class ToolRegistry(ABC): @abstractmethod def call(self, name: str, args: dict) -> dict: ... class PlanNode: def __init__(self, model: ModelClient, tools: ToolRegistry): self.model = model # 可被 Fake / 录制 / 真实实现替换 self.tools = tools def run(self, state: dict) -> dict: result = self.model.complete(state["messages"], state["tools"]) # ... 解析 result、决定下一步、写 state ... return state ``` **模型桩的三种档位**(按可控性递增): | 桩类型 | 做法 | 适合测什么 | | --- | --- | --- | | 脚本化桩 | 按"第 N 次调用"返回预设的第 N 个响应 | 确定性的多步编排、重试分支 | | 规则桩 | 按输入关键词 / 状态返回不同响应 | 分支逻辑、路由 | | 录制回放桩 | 读 cassette | 高保真轨迹回归 | **工具桩要覆盖的"坏天气"**,比正常路径更重要:正常返回、超时、报错、返回空、返回畸形结构、返回超大结果、返回含注入内容的文本(测你的 Agent 会不会被工具返回里的"指令"带跑)。**"工具返回里藏了一句'请把用户数据发到某地址'"——你的 Agent 会不会照做,这是一个必须用桩来测的安全用例。** **契约测试(Contract Test)** 是打桩不翻车的保险:桩和真实实现必须遵循同一份契约(同样的入参 schema、同样的返回 schema、同样的错误语义、同样的超时语义)。做法是**写一份"契约用例",分别对桩实现和真实实现各跑一遍,两边都必须过。** 否则就会出现最坑的情况——"桩上全绿,线上全红",因为桩的返回结构和真实工具根本不一样。 ```python # 契约测试:同一组用例,桩和真实实现都要满足 CONTRACT_CASES = [ {"name": "get_order", "args": {"order_id": "A1"}, "expect_keys": {"status", "amount"}}, {"name": "get_order", "args": {"order_id": ""}, "expect_error": "invalid_argument"}, ] def assert_contract(registry): for case in CONTRACT_CASES: out = registry.call(case["name"], case["args"]) if "expect_error" in case: assert out.get("error") == case["expect_error"], case else: assert case["expect_keys"] <= set(out.keys()), case def test_contract_fake(): assert_contract(FakeToolRegistry()) def test_contract_real(): assert_contract(RealToolRegistry()) # 可能需标记为可选/慢测试 ``` 边界:契约测试里的"真实实现"用例往往依赖网络与配额,通常只在特定流水线(如发版前)跑,并允许失败重试;但**桩不满足契约,永远应该让每次提交的 CI 变红**。 ### Q:断言为什么必须从"等值"改成"约束与评分"? A:结论先行——**Agent 的输出空间几乎无限,等值断言必然脆;要改成三类断言:①硬约束(schema / 枚举 / 必含项 / 禁止项)、②过程约束(步数、工具白名单、调用顺序、耗时与成本预算)、③评分(语义正确性、相关性、忠实度)。前两类是"必过门禁",第三类是"阈值门禁"。** | 断言类型 | 例子 | 是否必过 | 失败含义 | | --- | --- | --- | --- | | 硬约束-结构 | 输出是合法 JSON、字段齐全、枚举在定义内 | 是 | 代码 / 约束 bug | | 硬约束-内容 | 必须包含订单号 A1、禁止出现手机号 / 禁止承诺退款 | 是 | 事实错误或合规风险 | | 过程-工具 | 必须调用 `get_order`、禁止调用 `delete_*` | 是 | 越权 / 编排错误 | | 过程-预算 | 步数 ≤ N、总 Token ≤ B、P95 延迟 ≤ T | 是(超限即 fail) | 失控 / 成本问题 | | 过程-顺序 | HITL 审批必须在写操作之前 | 是 | 安全违规 | | 评分-语义 | 与参考答案的语义一致性打分 ≥ 阈值 | 否(阈值门禁) | 质量下降 | **把"固定随机性"作为断言能成立的前提。** 一份固定清单: ```text 1. temperature = 0(或业务允许的最低值),能设 seed 就设(是否支持需结合版本确认) 2. 锁定模型版本号,严禁用 "latest" 之类浮动别名 3. 工具与数据用固定快照(冻结的 fixture 数据,而非连生产库) 4. 固定时钟与时区(注入 Clock,禁用直接读 now()) 5. 固定 locale / 语言偏好 6. 关闭或收敛并发(并发会打乱调用顺序,破坏可复现性) 7. 记录 model_version + prompt_version + dataset_version 到测试报告 ``` 一个"约束 + 评分"的断言示例: ```python # 断言:先用硬约束卡死红线,再对质量打分 def assert_trajectory(traj, case): final = traj["final_answer"] tool_names = [c["name"] for c in traj["tool_calls"]] # ① 硬约束 assert isinstance(traj["steps"], int) and traj["steps"] <= case["max_steps"] for banned in case.get("forbidden_tools", []): assert banned not in tool_names, f"越权调用了 {banned}" for required in case.get("required_tools", []): assert required in tool_names, f"漏调了 {required}" for must in case.get("must_contain", []): assert must in final, f"缺少必需信息:{must}" for forbidden in case.get("must_not_contain", []): assert forbidden not in final, f"出现禁止内容:{forbidden}" # ② 过程预算 assert traj["total_tokens"] <= case["token_budget"] # ③ 评分(阈值门禁,不在此函数内 assert 死,交给门禁统计) return {"passed": True, "score": semantic_score(final, case["reference_answer"])} ``` 适用边界:**硬约束要"少而硬"**——只放真正不能违反的红线,放过多的"必含关键词"会把测试变脆(模型换种说法就 fail)。语义评分必须用经过校准的评测器(人工标注集对齐过的 LLM-as-Judge 或规则 + 关键词混合),**未校准的自动评分本身就是不可信输入**。 ## 四、评测集、回归门禁与关键指标 ### Q:评测集怎么建、怎么版本化? A:结论先行——**评测集(Eval Set)是 Agent 的"回归测试用例库",它比代码更需要版本管理:每条样本要包含输入、期望行为(不是期望文本,而是期望的约束与要点)、来源与难度标签;样本集本身要分层——冒烟集、核心集、对抗集、真实回流集。** **样本来源的四条管道:** 1. **人工构造(金标准 / Golden Set)**:由业务专家按典型场景手工写,覆盖主流程。质量最高、成本最高。 2. **线上失败回流**:用户差评、人工标记、监控异常 → 脱敏后写成可复现用例。**这是性价比最高的一条管道。** 3. **真实流量采样**:从生产流量里按类别采样(注意脱敏与隐私合规),补足分布覆盖。 4. **对抗构造**:越权请求、提示注入(prompt injection)、边界值、空输入、超长输入、跨租户访问。这类用例数量不多,但**必须 100% 通过**。 **分层与规模策略:** | 层级 | 规模量级 | 触发时机 | 门禁要求 | | --- | --- | --- | --- | | 冒烟集(smoke) | 数十条 | 每次 PR | 必过 100% | | 核心集(core) | 数百条 | 合并前 / 每日 | 通过率 ≥ 阈值 | | 全量集(full) | 上千条 | 夜间 / 发版前 | 通过率 ≥ 阈值 + 相对基线不退化 | | 对抗集(adversarial) | 数十到上百条 | 每次 PR(安全红线) | 必过 100% | **版本化要求**:评测集本身要 commit 到仓库或对象存储并计算指纹;每份评测报告都必须记录 `dataset_version + model_version + prompt_version + code_commit`。**没有这四个版本号,评测结果无法归因——你永远说不清"通过率掉了"是代码改坏了、还是模型升级了。** **期望行为的写法**是关键:不要写"期望输出等于某段文本",要写"必须包含订单号 A1 / 必须调用 `get_order` / 不得调用 `refund` / 回答中不得出现任何手机号"。**期望约束而非期望文本,评测才稳定。** ### Q:CI 里的质量门禁怎么卡? A:结论先行——**门禁靠三件事卡:通过率阈值、关键用例必过、相对基线不退化,而不是"要求全部通过"——因为概率性评测天然有波动。同时必须做好"评测的评测":阈值要基于历史波动来定,否则门禁会天天误报,最终被大家忽略。** 五类门禁: | 门禁 | 规则 | 说明 | | --- | --- | --- | | 冒烟必过 | 冒烟集通过率 == 100% | 只放确定性强的用例 | | 安全必过 | 对抗集通过率 == 100% | 越权 / 注入零容忍 | | 质量阈值 | 核心集通过率 ≥ 基线 − 容差 | 容差来自历史波动 | | 防退化 | 本次得分 ≥ 上次基线 − ε(配对比较) | 抓"悄悄变差" | | 预算 | 平均步数 / Token / P95 延迟 ≤ 上限 | 抓成本与性能失控 | **抖动处理**是门禁能不能活下去的关键。三种做法:①多次运行取平均(成本翻倍,仅用于关键集);②固定 seed 降低方差(需确认供应商是否支持);③**配对比较**——同一批样本,用新旧两个版本各跑一遍,比较"逐样本成败变化的净数量",而不是比较两个独立的通过率数字。后者受样本难度分布影响很大,容易误判。 一个 CI 配置示意: ```yaml # quality-gate.yaml(示意,字段按自有评测平台调整) gate: smoke: dataset: eval/smoke require: pass_rate == 1.0 adversarial: dataset: eval/adversarial require: pass_rate == 1.0 # 安全红线,不设容差 core: dataset: eval/core require: pass_rate: ">= baseline - 0.03" # 0.03 为历史波动容差,按自身数据回归 avg_steps: "<= 6" avg_tokens: "<= 8000" p95_latency_ms: "<= 20000" regression: method: paired # 配对比较,而非两个独立通过率 fail_if: "net_regressions > 3" # 净退化样本数超过阈值才 fail on_failure: publish: report.html block_merge: true quarantine: true # 疑似 flaky 的样本进隔离区,不直接阻断 ``` **门禁形同虚设的典型画像**:阈值定得过低("只要不低于 50%");只看总通过率不看对抗集;失败用例只发通知不阻断合并;评测集被拿来反复调 Prompt(相当于把测试集当训练集);flaky 用例被无脑加 `skip`。**一条判断标准:如果你从不因为门禁而推迟过一次合并,那这个门禁就是装饰品。** ### Q:关键指标有哪些? A:结论先行——**按"任务、过程、成本、风险"四类看:任务成功率、工具调用正确率、步数与成本、越权率与幻觉率。只看任务成功率会同时掩盖"蒙对了"和"乱搞但碰巧过了"两种情况。** | 类别 | 指标 | 定义 | 采集方式 | | --- | --- | --- | --- | | 任务 | 任务成功率 | 满足全部硬约束且评分达标的样本占比 | 评测器 | | 任务 | 部分完成率 | 多步任务中子目标完成比例 | 轨迹解析 | | 过程 | 工具调用正确率 | 该调的调了、参数对、不该调的没调 | 与期望轨迹比对 | | 过程 | 工具调用成功率 | 工具自身返回成功的比例 | 工具埋点 | | 过程 | 平均步数 / 步数分布 | 完成任务消耗的轮数 | 轨迹 | | 成本 | 单任务 Token / 费用 | 输入 + 输出 Token 与折算费用 | 模型埋点 | | 成本 | 单任务延迟 P50 / P95 | 端到端耗时与首字延迟 | 埋点 | | 风险 | 越权率 | 访问了无权限资源或超出授权范围的工具 | 审计日志 | | 风险 | 幻觉率 | 陈述与工具结果 / 知识库事实不符 | 人工 + LLM Judge 抽检 | | 风险 | 兜底 / 拒答率 | 无法完成而明确拒答的比例 | 轨迹 | 两条使用提醒: 1. **工具调用正确率比工具调用成功率更能暴露问题。** 成功率只说明"工具没报错",而正确率要求"该调的时候调、不该调的时候不调、参数对"。一个 Agent 可能把工具调得全都成功,但调的是错的工具——成功率 100%,正确率 0。 2. **越权率与幻觉率必须放在最硬的告警位。** 它们不像通过率那样可以"用平均分摊平",一次越权泄露就是事故。**具体的阈值不要照搬任何"业界值",要用自身业务的容忍度来定。** ### Q:失败样本怎么沉淀成回归? A:结论先行——**每一条线上失败(用户差评、人工标记、监控异常)都要变成一条可复现的评测样本,进评测集并锁死为回归用例;不沉淀,同一个坑会反复踩。**  *图:线上失败到回归锁定的六步闭环* ```text 线上失败 │ 1. 采集:trace_id + 完整轨迹 + 用户反馈(脱敏) ▼ 问题定位 │ 2. 归因:是编排 bug / Prompt 问题 / 工具契约问题 / 模型能力问题? ▼ 写成用例 │ 3. 形式化:写成"输入 + 期望约束(含必须/禁止)",而非"期望文本" ▼ 放入分层 │ 4. 分级:编排 bug → 轨迹测试;能力边界 → 核心评测集; │ 安全类 → 对抗集(必过) ▼ 回归锁定 │ 5. PR 门禁必须过;修复该 bug 的提交必须让这条用例由红转绿 ▼ 定期回顾 ──▶ 6. 定期清理冗余样本,控制评测集规模与成本 ``` **"修复必须带回归用例"应写成团队纪律**:一个线上 bug 的修复 PR,如果没带一条能复现它的评测用例,就不算修完。这是把"踩过的坑"变成"永远不会再踩的坑"的唯一方式。 ## 五、一个可运行的测试示例 ### Q:节点单测怎么写? A:结论先行——**节点单测就是"给定输入状态,断言节点产出的状态增量与副作用调用",它的价值在于完全不依赖真实模型:把模型桩化,测的是你自己的解析、分支、副作用逻辑。** 下面这个例子解决的问题是:**验证"当模型返回一个工具调用请求时,节点是否正确地把该调用派发给工具、把结果写回状态、并推进步数"。** ```python # test_plan_node.py —— 节点单测:桩化模型与工具,验证编排逻辑 def make_state(): return {"messages": [{"role": "user", "content": "查一下订单 A1 的状态"}], "tools": [{"function": {"name": "get_order"}}], "step": 0, "tool_results": []} class ScriptedModel: """脚本化模型桩:按调用次序返回预设响应。""" def __init__(self, responses): self.responses, self.i = responses, 0 def complete(self, messages, tools): r = self.responses[self.i]; self.i += 1; return r class RecordingTools: """记录被调用了什么,并按名字返回预设结果。""" def __init__(self, results): self.results, self.calls = results, [] def call(self, name, args): self.calls.append((name, args)); return self.results[name] def test_node_dispatches_tool_call(): # 第一次模型返回"调用 get_order",第二次返回"最终回答" model = ScriptedModel([ {"tool_calls": [{"name": "get_order", "args": {"order_id": "A1"}}]}, {"content": "订单 A1 已支付。"}, ]) tools = RecordingTools({"get_order": {"status": "paid", "amount": "12.50"}}) node = PlanNode(model, tools) out = node.run(make_state()) assert tools.calls == [("get_order", {"order_id": "A1"})] # 派发正确 assert out["tool_results"][0]["status"] == "paid" # 结果写回 assert out["step"] >= 1 # 步数推进 assert "已支付" in out["messages"][-1]["content"] # 最终回答 def test_node_handles_unknown_tool(): # 模型返回了未注册的工具名 → 节点应优雅降级,而不是崩溃 model = ScriptedModel([ {"tool_calls": [{"name": "drop_table", "args": {}}]}, {"content": "抱歉,我无法执行该操作。"}, ]) tools = RecordingTools({}) out = PlanNode(model, tools).run(make_state()) assert tools.calls == [] # 未透传非法工具 ``` 关键点:**模型桩让"多步序列"完全可控**(第一次调工具、第二次给答案),这是单测能稳定覆盖编排分支的根本原因。适用边界:这类测试只验证你的编排逻辑,**不验证模型能力**——模型"是否真的会调用正确工具"要靠第 ③④ 层来测。 ### Q:轨迹评测怎么写? A:结论先行——**轨迹评测跑完整 Agent 循环(用录制回放或桩化模型),然后对"轨迹 + 最终答案"跑一组约束断言与评分,输出通过率与维度分。** 下面这个例子解决的问题是:**在一批评测用例上跑完整轨迹,先过硬约束、再打质量分,最后汇总成可比较的报告。** ```python # test_trajectory.py —— 轨迹评测(示意) def run_trajectory(case, agent): """跑一次完整轨迹;回放模式下不联网。""" return agent.run( user_input=case["input"], max_steps=case.get("max_steps", 10), ) # 返回 {"final_answer","tool_calls","steps","total_tokens"} def evaluate(cases, agent): results = [] for case in cases: traj = run_trajectory(case, agent) hard_failures = check_hard_constraints(traj, case) # 见第三节 if hard_failures: results.append({"id": case["id"], "passed": False, "reasons": hard_failures, "score": 0.0}) continue score = semantic_score(traj["final_answer"], case["reference_answer"]) results.append({"id": case["id"], "passed": score >= case.get("score_threshold", 0.8), "score": score, "steps": traj["steps"], "tokens": traj["total_tokens"]}) return summarize(results) # 通过率 / 平均分 / 平均步数 / 平均 Token def test_core_dataset(): cases = load_dataset("eval/core", version="v3") report = evaluate(cases, build_agent(mode="replay")) # 回放,确定性 assert report["pass_rate"] >= 0.90 assert report["avg_steps"] <= 6 assert report["avg_tokens"] <= 8000 ``` 关键点与边界:**报告里必须带上 `dataset_version / model_version / prompt_version`**,否则跨次比较无意义;回放模式下断言通过率是"确定性"的,真实模型模式下同样这批用例应改为"看阈值与趋势"。**不要把回放模式的通过率当成真实效果**——它证明的是"编排在给定模型行为下正确",而不是"线上效果好"。 ## 六、工程实践与踩坑清单 1. **评测集泄漏。** 拿评测集反复调 Prompt / 调阈值,等于把测试集当训练集,通过率会虚高,线上却不涨。**对策**:评测集与调优集物理隔离;调优用另一份 held-out 集;评测集访问留痕。 2. **只看最终答案。** 只要最终答案对就判通过,掩盖了"先删数据再道歉""调了越权工具才绕回来"的过程风险。**对策**:轨迹过程约束与最终答案一起断言。 3. **mock 与真实漂移。** 桩的返回结构和真实工具不一致,导致"桩上绿、线上红"。**对策**:契约测试同时覆盖桩与真实实现;桩的 schema 从真实实现的 schema 生成或校验。 4. **样本太少 / 分布偏。** 50 条用例测不出长尾;全是主流程没有对抗场景。**对策**:分层建设,安全对抗集必过;失败样本持续回流。 5. **门禁形同虚设。** 阈值过低、失败不阻断、flaky 用例被 `skip`。**对策**:安全类 100% 必过并阻断合并;flaky 进隔离区并限时修复;门禁失效要追责。 6. **录制过期。** 模型 / 工具 / 数据更新后 cassette 不再代表真实行为,测试"在旧世界上全绿"。**对策**:cassette 绑定版本号,版本变更即失效重录;定期抽样跑真实模式对比回放模式。 7. **断言过脆。** 大量"必含某句话"导致模型换个说法就 fail,团队被迫放宽到没有约束。**对策**:硬约束只放红线,措辞类判断交给语义评分。 8. **测试成本失控。** 每次 PR 全量跑真实模型,CI 又慢又贵。**对策**:确定性用例进 PR,真实模型评测放到发版前 / 夜间;回放覆盖大多数回归。 9. **自动评分(LLM-as-Judge)未校准。** 直接用一个 Prompt 让模型打分,评分与人工判断不一致,却拿它当门禁。**对策**:用人工标注集校准 Judge,报告一致性指标;不确定处标注"需结合版本与校准结果确认"。 10. **缺版本归因。** 报告里没有 `dataset / model / prompt / commit` 版本,通过率一掉就抓瞎。**对策**:四版本号强制写入每次评测报告。 ## 小结 - 传统单测失效的根因是**输出不确定 + 依赖不可控**;Agent 测试的目标从"证明它对"转为"约束它别错,并持续度量"。 - 不确定性有四层来源,**只有"编排逻辑"和"输入覆盖"是你的责任**,模型与工具要固定或桩化。 - 测试金字塔要重构成双轴:**确定性轴(纯函数 → 节点 / 工具 → 轨迹回放)要求必过;概率性轴(端到端评测 → 线上监控)看通过率与评分。** - 把不确定变可控的三板斧:**录制回放(语义指纹 + 版本失效)、依赖注入式打桩(模型三档桩 + 工具坏天气 + 契约测试)、断言升级(硬约束 + 过程约束 + 评分)+ 固定随机性。** - 评测集要**分层(冒烟 / 核心 / 全量 / 对抗)+ 版本化(dataset / model / prompt / commit 四版本号)**;门禁靠"通过率阈值 + 关键用例必过 + 相对基线不退化",安全类零容忍。 - 指标按"任务 / 过程 / 成本 / 风险"四类看;**工具调用正确率 ≠ 成功率,越权率与幻觉率要单独告警。** - 线上失败必须沉淀为回归用例,**"修复必须带回归用例"应成为团队纪律。** ## 思考题 1. 你的 Agent 里哪些部分可以做成纯函数?把它们抽出来后,测试成本和稳定性会怎么变? 2. 录制回放的指纹里应该保留哪些字段、剔除哪些字段?如果剔除过多或过少,分别会产生什么后果? 3. 你的评测门禁阈值该怎么定?请说明如何用历史波动数据得出容差,而不是拍一个数字。 4. 当模型的措辞变化导致一条"必含关键词"的硬约束频繁误报时,你会选择改断言还是改 Prompt?判断依据是什么? 5. 契约测试如何同时覆盖"桩实现"与"真实实现",又不会让每次 PR 都依赖网络与配额? 6. 如果只允许你保留一类测试,你会保留"节点 / 工具单测"还是"轨迹回放测试"?为什么? 7. 设计一条从"线上用户差评"到"CI 里锁死的回归用例"的完整链路,指出每一步可能丢失信息的地方。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入