Section Anything

Section Anything

找出 PDF 中真正的章节：每个标题、标题级别、跨越的页码以及标题下方的准确文本。专为需要文档结构的 RAG 工作流和文档工具打造，并提供从免费规则到通读整份文档的大模型的多种模式，同时为每次付费运行设置严格的费用上限。

section-anything 0.1.3 的真实输出，使用 Quick 模式（gpt-6-luna）处理 Visual Instruction Tuning，Liu 等人撰写， arXiv:2304.08485，CC BY 4.0; 演示缩短了运行等待时间（录制内容，脚本）。 Quick 模式的输出在不同运行中可能略有差异。可在 Colab 笔记本 中试用该论文（Free 模式，无需密钥），或在浏览器中访问 Hugging Face Space（可对任意 PDF 使用 Free 模式，也提供三篇示例论文的已保存 Quick 检查和 Standard 运行；请勿上传机密文档）。

预发布版（0.1）。 API 在 1.0 之前可能会变更。

网站： https://omniwot.github.io/section-anything/（工作原理、基准测试、示例）

import section_anything

tree = section_anything.section("paper.pdf", mode="quick")
print(tree.to_markdown())
# # A Study of Sectioning
# ## 1 Introduction
# ### 1.1 Scope
# ## 2 Methods
print(tree.summary())  # mode, model, pages, sections, calls, tokens, cost_usd, seconds

在 Agent 中使用

Agent 可以先获取 PDF 的大纲，然后只读取所需章节（需要 0.1.6 或更高版本）。

MCP 服务可供 Claude Code、Claude Desktop、Cursor 和其他 MCP 宿主使用，提供三个只读工具：section_pdf（标题树；默认使用 Free 模式，无需模型，费用为 $0）、read_sections（所选章节的文本）和 estimate_cost（估算 quick 和 standard 的费用）。

claude mcp add --transport stdio section-anything -- uvx --from "section-anything[mcp]" section-anything-mcp

其他宿主在其 mcpServers JSON 中使用相同的命令：

{"mcpServers": {"section-anything": {"command": "uvx",
  "args": ["--from", "section-anything[mcp]", "section-anything-mcp", "--max-usd", "0"]}}}

付费模式使用服务环境中的 API 密钥（claude mcp add --env OPENAI_API_KEY=...），并通过 --max-usd 按文档设置费用上限（默认为 0.50；0 可确保所有运行都免费）。--root DIR 可限制服务能够读取的文件夹。

**Agent 技能：**将 skills/section-anything 复制到 Agent 的技能文件夹（Claude Code：~/.claude/skills/），Agent 就能以相同方式使用命令行：先获取大纲，再读取所需章节。

Shell：section-anything paper.pdf --format json --body 会以 heading_path、parent、页码和 text 的形式输出每个章节。

为什么要用

PDF 转换器大多根据行的外观推断标题，因此论文标题、作者姓名、图注和定理陈述可能被识别为章节，而真正的子章节也可能被分到错误的级别。任何依赖标题进行分块或导航的工具都会继承这些错误。Section Anything 会结合 PDF 自带的大纲（书签）、印刷版目录、排版和编号规则，并可选择使用大模型来审阅或读取文本。

结果

在 READoc 上的标题树相似度（TEDS，0–100，越高越好），使用 READoc 自带的评分代码，数据截至 2026 年 10 月。Docling 和 MinerU 转换整篇文档（布局、表格、图形、公式、OCR）；此处仅比较标题树。开发方法时未使用的论文：

READoc arXiv 论文（留出集）	文档数	TEDS
Section Anything standard（gpt-6-luna）	905	70.0
Section Anything quick（gpt-6-luna）	905	68.0
Section Anything free（无模型）	905	60.0
Docling 2.140（启用标题层级）	905	49.4

quick 对应 0.1.2 版，free 对应 0.1.5 版。0.1.1 找到了摘要的标题（期刊通常会把它设得较小、加粗，或与首行连在一起）：在预注册的留出测试中，free 提高了 2.4，quick 提高了 3.7（0.1.0：54.8 和 63.9）。0.1.2 会保留 PDF 提取器从标题中拆分出来的章节编号（“1” | “Introduction”）：在第二次预注册测试中，free 提高了 0.7（95% CI +0.5 至 +1.0），quick 提高了 0.5（95% CI +0.4 至 +0.8；在受其影响的 291 篇论文上提高了 1.7）（0.1.1：57.2 和 67.4）。 0.1.5 将正文后的部分（References、Acknowledgements、Appendix）和附录章节的层级设为与编号章节相同：在针对这些论文进行的第四次预注册测试中，free 提高了 2.1（95% CI +1.7 至 +2.4；136 篇论文得分更高，4 篇更低）（0.1.4：57.9）；README 未变。 standard 未使用上述任何改进。请参阅更新日志。

