pdf-converter

将文档转换为 Markdown

使用 MinerU Open API CLI，将 PDF、图片、Office 文档等转换为整洁的 Markdown。基本用法无需 API 密钥。

语言规则

请用用户使用的同一种语言回复。这一点不可妥协。

核心工作流

提取通常只是第一步。典型流程如下：

1. 提取 — 使用 mineru-open-api 将文档转换为 Markdown
2. 阅读与处理 — 根据用户的实际需求提供帮助

MinerU 输出的是原始 Markdown，不会解读或重组内容。如果用户要求“提取表格”“总结论文”或“找出主要发现”，你需要阅读输出并自行完成这些工作。MinerU 负责 OCR 和版面分析；你负责理解内容。

用户需要持久保存输出（转换、批量处理）时，使用 -o 保存到文件。如果内容会立即使用（总结、问答），则省略 -o，直接读取标准输出。

例如：

• “帮我把这个PDF转成markdown” → 使用 -o 保存到文件，完成
• “提取这篇论文里的表格” → 使用 -o 保存，然后读取文件并提取表格
• “这篇论文讲了什么” → 使用标准输出即可，直接读取输出并总结
• “把PDF里的参考文献整理出来” → 使用标准输出或 -o，然后解析参考文献部分

按页码范围提取规则

将 --pages 与指向目录的 -o 一起使用时，CLI 仅根据输入文件名生成输出文件名。这意味着对同一文件进行多次页码范围提取时，输出会相互覆盖。

重要：你必须通过将输出路径改为包含页码范围的明确文件路径来避免这种情况。

# ❌ WRONG — same file overwrites itself
mineru-open-api flash-extract report.pdf --pages 1-20  -o ./out/
mineru-open-api flash-extract report.pdf --pages 21-40 -o ./out/

# ✅ CORRECT — unique filenames per chunk
mineru-open-api flash-extract report.pdf --pages 1-20  -o ./out/report_p1-20.md
mineru-open-api flash-extract report.pdf --pages 21-40 -o ./out/report_p21-40.md

每当用户要求按页码范围拆分文档（例如，“提取第 1-20 页”“拆分成多个部分”），始终将 -o 生成为带有 _p{range} 后缀的确切文件路径。

用户表述	生成内容
“把 report.pdf 每20页拆分成多个文件”	-o ./out/report_p1-20.md、-o ./out/report_p21-40.md……
“提取第 1-10 页和第 11-20 页”	-o ./out/report_p1-10.md、-o ./out/report_p11-20.md

两种提取模式

flash-extract — 快速，无需身份验证

适合快速阅读。无需 API 密钥或设置。

mineru-open-api flash-extract report.pdf                               # to stdout (for immediate consumption)
mineru-open-api flash-extract report.pdf -o ./output/                  # save to file
mineru-open-api flash-extract report.pdf -o ./output/report_p1-10.md   # page range (explicit file path)
mineru-open-api flash-extract report.pdf -o ./output/ --language en    # language hint
mineru-open-api flash-extract https://example.com/paper.pdf            # URL input

支持： PDF、图片（PNG、JPG、WebP……）、DOCX、PPTX、Excel（XLS、XLSX） 限制： 每份文档最大 10 MB / 20 页 输出： 仅支持 Markdown — 图片、表格和公式可能会变为占位符

除非用户有更高需求，否则默认使用 flash-extract。

extract — 高精度，需要身份验证

用户需要保留完整内容时使用：保留图片、准确识别表格、LaTeX 公式或输出非 Markdown 格式。需要通过 mineru-open-api auth 获取令牌。

mineru-open-api extract report.pdf                              # to stdout
mineru-open-api extract report.pdf -o ./out/                    # save with all assets
mineru-open-api extract report.pdf -o ./out/ -f md,docx         # multiple output formats
mineru-open-api extract report.pdf -o ./out/report_p1-20.md --pages 1-20  # page range (explicit file path)
mineru-open-api extract report.pdf -o ./out/ --ocr          # force OCR for scanned docs
mineru-open-api extract *.pdf -o ./results/                 # batch processing
mineru-open-api extract --list files.txt -o ./results/      # batch from file list

支持： PDF、图片、DOC、DOCX、PPT、PPTX、HTML 限制： 每份文档最大 200 MB / 600 页 输出格式： md、json、html、latex、docx（使用 -f，以逗号分隔） 功能： 公式识别（默认开启）、表格识别（默认开启）、OCR 开关、批量模式、模型选择（vlm、pipeline、html）

如果用户尚未完成身份验证，先引导其运行 mineru-open-api auth。

如何选择

情况	模式
“这个 PDF 讲了什么？”	flash-extract
快速总结或浏览内容	flash-extract
需要保留图片、表格或公式	extract
文档大于 10 MB 或超过 20 页	extract
批量转换多个文件	extract
需要 DOCX/LaTeX/HTML 输出	extract
扫描文档需要 OCR	使用 --ocr 的 extract

语言支持

默认值为 ch（中文 + 英文）。使用 --language 指定其他语言。常用代码：

语言	代码	语言	代码
中文 + 英文	ch	日语	japan
英语	en	韩语	korean
法语	fr	繁体中文	chinese_cht
德语	de	西班牙语	es
俄语	ru	阿拉伯语	ar
葡萄牙语	pt	印地语	hi
意大利语	it	越南语	vi
泰语	th	土耳其语	tr

总共支持 80 多种语言——对于上面未列出的语言，请使用 PaddleOCR 语言代码。

数据流

这两个命令都会将文档发送到 MinerU 的 API（mineru.net）进行处理。这是一次无状态 API 调用，不会持久存储数据。MinerU 是由 OpenDataLab（Shanghai AI Lab）开发的开源项目：https://github.com/opendatalab/MinerU

故障排除

• 调试 API 请求： 添加 -v 标志以查看 HTTP 请求/响应详情（例如，mineru-open-api flash-extract report.pdf -v）
• 未找到 CLI： 通过以下任一方式安装：
  • npm i -g mineru-open-api（Node.js）
  • uv tool install mineru-open-api（Python/uv）
  • macOS/Linux：curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh
  • Windows：irm https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 | iex
• 提取时出现身份验证错误： 运行 mineru-open-api auth 设置令牌
• 大文件超时： 使用 --timeout 600 增加超时时间（秒）
• 输出语言错误： 明确设置 --language（例如，英文文档使用 --language en）