1. 为什么我要把 PDF 转成 MarkdownMinerU API 批量转换的真实场景如果你正在做论文复现、知识库搭建或者 RAG 检索大概率会遇到一个很烦的问题手里一堆 PDF想喂给大模型但直接丢 PDF 进去既浪费 token模型读起来也不稳定。PDF 本质上是给人看的排版格式不是给机器读的结构化数据表格、公式、多栏排版一进去就乱。MinerU 就是解决这个问题的工具。它是 OpenDataLab 推出的文档解析模型能把 PDF 转成 Markdown、JSON 这类机器可读格式表格和公式也能保留结构。我这次的目标很明确把本地papers/raw_papers目录下的论文批量转成 Markdown输出到papers/mineru_outputs并且用一套统一的 Key 管理调用凭证。这里会涉及两个层面一是直接写脚本调 MinerU 的 API二是把脚本包装成 MCP server让 Codex、Cursor、Claude Code 这类 AI Agent 用自然语言触发转换。而凭证管理这块我用 TaoToken 的统一 Key/API 通道来管避免每个工具各配一套 Key、到处散落。适合谁看需要批量处理 PDF 的科研党、做本地知识库的开发者、想把文档解析接进 Agent 工作流的人。下面从申请 Key 开始一步步把整条链路跑通。2. TaoToken 前置准备统一 Key 与 API 通道配置在写脚本之前先把凭证这层理清楚。MinerU 的精准解析 API 需要 Token而如果你同时还在用其他模型服务Key 会越攒越多。我的做法是用 TaoToken 作为统一的 API 通道来管理调用凭证这样脚本里读的是同一套环境变量切换和轮换都方便。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用它作为 Base URL。具体操作上先去控制台创建 Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。在 API Keys 页面生成一个 Key复制保存好后面脚本和 MCP 配置都要用。API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后不要写死在代码里。我在项目根目录建了一个.env文件内容就一行MINERU_API_TOKEN你的Key然后在.gitignore里加上.env防止 Key 被 Git 跟踪。这一步很关键我见过太多人把 Key 提交到仓库然后被迫轮换。如果你用的是 VS Code可以在.vscode/launch.json里配置envFile让调试时自动加载.env{ version: 0.2.0, configurations: [ { name: Run MinerU Batch PDF, type: python, request: launch, program: ${workspaceFolder}/tools/batch_pdf_to_markdown.py, console: integratedTerminal, envFile: ${workspaceFolder}/.env } ] }这样脚本运行时通过os.environ.get(MINERU_API_TOKEN)就能拿到 Key本地调试和命令行运行都不用手动 export。关于模型选择MinerU 提供pipeline、vlm、MinerU-HTML三个版本。官方推荐vlm解析精度最高我实测下来表格和公式的还原确实更好。语言参数用ch覆盖中英文混排的论文场景。输出格式除了默认的 Markdown、JSON还可以额外导出docx、html、latex。如果你打算长期跑批量转换或者接进 Agent 工作流可以考虑 Coding Plan地址https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它更适合持续性的编码和 Agent 调用场景。3. 可复制配置batch_pdf_to_markdown.py 脚本与 MCP 注册片段这一节给出可以直接复制的配置。先看脚本文件tools/batch_pdf_to_markdown.py的核心结构。它负责真正调用 MinerU API包含文件收集、页数校验、上传、轮询、下载解压几个阶段。关键常量部分BASE_URL https://mineru.net FILE_URLS_BATCH_ENDPOINT /api/v4/file-urls/batch URL_TASK_BATCH_ENDPOINT /api/v4/extract/task/batch BATCH_RESULTS_ENDPOINT /api/v4/extract-results/batch MAX_FILE_BYTES 200 * 1024 * 1024 MAX_PDF_PAGES 200 MAX_BATCH_FILES 200 SUPPORTED_MODELS {pipeline, vlm, MinerU-HTML} SUPPORTED_EXPORT_FORMATS {docx, html, latex}主流程在__main__里参数集中在这里改PDF_DIR Path(papers/raw_papers) OUTPUT_DIR Path(papers) / mineru_outputs MODEL_VERSION vlm EXPORT_FORMATS [docx, html, latex] ENABLE_FORMULA True ENABLE_TABLE True LANGUAGE ch POLL_SECONDS 15 TIMEOUT_SECONDS 60 * 60运行前先装依赖python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pypdf然后直接跑python tools/batch_pdf_to_markdown.py脚本会先校验每个 PDF 的大小和页数超过 200MB 或 200 页会直接报错。校验通过后请求签名上传 URL逐个 PUT 上传再轮询 batch 结果最后下载 ZIP 并解压到papers/mineru_outputs/extracted/下每篇论文一个文件夹。接下来是 MCP 部分。新建tools/mineru_mcp_server.py把上面的函数包装成 MCP toolfrom pathlib import Path from tools.batch_pdf_to_markdown import ( collect_pdf_paths, download_and_extract_results, get_api_token, request_local_upload_urls, poll_batch_results, upload_file_to_signed_url, validate_pdf_batch, ) DEFAULT_PDF_DIR papers/raw_papers DEFAULT_OUTPUT_DIR papers/mineru_outputs DEFAULT_MODEL_VERSION vlm def convert_pdfs_to_markdown( pdf_dirDEFAULT_PDF_DIR, output_dirDEFAULT_OUTPUT_DIR, model_versionDEFAULT_MODEL_VERSION, extra_formatsNone, enable_formulaTrue, enable_tableTrue, languagech, poll_seconds15, timeout_seconds60 * 60, ): pdf_dir_path Path(pdf_dir) output_dir_path Path(output_dir) requested_extra_formats list([html, latex] if extra_formats is None else extra_formats) api_token get_api_token() pdf_paths collect_pdf_paths(pdf_dir_path) validate_pdf_batch(pdf_paths) batch_id, signed_upload_urls request_local_upload_urls( pdf_paths, api_token, model_version, requested_extra_formats, enable_formula, enable_table, language, ) for pdf_path, signed_upload_url in zip(pdf_paths, signed_upload_urls): upload_file_to_signed_url(pdf_path, signed_upload_url) completed_results poll_batch_results(batch_id, api_token, poll_seconds, timeout_seconds) saved_zip_paths download_and_extract_results(completed_results, output_dir_path) return { batch_id: batch_id, pdf_count: len(pdf_paths), saved_zip_paths: [str(path) for path in saved_zip_paths], output_dir: str(output_dir_path), } def create_mcp_server(): from mcp.server.fastmcp import FastMCP mcp FastMCP(mineru) mcp.tool()(convert_pdfs_to_markdown) return mcp if __name__ __main__: create_mcp_server().run()MCP 环境建议单独建避免和旧项目冲突conda create -n mineru-mcp python3.12 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge conda activate mineru-mcp python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp pypdf注册给 Codexcodex mcp add mineru -- D:\Program\anaconda3\envs\mineru-mcp\python.exe D:\PycharmProjects\project\tools\mineru_mcp_server.py这里三件套要写全Base URL 用 TaoToken 的https://taotoken.net/apiKey 从.env读Model ID 用vlm。注册完验证codex mcp list codex mcp get mineru4. 验证请求与成功结果单文件与批量目录两种场景配置好之后先验证单文件场景再跑批量目录。单文件验证最简单的方式是临时把PDF_DIR指向一个只放了一篇 PDF 的目录或者直接在 MCP 里用自然语言指定。跑起来后终端会打印准备上传 1 个 PDF。 batch_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 上传: attention_is_all_you_need.pdf 上传完成开始轮询解析结果。 等待解析完成: attention_is_all_you_need.pdfpending 等待解析完成: attention_is_all_you_need.pdfrunning 下载完成: papers/mineru_outputs/zip/attention_is_all_you_need.zip看到下载完成并且列出 ZIP 路径就说明单文件链路通了。解压后的目录结构是papers/mineru_outputs/extracted/attention_is_all_you_need/ ├── attention_is_all_you_need.md ├── attention_is_all_you_need.json ├── attention_is_all_you_need.docx ├── attention_is_all_you_need.html └── attention_is_all_you_need.latex打开.md文件检查一下标题层级、表格、公式是否保留。我实测下来vlm模型对公式的还原比较到位行内公式和独立公式都能转成 LaTeX 形式。批量目录场景就是把多篇 PDF 放进papers/raw_papers重新跑脚本。终端会显示每个文件的上传和轮询状态。全部完成后extracted下会按 PDF 文件名生成多个文件夹。如果你用 MCP重启 Codex 后直接说调用 mineru把 papers/raw_papers 里的 PDF 转成 Markdown输出到 papers/mineru_outputs模型用 vlm。或者更短调用 mineru把 papers/raw_papers 里的 PDF 转成 Markdown。Agent 会调用convert_pdfs_to_markdown这个 tool返回 batch_id、pdf_count 和输出目录。你可以根据返回的saved_zip_paths去确认结果。验证成功的标准有三个一是终端或 Agent 返回里没有报错二是extracted目录下每个 PDF 都有对应文件夹三是 Markdown 文件能正常打开且内容完整。如果只想快速验证模型效果也可以去模型对话页面直接试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把我踩过的坑和常见报错对照列出来。401 Unauthorized最常见的原因是.env没被加载或者 Key 复制时带了空格。检查get_api_token()是否真的读到了值可以在脚本里临时打印api_token[:8]确认。另外确认.env文件在项目根目录且MINERU_API_TOKEN后面没有多余引号。local proxy failed / connection refused这类报错通常是网络层的问题。先确认BASE_URL写的是https://mineru.net没有多写路径。如果用了 TaoToken 的 API 通道确认 Base URL 是https://taotoken.net/api不要带 UTM 参数。签名上传 URL 是 MinerU 返回的临时地址不要手动改。reading choices / JSON 解析失败这个报错一般出现在request_json里说明返回的不是合法 JSON。可能是接口返回了 HTML 错误页或者 batch_id 拼错了。检查BATCH_RESULTS_ENDPOINT拼接后的完整 URL确认 batch_id 是从上传响应里取的data[batch_id]。OAuth / 登录态问题MinerU 的精准解析 API 用的是 Bearer Token不是 OAuth 流程。如果你看到 OAuth 相关报错大概率是误用了其他接口。确认请求头是Authorization: Bearer token而不是Authorization: OAuth ...。pypdf 缺失报错信息是需要安装 pypdf 才能在上传前校验 PDF 页数。解决python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pypdfMCP 注册后 Codex 找不到工具先codex mcp list确认 mineru 在列表里。如果不在检查codex mcp add命令里的 Python 路径和脚本路径是否都是绝对路径。Windows 下路径用反斜杠且确认mineru-mcp环境里装了mcp和pypdf。上传超时大文件上传可能超过默认超时。upload_bytes_to_signed_url里超时设的是 300 秒如果还超时检查文件是否接近 200MB 上限或者网络是否稳定。轮询一直 pendingpoll_batch_results默认超时 1 小时。如果一直 pending先确认 MinerU 服务状态再检查POLL_SECONDS是否设得太短导致请求过频。我一般设 15 秒。排障时如果涉及接入配置可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。6. 把链路接进你的工作流从脚本到 Agent 的下一步整条链路跑通之后你会发现真正省事的地方在于复用。batch_pdf_to_markdown.py里的函数是纯逻辑MCP server 只是薄薄一层包装。以后要加新功能比如只转某个子目录、按文件名过滤、转换后自动切分 chunk都只需要改脚本MCP tool 自动继承。凭证管理这块用 TaoToken 统一 Key 的好处是脚本、MCP、Agent 读的是同一套环境变量。轮换 Key 时只改.env一处不用去每个工具里翻配置。如果你后面还要接 Claude Code 做代码相关的 Agent 任务可以看 ClaudeCodeAnthropic 的接入方式https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。一个实用技巧转换完成后先别急着把整个 Markdown 丢给模型。MinerU 输出的 JSON 里带了版面结构信息做 RAG 切分时用 JSON 比用 Markdown 更可控。我一般先用 Markdown 做人工检查确认解析质量没问题再用 JSON 做后续处理。最后提醒一句.env一定要进.gitignore。我见过有人把 Key 推到公开仓库几分钟内就被扫到滥用。Key 泄露后第一时间去控制台轮换别拖。