02-ref-hallucination-arena

Reference Hallucination Arena（简称 RefArena）是 OpenJudge 项目中的技能，用来评估大语言模型推荐真实学术参考文献的准确程度，核心指标是幻觉率。它并不让模型直接生成答案，而是先让模型按 BibTeX 格式给出参考文献，再逐条与权威数据库比对，据此判断模型引用的文献是否真实存在。

用途该工具面向需要衡量模型学术引用可靠性的场景，例如对比不同模型推荐文献的真实性、检查模型是否会编造论文、评估特定学科或年份约束下的推荐质量。

主要能力流程包括：从 JSON/JSONL 数据集加载查询；收集目标模型输出的 BibTeX 响应；解析模型输出中的文献条目；与 Crossref、PubMed、arXiv、DBLP 进行交叉核验；计算核验通过率、各字段准确率和学科维度的分布情况；生成 Markdown 报告和可视化图表。

核验状态分为四类：VERIFIED（标题、作者、年份均与真实论文完全匹配）、SUSPECT（部分匹配，例如标题匹配但作者不符）、NOT_FOUND（任何数据库均未找到）、ERROR（API 超时或网络故障）。各字段准确率包括 title_accuracy、author_accuracy、year_accuracy、doi_accuracy。结果解读上，核验通过率高于 75% 为优秀，60–75% 为良好，40–60% 为一般，低于 40% 为较差。排名顺序依次比较总体准确率、年份符合率、平均置信度、完整性。

使用方式需先安装 OpenJudge：pip install py-openjudge；生成图表还需安装：pip install matplotlib。运行前需准备配置 YAML 路径、数据集路径和 API 密钥（如 OPENAI_API_KEY、DASHSCOPE_API_KEY 等），可选提供 CrossRef 邮箱、PubMed API key、输出目录、报告语言（en 或 zh）以及使用工具增强模式时的 Tavily API key。

命令行运行示例：

python -m cookbooks.ref_hallucination_arena --config config.yaml --save

默认从检查点续跑；加 --fresh 忽略检查点重新开始；可用 --output_dir 覆盖输出目录。

Python API 示例：

import asyncio
from cookbooks.ref_hallucination_arena.pipeline import RefArenaPipeline

async def main():
    pipeline = RefArenaPipeline.from_config("config.yaml")
    result = await pipeline.evaluate()

    for rank, (model, score) in enumerate(result.rankings, 1):
        print(f"{rank}. {model}: {score:.1%}")

asyncio.run(main())

配置文件包含 task、dataset、target_endpoints、tool_config、verification、evaluation、output、report 等部分。dataset 可设置 path、shuffle、max_queries；target_endpoints 下每个模型需配置 base_url、api_key（支持 ${ENV_VAR}）、model、system_prompt（可使用 {num_refs} 占位符）、max_concurrency、extra_params；tool_config 可启用基于 Tavily 的 ReAct 检索；verification 可设置 crossref_mailto、pubmed_api_key、max_workers、timeout、verified_threshold；report 可设置语言、示例数量和图表方向、是否显示数值、是否高亮最佳模型。

数据集每条记录包含 query（必填）、discipline（可选，如 computer_science、biomedical、physics 等）、num_refs、language、year_constraint（exact、min_year、max_year 等约束）。

输出目录默认是 ./evaluation_results/ref_hallucination_arena，包含 evaluation_report.md、evaluation_results.json、verification_chart.png、discipline_chart.png、queries.json、responses.json、extracted_refs.json、verification_results.json 和 checkpoint.json。

适用场景适合模型能力对比评测、学术引用可靠性研究、幻觉率量化分析，以及按学科或年份维度分析推荐质量。

限制评估依赖外部数据库 API，可能受速率限制或网络故障影响，产生 ERROR 状态；CrossRef 邮箱和 PubMed API key 可改善速率限制。工具增强模式需要额外 Tavily API key。资料未提供关于该技能自身收费、价格或平台支持范围的说明。

技能介绍