adk-python 评估数据文件解析：`.test.json` 与 `.evalset.json` 的同源异用-北京尧图网络

adk-python 评估数据文件解析.test.json与.evalset.json的同源异用【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读在 Google ADKAgent Development Kit的 Python 实现adk-python中.test.json与.evalset.json其实承载的是同一套EvalSetPydantic 数据模型二者由同一个加载函数按 Schema 校验、由同一条adk eval命令驱动。本文以仓库中 test_file_vs_evalset 示例为骨架结合src/google/adk/evaluation下的源码实现讲清两种文件后缀的命名约定、文件结构、命令行运行方式、评估指标配置IN_ORDER轨迹匹配与 ROUGE-1 文本匹配以及如何让同一份数据同时被pytest复用。读完本文你将能够为任意 Agent 编写、配置并运行单元级与集成级的离线评估。同一个 EvalSet扩展名只是命名约定一切始于EvalSetSchema无论是.test.json还是.evalset.json文件内容都会被解析为同一个EvalSet模型。该模型定义在 src/google/adk/evaluation/eval_set.py核心字段包括字段类型含义eval_set_idstr必填评估集的唯一标识nameOptional[str]数据集名称descriptionOptional[str]数据集描述eval_caseslist[EvalCase]评估用例列表每个用例代表一次待评估的交互creation_timestampfloat默认0.0数据集创建时间EvalCase模型位于 src/google/adk/evaluation/eval_case.py每个用例包含eval_id、conversation静态多轮对话或conversation_scenario交给 UserSimulator 动态生成二者二选一、session_input会话初始化输入如app_name、user_id、初始state等字段。conversation中的每一轮是一个Invocation见 eval_case.py由以下部分组成invocation_id本轮调用的唯一标识user_content用户输入内容final_response期望的 Agent 最终回复ground truthintermediate_data期望的中间过程数据其中tool_uses记录了按时间顺序排列的期望工具调用轨迹工具名参数。load_eval_set_from_file按 Schema 校验而非按扩展名adk eval之所以能用同一条命令加载两种后缀的文件关键在于加载函数不关心文件扩展名。在 src/google/adk/evaluation/local_eval_sets_manager.py 中def load_eval_set_from_file(eval_set_file_path: str, eval_set_id: str) - EvalSet: with open(eval_set_file_path, r, encodingutf-8) as f: content f.read() try: return EvalSet.model_validate_json(content) except ValidationError: # 若新 Schema 校验失败则假设数据为旧格式并尝试转换 return convert_eval_set_to_pydantic_schema(eval_set_id, json.loads(content))函数首先用EvalSet.model_validate_json直接按 Pydantic Schema 校验 JSON只有当新格式校验失败时才会回退到旧版 eval 数据格式的转换逻辑convert_eval_set_to_pydantic_schema同样位于该文件中负责把query/reference/expected_tool_use等旧字段映射到新的Invocation结构。因此扩展名对加载结果没有任何影响——foo.test.json、foo.evalset.json甚至foo.json都能被正常加载只要内容满足 Schema。两种后缀的定位单元测试 vs 集成测试既然 Schema 相同两种扩展名便只是一种命名约定用于表达数据的规模与意图.test.json—— 单元测试约定包含一个简单、聚焦的 session保持小而精对应单个单元测试.evalset.json—— 集成测试约定将多个更长、更多轮次的 session 组织在一起对应集成测试。这种约定的价值在于团队协作与 CI 语义扫描代码库时.test.json可以让开发者一眼识别出轻量级回归用例.evalset.json则标识出覆盖完整业务链路的场景集。样例资产剖析一个 Agent两份评估数据本示例针对共享的智能家居 Agenthome_automation_agent各提供一份数据文件。该 Agent 由内存字典模拟设备状态所有工具get_device_info、set_device_info、get_temperature、set_temperature、list_devices都是确定性的保证评估轨迹可复现模块内的reset_data()会被adk eval在每个 eval case 之间调用重置状态避免用例间相互污染。single_turn.test.json单轮单元测试文件位于 contributing/samples/evaluation/test_file_vs_evalset/single_turn.test.json仅包含 1 个 session、1 轮对话用户提问Whats the temperature in the Kitchen?期望最终回复The temperature in the Kitchen is 24 degrees Celsius.期望工具调用get_temperature参数{location: Kitchen}对应eval_id为kitchen_temperaturesession_input中app_name为home_automation_agent、user_id为user、state为空。这就是典型的一个断言点的单元级用例验证 Agent 收到特定问题后会调用正确的工具并给出正确的回复。multi_session.evalset.json多会话集成测试文件位于 contributing/samples/evaluation/test_file_vs_evalset/multi_session.evalset.json包含 2 个 sessionlist_then_turn_off两轮第 1 轮Which devices are on?→ 期望调用list_devices参数{status: ON}期望回复列出开启的设备第 2 轮Turn that one off.→ 期望调用set_device_info参数{device_id: device_1, status: OFF}期望回复确认已关闭。set_bedroom_temperature单轮Set the Bedroom to 21 degrees.→ 期望调用set_temperature参数{location: Bedroom, temperature: 21}。这个文件示范了集成测试的两个关键特征多会话两个独立场景与多轮上下文依赖第二轮Turn that one off.依赖第一轮返回的设备信息验证 Agent 的上下文记忆与指代消解能力。运行评估同一条adk eval命令命令与参数两种文件使用完全相同的adk eval命令唯一变化的是评估数据路径。在仓库根目录下执行运行.test.jsonadk eval contributing/samples/evaluation/home_automation_agent \ contributing/samples/evaluation/test_file_vs_evalset/single_turn.test.json \ --config_file_path contributing/samples/evaluation/test_file_vs_evalset/eval_config.json \ --print_detailed_results运行.evalset.jsonadk eval contributing/samples/evaluation/home_automation_agent \ contributing/samples/evaluation/test_file_vs_evalset/multi_session.evalset.json \ --config_file_path contributing/samples/evaluation/test_file_vs_evalset/eval_config.json \ --print_detailed_results两个位置参数分别为agent_module_file_pathAgent 模块所在目录必须是包含agent.py的目录且模块中定义root_agent或get_agent_asynceval_set_file_path_or_id可接受一个或多个评估数据文件路径或已注册的 eval set id文件路径与 id 不可混用。--print_detailed_results会在控制台打印Actual-vs-Expected 对照表逐轮对比 Agent 真实的工具调用与回复和文件中的期望值。从 src/google/adk/cli/cli_eval.py 的pretty_print_eval_result实现可以看到该表格以 DataFrame 形式输出每行包含prompt、expected_response、actual_response、expected_tool_calls、actual_tool_calls并为每个指标附加Status与Score列。命令的底层调用链从 src/google/adk/cli/cli_tools_click.py 可以看到cli_eval的完整流程解析参数后parse_and_get_evals_to_run将位置参数解析为{文件路径或 eval set id: [要运行的 eval_id 列表]}的映射若第一个参数是已存在的文件则切换到InMemoryEvalSetsManager对每个文件调用load_eval_set_from_file加载为EvalSet再逐个把eval_cases灌入内存管理器通过get_evaluation_criteria_or_default读取--config_file_path指定的评估配置见下文构建InferenceRequest交给LocalEvalService执行推理与指标计算。顺带一提如果省略--config_file_path且只传入单个eval 文件CLI 会自动回退到test_config.json作为配置见 cli_tools_click.py 的_resolve_eval_config_file_path——这与AgentEvaluator的约定保持一致。只运行部分用例如果只想运行某个文件中的特定 eval case可以在文件路径后追加:和逗号分隔的 eval id例如adk eval contributing/samples/evaluation/home_automation_agent \ contributing/samples/evaluation/test_file_vs_evalset/multi_session.evalset.json:list_then_turn_off \ --config_file_path contributing/samples/evaluation/test_file_vs_evalset/eval_config.json \ --print_detailed_results评估配置深入eval_config.json示例的评估配置位于 contributing/samples/evaluation/test_file_vs_evalset/eval_config.json{ criteria: { tool_trajectory_avg_score: {threshold: 1.0, match_type: IN_ORDER}, response_match_score: 0.6 } }配置的加载与解析在 src/google/adk/evaluation/eval_config.py 中完成若指定路径存在则以EvalConfig.model_validate_json解析否则回退到内置默认配置——tool_trajectory_avg_score: 1.0、response_match_score: 0.8见 eval_config.py。也就是说省略--config_file_path时评估仍可运行只是文本匹配阈值会更严格0.8。tool_trajectory_avg_score工具轨迹匹配该指标比较 Agent 实际工具调用轨迹与文件中期望的工具调用轨迹工具名参数。MatchType枚举定义在 src/google/adk/evaluation/eval_metrics.py共有三种取值EXACT默认要求实际工具调用与期望完全一致IN_ORDER期望的工具调用必须按给定顺序出现允许中间穿插额外工具调用ANY_ORDER期望的工具调用只需全部出现不关心顺序适合发起多次同类搜索等场景。示例配置选择了IN_ORDER期望调用必须按序出现但实际执行中插入的额外调用会被容忍。例如期望[T1, T2, T3]实际为[T1, T1.1, T2, T2.1, T2.2, T3, T3.1]即满足条件而一旦某个期望调用缺失如期望 4 个只出现 3 个则该指标失败。threshold设为1.0意味着每条期望调用名称参数都必须命中一次真实调用。此外ToolTrajectoryCriterion还提供ignore_args字段默认False设为True时只比较工具名、忽略参数见 eval_metrics.py适用于参数值本身不重要、只关心是否调用了正确工具的断言。response_match_scoreROUGE-1 文本匹配response_match_score使用ROUGE-1 unigram 重叠分数来比较 Agent 的真实回复与期望回复。之所以使用模糊匹配而非精确匹配是为了容忍真实推理live inference带来的措辞变化——只要关键词重叠度足够语义一致的回复即可通过。实现位于 src/google/adk/evaluation/final_response_match_v1.py 的RougeEvaluator判分规则为score threshold即PASSED见 final_response_match_v1.py。值得注意的是该项目使用自定义的_UnicodeAwareTokenizer见 final_response_match_v1.py默认的rouge_score分词器会丢弃非[a-z0-9]字符导致中文、泰文等非拉丁文字文本永远得 0 分该分词器通过 NFKC 归一化、按字符切分 CJK、按字素簇聚合泰文等逻辑使 ROUGE-1 在非拉丁语言上依然有效。示例将response_match_score阈值设为0.6期望回复与真实回复的 ROUGE-1 分数达到 0.6 即视为通过。与pytest复用AgentEvaluator.evaluate自动发现.test.json除了adk evalCLI同一份.test.json文件还可以直接由 Python 测试驱动。AgentEvaluator定义在 src/google/adk/evaluation/agent_evaluator.py其静态方法evaluate有以下行为传入目录时会递归扫描该目录下所有以.test.json结尾的文件并逐一评估见 agent_evaluator.py传入单个文件时直接评估该文件配置文件的自动查找遵循约定在 test 文件同目录下寻找test_config.jsonfind_config_for_test_file见 agent_evaluator.py评估结束时若有失败会抛出断言assert not failures天然适配 pytest 的失败语义。因此一个典型的 pytest 测试可以这样写示例本身只用adk eval此用法来自源码契约from google.adk.evaluation.agent_evaluator import AgentEvaluator def test_home_automation_agent(): AgentEvaluator.evaluate( agent_modulecontributing/samples/evaluation/home_automation_agent, eval_dataset_file_path_or_dircontributing/samples/evaluation/test_file_vs_evalset/single_turn.test.json, print_detailed_resultsTrue, )这种设计意味着你只需维护一份评估数据既能在 CI 中通过adk eval批量跑也能嵌入 pytest 做针对性回归。实践建议如何选择两种约定首选.test.json当验证目标是给定输入Agent 是否调用正确工具、给出正确回复这样的单一、原子化行为时。文件保持小而聚焦配合AgentEvaluator.evaluate的目录扫描能力可以按目录组织成一组单元测试套件。首选.evalset.json当验证目标是覆盖完整业务链路如多轮指代消解、跨轮状态保持、多场景组合时。把多个相关场景聚合到一个文件中运行一次命令即可获得整体通过率。评估配置始终独立无论数据文件用哪种后缀评估标准轨迹匹配方式、文本匹配阈值都由eval_config.json或默认配置统一控制做到数据与断言分离。总结.test.json与.evalset.json是 adk-python 评估体系中一对形异而神同的文件约定底层共享同一套EvalSet/EvalCasePydantic Schema由load_eval_set_from_file按 Schema而非扩展名加载由同一条adk eval命令执行并可被AgentEvaluator.evaluate无缝接入 pytest。区别仅在于数据规模与语义定位——前者是单元测试后者是集成测试。理解这一约定再配合IN_ORDER/ANY_ORDER轨迹匹配与 ROUGE-1 文本匹配的灵活配置你就能为 Agent 构建一套既能快速回归、又能深度验证的离线评估体系。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

adk-python 评估数据文件解析：`.test.json` 与 `.evalset.json` 的同源异用

相关推荐

GTK4 窗口

语音助手abort后旧声音不灭？深入解析中断机制与音频链路设计

Spring Cloud Alibaba电商微服务实战：Nacos+Gateway+多数据源

更多资讯

Zulip Heroku 集成：将应用构建与发布事件实时推送到团队聊天

移动电源新国标落地难点：锂保与SOC协同设计实战

PLC直连扫码支付：串口与Modbus RTU工业接入实战

Unleashed 固件 JS SDK 开发指南：用 `gui/dialog` 模块构建三按钮交互对话框

Verilog CPU课程设计：从单周期到五级流水线实战指南

改进非洲秃鹫优化算法(IAVOA)原理与应用

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？