中文 | English

docdistill

通过 VLM 将文档转为文本。一个独立的 Python MCP server，提供两个解耦的 tool： document_to_pdf（Office → PDF，走真实渲染器）和 analyze_doc（PDF → Markdown/LaTeX/JSON， 走 MinerU 的 VLM）。只接受本地文件路径，图片本地化落地，产物输出到源文件旁的 .docdistill/ 目录。

前身：seed-viz 的 analyze_doc（Node 版），现已独立为纯 Python 项目。

仓库：https://gitcode.com/Joe-zhouman/docdistill

安装

在 MCP 客户端配置（.mcp.json）：

{
  "mcpServers": {
    "docdistill": {
      "command": "uvx",
      "args": ["docdistill"],
      "env": { "BACKEND": "mineru-official", "AUTH": "<你的 MinerU token>" }
    }
  }
}

免费 MinerU token（1000 次/天）：https://mineru.net/apiManage/token

PyPI：https://pypi.org/project/docdistill/

后端

BACKEND	对接目标	AUTH	ENDPOINT
mineru-official（默认）	mineru.net 云服务	必填（MinerU token）	可选（默认 mineru.net）
mineru-tasks-v3.2	自部署 mineru-api	不需要	必填（如 http://127.0.0.1:5580）

mineru-tasks-v3.2 面向自部署 MinerU 的用户。典型场景：机构或校园网内部署一份，内网共享使用。 无鉴权、无频率限制、数据不出内网。

平台支持（v1）

• PDF 提取（analyze_doc）：全平台支持（走托管后端，任意联网机器均可）。
• Office → PDF（document_to_pdf）：仅 Linux（LibreOffice）+ Windows（Word/PowerPoint COM）。 macOS 用户处理 Office 文件时会收到明确报错 —— 请手动导出 PDF，再用 analyze_doc。

CLI

docdistill document-to-pdf paper.docx        # → paper.pdf，提示使用 analyze_doc
docdistill analyze-doc paper.pdf              # → .docdistill/paper.md + .docdistill/images-<hash>/
docdistill analyze-doc thesis.pdf --output-format latex
docdistill analyze-doc doc.pdf --backend mineru-tasks-v3.2 --endpoint http://127.0.0.1:5580

输出落在源文件旁的 .docdistill/ 目录。图片目录使用短 hash 命名（images-<hash>），而非源文件名 —— 这样即使源 PDF 文件名含空格或中文，Markdown 中的图片引用也能正常渲染。

PDF 超过 180 页自动并发分页处理，部分页失败不影响整体。超过 200MB 的文件直接报错。

已知行为：VLM 会拆分多子图

VLM 基于视觉语义做分割，不是机械切像素。对于含多个子图的大图（如论文中的 "图 4 (a)–(e)"）， VLM 倾向于按视觉边界拆成多个独立图块。反过来，视觉上像表格的区域（有清晰网格线）会被提取为 Markdown 表格而非图片 —— 这通常正是你想要的结果。

这是 VLM 自身的行为，不是 docdistill 的 bug，且没有 API 开关可以关闭。换成非 VLM 的 pipeline 模型可以避免拆分，但文本质量会明显下降，因此 docdistill 默认走 VLM。如需原始整图，请查阅源 PDF。

状态

0.2.0 beta。1.0 之前接口可能变动。