1. 从“黑盒”到“白盒”为什么我们需要对LLM Agent进行分层隔离评估最近和几个做LLM Agent落地的朋友聊天大家普遍有个共同的痛点Agent上线后一旦出了问题排查起来简直像在拆一个俄罗斯套娃。你改了一行提示词结果整个对话流程崩了你升级了底层的LLM模型发现之前跑得稳稳的Agent突然开始胡言乱语。更头疼的是在持续集成CI流水线里你很难设计一个稳定、快速且低成本的测试来保证每次代码提交的质量。传统的端到端测试E2E Test跑一次又慢又贵而且结果波动大今天通过明天失败你根本分不清是代码逻辑问题、提示词问题还是底层大模型API本身“抽风”了。这其实就是标题里“Layer-Isolated Evaluation”分层隔离评估要解决的核心问题。我们不能再把LLM Agent当成一个不可分割的“黑盒”整体来测试了。一个典型的、用于生产的LLM Agent其架构通常可以抽象为几个关键层确定性脚手架层Deterministic Scaffold这是Agent的“骨架”和“神经系统”。它包括所有非LLM驱动的、由代码实现的确定性逻辑比如工具调用Tool Calling的解析与分发、工作流Workflow的状态机管理、记忆Memory的存储与检索逻辑、外部API的调用封装等。这部分代码的行为是确定的输入相同输出必然相同。非确定性LLM层Non-Deterministic LLM这是Agent的“大脑”。它接收脚手架层构造的提示Prompt生成自然语言或结构化输出如JSON。这部分的行为是非确定性的受模型版本、温度Temperature参数、随机种子甚至API服务状态的影响。集成与编排层将上述两者粘合在一起处理输入输出、错误重试、流式响应等。“黑盒”测试的问题在于它将确定性和非确定性的部分混在一起测。一个测试用例失败了你无法快速定位问题是出在代码逻辑的bug上还是提示词设计有歧义抑或是LLM这次“发挥失常”。而“Layer-Isolated”的思路就是要把这个黑盒拆开尤其是要把那个昂贵、缓慢、不稳定的“大脑”LLM暂时拿掉单独、反复、低成本地测试那个“骨架”确定性脚手架。这就像测试一辆自动驾驶汽车。你不能每次都让它在真实道路上跑100公里来验证代码更新成本太高风险太大。更聪明的做法是在实验室里用高保真的模拟器Simulator来测试控制算法这个模拟器可以确定性地复现各种路况和传感器数据。只有当控制算法在模拟器里万无一失时才放到真车上结合实际的感知模块相当于LLM进行集成测试。“Gating the Deterministic Scaffold... with a Regression-Locked Test Harness”这句话精准地描绘了这个方法的核心价值用一个“回归锁定的测试工具链”来为确定性脚手架的代码变更设置质量门禁Gate。任何对脚手架代码的修改都必须先通过这套不依赖LLM的、快速且稳定的测试套件确保核心逻辑没有退化Regression才能进入后续更昂贵、更复杂的集成或端到端测试阶段。这是一种将软件工程中经典的测试金字塔Test Pyramid思想适配到LLM Agent这种新型架构上的实践。2. 构建“无LLM”测试工具链模拟、存根与契约测试要实现分层隔离评估首要任务就是构建一个能够完全绕过真实LLM API的测试环境。这个“No-LLM Test Harness”不是简单地关掉LLM调用而是需要精心设计一套模拟Mocking和存根Stubbing机制来替代LLM的功能同时还要能验证脚手架与LLM之间的交互契约。2.1 核心策略录制与回放Record Replay这是最实用、也是起步最快的策略。其核心思想是在开发或测试阶段使用真实的LLM例如GPT-4运行一批高质量的测试用例并将LLM的输入Prompt和输出Response完整地记录下来保存到本地文件或数据库中。在后续的回归测试或CI流水线中测试工具链将不再调用真实的LLM API而是直接根据输入的Prompt从录制好的数据集中查找并返回对应的Response。具体操作流程如下构建黄金测试集Golden Dataset精心设计一批覆盖核心场景、边界情况和错误处理的对话流程或任务。这些用例的输入用户Query和预期最终输出应该是明确的。首次录制在可控的环境下如固定的LLM模型、温度0、固定的系统提示词运行这些测试用例。你的Agent脚手架会生成Prompt并调用LLM。此时你需要拦截这个调用。数据存储将每次调用的“请求-响应对”持久化。关键是要建立一个可靠的索引方式。最朴素的方法是用Prompt文本的哈希值如SHA256作为键。但更健壮的做法是对Prompt进行一些规范化处理如去除多余空格、标准化换行符并记录关键的元数据如调用的工具列表、对话轮次等。# 示例一个简单的录制数据条目 { test_case_id: calculate_shipping_usa, prompt_hash: a1b2c3d4..., raw_prompt: 你是一个电商助手...用户问运到美国多少钱, normalized_prompt: 你是一个电商助手...用户问运到美国多少钱, // 规范化后 llm_response: json\n{\tool\: \get_shipping_rate\, \parameters\: {\country\: \US\}}\n, model: gpt-4, temperature: 0, timestamp: 2023-10-27... }实现回放模块在测试工具链中替换掉真实的LLM客户端。当脚手架发起LLM调用时回放模块执行以下逻辑对当前生成的Prompt进行相同的规范化处理并计算哈希。在录制数据集中查找匹配的哈希。如果找到则直接返回录制的Response完全跳过网络调用。如果未找到即遇到了新的、未录制的Prompt测试应该失败并提示“发现新的LLM交互模式需要审查并录制”。这强制要求任何代码变更如果导致了新的Prompt模式必须被显式地审查和记录。注意录制与回放的关键在于“确定性”。你必须确保录制和回放时的Prompt生成逻辑是完全一致的。任何细微的差别比如JSON序列化时字段顺序不同、随机生成的会话ID都会导致哈希值不匹配测试失败。因此在脚手架代码中所有可能导致非确定性的部分如随机数、时间戳在测试模式下都需要被固定或模拟。2.2 进阶策略基于规则的响应生成Rule-Based Response对于某些高度结构化、模式清晰的交互我们可以更进一步不依赖录制的数据而是编写规则来直接生成LLM响应。这特别适用于工具调用Function Calling场景。例如你的Agent有一个“查询天气”的工具。当测试工具链识别出Prompt中包含“天气”和城市名时可以直接根据规则构造一个符合工具调用格式的JSON响应甚至可以根据城市名返回预设的天气数据如“北京”返回“晴朗25℃”。class RuleBasedLLMMock: def generate(self, prompt): if 天气 in prompt and 北京 in prompt: # 直接返回一个工具调用结构的响应 return { choices: [{ message: { content: None, tool_calls: [{ function: { name: get_weather, arguments: json.dumps({city: 北京}) } }] } }] } elif prompt_hash_a1b2c3 in prompt: # 或者回退到录制回放 return self.replay_from_recording(prompt) else: raise ValueError(fNo rule or recording matched for prompt: {prompt[:100]}...)这种方法的优点是速度极快完全不依赖外部数据并且能精确测试脚手架对特定响应结构的处理逻辑。缺点是规则维护成本高无法覆盖LLM自由发挥的复杂场景。通常规则引擎和录制回放是结合使用的高频、核心的工具调用用规则覆盖复杂、多变的推理或总结任务用录制回放覆盖。2.3 契约测试验证Prompt的稳定性“无LLM”测试的另一个高级形态是契约测试Contract Test。它的关注点不是LLM返回什么而是脚手架发送给LLM的Prompt是否符合预期。当你的脚手架代码或提示词模板发生修改时你希望确保发送给LLM的“指令”没有发生非预期的、可能导致LLM行为劣化的变化。你可以在测试工具链中加入一个“Prompt差异对比”环节。每次测试运行时不仅执行逻辑还会收集生成的最终Prompt或中间的关键Prompt与一个事先保存的“基准Prompt”Golden Prompt进行对比。对比可以是简单的字符串匹配也可以是更智能的结构化对比如解析出JSON部分进行对比忽略一些无关紧要的空白字符或顺序差异。如果检测到差异测试不会立即失败而是会生成一个差异报告供开发者审查。如果这个差异是预期的例如你主动优化了提示词那么开发者可以更新“基准Prompt”。如果是非预期的例如因为代码bug导致部分提示词丢失则能立即发现问题。# 一个简化的契约测试失败输出示例 [FAIL] Prompt contract violation for test case handle_refund --- Expected Prompt (Golden) 你是一个客服助手请根据用户历史{history}处理当前请求{query}。请严格按JSON格式回复。 Actual Prompt Generated 你是一个客服助手请处理当前请求{query}。请严格按JSON格式回复。 # 差异实际生成的Prompt中缺失了 {history} 变量插值3. “回归锁定”在CI流水线中的实现与实践“Regression-Locked”是这套方法的价值落地点。它意味着测试套件必须是稳定的、可重复的并且能够像一把锁一样防止代码变更引入功能回退。将其集成到CI/CD流水线中才能实现快速反馈和质量门禁。3.1 测试套件的设计原则完全确定性这是铁律。测试不能有任何随机性。这意味着固定所有随机种子Python的random.seed()NumPy的np.random.seed。模拟时间datetime.now()和UUID生成器等。使用上述的“无LLM”工具链彻底消除LLM的不确定性。快速执行理想情况下整个针对确定性脚手架的测试套件应该在几分钟内完成以便在每次提交Commit时都能运行。这要求测试是高度隔离的单元测试或集成测试避免启动完整的服务或进行真实的网络I/O。高覆盖率重点覆盖脚手架的核心状态转换、错误处理路径、工具调用分发逻辑、以及Prompt的构建逻辑。覆盖率工具可以帮助识别未被测试的代码分支。独立性测试用例之间不应该有状态依赖。每个测试都从一个干净的状态开始确保失败不会相互影响。3.2 在CI中的集成步骤以GitLab CI为例一个简化的.gitlab-ci.yml配置可能如下所示stages: - test unit-test-deterministic-scaffold: stage: test image: python:3.11 before_script: - pip install -r requirements-dev.txt # 包含pytest, 测试框架等 script: # 1. 设置确定性环境 - export PYTHONHASHSEED0 - export TEST_MODEno_llm # 告知应用使用测试工具链 # 2. 运行核心的、不依赖LLM的脚手架测试 - pytest tests/unit/test_scaffold_logic.py -v - pytest tests/unit/test_tool_dispatcher.py -v - pytest tests/unit/test_prompt_builder.py -v # 3. 运行契约测试检查Prompt生成是否稳定 - pytest tests/contract/test_prompt_contracts.py -v artifacts: when: always paths: - test-reports/ reports: junit: test-reports/junit.xml rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH # 主分支合并时必跑 - if: $CI_PIPELINE_SOURCE merge_request_event # MR时必跑 - if: $CI_COMMIT_TAG # 打标签时必跑 # 后续可以接更重型的测试例如使用真实LLM但频率较低的集成测试 integration-test-with-llm: stage: test only: - schedules # 例如只在夜间定时任务运行 - tags # 或者发布标签时运行 script: - pytest tests/integration/ --run-llm-tests --expensive在这个流程中unit-test-deterministic-scaffold这个Job就是我们的“回归锁定”门禁。任何开发者的提交或合并请求Merge Request都必须先通过这个快速、稳定的测试阶段。只有通过了代码才能被合并。而那个昂贵、缓慢的integration-test-with-llm则可以放在夜间定时任务或者准备发布时执行作为另一道安全网。3.3 处理“未录制交互”与测试维护在实践中最大的挑战之一是维护录制好的LLM交互数据集。当开发新功能或修改提示词时必然会产生新的、未录制的Prompt。推荐的做法是将“发现未录制交互”视为测试失败的一种特殊类型但提供平滑的解决流程当回放模块找不到匹配的Prompt时测试用例会失败并在错误信息中清晰指出是哪个测试用例、生成了什么样的新Prompt。CI流水线可以提供一个“录制模式”的触发方式例如通过给Commit打上[record]的标签。当在这个模式下运行时测试工具链会调用指定的、版本固定的真实LLM例如gpt-4-0125-preview来获取响应并自动将新的“请求-响应对”添加到录制数据集中。新增的录制数据必须作为代码变更的一部分一并提交审查。在代码评审Code Review中其他开发者不仅要审查代码逻辑也要审查这些新录制的LLM交互是否合理、是否符合预期。这相当于把对LLM行为的审查也纳入了工程流程。对于规则引擎维护过程类似。当新的交互模式无法被现有规则覆盖时测试失败开发者需要评估是添加新规则还是将其归入录制回放更合适。4. 实战案例为一个客服Agent构建分层测试假设我们有一个简单的电商客服Agent它的核心功能是处理用户关于订单状态和退款的查询。其脚手架逻辑包括解析用户意图、调用“查询订单”或“创建退款工单”的工具、组织回复。4.1 传统E2E测试的痛点传统的测试可能会这样写pytest.mark.e2e def test_order_status_inquiry(): agent CustomerServiceAgent() response agent.chat(我的订单12345到哪里了) assert 物流 in response or 运输中 in response # 断言模糊依赖LLM发挥这个测试慢需要调用LLM API、贵消耗Token、不稳定LLM可能用“配送中”而不是“运输中”来回答导致测试失败。4.2 实施分层隔离评估第一步拆分并测试确定性脚手架我们首先编写不依赖LLM的单元测试验证工具调用解析逻辑。# tests/unit/test_intent_parser.py def test_parse_order_status_intent(): parser IntentParser() # 模拟LLM返回一个结构化的工具调用请求 mock_llm_response { tool_calls: [{ function: {name: get_order_status, arguments: {order_id: 12345}} }] } tools parser.parse(mock_llm_response) assert len(tools) 1 assert tools[0].name get_order_status assert tools[0].args[order_id] 12345 # tests/unit/test_tool_dispatcher.py def test_dispatch_get_order_status(): dispatcher ToolDispatcher() tool_call ToolCall(nameget_order_status, args{order_id: 12345}) # 模拟工具执行器 mock_executor Mock() mock_executor.get_order_status.return_value {status: shipped, tracking: XYZ789} dispatcher.register(get_order_status, mock_executor.get_order_status) result dispatcher.dispatch(tool_call) mock_executor.get_order_status.assert_called_once_with(order_id12345) assert result[status] shipped第二步使用录制回放测试完整流程我们为“查询订单状态”这个用户场景录制一个完整的交互。首次录制在开发环境手动或通过脚本输入用户Query:“我的订单12345到哪里了”脚手架生成的Prompt假设:“用户询问订单12345的状态。请调用合适的工具。”真实LLMGPT-4 temperature0返回:{tool_calls: [...]}建议使用结构化输出格式工具执行后返回数据:{status: shipped, tracking: XYZ789}脚手架组织最终回复的Prompt:“根据工具返回的结果告诉用户订单已发货运单号是XYZ789。”真实LLM返回最终回复:“您的订单12345已发货运单号为XYZ789正在运输途中。”将这两个阶段的(Prompt, Response)对都录制下来关联到测试用例test_order_status_flow。编写集成测试但使用回放# tests/integration/test_order_status_flow.py pytest.mark.no_llm # 使用pytest标记在conftest.py中根据此标记自动切换为回放模式 def test_order_status_flow(recorded_session): # recorded_session 是注入的回放夹具 agent CustomerServiceAgent(test_modeTrue) final_response agent.chat(我的订单12345到哪里了) # 断言最终回复包含关键信息这些信息来自录制的、确定性的数据 assert 12345 in final_response assert XYZ789 in final_response assert 发货 in final_response or shipped in final_response这个测试运行速度极快因为它只是从本地数据文件读取响应并且结果100%稳定。第三步在CI中设置门禁将tests/unit/和tests/integration/标记了pytest.mark.no_llm的测试套件加入CI的必跑任务。任何修改了意图解析、工具分发、Prompt模板的代码提交都会触发这些测试。只有当它们全部通过时代码才能合并。这确保了Agent的“骨架”在任何时候都是健壮的。对于提示词工程师Prompt Engineer来说如果他们修改了系统提示词导致生成的Prompt发生了变化契约测试会捕获到这个差异。他们需要审查这个差异是否是预期的并更新“基准Prompt”。这样提示词的修改也纳入了版本控制和回归测试的范围。我个人在多个Agent项目中推行这套方法后最深刻的体会是它极大地提升了团队对代码变更的信心。开发者不再害怕修改Agent的核心逻辑因为知道有一套快速的“安全网”会立即告诉他们是否破坏了现有功能。同时它也迫使团队更清晰地思考Agent的架构明确哪些是确定性逻辑哪些是非确定性部分这种架构上的清晰度本身就是一种巨大的价值。当然初期搭建测试工具链和录制数据集需要投入但比起在线上问题中熬夜排查或者在不可靠的E2E测试中反复调试这种投入的回报是立竿见影的。 LLM Agent分层隔离评估：构建稳定高效的测试工具链
1. 从“黑盒”到“白盒”为什么我们需要对LLM Agent进行分层隔离评估最近和几个做LLM Agent落地的朋友聊天大家普遍有个共同的痛点Agent上线后一旦出了问题排查起来简直像在拆一个俄罗斯套娃。你改了一行提示词结果整个对话流程崩了你升级了底层的LLM模型发现之前跑得稳稳的Agent突然开始胡言乱语。更头疼的是在持续集成CI流水线里你很难设计一个稳定、快速且低成本的测试来保证每次代码提交的质量。传统的端到端测试E2E Test跑一次又慢又贵而且结果波动大今天通过明天失败你根本分不清是代码逻辑问题、提示词问题还是底层大模型API本身“抽风”了。这其实就是标题里“Layer-Isolated Evaluation”分层隔离评估要解决的核心问题。我们不能再把LLM Agent当成一个不可分割的“黑盒”整体来测试了。一个典型的、用于生产的LLM Agent其架构通常可以抽象为几个关键层确定性脚手架层Deterministic Scaffold这是Agent的“骨架”和“神经系统”。它包括所有非LLM驱动的、由代码实现的确定性逻辑比如工具调用Tool Calling的解析与分发、工作流Workflow的状态机管理、记忆Memory的存储与检索逻辑、外部API的调用封装等。这部分代码的行为是确定的输入相同输出必然相同。非确定性LLM层Non-Deterministic LLM这是Agent的“大脑”。它接收脚手架层构造的提示Prompt生成自然语言或结构化输出如JSON。这部分的行为是非确定性的受模型版本、温度Temperature参数、随机种子甚至API服务状态的影响。集成与编排层将上述两者粘合在一起处理输入输出、错误重试、流式响应等。“黑盒”测试的问题在于它将确定性和非确定性的部分混在一起测。一个测试用例失败了你无法快速定位问题是出在代码逻辑的bug上还是提示词设计有歧义抑或是LLM这次“发挥失常”。而“Layer-Isolated”的思路就是要把这个黑盒拆开尤其是要把那个昂贵、缓慢、不稳定的“大脑”LLM暂时拿掉单独、反复、低成本地测试那个“骨架”确定性脚手架。这就像测试一辆自动驾驶汽车。你不能每次都让它在真实道路上跑100公里来验证代码更新成本太高风险太大。更聪明的做法是在实验室里用高保真的模拟器Simulator来测试控制算法这个模拟器可以确定性地复现各种路况和传感器数据。只有当控制算法在模拟器里万无一失时才放到真车上结合实际的感知模块相当于LLM进行集成测试。“Gating the Deterministic Scaffold... with a Regression-Locked Test Harness”这句话精准地描绘了这个方法的核心价值用一个“回归锁定的测试工具链”来为确定性脚手架的代码变更设置质量门禁Gate。任何对脚手架代码的修改都必须先通过这套不依赖LLM的、快速且稳定的测试套件确保核心逻辑没有退化Regression才能进入后续更昂贵、更复杂的集成或端到端测试阶段。这是一种将软件工程中经典的测试金字塔Test Pyramid思想适配到LLM Agent这种新型架构上的实践。2. 构建“无LLM”测试工具链模拟、存根与契约测试要实现分层隔离评估首要任务就是构建一个能够完全绕过真实LLM API的测试环境。这个“No-LLM Test Harness”不是简单地关掉LLM调用而是需要精心设计一套模拟Mocking和存根Stubbing机制来替代LLM的功能同时还要能验证脚手架与LLM之间的交互契约。2.1 核心策略录制与回放Record Replay这是最实用、也是起步最快的策略。其核心思想是在开发或测试阶段使用真实的LLM例如GPT-4运行一批高质量的测试用例并将LLM的输入Prompt和输出Response完整地记录下来保存到本地文件或数据库中。在后续的回归测试或CI流水线中测试工具链将不再调用真实的LLM API而是直接根据输入的Prompt从录制好的数据集中查找并返回对应的Response。具体操作流程如下构建黄金测试集Golden Dataset精心设计一批覆盖核心场景、边界情况和错误处理的对话流程或任务。这些用例的输入用户Query和预期最终输出应该是明确的。首次录制在可控的环境下如固定的LLM模型、温度0、固定的系统提示词运行这些测试用例。你的Agent脚手架会生成Prompt并调用LLM。此时你需要拦截这个调用。数据存储将每次调用的“请求-响应对”持久化。关键是要建立一个可靠的索引方式。最朴素的方法是用Prompt文本的哈希值如SHA256作为键。但更健壮的做法是对Prompt进行一些规范化处理如去除多余空格、标准化换行符并记录关键的元数据如调用的工具列表、对话轮次等。# 示例一个简单的录制数据条目 { test_case_id: calculate_shipping_usa, prompt_hash: a1b2c3d4..., raw_prompt: 你是一个电商助手...用户问运到美国多少钱, normalized_prompt: 你是一个电商助手...用户问运到美国多少钱, // 规范化后 llm_response: json\n{\tool\: \get_shipping_rate\, \parameters\: {\country\: \US\}}\n, model: gpt-4, temperature: 0, timestamp: 2023-10-27... }实现回放模块在测试工具链中替换掉真实的LLM客户端。当脚手架发起LLM调用时回放模块执行以下逻辑对当前生成的Prompt进行相同的规范化处理并计算哈希。在录制数据集中查找匹配的哈希。如果找到则直接返回录制的Response完全跳过网络调用。如果未找到即遇到了新的、未录制的Prompt测试应该失败并提示“发现新的LLM交互模式需要审查并录制”。这强制要求任何代码变更如果导致了新的Prompt模式必须被显式地审查和记录。注意录制与回放的关键在于“确定性”。你必须确保录制和回放时的Prompt生成逻辑是完全一致的。任何细微的差别比如JSON序列化时字段顺序不同、随机生成的会话ID都会导致哈希值不匹配测试失败。因此在脚手架代码中所有可能导致非确定性的部分如随机数、时间戳在测试模式下都需要被固定或模拟。2.2 进阶策略基于规则的响应生成Rule-Based Response对于某些高度结构化、模式清晰的交互我们可以更进一步不依赖录制的数据而是编写规则来直接生成LLM响应。这特别适用于工具调用Function Calling场景。例如你的Agent有一个“查询天气”的工具。当测试工具链识别出Prompt中包含“天气”和城市名时可以直接根据规则构造一个符合工具调用格式的JSON响应甚至可以根据城市名返回预设的天气数据如“北京”返回“晴朗25℃”。class RuleBasedLLMMock: def generate(self, prompt): if 天气 in prompt and 北京 in prompt: # 直接返回一个工具调用结构的响应 return { choices: [{ message: { content: None, tool_calls: [{ function: { name: get_weather, arguments: json.dumps({city: 北京}) } }] } }] } elif prompt_hash_a1b2c3 in prompt: # 或者回退到录制回放 return self.replay_from_recording(prompt) else: raise ValueError(fNo rule or recording matched for prompt: {prompt[:100]}...)这种方法的优点是速度极快完全不依赖外部数据并且能精确测试脚手架对特定响应结构的处理逻辑。缺点是规则维护成本高无法覆盖LLM自由发挥的复杂场景。通常规则引擎和录制回放是结合使用的高频、核心的工具调用用规则覆盖复杂、多变的推理或总结任务用录制回放覆盖。2.3 契约测试验证Prompt的稳定性“无LLM”测试的另一个高级形态是契约测试Contract Test。它的关注点不是LLM返回什么而是脚手架发送给LLM的Prompt是否符合预期。当你的脚手架代码或提示词模板发生修改时你希望确保发送给LLM的“指令”没有发生非预期的、可能导致LLM行为劣化的变化。你可以在测试工具链中加入一个“Prompt差异对比”环节。每次测试运行时不仅执行逻辑还会收集生成的最终Prompt或中间的关键Prompt与一个事先保存的“基准Prompt”Golden Prompt进行对比。对比可以是简单的字符串匹配也可以是更智能的结构化对比如解析出JSON部分进行对比忽略一些无关紧要的空白字符或顺序差异。如果检测到差异测试不会立即失败而是会生成一个差异报告供开发者审查。如果这个差异是预期的例如你主动优化了提示词那么开发者可以更新“基准Prompt”。如果是非预期的例如因为代码bug导致部分提示词丢失则能立即发现问题。# 一个简化的契约测试失败输出示例 [FAIL] Prompt contract violation for test case handle_refund --- Expected Prompt (Golden) 你是一个客服助手请根据用户历史{history}处理当前请求{query}。请严格按JSON格式回复。 Actual Prompt Generated 你是一个客服助手请处理当前请求{query}。请严格按JSON格式回复。 # 差异实际生成的Prompt中缺失了 {history} 变量插值3. “回归锁定”在CI流水线中的实现与实践“Regression-Locked”是这套方法的价值落地点。它意味着测试套件必须是稳定的、可重复的并且能够像一把锁一样防止代码变更引入功能回退。将其集成到CI/CD流水线中才能实现快速反馈和质量门禁。3.1 测试套件的设计原则完全确定性这是铁律。测试不能有任何随机性。这意味着固定所有随机种子Python的random.seed()NumPy的np.random.seed。模拟时间datetime.now()和UUID生成器等。使用上述的“无LLM”工具链彻底消除LLM的不确定性。快速执行理想情况下整个针对确定性脚手架的测试套件应该在几分钟内完成以便在每次提交Commit时都能运行。这要求测试是高度隔离的单元测试或集成测试避免启动完整的服务或进行真实的网络I/O。高覆盖率重点覆盖脚手架的核心状态转换、错误处理路径、工具调用分发逻辑、以及Prompt的构建逻辑。覆盖率工具可以帮助识别未被测试的代码分支。独立性测试用例之间不应该有状态依赖。每个测试都从一个干净的状态开始确保失败不会相互影响。3.2 在CI中的集成步骤以GitLab CI为例一个简化的.gitlab-ci.yml配置可能如下所示stages: - test unit-test-deterministic-scaffold: stage: test image: python:3.11 before_script: - pip install -r requirements-dev.txt # 包含pytest, 测试框架等 script: # 1. 设置确定性环境 - export PYTHONHASHSEED0 - export TEST_MODEno_llm # 告知应用使用测试工具链 # 2. 运行核心的、不依赖LLM的脚手架测试 - pytest tests/unit/test_scaffold_logic.py -v - pytest tests/unit/test_tool_dispatcher.py -v - pytest tests/unit/test_prompt_builder.py -v # 3. 运行契约测试检查Prompt生成是否稳定 - pytest tests/contract/test_prompt_contracts.py -v artifacts: when: always paths: - test-reports/ reports: junit: test-reports/junit.xml rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH # 主分支合并时必跑 - if: $CI_PIPELINE_SOURCE merge_request_event # MR时必跑 - if: $CI_COMMIT_TAG # 打标签时必跑 # 后续可以接更重型的测试例如使用真实LLM但频率较低的集成测试 integration-test-with-llm: stage: test only: - schedules # 例如只在夜间定时任务运行 - tags # 或者发布标签时运行 script: - pytest tests/integration/ --run-llm-tests --expensive在这个流程中unit-test-deterministic-scaffold这个Job就是我们的“回归锁定”门禁。任何开发者的提交或合并请求Merge Request都必须先通过这个快速、稳定的测试阶段。只有通过了代码才能被合并。而那个昂贵、缓慢的integration-test-with-llm则可以放在夜间定时任务或者准备发布时执行作为另一道安全网。3.3 处理“未录制交互”与测试维护在实践中最大的挑战之一是维护录制好的LLM交互数据集。当开发新功能或修改提示词时必然会产生新的、未录制的Prompt。推荐的做法是将“发现未录制交互”视为测试失败的一种特殊类型但提供平滑的解决流程当回放模块找不到匹配的Prompt时测试用例会失败并在错误信息中清晰指出是哪个测试用例、生成了什么样的新Prompt。CI流水线可以提供一个“录制模式”的触发方式例如通过给Commit打上[record]的标签。当在这个模式下运行时测试工具链会调用指定的、版本固定的真实LLM例如gpt-4-0125-preview来获取响应并自动将新的“请求-响应对”添加到录制数据集中。新增的录制数据必须作为代码变更的一部分一并提交审查。在代码评审Code Review中其他开发者不仅要审查代码逻辑也要审查这些新录制的LLM交互是否合理、是否符合预期。这相当于把对LLM行为的审查也纳入了工程流程。对于规则引擎维护过程类似。当新的交互模式无法被现有规则覆盖时测试失败开发者需要评估是添加新规则还是将其归入录制回放更合适。4. 实战案例为一个客服Agent构建分层测试假设我们有一个简单的电商客服Agent它的核心功能是处理用户关于订单状态和退款的查询。其脚手架逻辑包括解析用户意图、调用“查询订单”或“创建退款工单”的工具、组织回复。4.1 传统E2E测试的痛点传统的测试可能会这样写pytest.mark.e2e def test_order_status_inquiry(): agent CustomerServiceAgent() response agent.chat(我的订单12345到哪里了) assert 物流 in response or 运输中 in response # 断言模糊依赖LLM发挥这个测试慢需要调用LLM API、贵消耗Token、不稳定LLM可能用“配送中”而不是“运输中”来回答导致测试失败。4.2 实施分层隔离评估第一步拆分并测试确定性脚手架我们首先编写不依赖LLM的单元测试验证工具调用解析逻辑。# tests/unit/test_intent_parser.py def test_parse_order_status_intent(): parser IntentParser() # 模拟LLM返回一个结构化的工具调用请求 mock_llm_response { tool_calls: [{ function: {name: get_order_status, arguments: {order_id: 12345}} }] } tools parser.parse(mock_llm_response) assert len(tools) 1 assert tools[0].name get_order_status assert tools[0].args[order_id] 12345 # tests/unit/test_tool_dispatcher.py def test_dispatch_get_order_status(): dispatcher ToolDispatcher() tool_call ToolCall(nameget_order_status, args{order_id: 12345}) # 模拟工具执行器 mock_executor Mock() mock_executor.get_order_status.return_value {status: shipped, tracking: XYZ789} dispatcher.register(get_order_status, mock_executor.get_order_status) result dispatcher.dispatch(tool_call) mock_executor.get_order_status.assert_called_once_with(order_id12345) assert result[status] shipped第二步使用录制回放测试完整流程我们为“查询订单状态”这个用户场景录制一个完整的交互。首次录制在开发环境手动或通过脚本输入用户Query:“我的订单12345到哪里了”脚手架生成的Prompt假设:“用户询问订单12345的状态。请调用合适的工具。”真实LLMGPT-4 temperature0返回:{tool_calls: [...]}建议使用结构化输出格式工具执行后返回数据:{status: shipped, tracking: XYZ789}脚手架组织最终回复的Prompt:“根据工具返回的结果告诉用户订单已发货运单号是XYZ789。”真实LLM返回最终回复:“您的订单12345已发货运单号为XYZ789正在运输途中。”将这两个阶段的(Prompt, Response)对都录制下来关联到测试用例test_order_status_flow。编写集成测试但使用回放# tests/integration/test_order_status_flow.py pytest.mark.no_llm # 使用pytest标记在conftest.py中根据此标记自动切换为回放模式 def test_order_status_flow(recorded_session): # recorded_session 是注入的回放夹具 agent CustomerServiceAgent(test_modeTrue) final_response agent.chat(我的订单12345到哪里了) # 断言最终回复包含关键信息这些信息来自录制的、确定性的数据 assert 12345 in final_response assert XYZ789 in final_response assert 发货 in final_response or shipped in final_response这个测试运行速度极快因为它只是从本地数据文件读取响应并且结果100%稳定。第三步在CI中设置门禁将tests/unit/和tests/integration/标记了pytest.mark.no_llm的测试套件加入CI的必跑任务。任何修改了意图解析、工具分发、Prompt模板的代码提交都会触发这些测试。只有当它们全部通过时代码才能合并。这确保了Agent的“骨架”在任何时候都是健壮的。对于提示词工程师Prompt Engineer来说如果他们修改了系统提示词导致生成的Prompt发生了变化契约测试会捕获到这个差异。他们需要审查这个差异是否是预期的并更新“基准Prompt”。这样提示词的修改也纳入了版本控制和回归测试的范围。我个人在多个Agent项目中推行这套方法后最深刻的体会是它极大地提升了团队对代码变更的信心。开发者不再害怕修改Agent的核心逻辑因为知道有一套快速的“安全网”会立即告诉他们是否破坏了现有功能。同时它也迫使团队更清晰地思考Agent的架构明确哪些是确定性逻辑哪些是非确定性部分这种架构上的清晰度本身就是一种巨大的价值。当然初期搭建测试工具链和录制数据集需要投入但比起在线上问题中熬夜排查或者在不可靠的E2E测试中反复调试这种投入的回报是立竿见影的。