| # 评估脚本使用说明 |
|
|
| 本目录包含用于评估推理结果的独立脚本。 |
|
|
| ## 📁 文件说明 |
|
|
| - `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. 内存是否充足 |
|
|
