mineru2md 0.1.1

使用 MinerU API 将 PDF 文件转换为 Markdown 的命令行工具

mineru2md

使用 MinerU API 将 PDF 文件转换为 Markdown 的命令行工具。

功能

• 🚀 单个命令将本地 PDF 转为 Markdown
• 🎯 支持 免费模式（无需 API Key，限制 10MB / 20 页）
• 🔑 支持 精准解析模式（配置 MINERU_API_KEY 后自动启用，最高支持 200MB / 600 页）
• 📁 输出 Markdown 文件默认与源 PDF 同名、同目录
• 🔄 自动重试（最多 3 次，指数退避）
• ⚡ 若目标 Markdown 已存在则跳过，避免重复转换

环境要求

• Python >= 3.11
• uv 包管理工具（推荐），或 pip

安装

方式一：通过 uv 全局安装（推荐）

uv tool install mineru2md

方式二：通过 pip 安装

pip install mineru2md

方式三：从源码安装

git clone <repo-url>
cd mineru-cli
uv tool install .

安装成功后，mineru 命令即可在终端直接使用。

环境变量配置

变量名	必填	说明
MINERU_API_KEY	否	MinerU 精准解析 API 的 Token。未设置时使用免费 Agent API

获取 API Key

1. 访问 MinerU 官网 注册/登录
2. 进入个人中心或 API 管理页面，申请 Token
3. 将 Token 设置为环境变量：

macOS / Linux：

export MINERU_API_KEY="your-api-token"

可将该行添加到 ~/.zshrc 或 ~/.bashrc 中持久化。

Windows（PowerShell）：

$env:MINERU_API_KEY="your-api-token"

两种模式对比

维度	免费模式（无 API Key）	精准解析模式（有 API Key）
API 接口	/api/v1/agent	/api/v4
文件大小限制	≤ 10 MB	≤ 200 MB
页数限制	≤ 20 页	≤ 600 页
模型	pipeline 轻量模型	vlm 模型
输出格式	Markdown	Zip 包（含 Markdown、JSON 等）

使用方法

mineru <pdf路径> [-o 输出目录]

参数说明

参数	说明
pdf_path	（必填）本地 PDF 文件路径
-o, --output-dir	（可选）输出目录，默认为 PDF 文件所在目录

示例

# 基本用法：将 example.pdf 转为 example.md（输出到同目录）
mineru ./example.pdf

# 指定输出目录
mineru ./example.pdf -o ./output

# 配合环境变量使用精准解析
export MINERU_API_KEY="your-token"
mineru ./large-document.pdf

开发

# 克隆项目
git clone <repo-url>
cd mineru-cli

# 创建虚拟环境并安装依赖
uv sync

# 直接运行
python main.py ./example.pdf

技术栈

• Python 3.11+
• requests — HTTP 客户端
• uv — 包管理与构建

License

MIT