1. 长 PDF 解析为什么总在 RAG 和 Agent 里翻车如果你正在做 RAG 或 Agent 项目大概率遇到过这种场景一份 200 页的科研论文或企业年报丢进流水线解析到一半超时重跑一次又从第一页开始或者解析成功了但跨页表格被截成两半、公式编号丢失、双栏论文阅读顺序错乱chunk 里混进页眉页脚检索出来的证据链根本对不上原文。这不是模型不行而是把长文档解析当成了大文件上传而不是长任务编排。RAG 和 Agent 需要的不是手工拆 PDF 的脚本而是一条可恢复、可追踪、可验收的解析流水线。核心思路是用 MinerU 3.x 做结构化文档产出Markdown、JSON、LaTeX、图片资产通过 MCP 接入统一的 Key/API 通道 TaoToken把解析能力变成 Agent 可调用的工具同时用检查点机制保证中断后能续跑。这篇就给你一套可复制的config.toml与settings.json骨架并演示中断续跑和结果校验的完整动作。适合谁看正在搭 RAG 知识库、做 Agent 工具链、或者被长 PDF 解析折磨过的工程师。读完你能拿到一套能直接改参数就跑的配置而不是又一篇注册即用的注水教程。2. TaoToken 前置统一 Key 与 API 通道在把 MinerU 接进流水线之前先解决一个工程问题解析服务、Agent 调用、模型对话往往散落在不同的 Key 和 endpoint 上一旦要换通道或做审计就得满项目改配置。TaoToken 在这里的角色是统一入口——你可以在一个控制台里管理 Key把模型对话、编码任务、文档解析相关的调用收敛到同一条 API 通道上。具体操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 基地址统一用 https://taotoken.net/api 不加 UTM。拿到 Key 之后不要硬编码进脚本。正确做法是写进环境变量或配置文件让 MinerU 的 MCP Server、Python SDK、以及后续的 Agent 调用都从同一处读取。这样做的直接好处是解析任务失败时你能快速判断是 Key 额度问题、通道问题还是文档本身的问题而不是在多个 token 之间来回猜。注意MCP Server 会把文件或 URL 发往解析服务涉及未公开论文、合同、财务数据时先确认外发权限必要时走本地部署。3. 可复制配置骨架config.toml 与 settings.json这一节是全文的核心。下面给出两份可直接落地的配置骨架一份给 MinerU 解析流水线用config.toml一份给 MCP 客户端和 Agent 用settings.json。参数按你的实际环境替换即可。3.1 config.toml解析流水线与检查点# config.toml —— MinerU 解析流水线配置骨架 [api] # 统一走 TaoToken 通道Key 从环境变量读取避免硬编码 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_seconds 600 max_retries 3 [parse] # 输入与输出 input_dir ./samples output_dir ./runs # 页码范围支持断点续跑中断后改这里即可 pages 1-120 model vlm ocr true table true formula true language ch extra_formats [docx, html, latex] [checkpoint] # 检查点文件记录已完成页、失败页、task_id enabled true path ./runs/checkpoint.json # 每完成 N 页写一次盘防止长任务全丢 flush_every_pages 10 resume true [review] # 抽样验收配置 sample_pages [1, 18, 19, 35, 36] high_risk_types [cross_page_table, formula, scanned_page] fail_log ./runs/failures.jsonl关键点说明pages字段是续跑的抓手中断后不用从头再来checkpoint.flush_every_pages控制写盘频率长文档建议 10 页一次太频繁伤 IO太稀疏丢进度review.sample_pages把高风险页固定下来每次回归都查这几页。3.2 settings.jsonMCP 客户端与 Agent 接入{ mcpServers: { mineru: { command: uvx, args: [mineru-open-mcp], env: { MINERU_API_TOKEN: ${TAOTOKEN_API_KEY}, MINERU_BASE_URL: https://taotoken.net/api, OUTPUT_DIR: /absolute/path/to/mineru-runs, CHECKPOINT_FILE: /absolute/path/to/mineru-runs/checkpoint.json, MAX_PAGES_PER_TASK: 120 } } }, agent: { tool_timeout_seconds: 900, allow_local_paths: [./samples], allow_urls: [], auto_write_to_kb: false } }auto_write_to_kb设为false是刻意的解析成功不等于适合入库半成品 Markdown 直接进生产知识库后面检索出来的答案会带着错误结构一起被 embedding 放大。allow_urls留空避免 Agent 自动抓取未授权地址。3.3 参数对照表参数作用建议值踩坑提示pages页码范围按检查点动态调整续跑时只填未完成段model解析模式vlm或pipeline扫描件优先 vlmocr文字识别扫描件必开原生文本 PDF 可关省时间table表格提取有表格就开跨页表需人工复核formula公式识别论文必开输出 LaTeX 需抽样核对flush_every_pages写盘频率10太小伤 IO太大丢进度max_retries重试次数3配合失败日志定位阶段4. 验证请求与成功结果配置写好后先做小样本预检再跑长任务。下面给出 CLI、Python SDK 和 MCP 三种入口的验证动作。4.1 CLI 预检# 先用单份小样本确认通道和参数没问题 export TAOTOKEN_API_KEY你的Key mineru -p ./samples/long-report.pdf -o ./runs/long-report -b pipeline跑通后检查./runs/long-report下是否同时生成了 Markdown、JSON 和图片资产目录。如果只有 Markdown 没有 JSON说明结构化输出没开回去检查extra_formats。4.2 Python SDK 提交长任务并轮询from mineru import MinerU import time, json, os client MinerU(os.environ[TAOTOKEN_API_KEY]) batch_id client.submit( ./samples/long-report.pdf, modelvlm, ocrTrue, tableTrue, formulaTrue, pages1-120, extra_formats[docx, html, latex], ) while True: result client.get_batch(batch_id)[0] print(result.state, result.progress) if result.state in (done, failed): break time.sleep(10) if result.state done: result.save_all(./runs/long-report) # 写检查点记录已完成页 with open(./runs/checkpoint.json, w) as f: json.dump({task_id: result.task_id, pages_done: 1-120}, f) else: raise RuntimeError(fparse failed: {result.task_id})成功结果的判断标准不是state done而是三件事同时成立Markdown 能正常渲染、JSON 里元素类型和页码对得上、图片资产路径在 Markdown 里可回溯。我试过只看 state 就入库结果跨页表格缺表头检索时证据链直接断掉。4.3 MCP 调用验证Agent 侧调用解析工具后应该拿到的是任务句柄而不是阻塞等待{ tool: submit_parse_task, args: { file: ./samples/long-report.pdf, pages: 1-120, outputs: [markdown, json] }, returns: { task_id: task_20260721_001, state: running, progress: 0.35 } }随后用get_parse_task(task_id)查询状态拿到markdown_path、json_path、assets和failures。这样 Agent 不会因为一次长解析超时而卡死。4.4 中断续跑演示假设解析到第 60 页时进程被杀检查点里记录了pages_done: 1-60。续跑时只需把pages改成61-120重新提交# 读取检查点只跑未完成段 python resume_parse.py --checkpoint ./runs/checkpoint.json --input ./samples/long-report.pdfresume_parse.py的核心逻辑就是读检查点、算剩余页、提交新任务、合并输出。这样一份 200 页文档中断三次也能拼回完整结果而不是每次从第一页重来。5. 本篇常见错排查5.1 解析成功但表格错列现象JSON 里表格元素存在但行列关系错乱合并单元格被拆散。原因通常是跨页表格没开滑动窗口或者table参数没生效。排查动作检查config.toml里table true并在review.sample_pages里固定几个关键表格页做单元格级核对。跨页大表建议人工复核后再入库。5.2 中断后重跑从头开始现象进程被杀后重新提交进度从 0 开始。原因是没有启用检查点或者resume true没配。排查动作确认checkpoint.enabled true检查checkpoint.json是否真的写入了pages_done。如果检查点文件为空说明flush_every_pages设得太大任务还没到写盘点就挂了。5.3 MCP 调用超时现象Agent 调用解析工具后长时间无响应。原因是把长任务当成了短 RPC。排查动作确认 MCP Server 返回的是task_id而不是阻塞结果agent.tool_timeout_seconds设到 900 以上并让 Agent 用轮询而不是同步等待。5.4 Key 或通道报错现象提交任务返回鉴权失败或额度不足。排查动作确认TAOTOKEN_API_KEY环境变量已导出base_url用的是https://taotoken.net/api。如果 Key 没问题去控制台核对额度和调用记录。接入细节参考接入文档Key 管理在 API Keys 页面。5.5 扫描件 OCR 漏字现象扫描页文字可读但关键数字或单位错误。原因是低清扫描或特殊字体。排查动作把该页加入high_risk_types的scanned_page人工标注错字漏字必要时换更高分辨率重扫。OCR 结果不要直接进 RAG先过抽样验收。5.6 版本漂移导致输出结构变化现象升级 MinerU 或 SDK 后同样的文档输出结构变了。排查动作保留解析版本号升级前重跑固定回归集就是review.sample_pages那几页对比 JSON 元素类型和 Markdown 结构。许可证和页数上限也要逐项核对以当前官方文档为准。6. 把解析能力接进你的 Agent 工具链配置和验证都跑通之后下一步是让这套流水线真正为 RAG 和 Agent 服务。如果你主要在做模型对话相关的调试可以先用模型对话入口验证通道是否顺畅如果长期跑编码任务或 Agent 工作流建议了解 Coding Plan 的额度与调用方式接入和排障过程中遇到 Key、通道、参数问题直接查接入文档和 API Keys 页面最快。回到工程本身长文档解析的稳定性不取决于你把页数上限调多大而取决于任务是否可恢复、失败是否可定位、结果是否可验收。MinerU 负责结构化产出TaoToken 负责统一通道检查点负责续跑抽样验收负责质量。这四件事凑齐RAG 的上下文质量才有底。最后留一个实用习惯每次升级解析组件或改切块逻辑先跑一遍失败集回归别让版本漂移悄悄污染你的知识库。
