# 评估脚本使用说明

本目录包含用于评估推理结果的独立脚本。

## 📁 文件说明

- `evaluate_results.py` - 完整的评估脚本，支持多种指标
- `quick_eval.py` - 快速评估脚本，计算基本指标
- `README.md` - 使用说明

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install evaluate rouge-score sacrebleu nltk
```

### 2. 基本使用

#### 完整评估（推荐）
```bash
python eval/evaluate_results.py \
  --results_path /path/to/inference_results.json \
  --output_path /path/to/evaluation_report.json \
  --task topic_writing
```

#### 快速评估
```bash
python eval/quick_eval.py \
  --results_path /path/to/inference_results.json
```

## 📊 评估指标

### 自动指标
- **ROUGE-1**: 单字重叠率
- **ROUGE-2**: 双字重叠率  
- **ROUGE-L**: 最长公共子序列
- **ROUGE-Lsum**: 句子级ROUGE-L
- **BLEU**: 双语评估替补
- **METEOR**: 基于精确匹配的指标

### 文本统计
- 平均词数/字符数
- 词数/字符数标准差
- 词数/字符数范围
- 平均句子数
- 词汇表大小
- 高频词汇统计

## 📋 输入格式

评估脚本支持以下JSON格式：

```json
[
  {
    "user_id": "user_1",
    "query": "写一个关于AI的故事",
    "generated_answer": "人工智能是...",
    "ground_truth": "AI技术正在改变世界..."
  }
]
```

### 支持的字段名
- 预测文本: `generated_answer`, `generated_text`, `prediction`
- 参考文本: `ground_truth`, `output`, `reference`, `target`

## 🎯 使用示例

### 评估零样本结果
```bash
# 运行推理
python inference/zero_shot.py \
  --test_data_path data/test.json \
  --output_path results/zero_shot_results.json \
  --task topic_writing

# 评估结果
python eval/evaluate_results.py \
  --results_path results/zero_shot_results.json \
  --output_path reports/zero_shot_evaluation.json \
  --task topic_writing
```

### 评估RAG结果
```bash
# 运行RAG推理
python inference/zero_shot.py \
  --test_data_path data/test.json \
  --output_path results/rag_results.json \
  --task topic_writing \
  --use_rag \
  --ret_type bm25

# 评估结果
python eval/evaluate_results.py \
  --results_path results/rag_results.json \
  --output_path reports/rag_evaluation.json \
  --task topic_writing
```

### 批量评估
```bash
# 评估多个结果文件
for result_file in results/*.json; do
  echo "评估: $result_file"
  python eval/evaluate_results.py \
    --results_path "$result_file" \
    --output_path "reports/$(basename $result_file .json)_eval.json"
done
```

## 📈 输出格式

评估报告包含以下部分：

```json
{
  "task": "topic_writing",
  "total_samples": 100,
  "metrics": {
    "rouge-1": 0.4523,
    "rouge-2": 0.3124,
    "rouge-L": 0.4234,
    "rouge-Lsum": 0.4156,
    "bleu": 0.3845,
    "meteor": 0.4567
  },
  "text_statistics": {
    "total_samples": 100,
    "avg_word_count": 45.2,
    "std_word_count": 12.3,
    "avg_char_count": 234.5,
    "vocabulary_size": 1234,
    "most_common_words": [["the", 45], ["and", 32], ...]
  },
  "sample_results": {
    "predictions": ["样本1预测", "样本2预测", ...],
    "references": ["样本1参考", "样本2参考", ...]
  }
}
```

## 🔧 高级用法

### 自定义评估
```python
from eval.evaluate_results import evaluate_results, load_results

# 加载结果
results = load_results("results.json")

# 自定义评估
evaluation = evaluate_results(results, task="custom_task")

# 访问指标
rouge1 = evaluation['metrics']['rouge-1']
avg_words = evaluation['text_statistics']['avg_word_count']
```

### 批量比较
```bash
# 比较不同方法的结果
python eval/evaluate_results.py --results_path zero_shot.json --output_path zero_shot_eval.json
python eval/evaluate_results.py --results_path rag_bm25.json --output_path rag_bm25_eval.json
python eval/evaluate_results.py --results_path rag_contriver.json --output_path rag_contriver_eval.json

# 比较报告
echo "零样本结果:"
cat zero_shot_eval.json | jq '.metrics'
echo "RAG BM25结果:"
cat rag_bm25_eval.json | jq '.metrics'
echo "RAG Contriever结果:"
cat rag_contriver_eval.json | jq '.metrics'
```

## 🐛 故障排除

### 常见问题

1. **依赖安装失败**
   ```bash
   pip install --upgrade pip
   pip install evaluate rouge-score sacrebleu nltk
   ```

2. **NLTK数据下载**
   ```python
   import nltk
   nltk.download('punkt')
   nltk.download('wordnet')
   ```

3. **内存不足**
   - 使用 `quick_eval.py` 进行快速评估
   - 分批处理大文件

4. **格式错误**
   - 检查JSON格式是否正确
   - 确认字段名是否匹配

### 性能优化

- 对于大文件，使用 `quick_eval.py`
- 分批处理超过1000个样本的结果
- 使用SSD存储以提高I/O性能

## 📞 支持

如有问题，请检查：
1. 输入文件格式是否正确
2. 依赖是否完整安装
3. 文件路径是否正确
4. 内存是否充足