如果你手上有大量 PDF、扫描件要进 RAGFlow，光靠自带解析常常遇到表格错乱、公式丢失、长文档超时；想换成 MinerU 出结构化文本，又卡在「在哪一步调、怎么传文件、失败了怎么办」。这篇按流水线顺序给你一套可照做的接法，重点是超时、并发、降级、日志和上线前的核对动作，不涉及具体价格和版本号。
把 MinerU 接进 RAGFlow，难点不在「能不能调通接口」，而在流水线里那几步工程细节：文件在哪传、解析结果怎么落盘、超时怎么设、失败了退回哪一层。这几件事没想清楚，接口调通也只是个玩具。下面按流水线顺序拆一遍，每一步都给可照做的动作和判断标准。
先声明一句：这篇不涉及任何具体价格、跑分和版本号。凡是需要看数字的地方，我都只给站内路径，你自己去核对当时的情况。因为这类数字变化快，写死在文章里反而是坑。
先想清楚 MinerU 插在流水线哪一环
这件事决定了后面所有工程细节。两种接法差别很大，选错了后面全是返工。判断依据不是你喜不喜欢某种架构，而是你的文档量级、要不要人工校对、解析失败能不能接受整批重跑。
- 上游离线解析器
- 先批量跑出 Markdown 或 JSON 产物，再统一上传 RAGFlow。适合历史存量文档，解析慢一点无所谓，重跑一批也不心疼。
- 同步解析服务
- 在文档入库前调一次接口，拿到结果立即切分入库。适合每天新增几十份的小批量场景，链路短、维护简单。
- 存量上千份：走离线。解析可以慢慢排队，失败了单独重投，不阻塞任何人。
- 每天新增几十份：走同步。省掉中间存储和调度，代码量小很多。
- 解析结果要人工校对：走离线。人工看的是解析产物，不是线上知识库。
- 文档本身是纯文本或有干净电子层的 Word、HTML：直接用 RAGFlow 内置解析，别多接一层，多一层就多一个失败面。
- 接口地址、鉴权方式、支持的输入格式，以官方文档为准；先确认通道通不通，可以按探针思路到 /tools/verify 测一遍连通性。
调用约定：文件怎么传、结果怎么落
文件传递方式主要看你 RAGFlow 和解析服务的部署形态。同一内网、能挂共享存储，是最省事也最好排查的一种；跨网络才考虑直传二进制或给可访问 URL。这三种没有绝对优劣，关键是别在同一个项目里混用。
| 传递方式 | 适用形态 | 排查难度 |
|---|---|---|
| 共享目录给路径 | 同一内网、能挂载存储 | 低，文件在不在磁盘上一看便知 |
| 直传二进制 | 跨网络、文件不大 | 中，出错多半是编码或大小限制 |
| 给可访问 URL | 解析服务能拉公网或内网地址 | 高，经常卡在权限和有效期 |
不管走哪种，解析结果一定要落盘留档：原始文件、解析产物、接口返回的状态各存一份，按文档 ID 命名。这一步看着多余，等发现切片质量差的时候你就知道它多值钱了——能直接判断是解析出的问题还是切分出的问题，而不是靠猜。
- 落盘命名以文档 ID 为主键，原始文件、解析产物、状态记录三个文件放同一目录，方便回查。
- 清洗产物去掉页眉页脚、修正硬换行、拆掉过长的表格块，规则可以对照 /guides/pdf-ocr-doc-cleaning 那份清单。
- 再上传切分清洗完再进 RAGFlow，分块与向量模型的配置项逻辑，和 /guides/fastgpt-relay-embedding-chunking 里讲的是同一套，可以直接参考。
这里要提醒一句：清洗规则别写得过于激进。把表格结构整个拆平成纯文本，检索时反而容易丢上下文。拿不准的时候就保守一点，先上线看效果再调。
超时、并发与失败降级
超时和并发是最容易拍脑袋设错的两项。长文档解析慢是常态，用同一个超时值一刀切，结果就是短文档没事、长文档全挂。正确做法是先小批量跑一次量出基线，再到 /tools/speed-test 之类的地方记录你自己的延迟水平，后面所有阈值都从这份基线推。
- 单文件超时和整批任务超时分开设，别共用一个值。
- 并发不要一上来拉满，解析类服务通常是 CPU 或 GPU 密集型，并发翻倍吞吐不一定翻倍，还容易触发限流。
- 按批提交，批与批之间留间隔，失败重投单独排队，不要混在正常批次里。
- 超时阈值留出余量，按基线的一倍半到两倍设，具体到你自己的链路去实测。
降级顺序建议固定成一条链，别每处代码各写一套。解析失败先重试一次；仍失败退回 RAGFlow 内置解析；再失败就扔进待人工处理队列，绝不卡住整批。这条链的价值在于任何一份文档最多拖累自己，不会让整批任务停摆。
日志、监控与上线前核对
日志留什么字段，决定了你出问题时要花十五分钟还是一整天去定位。别只记一个「成功/失败」，那样等于没记。需要的是一组能互相印证的字段，从文件特征一路串到最终结果。
| 字段 | 看什么用 |
|---|---|
| 文档 ID | 串起原始文件、产物、状态三份记录 |
| 文件大小与页数 | 判断失败是否和文档体量相关 |
| 调用耗时 | 对比基线，识别变慢趋势 |
| 返回状态 | 区分超时、报错、空结果三种情况 |
| 产物字符数 | 字符数异常偏低往往意味着解析出了空内容 |
| 是否降级 | 看降级率，比看单次失败率更有意义 |
上线前一定要跑一遍小评测：挑十几份有代表性的文档，表格、扫描件、多栏排版各来一份，人工看解析加检索的结果，确认答案能引到正确段落再全量跑。这一步花不了多少时间，但能挡掉大部分上线后才发现的尴尬。
日常盯的是失败率和降级率两个指标，而不是单次耗时。失败率抬头通常说明输入文档的类型变了，这时候要回头补清洗规则，而不是去调并发。解析质量的口径要统一，可以对照 /tools/quality-check 和 /tools/quality-monitor，按同一套标准看才有可比性。
下一步如果你还没选好解析服务或中转站，先去站内看看当前的检测和价格情况，再回来定你的超时与并发基线。→常见问题
MinerU 和 RAGFlow 自带的解析到底该用哪个？
看文档类型。有干净电子层的 PDF、Word，内置解析够用，少接一层少一份故障。扫描件、多栏论文、公式表格密集的文档，换成 MinerU 这类专门解析服务通常更值。稳妥做法是先挑十几份典型文档两边各跑一遍，人工比一下再决定，不要一刀切全站替换。
解析完发现检索还是答不准，是解析的问题吗？
不一定。按顺序排：先看解析产物本身有没有丢段、串行；再看切片粒度是不是把一段拆碎了；最后看向量模型和召回参数。三段分开验证，别直接归因到解析。检索侧的调法见 /guides/rag-retrieval-pipeline，解析侧的清洗见 /guides/pdf-ocr-doc-cleaning。
批量解析跑到一半挂了，怎么补最省事？
关键是有没有留状态记录。做法是每份文档记一条状态，重跑时只挑失败和未完成的，已完成的不重跑。没做这层记录的话，先按文件修改时间或大小分批复跑，同时把状态记录补上，否则下次还会踩同一个坑。
