paper-fulltext-extract

Overview

把一批科研 PDF 变成可检索、可引用的结构化全文：

PDF 目录 ──GROBID(本地服务)──► TEI XML ──解析──► JSON / Markdown / HTML
                                                 └──► 语料索引（章节/正文/标题检索）
                                                 └──► 引言首句 CSV

GROBID 是本地部署的 Java 服务（不是云 API），负责把 PDF 的版面信息还原成带章节层级、图表位置、参考文献条目的 TEI XML；本技能负责后续的解析、转换、索引与检索。

技术上从老仓库 paper_extract/ 移植而来，修掉了 5 个真实缺陷：关键词被空格切开、标题误判、章节树重复计数、参考文献数量多算 1 条、xml:id 取不到值。

When to Use This Skill

• 手里有一批论文 PDF，需要结构化元数据（标题/作者/摘要/关键词/DOI/期刊），而不是纯文本
• 需要把论文转成 Markdown 或 HTML 以便本地阅读、翻译或喂给 LLM
• 需要在几十上百篇文献里做跨文献全文检索（"哪些论文提到 off-target"）
• 需要快速扫读一批论文的引言首句来判断相关性（每段第一句通常就点明了这篇文章要解决什么）
• 需要抽取每篇论文的参考文献列表用于引文网络分析

Quick Start

export PYTHONPATH="$PWD/packages"

# 0) 部署 GROBID（只需一次；首次启动要下模型，等日志出现 "Server started"）
docker run -it -p 8070:8070 kermitt/grobid

# 1) 全流程：PDF → TEI → JSON/Markdown/HTML + 语料索引
python skills/paper-fulltext-extract/scripts/extract_fulltext.py \
    --pdf-dir ./pdfs --output ./out \
    --formats json,markdown,html --build-index

# 2) 只提取引言首句（快速扫读一批论文）
python skills/paper-fulltext-extract/scripts/extract_fulltext.py \
    --tei-dir ./tei --output ./out --intro-only

# 3) 已有 TEI XML，只做解析
python skills/paper-fulltext-extract/scripts/tei_parser.py \
    --input ./tei/paper.tei.xml \
    --json out/paper.json --markdown out/paper.md --html out/paper.html

# 4) 单独调 GROBID 批量转 PDF（支持断点续跑）
python skills/paper-fulltext-extract/scripts/grobid_client.py \
    --input ./pdfs --output ./tei --check-only

# 5) 全文检索
python skills/paper-fulltext-extract/scripts/search_corpus.py \
    --xml-dir ./tei --keyword "CRISPR" --scope all \
    --export-csv out/corpus_metadata.csv

Workflow

1. PDF → TEI（可选，需 GROBID 服务）
   • POST /api/processFulltextDocument，文件字段名固定为 input
   • consolidateHeader / consolidateCitations 默认开启；flavor 选 precision（准）或 speed（快）
   • 批量处理支持断点续跑：已存在 <name>.tei.xml 直接跳过
2. TEI → 结构化数据
   • 元数据：标题、作者、机构、摘要、关键词、DOI、年份、期刊
   • 正文：章节树（<div> 可嵌套，层级保留）
   • 图表：编号、图注、图形相对路径
   • 参考文献：只取 <back> 下的条目
3. 产出多格式：JSON（机器可读）/ Markdown（阅读与喂 LLM）/ HTML（带图注与样式）
4. 建索引 + 检索：章节标题 / 正文段落 / 论文标题三种范围，可导出元数据 CSV
5. 引言首句提取：每篇每个引言段落的第一个句子，导出 CSV 用于快速筛读

flowchart TD
    A[PDF 目录] -->|grobid_client| B[TEI XML 目录]
    B -->|tei_parser| C[ParsedPaper]
    C --> D[JSON]
    C --> E[Markdown]
    C --> F[HTML]
    C -->|search_corpus| G[语料索引]
    G --> H[章节/正文/标题检索]
    C -->|extract_first_sentences| I[引言首句 CSV]

Parameters

extract_fulltext.py（主入口）

tei_parser.py

grobid_client.py

search_corpus.py

Outputs

out/
├── json/       <name>.json      完整结构化数据（含章节树、图表、参考文献）
├── markdown/   <name>.md        Markdown 正文（标题/作者/关键词/摘要/章节）
├── html/       <name>.html      带图注与内联样式的 HTML
├── tei/        <name>.tei.xml   GROBID 原始输出（仅 --pdf-dir 模式）
├── corpus_index.json            语料索引（可 --load-index 复用）
├── corpus_metadata.csv          文献元数据表（UTF-8 BOM，Excel 直开）
├── search_hits.json             检索命中明细
└── intro_sentences.csv          引言首句表

intro_sentences.csv 列：file, title, sentence_index, first_sentence corpus_metadata.csv 列：file, title, keywords, n_sections, n_paragraphs, abstract_chars

Validation

• GROBID 可用性：脚本会先调 /api/isalive 探测；不可用时给出明确的部署命令。日志里出现 Server started 才算就绪
• 解析成功率：解析完成：成功 N 篇，失败 M 篇 —— 单篇 XML 损坏不会中断整批，损坏文件记入警告
• 标题正确性：若标题显示为 INTRODUCTION、Methods 之类，说明 GROBID 把章节名误填进了 title，脚本会自动回退到文件名。回退到文件名是正确行为，比回退到期刊名好
• 关键词完整性：多词关键词（tumor necrosis factor）应保持完整。若看到被拆成三个词，说明关键词走了空格分隔的兜底分支 —— 检查 TEI 里有没有 <term> 子元素
• 参考文献条数：应等于论文末尾的条目数。若比实际多 1，多出来的是本文自己的元数据（<sourceDesc> 里的 <biblStruct>）
• 章节层级：corpus_index.json 里 sections[].level 应体现嵌套关系；标题重复出现说明章节树解析有重复
• 输出目录：所有产物都应平铺在 out/json/、out/markdown/、out/html/ 下；出现嵌套子目录说明文件名推导用了绝对路径
• 引言首句质量：首句应当是完整句子（以句号结尾），若在半句处截断说明缩写（如 e.g.）被误判为句末

References

• references/methodology.md —— TEI 结构详解、GROBID 部署与参数、章节树与首句提取算法、修掉的 5 个老仓库缺陷原理
• references/troubleshooting.md —— 常见报错（服务不可达、404、标题误填、关键词被切、参考文献多算、输出目录逃逸）与排错步骤