在同样的 905 篇论文上使用 MinerU 云服务（3.4.4，VLM）测试：我们的 standard 得分为 70.0，quick 为 68.0；MinerU 加上其自带的大模型标题层级处理（gpt-6.1-sol）为 64.8（配对差值：standard 高 5.1，95% CI +4.0 至 +6.2；若排除由我们使用 gpt-6.1-sol 执行该步骤时未返回可解析层级、因此保留 MinerU 原始层级的 154 篇论文，则高 2.8；quick 高 3.1，95% CI +2.1 至 +4.1，但排除这些论文后，层级差值为 +1.0，95% CI −0.03 至 +2.0）， MinerU 单独使用为 53.9，Docling 为 49.4。

在 GitHub README 上，free 得分高于 Docling：在开发时未使用的 1,112 篇已收藏的 READoc README 上，得分分别为 81.9 和 75.5；启用我们向上游提议的可选大纲检查后，Docling 得分为 79.7（docling#5002），其思路与 free 的大纲检查相同。 在开发时从未使用过的 27 份英国政府报告上（答案依据各报告的 HTML 版本），大纲检查使 free 的得分提高了 5.7（95% CI +0.4 至 +12.2；43.1 → 48.8；基于 0.1.0 测得）。

**其他工具表现更好的地方：**在 1,124 篇留出的 READoc README 上，我们的 quick 和 standard 与 Docling 持平（约 75）。在 905 篇留出的论文上，Docling 在 103 篇论文上的得分高于 standard，在 773 篇论文上的得分更低（差距超过 0.5 分）。Nougat 是一个使用 arXiv 数据训练的 OCR 模型，在已发表的 READoc arXiv 结果中得分最高（READoc 论文中为 88.5，使用的是较早版本的工具；我们未运行该模型）。Docling 和 MinerU 也能通过 OCR 读取扫描页面；Section Anything 需要文本层。更好的标题提升了我们在 Qasper 测试中的 RAG 检索效果，但没有提高答案质量。

设置和成本

模式	运行内容	发送给模型的内容	每 1,000 页的成本
free（默认）	将书签或印刷的目录作为大纲，然后应用排版和编号规则；完整大纲中未列出的标题会被舍弃	无	$0
quick	规则提出候选标题行；小型模型保留真正的标题并设置层级	仅候选行	约 $0.07（gpt-6-luna）
standard	模型读取每一行，并参考字体提示，标记各章节的起止位置	文档文本	约 $0.16（gpt-6-luna，默认）；使用 gpt-6.1-sol 时为 $2.90
local:<model>	使用本地 Ollama 模型执行 quick	不会有任何内容离开本机	$0
auto	先运行 free，然后仅对 Free 无法确定标题的文档运行 quick	无，或 quick 发送的内容	对 Free 确定的文档为 $0；其余文档按 quick 的费用计算

每次付费运行都会先估算费用并设置上限（每份文档默认 $0.50）；超过上限时会按你的选择降级（standard → quick → free）或失败。

