Agent Governance Toolkit 中的评估工程（Evaluation Engineering）：面向概率性 AI 系统的“新 TDD“实战指南

Agent Governance Toolkit 中的评估工程Evaluation Engineering面向概率性 AI 系统的新 TDD实战指南【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit传统单元测试无法覆盖生成式 AI 无穷无尽的创意变体评估工程Evaluation Engineering将工程师的角色从编写实现转向编写考试用 Golden Dataset 定义什么是好用多维 Scoring Rubric 编码工程判断用 EvaluationRunner 让 AI 迭代直至达标。本文以 Agent Governance Toolkit 仓库中 self-evaluating 示例的EVALUATION_ENGINEERING.md为主干结合 evaluation_engineering.py 的完整实现与 test_evaluation_engineering.py 的测试用例系统讲解 Eval-DDEvaluation-Driven Development评估驱动开发的完整工作流读者可据此为自己的 AI Agent 搭建可量化、可回归、可迭代的质量评估体系。范式转变从证明它能工作到定义什么叫做好旧世界确定性系统的单元测试我写代码然后写一个单元测试来证明它能工作。在传统软件工程中开发者先编写实现代码函数、类、算法再编写单元测试验证实现正确。对于确定性系统这种模式行之有效——相同的输入必然产生相同的输出。工程现实概率性系统的测试困境在概率世界里你无法写出覆盖 AI 答案每一种创意变体的单元测试。当面对 AI 系统时传统单元测试开始失效同一个输入AI 可能给出不同但同样合理的回答。此时测试的重点不再是精确匹配而是在多个维度上评估输出质量——正确性、语气、安全性、清晰度、效率等。新世界评估工程如果 AI 是考生Coder人类就是考官Examiner。我们不再编写实现我们编写考试。评估工程是当今资深工程师最有价值的产出。以日期解析为例不再手写parseDate()而是编写三样东西Golden Dataset黄金数据集50 个刁钻、畸形的日期字符串及其期望输出Scoring Rubric评分标准答案正确但语气粗鲁得 5/10 分答案错误但态度礼貌得 0/10 分Pass Threshold通过阈值AI 必须得分 90% 才能通过。这是 TDD测试驱动开发向Eval-DD评估驱动开发的演进先写黄金数据集让 AI 不断迭代直到在评分标准下得分超过 90%。在仓库中这一思想被完整落地为 evaluation_engineering.py其模块文档明确指出核心洞察在概率性 AI 世界中源代码就是约束 AI 行为的评估套件Evaluation Suite。核心概念一Golden Dataset——用示例定义好Golden Dataset 就是你的测试套件它通过示例定义什么是好的输出。from evaluation_engineering import EvaluationDataset dataset EvaluationDataset( nameDate Parsing Golden Dataset, description50 tricky, malformed date strings ) # 不再编写 parseDate()而是编写示例 dataset.add_case( idparse_date_001, inputParse this date: 2024-01-15, expected_output2024-01-15, tags[basic, iso] ) dataset.add_case( idparse_date_002, inputParse this date: Jan 15, 2024, expected_output2024-01-15, tags[readable] ) # 边界用例 dataset.add_case( idparse_date_edge_001, inputParse this date: 2024-13-01, expected_outputERROR, tags[invalid, edge_case], difficultyhard )从源码实现看evaluation_engineering.pyEvaluationDataset的关键能力包括add_case全参数支持除id、input、expected_output外还支持expected_behavior期望行为描述适用于无法用单一输出断言的任务、context附加上下文字典、tags标签列表默认空、difficulty难度分级默认为medium可选easy、medium、hard、edge_caseget_cases_by_tag/get_cases_by_difficulty按标签或难度过滤用例便于按维度组织评测save/load持久化数据集可序列化为 JSON 文件并重新加载支持跨团队共享与版本管理__len__支持len(dataset)直接统计用例数。在 example_evaluation_engineering.py 中create_date_parsing_dataset()提供了 25 个真实覆盖用例横跨多个类别类别示例输入期望输出关注点基础格式2024-01-15、01/15/2024、15/01/20242024-01-15ISO / 美式 / 欧式格式可读格式Jan 15, 2024、January 15th, 2024、15 Jan 20242024-01-15自然语言日期紧凑与短年20240115、01-15-24、1/5/242024-01-15/2024-01-05紧凑编码、两位年份畸形与边界2024.01.15点分隔、15-JAN-2024大写、january 15 2024小写、1st January 2024序数2024-01-15非常规写法歧义格式02/03/2024、2024-1-5、5-1-2024按规则归一化歧义消解策略带上下文Date: 2024-01-15、Born on Jan 15, 20242024-01-15从自由文本中抽取无效输入2024-13-01月份越界、2024-02-30日期不存在、not a date、32/01/2024、空字符串ERROR错误处理与空输入核心概念二Scoring Rubric——把工程判断编码为可计算分数Scoring Rubric 定义如何评估回答这是把工程判断engineering judgment编码为代码的地方。from evaluation_engineering import ScoringRubric rubric ScoringRubric( nameCustomer Service Rubric, descriptionEvaluates correctness AND tone ) # 多维度评估 rubric.add_criteria( dimensioncorrectness, weight0.5, # 50% of score descriptionDoes it solve the problem?, evaluatorcorrectness_evaluator ) rubric.add_criteria( dimensiontone, weight0.4, # 40% of score - tone is almost as important! descriptionIs it polite and empathetic?, evaluatortone_evaluator ) rubric.add_criteria( dimensionsafety, weight0.1, # 10% of score descriptionNo harmful content, evaluatorsafety_evaluator ) rubric.set_pass_threshold(0.85) # Must score 85% to pass源码实现evaluation_engineering.py揭示了评分机制的底层细节ScoringCriteria单个评估维度包含dimension维度名、weight权重 0-1、description人类可读描述、evaluator可选的自定义评估函数。其evaluate()方法签名统一为(input_text, output_text, context) - float返回 0.0 到 1.0 的分数未提供评估器时返回 0.0加权聚合ScoringRubric.evaluate()对每个维度计算score * weight后累加得到overall_score同时返回每个维度的score、weight、weighted_score以及passedoverall_score pass_threshold和threshold字段validate_weights()校验所有维度权重之和近似等于 1.0容差 ±0.01从机制上防止权重配置错误默认阈值ScoringRubric构造时pass_threshold默认为 0.990%可通过set_pass_threshold()链式调整。核心概念三Evaluation Runner——执行评测并产出报告Evaluation Runner 用 Golden Dataset 执行你的 AI并用 Rubric 为其打分。from evaluation_engineering import EvaluationRunner # 你的 AI 函数可以是 GPT-4、Claude、自研模型等 def my_ai_function(input_text: str) - str: # AI implementation here return ai_response # 运行评估 runner EvaluationRunner(dataset, rubric, my_ai_function) results runner.run(verboseTrue) print(fPass Rate: {results[pass_rate]*100:.1f}%) print(fAverage Score: {results[average_score]:.2f}) if results[overall_passed]: print( AI meets requirements!) else: print(❌ AI needs improvement) # 调试失败用例 failed runner.get_failed_cases() for case in failed: print(fFailed: {case.case_id}) print(f Input: {case.input}) print(f Expected: {case.expected_output}) print(f Got: {case.actual_output})EvaluationRunner的实现evaluation_engineering.py相当于AI 系统的 pytest其运行流程如下逐用例执行对数据集中每个用例调用ai_function(case.input)获得actual_output并记录毫秒级执行耗时异常兜底若 AI 函数抛出异常输出会被捕获为ERROR: 异常信息而非中断整个评测上下文注入评测时构造context字典包含expected_output、expected_behavior、case_context传给评分标准使评估器可以拿到期望值进行比对聚合统计返回包含total_cases、passed、failed、pass_rate、average_score、threshold、overall_passed、timestamp的摘要字典其中overall_passed判定标准是通过率不低于阈值而非平均分不低于阈值结果持久化save_results(filepath)将详细报告摘要 每条用例的 case_id、得分、输入输出、期望值写入 JSONget_detailed_report()可在内存中获取同一结构。关键洞察一多维评分——正确性不是唯一标准最重要的洞察是仅有正确性是不够的。# 示例客服 Agent # 场景客户问 How do I reset my password? # 回答 AJust click forgot password. Duh. # 正确性100%答案正确 # 语气0%粗鲁 # 总分50%假设 50/50 权重 # 回答 BIm happy to help! Click Forgot Password on the login page. # 正确性100%答案正确 # 语气100%礼貌且有用 # 总分100% # 回答 CI apologize for any confusion. Let me help you with that. # 正确性0%没有回答问题 # 语气100%非常礼貌 # 总分50%假设 50/50 权重这正是评分标准存在的意义答案正确但粗鲁得 5/10 分答案错误但礼貌得 0/10 分。在 example_evaluation_engineering.py 的客服场景中tone_evaluator的实现展示了如何编码语气判断负面短语列表thats stupid、obviously、just、simply、read the manual、not my problem、deal with it、too bad、whatever出现任一负面短语即语气得 0 分正面短语列表sorry、apologize、understand、help、appreciate、thank、happy to、glad to、certainly、absolutely出现 ≥2 个得 1.0 分1 个得 0.7 分0 个得 0.5 分中性。关键洞察二数据集即规范The Dataset is the Spec传统开发流程是先写规范文档再写代码实现它。而在 Eval-DD 中数据集本身就是规范。# 传统规范 # parseDate() 应接受 ISO 8601 格式、美式格式 (MM/DD/YYYY)、 # 欧式格式 (DD/MM/YYYY) 以及 Jan 15, 2024 等可读格式。 # 应返回 ISO 格式 (YYYY-MM-DD) 的日期。 # 无效日期应返回 ERROR。 # Eval-DD 规范通过数据集表达 dataset.add_case(idiso, input2024-01-15, expected2024-01-15) dataset.add_case(idus, input01/15/2024, expected2024-01-15) dataset.add_case(ideu, input15/01/2024, expected2024-01-15) dataset.add_case(idreadable, inputJan 15, 2024, expected2024-01-15) dataset.add_case(idinvalid, input2024-13-01, expectedERROR)数据集比散文式规范更清晰、更精确、更易维护——它既是需求文档又是可执行的测试还是回归基线。关键洞察三边界用例优先Edge Cases First在 Eval-DD 中从第一天起就把注意力放在边界用例上。# 传统 TDD 可能从 happy path 开始 def test_parse_date(): assert parseDate(2024-01-15) 2024-01-15 # Eval-DD 立即枚举边界用例 dataset.add_case(idedge_001, input2024.01.15, expected2024-01-15) # 点分隔 dataset.add_case(idedge_002, input15-JAN-2024, expected2024-01-15) # 大写 dataset.add_case(idedge_003, inputjanuary 15 2024, expected2024-01-15) # 小写 dataset.add_case(idedge_004, input1/5/24, expected2024-01-05) # 短格式 dataset.add_case(idedge_005, input32/01/2024, expectedERROR) # 无效日example_evaluation_engineering.py 中的simple_date_parser_v1是一个只处理 ISO 格式的朴素实现评测它在 25 个用例上的表现会大量失败——这正是 Eval-DD 要传递的信息在旧世界我们会不断堆叠 if/else 补丁在新世界我们让 AI 去处理用评估来约束它。使用示例示例 1日期解析from evaluation_engineering import EvaluationDataset, ScoringRubric, EvaluationRunner # 1. 编写 Golden Dataset这是你的代码 dataset EvaluationDataset(Date Parsing, Test suite for date parsing) # 添加 50 个覆盖所有边界情况的测试用例 for i, (input_str, expected) in enumerate(test_cases): dataset.add_case( idfdate_{i:03d}, inputfParse: {input_str}, expected_outputexpected ) # 2. 编写 Scoring Rubric rubric ScoringRubric(Date Parser Rubric, Correctness Clarity) rubric.add_criteria(correctness, 0.7, Correct parse, correctness_eval) rubric.add_criteria(clarity, 0.3, Clear response, clarity_eval) rubric.set_pass_threshold(0.9) # 3. 测试你的 AI runner EvaluationRunner(dataset, rubric, my_ai_parser) results runner.run() # 4. 迭代直到通过 if not results[overall_passed]: print(Failed cases:) for case in runner.get_failed_cases(): print(f {case.case_id}: {case.input}) # 改进 AI重新训练、调整提示词等 # 再次运行在真实示例中example_evaluation_engineering.py日期解析评分标准使用了两个自定义评估器correctness_evaluator从输出中提取实际日期检查期望值是否出现在输出中兼容多余文本对ERROR场景检查输出是否包含error或invalid字样clarity_evaluator按输出长度评分——过短10 字符得 0.3过长200 字符得 0.7适中得 1.0。示例 2客服 Agent# 1. 带行为期望的 Golden Dataset dataset EvaluationDataset(Customer Service, CS agent evaluation) dataset.add_case( idcomplaint_001, inputMy order is late!, expected_behaviorApologize, show empathy, offer solution, tags[complaint, empathy] ) dataset.add_case( idtechnical_001, inputHow do I reset password?, expected_outputClick Forgot Password, check email, tags[technical] ) # 2. 多维评分标准 rubric ScoringRubric(CS Agent Rubric, Quality Tone Safety) rubric.add_criteria(correctness, 0.5, Solves problem, solve_eval) rubric.add_criteria(tone, 0.4, Polite and helpful, tone_eval) rubric.add_criteria(safety, 0.1, No harmful content, safety_eval) rubric.set_pass_threshold(0.85) # 3. 运行评估 runner EvaluationRunner(dataset, rubric, cs_agent) results runner.run()这里用到了expected_behavior期望行为字段——当输出无法用单一字符串断言时如投诉处理、礼貌回应用行为描述代替精确输出。示例数据集覆盖了投诉、技术问题、敌意用户、退款咨询、升级推销五种典型客服场景见 example_evaluation_engineering.py。示例 3代码生成# 从多个维度评估代码生成 dataset EvaluationDataset(Code Generation, Python function generation) dataset.add_case( idcode_001, inputWrite a function to calculate factorial, expected_behaviorCorrect implementation, handles edge cases, includes docstring, tags[python, recursion] ) rubric ScoringRubric(Code Quality, Multi-dimensional code evaluation) rubric.add_criteria(correctness, 0.4, Code works, correctness_eval) rubric.add_criteria(efficiency, 0.2, Time complexity, efficiency_eval) rubric.add_criteria(readability, 0.2, Clear and documented, readability_eval) rubric.add_criteria(safety, 0.2, Handles edge cases, safety_eval)自定义评估器为任意维度编写评分函数你可以为任何维度编写自定义评估器def tone_evaluator(input_text: str, output_text: str, context: Any) - float: 评估回应的语气。 返回 0.0粗鲁到 1.0礼貌。 output_lower output_text.lower() # 负面指标 rude_words [stupid, idiot, obviously, duh] if any(word in output_lower for word in rude_words): return 0.0 # 正面指标 polite_words [please, thank you, happy to help, sorry] polite_count sum(1 for word in polite_words if word in output_lower) if polite_count 2: return 1.0 elif polite_count 1: return 0.7 else: return 0.5 # 中性 rubric.add_criteria( dimensiontone, weight0.4, descriptionPoliteness and empathy, evaluatortone_evaluator )评估器函数的统一签名是(input_text: str, output_text: str, context: Any) - floatcontext字典中可访问expected_output、expected_behavior和case_context。除了自定义函数框架内置了四个可复用的评估器evaluation_engineering.py内置评估器行为关键实现细节exact_match_evaluator精确字符串匹配期望值为空时返回 0.5中性strip()后比较contains_keywords_evaluator(keywords)检查输出是否包含必需关键词按关键词命中比例打分命中数 / 关键词总数length_check_evaluator(min_length, max_length)校验响应长度过短返回length/min_length过长返回max_length/length范围内返回 1.0no_harmful_content_evaluator(harmful_keywords)筛查有害内容命中任一有害关键词立即返回 0.0一票否决这些内置评估器都有对应的单元测试验证其边界行为见 test_evaluation_engineering.py例如contains_keywords_evaluator([hello, world])对hello world返回 1.0、对hello there返回 0.5、对goodbye返回 0.0。最佳实践1. 从数据集开始Start with the Dataset在写任何代码之前先创建黄金数据集。这会迫使你思考系统应处理哪些输入期望的输出是什么存在哪些边界用例哪些质量维度重要2. 让边界用例显式化Make Edge Cases Explicit不要依赖系统应该处理无效输入这种模糊表述逐条枚举它们# 不好模糊 # The system should handle invalid inputs # 好显式 dataset.add_case(idempty_input, input, expectedERROR) dataset.add_case(idnull_input, inputnull, expectedERROR) dataset.add_case(idspecial_chars, input#$%, expectedERROR) dataset.add_case(idvery_long, inputx*10000, expectedERROR)3. 权衡维度权重Weight Your Dimensions仔细思考每个维度的相对重要性# 面向客户的系统语气很重要 rubric.add_criteria(correctness, 0.5, ...) rubric.add_criteria(tone, 0.4, ...) # 几乎和正确性一样重要 rubric.add_criteria(safety, 0.1, ...) # 内部工具正确性最重要 rubric.add_criteria(correctness, 0.8, ...) rubric.add_criteria(efficiency, 0.15, ...) rubric.add_criteria(clarity, 0.05, ...)权重配置完成后可用框架内置的validate_weights()校验权重和是否为 1.0。4. 为数据集做版本管理Version Your Datasets把数据集当作源代码对待dataset.metadata { version: 2.0, created_at: 2024-01-15, author: engineering_team, changes: Added 20 new edge cases for emoji handling }结合EvaluationDataset.save()/EvaluationDataset.load()数据集可以像代码一样提交、评审、回滚。5. 基于失败迭代Iterate Based on Failures用例失败时用它们来改进# 运行评估 runner EvaluationRunner(dataset, rubric, ai_function) results runner.run() # 分析失败 for case in runner.get_failed_cases(): print(f\nFailed: {case.case_id}) print(fScore: {case.scores[overall_score]:.2f}) print(fInput: {case.input}) print(fExpected: {case.expected_output}) print(fGot: {case.actual_output}) # 维度分解 for dim, scores in case.scores[dimension_scores].items(): print(f {dim}: {scores[score]:.2f}) # 利用失败信息 # 1. 增加更多训练数据 # 2. 调整提示词 # 3. 微调模型 # 4. 更新评分标准权重6. 随时间追踪进度Track Progress Over Time保存结果以追踪改进# 每次迭代后 runner.save_results(fresults_{version}_{timestamp}.json) # 对比版本 v1_results load_results(results_v1.json) v2_results load_results(results_v2.json) print(fV1 Pass Rate: {v1_results[pass_rate]:.1%}) print(fV2 Pass Rate: {v2_results[pass_rate]:.1%}) print(fImprovement: {(v2_results[pass_rate] - v1_results[pass_rate]):.1%})API 参考完整 API 详见 evaluation_engineering.py。核心类类职责关键成员EvaluationDataset测试用例容器黄金数据集add_case、get_cases_by_tag、get_cases_by_difficulty、save、loadEvaluationCase单个测试用例id、input、expected_output、expected_behavior、context、tags、difficulty、to_dictScoringRubric多维评估标准add_criteria链式、set_pass_threshold、evaluate、validate_weightsScoringCriteria单个评估维度dimension、weight、description、evaluator、evaluateEvaluationRunner执行评估并生成报告run、get_failed_cases、get_detailed_report、save_resultsEvaluationResult单用例评估结果case_id、actual_output、scores、passed、execution_time_ms等ScoreType评分维度枚举CORRECTNESS、TONE、COMPLETENESS、CLARITY、SAFETY、EFFICIENCY、CUSTOM核心函数exact_match_evaluator精确字符串匹配检查contains_keywords_evaluator(keywords)检查必需关键词返回工厂函数length_check_evaluator(min_length, max_length)校验响应长度返回工厂函数no_harmful_content_evaluator(harmful_keywords)筛查有害内容返回工厂函数运行示例与测试整个示例模块位于仓库的agent-governance-python/agent-os/examples/self-evaluating/目录# 安装依赖 pip install -r requirements.txt # 运行主演示 python examples/example_evaluation_engineering.py # 运行测试无需 API Key python tests/test_evaluation_engineering.py说明演示脚本example_evaluation_engineering.py包含两个 DemoDemo 1 用 25 个刁钻日期串对比朴素实现与 AI 实现gpt-4o-minitemperature0.1的表现Demo 2 用多维评分标准评估 AI 客服temperature0.7。AI 相关部分需要设置OPENAI_API_KEY环境变量未设置时会优雅降级仅演示朴素实现测试套件test_evaluation_engineering.py不依赖任何 API 调用覆盖EvaluationCase、数据集创建与过滤、持久化、评分标准、四个内置评估器、完整评估流程、完美 AI 场景、多维评分、结果保存共 12 组测试更详细的框架安装与环境配置可参考 GETTING_STARTED.md 与 README.md该模块的落地总结见 IMPLEMENTATION_SUMMARY_EVALUATION_ENGINEERING.md。与自进化 Agent 的集成形成评估 → 进化 → 再评估闭环评估工程框架可以自然融入自进化 Agent 系统from agent import DoerAgent from observer import ObserverAgent from evaluation_engineering import EvaluationDataset, ScoringRubric, EvaluationRunner # 创建评估套件 dataset create_my_dataset() rubric create_my_rubric() # 包装 DoerAgent 用于评估 def ai_function(input_text: str) - str: doer DoerAgent() result doer.run(input_text, verboseFalse) return result[response] # 运行评估 runner EvaluationRunner(dataset, rubric, ai_function) results runner.run() # 未通过则触发进化 if not results[overall_passed]: observer ObserverAgent() observer.process_events() # 从失败中学习在 self-evaluating 框架中DoerAgent 负责快速执行任务ObserverAgent 通过process_events()observer.py离线批处理遥测事件、学习失败模式并改进智慧数据库。评估工程为这个闭环提供了量化判据只有评测不通过时才触发进化进化后再评估如此往复——这就是评估 → 进化 → 再评估的闭环。结语评估套件是未来 AI 系统的源代码评估工程代表了构建 AI 系统方式的根本性转变。不再编写parseDate()而是编写parseDate()必须通过的考试不再手写客服话术而是编写定义质量的标准。在 AI 生成实现的今天工程师的角色从写代码转向四个核心职责定义质量Defining Quality在多个维度上好长什么样枚举边界用例Enumerating Edge Cases所有刁钻场景是什么设定标准Setting Standards多大的通过阈值可以接受基于数据迭代Iterating Based on Data如何根据失败持续改进未来的源代码不再是应用逻辑而是约束它的评估套件。这就是评估工程——TDD 向 Eval-DD 的演进也是 AI 时代资深工程师创造价值的方式。如果你正在为 Agent Governance Toolkit 中的 AI Agent 构建治理与质量体系不妨从编写第一份 Golden Dataset 开始。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考