alterlab-pdf-extract

PDF 提取 — 用户定义的证据表

概述

Elicit“列”功能的免费替代方案。指定一组 PDF，声明你关心的列，即可获得整洁的证据表——每篇论文一行，每个问题一列——并导出为 CSV 或 Markdown 表格。专为语料库数据提取而设计：文献筛选、方法比较、PICO/样本量提取，以及综述证据表。

在提取任何列之前，所有输入都会通过 Microsoft MarkItDown（见 alterlab-markitdown 技能）转换为规范的 Markdown，因此 PDF、DOCX、PPTX、HTML 及其他 MarkItDown 格式都适用。

何时使用此技能

• 从多篇论文中提取相同字段，并整理成对照表或电子表格。
• 为综述建立数据提取表（样本量、设计、干预、结局、效应量、局限性）。
• 将一组 PDF 筛选并整理为可排序/筛选的 CSV。
• 任何“给我做个表，每行一篇论文，每列是 X”的请求。

此技能处理你已有的文档，并生成结构化表格，而不是散文——请在拿到论文之后使用。

不适用的情况

场景	改用
搜索数据库以查找论文，或撰写叙述性综合	alterlab-literature-review
深入检视一篇 PDF（所有章节、图、表、附录）	alterlab-pdf-explore
只将文档转换为 Markdown	alterlab-markitdown
提取磁盘上没有的论文的结构化实验数据	alterlab-bgpt-search
在 Zotero 文献库中管理 PDF 及其参考文献	alterlab-pyzotero

快速开始

SCRIPT=skills/research-tools/alterlab-pdf-extract/scripts/extract_to_table.py

# Heuristic backend: use 'label:question' so the question carries the words the
# papers actually use — overlap is lexical, so a bare label like "Sample size"
# rarely matches "we enrolled 240 participants" (see Backends below).
uv run python "$SCRIPT" papers/*.pdf \
    --column "Sample size:how many participants were enrolled" \
    --column "Main finding:primary result reported" \
    --column "Limitations:study limitations weaknesses" --format md

# Columns with explicit extraction questions, CSV to a file:
uv run python "$SCRIPT" a.pdf b.pdf \
    --column "n:how many participants were enrolled" \
    --column "effect:what was the main reported effect size" \
    --format csv -o evidence.csv

# Precise LLM-backed extraction (needs OPENROUTER_API_KEY) — label-only columns
# are fine here, since the model reads the paper rather than matching keywords:
uv run python "$SCRIPT" lit/*.pdf \
    --columns "Population" "Intervention" "Outcome" --backend llm

定义列

一列由一个标签和一个用于驱动提取的问题组成。可通过两种方式声明：

规格形式	含义
"Sample size"	标签 == 问题；关键词来自标签
"n:how many participants"	标签为 n，问题为 how many participants

使用 --columns 指定以空格分隔的简单标签列表；对于需要明确问题的规格，则重复使用 --column。两者可以组合使用；不允许重复标签。

后端

• heuristic（默认、离线、免费）：针对每一列，根据 Markdown 句子与列规格之间的字面关键词重合度进行评分，并输出得分最高的证据片段。结果确定性强——适合初步提取、筛选和可复现的运行。如果没有句子包含相同关键词，则返回空单元格。 注意：匹配依据是词汇，而非语义。通用标签如 "Sample size" 会被拆分为 sample、size，而这些词不会出现在 "we enrolled 240 participants" 中，因此单元格会为空。使用 heuristic 后端时，请将列写成 Label:question，并让问题采用论文实际使用的词语（participants、enrolled、cohort、n=）。如果问题本身含有数字或 %，定量问题也会为包含数字的句子提供少量排序加分。若只有通用标签，请改用 llm 后端。
• llm（可选、精准）：将转换后的 Markdown（前 24,000 个字符）以及所有列问题发送至兼容 OpenAI 的端点，获取每列的简洁回答（论文未提及时为 N/A）。设置 OPENROUTER_API_KEY 后，请求会发送至 OpenRouter；否则，OPENAI_API_KEY 会发送至 OPENAI_BASE_URL（或 OpenAI 默认端点）——每个密钥只会发送至其对应的端点。模型 ID 遵循 ALTERLAB_MODEL 约定（skills/core/shared/model_env.md）：使用 $ALTERLAB_MODEL，否则使用带日期的默认值；可通过 --model 为单次运行指定其他模型（对于非 OpenRouter 端点，请传入该端点提供的模型 ID）。在将 LLM 的回答纳入综述前，请对照 PDF 抽查，因为表格中的错误数字即使看起来很可信，也与正确数字无异。

输出

• --format md → GitHub 风格的 Markdown 表格（单元格文本中的竖线会转义）。
• --format csv → 通过 csv.DictWriter 输出 CSV。
• -o FILE 将结果写入磁盘（UTF-8）；否则表格会输出到标准输出。

第一列始终是 Source（输入文件名）；转换失败的文件会生成一个 ERROR 行，以保持表格对齐。

工作流衔接

alterlab-pdf-extract 位于论文发现之后、综合分析之前：

1. 查找论文——数据库/搜索技能（alterlab-literature-review、搜索后端）。
2. 提取证据表格——本技能。
3. 综合分析/撰写——alterlab-literature-review、alterlab-paper-writer。

文件

• scripts/extract_to_table.py——CLI。--help 会列出所有标志；--columns / --column 用于定义表格；--backend、--format、--model、-o 用于控制提取 和输出。

属于 AlterLab Academic Skills 套件。