评估脚本使用说明

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

📁 文件说明

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

🚀 快速开始

1. 安装依赖

pip install evaluate rouge-score sacrebleu nltk

2. 基本使用

完整评估（推荐）

python eval/evaluate_results.py \
  --results_path /path/to/inference_results.json \
  --output_path /path/to/evaluation_report.json \
  --task topic_writing

快速评估

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格式：

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

支持的字段名

预测文本: generated_answer, generated_text, prediction
参考文本: ground_truth, output, reference, target

🎯 使用示例

评估零样本结果

# 运行推理
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结果

# 运行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

批量评估

# 评估多个结果文件
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

📈 输出格式

评估报告包含以下部分：

{
  "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参考", ...]
  }
}

🔧 高级用法

自定义评估

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']

批量比较

# 比较不同方法的结果
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'

🐛 故障排除

常见问题

依赖安装失败

pip install --upgrade pip
pip install evaluate rouge-score sacrebleu nltk

NLTK数据下载

import nltk
nltk.download('punkt')
nltk.download('wordnet')

内存不足
- 使用 quick_eval.py 进行快速评估
- 分批处理大文件
格式错误
- 检查JSON格式是否正确
- 确认字段名是否匹配

性能优化

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

📞 支持

如有问题，请检查：

输入文件格式是否正确
依赖是否完整安装
文件路径是否正确
内存是否充足