HelloAgents 第十二章智能体性能评估实战——BFCL、GAIA 与数据生成质量评估全流程【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本文是《从零开始构建智能体》HelloAgents第十二章《智能体性能评估》的实战指南围绕仓库 code/chapter12 目录下 9 个示例脚本展开。你将掌握 BFCL 工具调用评估、GAIA 通用能力评估以及 LLM Judge / Win Rate 数据生成质量评估三大场景的完整操作流程并理解每个评估背后的底层组件与最佳实践能够直接复制代码为自己的智能体建立可量化的评估体系。1. 为什么需要智能体评估从基础示例说起在 HelloAgents 框架中我们已经拥有了具备推理与工具调用能力的SimpleAgent。例如 01_basic_agent_example.py 展示了这样一段典型用法from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import SearchTool llm HelloAgentsLLM() system_prompt 你是一个AI助手可以使用搜索工具来获取最新信息。 当需要搜索信息时请使用以下格式 [TOOL_CALL:search:搜索关键词] 例如 - [TOOL_CALL:search:最新AI新闻] - [TOOL_CALL:search:Python编程教程] 请在回答问题前先使用搜索工具获取最新信息。 agent SimpleAgent(nameAI助手, llmllm, system_promptsystem_prompt) agent.add_tool(SearchTool()) response agent.run(最新的AI技术发展趋势是什么) print(f\n回答{response})这个智能体可以正常工作但我们立刻面临三个核心问题当优化 Prompt 或更换 LLM 模型后如何判断效果是否真的变好在不同任务上智能体的表现究竟如何与其它智能体相比它处于什么水平这些问题无法靠肉眼观察解决必须借助系统化的评估Evaluation用统一的测试数据集、统一的评分算法把智能体能力量化为具体指标。与传统软件测试不同智能体评估面临三个独特挑战输出不确定性同一问题可能有多个正确答法无法简单地用对/错判定评估标准多样性工具调用要检查函数签名是否正确问答任务要评估语义相似度需要不同的评估方法评估成本高每次评估都要消耗大量 LLM API 调用。为此学术界与工业界提出了多个标准化Benchmark提供统一的数据集、指标与评分方法。HelloAgents 第十二章从中选择了三个最契合学习与实战的场景评估场景评估对象典型 Benchmark / 方法工具调用能力函数调用准确率BFCLBerkeley Function Calling Leaderboard通用 AI 助手能力多步推理、工具使用、问题求解GAIAGeneral AI Assistants数据生成质量生成题目的质量LLM Judge、Win Rate、人工验证仓库 code/chapter12 中的 9 个示例脚本正是围绕这三类场景组织的对应关系如下表文件名对应章节说明01_basic_agent_example.py12.1.1基础智能体示例说明为何需要评估02_bfcl_quick_start.py12.2.5BFCL 快速开始一键评估03_bfcl_custom_evaluation.py12.2.5BFCL 自定义评估底层组件04_run_bfcl_evaluation.py12.2.9BFCL 评估最佳实践05_gaia_quick_start.py12.3.5GAIA 快速开始一键评估06_gaia_best_practices.py12.3.9GAIA 评估最佳实践07_data_generation_complete_flow.py12.4.6数据生成完整评估流程08_data_generation_llm_judge.py12.4.3LLM Judge 评估09_data_generation_win_rate.py12.4.4Win Rate 评估2. 环境准备三步完成评估前置条件在运行任何评估示例之前需要完成三项准备工作。2.1 安装 HelloAgents 评估组件pip install hello-agents[evaluation]0.2.3[evaluation]是 extras 依赖标记会一并安装评估所需的 BFCL / GAIA 工具组件。如果开发环境下已经克隆了框架源码也可以用可编辑模式安装cd ../HelloAgents pip install -e .2.2 设置环境变量# OpenAI API Key用于 GPT-4o也是默认评估/生成模型 export OPENAI_API_KEYyour_openai_api_key # HuggingFace Token用于 GAIA 数据集鉴权下载 export HF_TOKENyour_huggingface_token两个变量的职责不同OPENAI_API_KEY驱动评估过程中的 LLM 调用GPT-4oHF_TOKEN则用于从 HuggingFace 拉取 GAIA 受限数据集。2.3 下载 BFCL 数据集可选BFCL 数据集首次运行时通常会自动下载如果下载失败或需要离线准备可手动克隆官方仓库cd ../HelloAgents git clone https://github.com/ShishirPatil/gorilla.git temp_gorilla克隆后BFCL 测试数据位于temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data目录03_bfcl_custom_evaluation.py 中的BFCLDataset默认路径即指向此处。3. BFCL 评估衡量智能体工具调用能力BFCLBerkeley Function Calling Leaderboard由加州大学伯克利分校推出包含 1120 测试样本覆盖简单、多重、并行、无关调用等类别采用 AST抽象语法树匹配算法判断函数调用是否准确。它是衡量智能体会不会正确调用工具的主流基准。3.1 方式一一行代码完成一键评估02_bfcl_quick_start.py 展示了最简用法——通过BFCLEvaluationTool的run()方法自动完成数据加载、评估、报告生成与官方评估from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import BFCLEvaluationTool llm HelloAgentsLLM() agent SimpleAgent(nameTestAgent, llmllm) bfcl_tool BFCLEvaluationTool() results bfcl_tool.run( agentagent, categorysimple_python, # 评估类别 max_samples5 # 评估样本数0 表示全部 ) print(f准确率: {results[overall_accuracy]:.2%}) print(f正确数: {results[correct_samples]}/{results[total_samples]})运行输出大致如下 BFCL一键评估 配置: 智能体: TestAgent 类别: simple_python 样本数: 5 评估进度: 100%|██████████| 5/5 [00:1500:00, 3.12s/样本] ✅ 评估完成 总样本数: 5 正确样本数: 5 准确率: 100.00% 准确率: 100.00% 正确数: 5/5关键参数说明categoryBFCL 的评估类别例如simple_python、multiple、parallel、irrelevance等max_samples抽取的样本数设为0表示使用全部样本用于快速验证时通常设为 510。3.2 方式二用底层组件实现自定义评估流程当默认的一键评估无法满足定制需求时03_bfcl_custom_evaluation.py 展示了如何拆解评估流水线直接使用BFCLDataset与BFCLEvaluator两个底层组件from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.evaluation import BFCLDataset, BFCLEvaluator llm HelloAgentsLLM() agent SimpleAgent(nameTestAgent, llmllm) # 1. 加载数据集 dataset BFCLDataset( bfcl_data_dir./temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data, categorysimple_python ) data dataset.load() print(f✅ 加载了 {len(data)} 个测试样本) # 2. 创建评估器 evaluator BFCLEvaluator(datasetdataset, categorysimple_python) # 3. 运行评估只评估 5 个样本 results evaluator.evaluate(agentagent, max_samples5) # 4. 查看结果 print(f总样本数: {results[total_samples]}) print(f正确样本数: {results[correct_samples]}) print(f准确率: {results[overall_accuracy]:.2%}) # 5. 查看每个样本的详细结果 for detail in results[detailed_results]: print(f样本 {detail[sample_id]}:) print(f 问题: {detail[question][:50]}...) print(f 预测: {detail[predicted]}) print(f 正确答案: {detail[expected]}) print(f 结果: {✅ 正确 if detail[success] else ❌ 错误}) # 6. 导出结果 evaluator.export_results(results, output_file./evaluation_results/bfcl_custom_result.json)自定义流程的价值在于你可以逐样本检查预测与标准答案定位具体是哪些函数调用出错评估结果会导出为 JSON 文件便于后续统计分析。3.3 最佳实践一键评估脚本的五步流水线04_run_bfcl_evaluation.py 是 BFCL 评估的完整落地脚本它将整个评估过程串成五步自动检查和准备 BFCL 数据运行 HelloAgents 评估导出 BFCL 格式结果调用 BFCL 官方评估工具展示评估结果。脚本支持三个命令行参数python 04_run_bfcl_evaluation.py \ --category simple_python \ # 评估类别默认simple_python --samples 5 \ # 样本数量默认5设为 0 表示全部 --model-name Qwen/Qwen3-8B # 模型名称默认Qwen/Qwen3-8B必须是 BFCL 支持的模型脚本中值得关注的两个实现细节1函数调用系统提示词。脚本内置了一段FUNCTION_CALLING_SYSTEM_PROMPT要求智能体输出纯 JSON 数组格式的函数调用结果例如用户问题查询北京的天气 可用函数get_weather(city: str) 正确输出[{name: get_weather, arguments: {city: 北京}}]同时在创建SimpleAgent时设置enable_tool_callingFalse让评估聚焦于函数调用文本是否正确生成这一核心能力。2与官方评估工具的对接。脚本将 HelloAgents 的评估结果导出为 BFCL 官方格式文件BFCL_v4_{category}_result.json复制到 BFCL 约定的结果目录注意官方工具会把模型名中的/替换为_然后调用官方 CLI 完成最终评分bfcl evaluate --model Qwen/Qwen3-8B --test-category simple_python --partial-eval如果环境中未安装bfcl命令脚本会提示先执行pip install bfcl-eval。官方评估完成后评分会写入score/data_non_live.csv与score/{model_name}/non_live/BFCL_v4_{category}_score.json脚本会自动读取并打印最终准确率。这个脚本体现了 BFCL 评估的四种最佳实践渐进式评估先小样本再全量、多类别评估、对比评估更换模型/提示词对比与错误分析。4. GAIA 评估衡量智能体通用问题求解能力GAIAGeneral AI Assistants由 Meta AI 与 Hugging Face 联合推出包含 466 个贴近真实世界的问题按难度分为 Level 1/2/3 三级考察多步推理、工具使用、文件处理、网页浏览等综合能力采用 Quasi Exact Match 算法评分。它是衡量通用 AI 助手能力的代表性基准。4.1 申请数据集访问权限重要前置步骤GAIA 是受限数据集无法直接下载需要先申请访问权限访问 HuggingFace 数据集页面gaia-benchmark/GAIA点击 Request Access 申请访问权限等待审核通过通常 12 天审核通过后设置HF_TOKEN环境变量。不完成这步GAIAEvaluationTool在加载数据时会因权限不足而失败。4.2 快速开始一行代码完成 GAIA 评估05_gaia_quick_start.py 展示了 GAIA 评估的最简用法。与 BFCL 不同GAIA 对系统提示词有严格要求——必须使用 GAIA 官方系统提示词否则答案格式不符会严重影响评分import os from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import GAIAEvaluationTool # GAIA 官方系统提示词必须使用 GAIA_SYSTEM_PROMPT You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, dont use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, dont use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string. # 创建智能体必须使用 GAIA 官方系统提示词 llm HelloAgentsLLM() agent SimpleAgent( nameTestAgent, llmllm, system_promptGAIA_SYSTEM_PROMPT ) # 创建 GAIA 评估工具 gaia_tool GAIAEvaluationTool() # 运行评估 results gaia_tool.run( agentagent, level1, # 评估级别1简单2中等3困难 max_samples2, # 评估样本数0 表示全部 export_resultsTrue, # 导出结果到 GAIA 官方格式 generate_reportTrue # 生成详细报告 ) print(f精确匹配率: {results[exact_match_rate]:.2%}) print(f部分匹配率: {results[partial_match_rate]:.2%}) print(f正确数: {results[correct_samples]}/{results[total_samples]})运行输出大致如下 GAIA一键评估 配置: 智能体: TestAgent 级别: Level 1 样本数: 2 ✅ GAIA数据集加载完成 数据源: gaia-benchmark/GAIA 分割: validation 级别: 1 样本数: 2 评估进度: 100%|██████████| 2/2 [00:1000:00, 5.23s/样本] ✅ 评估完成 总样本数: 2 正确样本数: 2 精确匹配率: 100.00% 部分匹配率: 100.00% ✅ 结果已导出到 ./evaluation_results/gaia_submission.json ✅ 报告已生成到 ./evaluation_results/gaia_report.md 评估结果: 精确匹配率: 100.00% 部分匹配率: 100.00% 正确数: 2/2GAIA 评估结果有两个核心指标注意区分精确匹配率exact_match_rate答案与标准答案完全一致的样本占比是主指标部分匹配率partial_match_rate答案部分命中的样本占比用于参考。同时脚本支持export_results导出官方提交格式gaia_submission.json与generate_report生成详细报告gaia_report.md便于后续提交官方榜单或人工复盘。4.3 最佳实践分级评估、小样本测试与结果解读06_gaia_best_practices.py 把 GAIA 评估沉淀为三条可复用的最佳实践。最佳实践 1分级评估由易到难递进GAIA 的 Level 1/2/3 难度递增评估时应遵循先简单后困难的阶梯式策略——只有低级别表现达标才继续评估更高级别# 第一步评估 Level 1简单任务 results_l1 gaia_tool.run(agent, level1, max_samples10) # 第二步如果 Level 1 表现良好评估 Level 2 if results_l1[exact_match_rate] 0.6: results_l2 gaia_tool.run(agent, level2, max_samples10) # 第三步如果 Level 2 表现良好评估 Level 3 if results_l2[exact_match_rate] 0.4: results_l3 gaia_tool.run(agent, level3, max_samples10)这种策略能快速暴露智能体的能力边界Level 1 都达不到 60% 时投入更多成本评估 Level 3 意义不大。最佳实践 2小样本快速测试在完整评估前先用每个级别 2 个样本做冒烟测试几秒钟即可判断评估链路是否通畅、提示词是否生效for level in [1, 2, 3]: results gaia_tool.run(agent, levellevel, max_samples2) print(f快速测试 Level {level}: 精确匹配率 {results[exact_match_rate]:.2%})最佳实践 3结果解读与难度递进分析脚本内置了分级的达标阈值与改进建议帮助开发者把指标转化为行动项级别优秀良好不达标时的改进建议Level 1≥ 60%≥ 40%检查系统提示词是否包含 GAIA 官方格式要求、检查答案提取逻辑、更换更强的 LLMLevel 2≥ 40%≥ 20%增强多步推理能力、增加工具使用能力、优化推理链构建Level 3≥ 20%≥ 10%增强复杂推理、长上下文处理、工具链组合使用此外脚本还会做难度递进分析正常情况下Level 1 Level 2 Level 3若出现反超如 Level 2 ≥ Level 1则提示可能存在数据集偏差或智能体特性问题需要进一步排查。5. 数据生成质量评估LLM Judge 与 Win Rate第三个评估场景聚焦智能体生成数据的质量——这在为模型构造训练/测试数据时尤为关键。本仓库以生成 AIME 数学竞赛题目为例将评估任务交给 LLM 自身LLM Judge与对比打分Win Rate并保留人工验证环节。相关的完整工具链位于 code/chapter12/data_generation 目录包含aime_generator.py题目生成器、run_complete_evaluation.py完整流程入口、step1_generate_only.py/step2_evaluate_only.py分步执行以及human_verification_ui.py人工验证界面。5.1 LLM Judge从四个维度打分08_data_generation_llm_judge.py 演示了如何让 LLM 充当裁判从四个维度为生成的题目打分每题 15 分正确性Correctness题目和答案是否正确清晰度Clarity题目表述是否清晰难度匹配Difficulty Match难度是否符合 AIME 水平完整性Completeness题目信息是否完整。核心代码如下from hello_agents import HelloAgentsLLM from hello_agents.evaluation import LLMJudge llm HelloAgentsLLM(model_namegpt-4o) judge LLMJudge(llmllm) # 评估单道题目 result judge.evaluate_single(problem) print(f正确性: {result[correctness]}/5) print(f清晰度: {result[clarity]}/5) print(f难度匹配: {result[difficulty_match]}/5) print(f完整性: {result[completeness]}/5) print(f平均分: {result[average_score]:.2f}/5) print(f评语: {result[feedback]})每道题除了分数还会得到一段 LLM 生成的英文评语例如对一道难度的反馈The problem is correct and clear, but the difficulty is slightly below AIME level. Consider adding more complexity.脚本会汇总全部题目的平均分并按阈值给出质量结论总体平均 ≥ 4.0✅ 优秀题目质量很高可直接使用3.0 ≤ 平均 4.0⚠️ 良好质量可用建议人工审核2.0 ≤ 平均 3.0⚠️ 一般需要大幅改进平均 2.0❌ 较差需要重新生成。示例中的预期输出为平均分: 正确性: 5.00/5 清晰度: 4.50/5 难度匹配: 4.00/5 完整性: 5.00/5 总体平均: 4.62/5 质量评估: ✅ 优秀 - 题目质量很高可以直接使用5.2 Win Rate与真题对战来衡量相对质量LLM Judge 是绝对打分而 09_data_generation_win_rate.py 演示的 Win Rate 是相对对战——让评估模型在生成的题目 vs AIME 真题之间二选一并说明理由统计生成题目的胜率from hello_agents import HelloAgentsLLM from hello_agents.evaluation import WinRateEvaluator, AIDataset # 加载参考数据集AIME 真题 dataset AIDataset() reference_problems dataset.load() # 示例中加载了 963 道真题 # 创建 Win Rate 评估器 llm HelloAgentsLLM(model_namegpt-4o) evaluator WinRateEvaluator(llmllm, reference_problemsreference_problems) # 运行评估进行 20 次对比 results evaluator.evaluate( generated_problemsgenerated_problems, num_comparisons20 ) print(fWin Rate: {results[win_rate]:.2%}) print(fTie Rate: {results[tie_rate]:.2%}) print(fLoss Rate: {results[loss_rate]:.2%})Win Rate 的结果解读有一条黄金基准Win Rate ≈ 50%生成质量与真题相当理想情况Win Rate 50%生成质量优于真题需警惕评估偏差Win Rate 50%生成质量低于真题需要改进。质量评估阈值如下Win Rate 区间结论45% ~ 55%✅ 优秀生成质量接近 AIME 真题水平35% ~ 45%⚠️ 良好质量可用但略低于真题25% ~ 35%⚠️ 一般需要改进 25%❌ 较差需要大幅改进此外每次对比都保留resultgenerated / reference / tie与reason理由可以深入分析生成题目在哪些维度上不敌真题。示例预期输出为Win Rate: 45.00% Tie Rate: 10.00% Loss Rate: 45.00% 质量评估: ✅ 优秀 - 生成质量接近AIME真题水平5.3 完整评估流程生成 → 自动评估 → 人工验证07_data_generation_complete_flow.py 将上述环节串成端到端流水线一条命令完成生成 → LLM Judge → Win Rate → 人工验证python 07_data_generation_complete_flow.py 30 3.0参数说明30生成 30 道题目3.0每道题之间的延迟秒数用于避免 LLM 速率限制。脚本内部调用 run_complete_evaluation.py 的main(num_problems, delay_seconds)完整流程包括生成 AIME 题目以 963 道参考题为样本使用 GPT-4o 生成新题产物保存到data_generation/generated_data/aime_problems_*.json并附带generation_report_*.md报告LLM Judge 评估对生成题做四维度打分Win Rate 评估与 AIME 2025 真题963 道进行约 20 次对战对比人工验证启动本地 Gradio 界面http://127.0.0.1:7860人工对自动评估结论做最终把关。预期输出示例✅ 已加载 963 道参考题目 开始生成AIME题目 目标数量: 30 生成模型: gpt-4o 延迟设置: 3.0秒/题 生成AIME题目: 100%|██████████| 30/30 [02:3000:00, 5.01s/题] ✅ 生成完成 成功: 30/30 保存位置: ./data_generation/generated_data/aime_problems_20241211_143022.json LLM Judge评估 ✅ LLM Judge评估完成 平均分: 3.5/5.0 评估维度: - 正确性: 3.8/5.0 - 清晰度: 3.6/5.0 - 难度匹配: 3.4/5.0 - 完整性: 3.2/5.0 Win Rate评估 ✅ Win Rate评估完成 Win Rate: 45.0% Tie Rate: 10.0% Loss Rate: 45.0% 人工验证 启动人工验证界面 访问地址: http://127.0.0.1:7860 评估总结: 生成数量: 30道题目 LLM Judge平均分: 3.5/5.0 Win Rate: 45.0% 建议: 生成质量接近AIME真题水平仓库 code/chapter12/data_generation/evaluation_results 目录下还保留了完整的运行产物示例llm_judge/与win_rate/两个子目录分别存放评分 JSON 与 Markdown 报告以及汇总三者的comprehensive_report.md可以作为你本地运行后输出格式的参照。6. 学习路径初学者与进阶两条路线初学者路径先建立整体认知运行 01_basic_agent_example.py理解为什么需要评估学习 BFCL 评估运行 02_bfcl_quick_start.py快速开始→ 04_run_bfcl_evaluation.py最佳实践学习 GAIA 评估运行 05_gaia_quick_start.py快速开始→ 06_gaia_best_practices.py最佳实践。进阶路径深入定制与数据评估自定义评估流程阅读并改造 03_bfcl_custom_evaluation.py理解BFCLDataset/BFCLEvaluator底层组件数据生成评估运行 08_data_generation_llm_judge.pyLLM Judge→ 09_data_generation_win_rate.pyWin Rate→ 07_data_generation_complete_flow.py完整流程。7. 常见问题排查Q1运行示例时提示找不到模块请确认已安装 HelloAgents 评估组件或在开发目录下执行cd ../HelloAgents pip install -e .Q2BFCL 评估提示找不到数据集首次运行会自动下载数据集请确保网络连接正常。若下载失败可手动克隆仓库后重试数据路径见第 2.3 节。Q3GAIA 评估提示没有访问权限GAIA 是受限数据集请依次完成在 HuggingFace 数据集页面点击 Request Access → 等待审核通过通常 12 天→ 设置HF_TOKEN环境变量。Q4评估速度太慢可以通过减少样本数快速验证# BFCL 评估 results bfcl_tool.run(agent, categorysimple_python, max_samples5) # GAIA 评估 results gaia_tool.run(agent, level1, max_samples2) # 数据生成评估只生成 10 道题目 python 07_data_generation_complete_flow.py 10 3.0Q5如何估算评估成本评估成本主要来自 LLM API 调用以下为参考量级价格会随模型与供应商浮动BFCL 评估每个样本约 1 次 API 调用成本约 0.010.02 元/样本完整评估约 400 样本约 48 元GAIA 评估每个样本约 15 次 API 调用取决于任务复杂度成本约 0.050.20 元/样本完整评估466 样本约 2393 元数据生成评估生成约 0.05 元/题LLM Judge 约 0.02 元/题Win Rate 约 0.02 元/对比生成 30 道题目总计约 23 元。因此在正式全量评估前务必先用max_samples做小样本冒烟测试。8. 小结通过第十二章的 9 个示例脚本你可以在 HelloAgents 框架上建立一套覆盖工具调用能力BFCL→ 通用求解能力GAIA→ 数据生成质量LLM Judge / Win Rate的三层评估体系BFCL用一行BFCLEvaluationTool.run()快速量化函数调用准确率用BFCLDatasetBFCLEvaluator实现自定义评估用04_run_bfcl_evaluation.py对接官方评估工具完成端到端流水线GAIA强调官方提示词 受限数据集授权 分级递进评估以精确/部分匹配率为双指标附赠一套可直接套用的达标阈值与改进建议数据生成评估展示了绝对打分LLM Judge 相对对战Win Rate 人工验证三位一体的质量把关方案。这套方法论不局限于本仓库示例无论你的智能体是用于检索问答、工具调用还是数据生产都可以按同样的思路搭建专属评估基线让每一次 Prompt 优化、模型替换都有数据可依。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考