对于同一类型的许多长文档，standard 可以选择性地进行集合调优：提供一段简短的指导文本，说明该类型文档的章节长什么样。该文本可以由库根据几份示例 PDF 撰写（write_guidance，或 section-anything guidance samples/*.pdf -o sheet.md），并附加到模型的指令中（Settings(heading_guidance=...)）。默认关闭；quick 会忽略它，因为测试发现这些指导表会导致它漏掉真实章节。在预注册测试中，模型根据几份示例文档撰写的指导表使 Claude Haiku 5.5 的章节 F1 提高了 0.081（95% CI +0.037 至 +0.127，39 份、四种类型的文档），使 gpt-6-luna 提高了 0.028（CI +0.006 至 +0.053，40 份文档）；根据缺乏代表性的示例撰写的指导表可能会降低表现。请参阅软件包 README。

quick 和 standard 默认使用 gpt-6-luna，这是上述 READoc 分数所对应的模型。standard 也可以改用 gpt-6.1-sol（SECTIONANY_STANDARD_MODEL=gpt-6.1-sol 或 model="gpt-6.1-sol"），成本约为 18 倍。仅在开发文档上测试（98 篇 READoc 论文和 100 篇 README，代码相同），它在 README 上的得分高出 5.8 分（95% CI +2.1 至 +9.6），在论文上高出 0.9 分（CI -0.3 至 +2.1，差异不显著）；尚未在留出文档上确认这一结果。

安装

Python 3.11 或更高版本：

pip install section-anything
pip install "section-anything[anthropic]" # optional: Claude models on Anthropic's own API
pip install "section-anything[docling]"   # optional: tree.to_docling_document()
pip install "section-anything[langfuse]"  # optional Langfuse tracing
pip install "section-anything[mcp]"       # optional MCP server: section-anything-mcp
# latest from GitHub:
pip install "git+https://github.com/Omniwot/section-anything#subdirectory=packages/section-anything"

命令行：

section-anything paper.pdf                                # free, Markdown headings
section-anything paper.pdf --mode quick --format json     # JSON with spans and cost
section-anything paper.pdf --mode standard --max-usd 0.5  # cap this document at $0.50

API 密钥仅从环境变量读取（SECTIONANY_API_KEY；对于 OpenAI 端点，则使用 OPENAI_API_KEY）；任何兼容 OpenAI 的端点都可使用。Claude 模型通过 Anthropic 自有 API 运行，需要安装 anthropic extra 并设置 ANTHROPIC_API_KEY；在开发文档上，Claude Haiku 5.5 的表现与默认模型持平，成本约为 3 倍（提供商）。完整选项、输出格式以及针对不可信 PDF 的安全模型，请参阅：packages/section-anything/README.md。

集成

每个章节对应一份文档，并将标题路径、页码和字符范围作为元数据。每个 软件包仅依赖 section-anything 和对应框架的核心软件包。

pip install langchain-section-anything
pip install llama-index-readers-section-anything
pip install lightrag-section-anything

框架	软件包	用法
LangChain	langchain-section-anything	SectionAnythingLoader("paper.pdf", mode="free").load()
LlamaIndex	llama-index-readers-section-anything	SectionAnythingReader(mode="free").load_data("paper.pdf")，或用作 SimpleDirectoryReader 的 .pdf 阅读器
LightRAG	lightrag-section-anything	用于 LightRAG 基于标题的分块器的解析器引擎（sectionany_free、sectionany_quick 等），无需 MinerU 或 Docling 服务

要对这些标题运行 Docling 的 HybridChunker 或 Unstructured 的 chunk_by_title，请使用 tree.to_docling_document() 或 tree.to_unstructured_elements() 导出树 （方法）。如果你已经在 运行 Docling，section("report.pdf", docling=doc) 会将其布局标签作为提示，而 section(doc) 会根据 Docling 的文本 为扫描版 PDF 划分章节 （方法）。

局限性

• 读取 PDF 的文本层；扫描版 PDF 需要先进行 OCR，或使用 Docling 生成其输出 （可选，与 Docling 搭配使用）。
• 表格、图形和公式不会被结构化；其中的文本仍保留在章节文本中。
• 当 PDF 带有书签或印刷版目录时，free 效果最佳。当书签看起来完整时，它会丢弃书签中未列出的标题；如果书签只列到顶层，实际存在的更深层标题就会丢失（约 6% 的 README 会损失超过 5 分）。可通过 SECTIONANY_DEMOTE_UNLISTED_HEADINGS='[]' 关闭此功能。
• quick 和 standard 会将文本发送到你配置的提供方。

仓库

路径	内容
packages/section-anything/	库和 CLI（Apache-2.0）
packages/langchain-section-anything/	LangChain 文档加载器
packages/llama-index-readers-section-anything/	LlamaIndex 阅读器
packages/lightrag-section-anything/	LightRAG 解析器插件
backend/、frontend/	演示 Web 应用：上传 PDF，查看高亮显示的章节（文档）
site/	项目网站和基准测试表（site/data/results.js）
corpus/	我们的测试语料库：答案键、结果以及用于重建语料库的工具（不存储 PDF）
docs/	文档：Qasper 上的 RAG、Docling 贡献、计划和论文草稿

数据与致谢

• 基准测试使用 READoc（数据集采用 MIT 许可证， Hugging Face），并使用 READoc 自带的评分代码； 此处未包含该代码。
• 未见过的文档检查使用 HiPS 法律书籍标注 （CC BY-NC 4.0）、英国政府报告（Open Government Licence v3）和加拿大联邦法案 （Justice Laws 网站）。
• 每个语料库来源及其许可证：corpus/DATA-LICENSES.md。
• 引用本项目的方法请参阅 CITATION.cff。

许可证

代码：Apache-2.0（LICENSE、NOTICE）。corpus/ 下的数据遵循其来源的许可证：请参阅 corpus/DATA-LICENSES.md。