hello-agents/code/chapter12/README.md

第十二章示例代码

本目录包含第十二章《智能体性能评估》的所有示例代码，按照文档顺序编号，方便学习者跟随文档学习。

📁 文件列表

文件名	对应章节	说明
01_basic_agent_example.py	12.1.1	基础智能体示例，说明为何需要评估
02_bfcl_quick_start.py	12.2.5	BFCL快速开始（一键评估）
03_bfcl_custom_evaluation.py	12.2.5	BFCL自定义评估（底层组件）
04_run_bfcl_evaluation.py	12.2.9	BFCL评估最佳实践
05_gaia_quick_start.py	12.3.5	GAIA快速开始（一键评估）
06_gaia_best_practices.py	12.3.9	GAIA评估最佳实践
07_data_generation_complete_flow.py	12.4.6	数据生成完整评估流程
08_data_generation_llm_judge.py	12.4.3	LLM Judge评估
09_data_generation_win_rate.py	12.4.4	Win Rate评估

🚀 快速开始

环境准备

1. 安装HelloAgents框架：

   pip install hello-agents[evaluation]==0.2.3
   

2. 设置环境变量：

   # OpenAI API Key（用于GPT-4o）
   export OPENAI_API_KEY="your_openai_api_key"
   
   # HuggingFace Token（用于GAIA数据集）
   export HF_TOKEN="your_huggingface_token"
   

3. 下载BFCL数据集（可选，首次运行会自动下载）：

   cd ../HelloAgents
   git clone https://github.com/ShishirPatil/gorilla.git temp_gorilla
   

运行示例

1. 基础智能体示例

python 01_basic_agent_example.py

这个示例展示了一个基本的ReAct智能体，说明为何需要评估系统。

2. BFCL快速开始

python 02_bfcl_quick_start.py

这是最简单的BFCL评估方式，一行代码完成评估。

预期输出：

准确率: 100.00%
正确数: 5/5

3. BFCL自定义评估

python 03_bfcl_custom_evaluation.py

展示如何使用底层组件进行自定义评估流程。

4. BFCL最佳实践

python 04_run_bfcl_evaluation.py

展示BFCL评估的最佳实践，包括：

• 渐进式评估
• 多类别评估
• 对比评估
• 错误分析

5. GAIA快速开始

重要提示：GAIA是受限数据集，需要先申请访问权限。

1. 访问 https://huggingface.co/datasets/gaia-benchmark/GAIA
2. 点击"Request Access"申请访问权限
3. 等待审核通过（通常1-2天）
4. 设置HF_TOKEN环境变量

python 05_gaia_quick_start.py

预期输出：

精确匹配率: 100.00%
部分匹配率: 100.00%
正确数: 2/2

6. GAIA最佳实践

python 06_gaia_best_practices.py

展示GAIA评估的最佳实践，包括：

• 分级评估
• 小样本快速测试
• 结果解读

7. 数据生成完整评估流程

python 07_data_generation_complete_flow.py 30 3.0

参数说明：

• 30：生成30道题目
• 3.0：每道题目之间延迟3秒

这个示例展示了数据生成的完整评估流程：

1. 生成AIME题目
2. LLM Judge评估
3. Win Rate评估
4. 人工验证

预期输出：

生成数量: 30道题目
LLM Judge平均分: 3.5/5.0
Win Rate: 45.0%
建议: 生成质量接近AIME真题水平

8. LLM Judge评估

python 08_data_generation_llm_judge.py

展示如何使用LLM Judge评估生成的AIME题目质量。

预期输出：

平均分:
  正确性: 5.00/5
  清晰度: 4.50/5
  难度匹配: 4.00/5
  完整性: 5.00/5
  总体平均: 4.62/5

质量评估:
✅ 优秀 - 题目质量很高，可以直接使用

9. Win Rate评估

python 09_data_generation_win_rate.py

展示如何使用Win Rate评估生成的AIME题目质量。

预期输出：

Win Rate: 45.00%
Tie Rate: 10.00%
Loss Rate: 45.00%

质量评估:
✅ 优秀 - 生成质量接近AIME真题水平

📊 学习路径

初学者路径

1. 了解评估的必要性：

   • 运行 01_basic_agent_example.py

2. 学习BFCL评估：

   • 运行 02_bfcl_quick_start.py（快速开始）
   • 运行 04_run_bfcl_evaluation.py（最佳实践）

3. 学习GAIA评估：

   • 运行 05_gaia_quick_start.py（快速开始）
   • 运行 06_gaia_best_practices.py（最佳实践）

进阶路径

1. 自定义评估流程：

   • 运行 03_bfcl_custom_evaluation.py

2. 数据生成评估：

   • 运行 08_data_generation_llm_judge.py（LLM Judge）
   • 运行 09_data_generation_win_rate.py（Win Rate）
   • 运行 07_data_generation_complete_flow.py（完整流程）

💡 常见问题

Q1: 运行示例时提示找不到模块？

A: 请确保已安装HelloAgents框架：

cd ../HelloAgents
pip install -e .

Q2: BFCL评估提示找不到数据集？

A: 首次运行会自动下载数据集，请确保网络连接正常。如果下载失败，可以手动下载：

cd ../HelloAgents
git clone https://github.com/ShishirPatil/gorilla.git temp_gorilla

Q3: GAIA评估提示没有访问权限？

A: GAIA是受限数据集，需要先申请访问权限：

1. 访问 https://huggingface.co/datasets/gaia-benchmark/GAIA
2. 点击"Request Access"
3. 等待审核通过
4. 设置HF_TOKEN环境变量

Q4: 评估速度太慢？

A: 可以减少样本数量：

# BFCL评估
results = bfcl_tool.run(agent, category="simple_python", max_samples=5)

# GAIA评估
results = gaia_tool.run(agent, level=1, max_samples=2)

# 数据生成评估
python 07_data_generation_complete_flow.py 10 3.0  # 只生成10道题目

Q5: 如何估算评估成本？

A: 评估成本主要来自LLM API调用：

BFCL评估：

• 每个样本约1次API调用
• 成本约0.01-0.02元/样本
• 完整评估（400样本）约4-8元

GAIA评估：

• 每个样本约1-5次API调用（取决于任务复杂度）
• 成本约0.05-0.20元/样本
• 完整评估（466样本）约23-93元

数据生成评估：

• 生成：约0.05元/题
• LLM Judge：约0.02元/题
• Win Rate：约0.02元/对比
• 生成30道题目约2-3元

📚 相关资源

• HelloAgents框架：https://github.com/jjyaoao/HelloAgents
• BFCL官方仓库：https://github.com/ShishirPatil/gorilla
• GAIA官方仓库：https://huggingface.co/datasets/gaia-benchmark/GAIA

🤝 贡献

如果你发现示例代码有问题或有改进建议，欢迎提交Issue或Pull Request。

📄 许可证

本示例代码遵循与HelloAgents框架相同的许可证。