RefGuard

数据版本说明：论文最终稿所报告的实验结果基于V4冻结数据集。V5为数据勘误版本，不替代V4历史实验记录，未用于论文所报指标；勘误对评测结果的影响尚待核实。

版本详情及修改清单见 data/VERSION_HISTORY.md。

RefGuard 是一个面向学术参考文献的开源核验工具，用于检查 BibTeX 条目是否能被公开学术元数据源支持。

项目关注“参考文献身份核验”：题名、作者、年份、DOI、arXiv ID 与来源证据。当前方法不使用 LLM。

功能

• 基于 Crossref、OpenAlex、arXiv、DBLP、Semantic Scholar 核验 BibTeX 参考文献。
• 将多数据源候选证据融合为匹配概率和明确状态。
• 检测重复参考文献条目。
• 对 LaTeX 项目检查 BibTeX 条目使用情况。
• 输出 JSON 与 Markdown 报告。
• 支持命令行工具和 FastAPI 服务。

不做什么

• 默认只接入公开、可文档化的学术元数据源。
• 不抓取 Google Scholar。
• 不使用 LLM 判断参考文献是否真实存在。
• 不包含用户上传论文或私人项目数据。

合规与职业边界

RefGuard 是个人研究与开源项目，不代表作者任职机构、任何数据平台或商业服务。本项目不使用雇主资源、内部资料、非公开数据、账号凭据或工作产出。

项目代码只面向公开可访问的学术元数据接口和公开书目信息。公开可访问不等于自动可再分发；用于论文附件、公开 release 或第三方复用前，应逐项核查数据来源、许可、API 条款和引用要求。

详见 DISCLAIMER.md。

安装

pip install -e .

开发环境：

pip install -e ".[dev]"

命令行用法

核验 BibTeX 文件：

refguard verify bib --input tests/test_bib.bib --profile balanced --out ./report

核验 BibTeX 并检查 LaTeX 引用使用情况：

refguard verify project --bib paper/references.bib --tex paper/main.tex --check-usage on --out ./report

API 用法

启动 API 服务：

uvicorn main:app --reload

打开：

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/api/v1/sources/status

请求示例：

curl -X POST "http://127.0.0.1:8000/api/v1/verify/bib" \
  -H "Content-Type: application/json" \
  -d '{"bibtex_content":"@article{demo,title={Attention Is All You Need},author={Vaswani, Ashish and Shazeer, Noam},year={2017}}","profile":"balanced"}'

配置

只有需要本地覆盖配置时，才将 .env.example 复制为 .env。

所有 API key 都是可选项，仅用于公开元数据源的访问限额，不应提交到版本库：

• SEMANTIC_SCHOLAR_API_KEY：可选，用于提高请求限额。
• OPENALEX_API_KEY：可选。
• CROSSREF_MAILTO：可选，用于 Crossref polite pool。

实验数据

论文数据采用明确的版本边界：V4 是录用稿结果的不可变历史快照；V5 是录用后 书目身份校正版，二者不得混用或静默覆盖。由于尚未取得 GPTZero 第三方数据的 再分发许可，公开 V5 核心集不包含该 100 条子集。完整说明见 data/VERSION_HISTORY.md。

生成校正公开核心集：

python scripts/build_corrected_v5.py

该命令只修正数据和生成版本清单，不修改 RefGuard 的检索、特征融合或决策算法， 也不会把 V5 结果写成录用稿指标。

当前基准数据将重新整理。整理完成后，源数据应放在 data/citation_dataset_final_v4.json 或后续版本文件中，data/refguard_input.jsonl 由 scripts/build_refguard_input.py 生成。

当前项目数据来自公开来源和公开元数据。请将其视为研究数据：只保留书目信息、标签与来源说明。不要提交论文全文、用户上传文件、非公开数据源导出、API key 或 cookie。正式公开完整数据集前，请单独附数据说明和许可核查结果。

后续补充真实文献 BibTeX 时，请按 data/BIBTEX_DATA_PREPARATION.md 整理字段、清洗 DOI/arXiv/URL，并记录可公开复核来源。

整理完源数据后，运行基准测试辅助脚本。输出目录默认为 eval_report/，该目录是生成产物，不纳入版本库：

python scripts/build_refguard_input.py
# 论文主结果（自适应阈值 + 跨注册商 DOI 内容协商，测试集 n=2037）
python eval/run_benchmark.py --input data/refguard_input.jsonl --out eval_report_final \
  --profile adaptive --sources crossref,openalex,arxiv,dblp,semanticscholar,doicn \
  --model-dir fusion_models_nodoi6 --split test \
  --split-source data/citation_dataset_final_v4.json
# 论文图2 的 DOI 注册商分布（实测，非硬编码）
python scripts/compute_doi_ra.py            # -> data/doi_ra_distribution.json
# 论文表4：各特征子集在开发集独立重训和选阈值，再评估冻结测试子集
python scripts/run_ablation.py --offline-only \
  --cache paper_results/ablation_cache_openalex_clean_v4.jsonl \
  --dev-features paper_results/dev_features_v4.jsonl \
  --ablation-json paper_results/feature_ablation_retrained_v5.json
# 其他论文表/图
python scripts/make_paper_tables.py
python scripts/make_figures.py

旧版表4脚本仅在推理阶段把特征置零，却继续使用全特征模型的偏置、阈值和部分未遮蔽决策规则，容易使多个组合机械地产生相同结果。修订版对每个特征子集独立重训，并且只用开发集选择阈值；测试标签不参与拟合或选阈值。

OpenAlex 会先执行免费的 DOI 精确查询；精确命中后不再继续付费题名搜索，只有 DOI 缺失或未命中时才回退到题名搜索。若遇到 401、403、429、超时或服务端错误，评测会中止并保留断点，修复凭据或额度后使用 --resume 继续，避免把接口故障误记为“无候选”。

数据集公开

完整基准数据默认不入库。如需公开发布，请先阅读 data/DATASET_CARD.md 的伦理声明与公开发布清单，并运行 scripts/make_public_dataset.py 生成剥离第三方原始判定字段、注入使用限制的公开版。合成的"幻觉"条目仅为检测负样本，严禁当作真实文献引用。

开发检查

python -m pytest tests -q
python -m compileall -q refguard eval scripts
refguard --help

许可证

代码采用 MIT License 发布，详见 LICENSE。