hello-agents/code/chapter12/data_generation/运行指南.md

# AIME数据生成与评估完整运行指南

本文档提供完整的运行步骤，从数据生成到评估报告生成。

## 前置准备

### 1. 环境配置

确保已安装所有依赖：

```bash
# 安装评估系统依赖
pip install hello-agents[evaluation]

# 或手动安装
pip install datasets huggingface_hub pandas tqdm gradio
```

### 2. 环境变量配置

在 `.env` 文件中配置：

```bash
# LLM API密钥（二选一）
DASHSCOPE_API_KEY=your_dashscope_key  # 阿里云DashScope
OPENAI_API_KEY=your_openai_key        # OpenAI

# HuggingFace Token（用于下载数据集）
HF_TOKEN=your_hf_token
```

## 完整运行步骤

### 步骤1：运行完整评估流程

这是**一键运行**的方式，会自动完成生成、评估、报告生成：

```bash
cd docs/chapter12/HelloAgents
python data_generation/run_complete_evaluation.py 30 3.0
```

**参数说明**：
- `30` - 生成30道题目
- `3.0` - 每次生成间隔3秒（推荐2-3秒）

**说明**：
- 使用AIME 2025年真题作为评估参考
- 数据集来源：math-ai/aime25（JSONL格式）

**预计耗时**：
- 生成30道题：约15-30分钟（取决于API速度）
- LLM Judge评估：约10-15分钟
- Win Rate评估：约5-10分钟
- **总计**：约30-55分钟

**输出文件**：
```
data_generation/
├── generated_data/
│   └── aime_generated_YYYYMMDD_HHMMSS.json  # 生成的题目
└── evaluation_results/
    └── YYYYMMDD_HHMMSS/
        ├── llm_judge/
        │   ├── llm_judge_result_YYYYMMDD_HHMMSS.jsonl
        │   └── llm_judge_report_YYYYMMDD_HHMMSS.md
        ├── win_rate/
        │   ├── win_rate_result_YYYYMMDD_HHMMSS.jsonl
        │   └── win_rate_report_YYYYMMDD_HHMMSS.md
        └── comprehensive_report.md  # 综合报告
```

### 步骤2：查看评估报告

#### 2.1 查看综合报告

```bash
# 找到最新的评估结果目录
cd data_generation/evaluation_results
ls -lt  # 查看最新的目录

# 查看综合报告
cat YYYYMMDD_HHMMSS/comprehensive_report.md
```

**综合报告包含**：
- 基本信息（生成时间、题目数量等）
- 数据生成统计（主题分布、答案分析）
- LLM Judge评估结果（总体评分、各维度评分）
- Win Rate评估结果（胜率统计、对比分析）
- 综合结论和改进建议

#### 2.2 查看详细报告

**LLM Judge详细报告**：
```bash
cat YYYYMMDD_HHMMSS/llm_judge/llm_judge_report_YYYYMMDD_HHMMSS.md
```

**Win Rate详细报告**：
```bash
cat YYYYMMDD_HHMMSS/win_rate/win_rate_report_YYYYMMDD_HHMMSS.md
```

### 步骤3：人工验证（可选）

如果需要进行人工验证，运行：

```bash
python data_generation/human_verification_ui.py data_generation/generated_data/aime_generated_YYYYMMDD_HHMMSS.json
```

**操作步骤**：
1. 浏览器自动打开 `http://127.0.0.1:7860`
2. 阅读题目、答案、解答
3. 从4个维度评分（1-5分）
4. 选择验证状态（approved/rejected/needs_revision）
5. 添加评论（可选）
6. 点击"提交验证"
7. 查看下一题

**验证结果保存**：
```
data_generation/generated_data/aime_generated_YYYYMMDD_HHMMSS_verifications.json
```

## 分步运行（高级）

如果需要分步运行，可以按以下步骤：

### 步骤1：仅生成数据

```python
from data_generation.aime_generator import AIMEGenerator

generator = AIMEGenerator(delay_seconds=3.0)
generated_data_path = generator.generate_and_save(num_problems=30)
print(f"生成数据保存在: {generated_data_path}")
```

### 步骤2：仅运行LLM Judge评估

