CiteExtract：批量抽取 PDF 论文里的作者-年份引用句子（PyMuPDF）

目标：对一批论文 PDF，抽取正文中包含 author-year 引用（如 Smith (2020)、(Jones, 2019; Brown and White, 2018)）的句子，并导出结构化数据用于后续分析/检索/语义聚类。

技术栈（MVP）

• 解析：PyMuPDF（fitz）按页抽取文本（含去断字 TEXT_DEHYPHENATE）
• 清洗：软换行合并、重复页眉页脚移除、References 页检测（默认遇到 References 就停止）
• 切句：轻量规则切句（避免把 et al. / e.g. 之类误当句号）
• 引用识别：正则 + 规则解析
  • 叙述式：Smith (2020)
  • 括号式：(Smith, 2020; Jones, 2019)
• 参考文献列表：从 References/Bibliography 段落抽取条目（多行合并为单条）
• 导出：jsonl / csv / xlsx（xlsx 含 citations + references 两个 sheet）

安装

python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt

打包成 exe（Windows）

参考 F:\ai_words 的打包方式，本项目提供同样的脚本：

1. 安装/重建环境：双击运行 setup_env.bat
2. 打包：双击运行 build.bat

产物：

• 离线发行目录：release\CiteExtract_<VERSION>_offline\
  • CiteExtract.exe（GUI，双击打开）
• 离线发行压缩包：release\CiteExtract_<VERSION>_offline.zip（包含 exe + scripts + models）

离线语义模型（可选：生成 embeddings / 做语义检索与聚类）

本项目支持使用离线 ONNX 语义模型为“引用句子”生成句向量（384 维，L2-normalized）。

• 如果你已经有 F:\ai_words\models\semantic（你提到的项目里就有），一键复制到本项目：
  • powershell -ExecutionPolicy Bypass -File scripts/copy_semantic_model_from_ai_words.ps1
• 或者从 HuggingFace 下载（模型较大）：
  • python scripts/download_semantic_model.py models/semantic

默认会优先使用 models/semantic，也可用环境变量/参数指定：

• 环境变量：CITEEXTRACT_SEMANTIC_MODEL_DIR
• CLI：--semantic-model-dir

用法

抽取并导出 JSONL（推荐，信息最完整）：

python -m citeextract --input "D:\\papers" --output citations.jsonl

导出 CSV（便于 Excel/统计）：

python -m citeextract --input "D:\\papers" --output citations.csv

导出 XLSX（包含 citations + references 两个 sheet）：

python -m citeextract --input "D:\\papers" --output citations.xlsx

只处理前 N 篇 PDF（目录下排序后取前 N 个，便于快速试跑）：

python -m citeextract --input "D:\\papers" --output citations.jsonl --limit-pdfs 10

只处理前 N 页（快速试跑）：

python -m citeextract --input "D:\\papers" --output citations.jsonl --max-pages 5

不在 References 停止（会更“脏”，但有时你想把参考文献也扫出来）：

python -m citeextract --input "D:\\papers" --output citations.jsonl --no-stop-at-references

抽取 JSONL 并同时生成 embeddings：

python -m citeextract --input "D:\\papers" --output citations.jsonl --embed

默认会在同目录生成：

• citations.embeddings.npy
• citations.semantic_meta.json

输出格式

JSONL（每行一个句子）

字段：

• pdf：PDF 相对路径（相对 --input 文件夹）
• page：页码（从 1 开始）
• sentence：句子文本
• citations[]：该句中解析出的引用（可能多条）
  • kind：narrative / parenthetical
  • authors：作者部分（原样字符串，如 Smith et al. / Brown and White）
  • year：年份（含 2020a 这种后缀）
  • raw：该引用所在的括号片段或命中片段

CSV（每行一个 citation）

列：pdf,page,sentence,kind,authors,year,raw

XLSX

• citations：每行一个 citation（同 CSV 列）
• references：每行一个参考文献条目：pdf,page,ref_index,authors,year,reference

参考 F:\\ai_words（可选增强）

你提到的 F:\\ai_words 里已经有：

• PyMuPDF 抽取 + 更强的句子切分/清洗思路
• 离线语义模型（ONNX MiniLM + tokenizers + onnxruntime），可对句子做 embedding，进而做：
  • 引用句子的聚类/近邻检索（按“引用意图/语境”分组）
  • 去重、相似句合并、主题聚合

目前本项目已提供 --embed 生成 embeddings（复用 ai_words 的离线模型方案）；下一步可以在此基础上加 --cluster/--search 等能力做“按语境聚类/相似句检索/去重”。

局限与下一步

• 扫描版 PDF 需要 OCR（当前未做）
• 复杂多栏版式可能会影响阅读顺序（可进一步用 block 坐标做更强排序/分栏）
• “把 in-text citation 映射到参考文献条目”暂未实现（可再加 bibliography 解析与模糊匹配）