```python
from hello_agents import HelloAgentsLLM
from hello_agents.tools import LLMJudgeTool

llm = HelloAgentsLLM()
llm_judge_tool = LLMJudgeTool(llm=llm)

result = llm_judge_tool.run({
    "generated_data_path": "data_generation/generated_data/aime_generated_XXXXXX.json",
    "reference_year": 2025,
    "max_samples": 30,
    "output_dir": "data_generation/evaluation_results/llm_judge"
})
```

### 步骤3：仅运行Win Rate评估

```python
from hello_agents import HelloAgentsLLM
from hello_agents.tools import WinRateTool

llm = HelloAgentsLLM()
win_rate_tool = WinRateTool(llm=llm)

result = win_rate_tool.run({
    "generated_data_path": "data_generation/generated_data/aime_generated_XXXXXX.json",
    "reference_year": 2025,
    "num_comparisons": 20,
    "output_dir": "data_generation/evaluation_results/win_rate"
})
```

## 常见问题

### 1. API速率限制

**问题**：
```
INFO:openai._base_client:Retrying request to /chat/completions in 0.451826 seconds
```

**解决**：
- 增加延迟时间：`python data_generation/run_complete_evaluation.py 30 5.0`
- 使用检查点恢复：中断后重新运行相同命令会自动恢复

### 2. HuggingFace下载慢

**问题**：下载AIME数据集很慢

**解决**：
```bash
# 使用镜像源
export HF_ENDPOINT=https://hf-mirror.com

# 或手动下载后使用本地路径
```

### 3. 生成题目重复

**问题**：生成的题目有重复

**解决**：
- 已使用900+道真题作为参考样例
- 每次生成都随机选择不同的参考
- 提示词强调"生成完全不同的题目"

### 4. 评估失败

**问题**：LLM Judge或Win Rate评估失败

**解决**：
- 检查API密钥是否正确
- 检查生成的数据文件是否存在
- 检查数据文件格式是否正确

## 质量标准

### 优秀标准
- LLM Judge平均分 ≥ 4.5/5.0
- Win Rate ≥ 48%（接近50%）
- 通过率 ≥ 90%
- 人工验证通过率 ≥ 95%

### 良好标准
- LLM Judge平均分 ≥ 4.0/5.0
- Win Rate ≥ 45%
- 通过率 ≥ 80%
- 人工验证通过率 ≥ 90%

### 需要改进
- LLM Judge平均分 < 4.0/5.0
- Win Rate < 45%
- 通过率 < 80%
- 人工验证通过率 < 90%

## 下一步

根据评估结果：

1. **如果质量优秀**：
   - 可以使用生成的数据
   - 考虑生成更多数据
   - 保留评估报告作为质量证明

2. **如果质量良好**：
   - 进行人工验证
   - 筛选高质量数据
   - 调整生成提示词

3. **如果需要改进**：
   - 分析低分题目的共同问题
   - 调整生成提示词
   - 重新生成并评估

## 示例输出

### 综合报告示例

```markdown
# AIME数据生成与评估综合报告

## 1. 基本信息

- **生成时间**: 2025-01-10 12:00:00
- **生成题目数量**: 30
- **参考AIME年份**: 2025

## 2. 数据生成统计

### 主题分布

| 主题 | 数量 | 占比 |
|------|------|------|
| 代数 | 10 | 33.3% |
| 几何 | 8 | 26.7% |
| 数论 | 7 | 23.3% |
| 组合 | 3 | 10.0% |
| 概率 | 2 | 6.7% |

## 3. LLM Judge评估结果

- **平均总分**: 4.2/5.0
- **通过率**: 85.0%
- **优秀率**: 40.0%

## 4. Win Rate评估结果

- **Win Rate**: 45.0%
- **评级**: 良好

## 5. 综合结论

✅ 生成数据质量**良好**，接近AIME真题水平。
```

## 总结

完整流程：
1. 运行 `python data_generation/run_complete_evaluation.py 30 3.0`
2. 等待30-55分钟
3. 查看综合报告 `data_generation/evaluation_results/XXXXXX/comprehensive_report.md`
4. （可选）运行人工验证
5. 根据评估结果决定下一步

**说明**：
- 所有评估都使用AIME 2025年真题作为参考
- 数据集来源：math-ai/aime25（JSONL格式）

祝你使用愉快！