MinerU 接入 n8n：使用 n8n-nodes-mineru 社区节点构建文档解析自动化工作流

本篇技术指南介绍如何将 MinerU 的文档解析能力以 n8n 社区节点（n8n-nodes-mineru）的形式接入 n8n 低代码工作流平台，覆盖节点安装、凭证与 API 配置、输出选项、带解压能力的工作流模板及调试排障。读完后你可以独立搭建一条“获取文档 → MinerU 解析 → 提取 Markdown/JSON 结果”的自动化流水线，并结合 MinerU 仓库中 FastAPI 服务端实现理解每个输出参数背后的真实行为。

1. 背景：为什么把 MinerU 封装成 n8n 节点

n8n 是一款以低代码（Low-code）、工作流自动化为核心的应用开发平台，许多企业借助其灵活的节点（Node）配置实现业务流程的自动化执行：它通过可视化界面和代码扩展能力，帮助用户连接各种应用程序与服务，构建复杂的自动化流程，降低使用门槛。

MinerU 是一款将 PDF、图片、DOCX/PPTX/XLSX 等复杂文档转换为 LLM 就绪的 Markdown/JSON 的开源文档解析引擎。目前 MinerU 已将其文档解析能力封装为 n8n 节点，用户在搭建工作流时可以更便捷地处理复杂的文档解析任务，无需自行维护 HTTP 调用与结果解析逻辑。

相关资源（以官方发布渠道为准）：

• n8n 官方站点：n8n.io
• MinerU n8n 插件 npm 包：n8n-nodes-mineru（npm 注册表）
• 本仓库中的节点使用说明原文：n8n 插件文档

2. 第一步：安装 n8n-nodes-mineru 社区节点

n8n-nodes-mineru 属于 n8n 社区节点（Community Node），安装步骤如下：

1. 进入社区节点安装界面：在 n8n 界面中打开社区节点安装入口（Settings → Community Nodes 中的安装界面）。
2. 安装 n8n-nodes-mineru 节点：在搜索框中输入 n8n-nodes-mineru 并点击安装。安装完成后，节点会出现在工作流节点的可用列表中。

安装完成后无需额外配置服务端，节点本身只是一个“客户端”：它把文档和解析参数发往 MinerU 解析服务，再把服务端返回的 Markdown/JSON/ZIP 结果交给后续节点处理。

3. 第二步：新建工作流、添加节点并配置凭证

3.1 添加节点与设置 API Key

1. 新建一个工作流（Workflow）。
2. 拖入 n8n-nodes-mineru 节点。
3. 在节点的凭证（Credentials）区域设置 api key：节点以 n8n 凭证形式保存访问 MinerU 服务的认证信息，凭证配置一次后可被多个工作流复用。
4. 在节点的输入字段中填写待解析文档的 URL（即文档下载地址），节点会先拉取文档再提交解析。

3.2 服务端对应的接口与参数

节点请求的解析服务对应本仓库中的 mineru-api（FastAPI 服务，见 mineru/cli/fast_api.py）。从源码看，其对外提供以下端点：

端点	方法	行为
/file_parse	POST	同步解析：提交解析任务，等待完成后在同一响应中返回最终结果
/tasks	POST	异步提交：立即返回 task_id（HTTP 202）
/tasks/{task_id}	GET	查询任务状态（pending/processing/completed/failed）
/tasks/{task_id}/result	GET	拉取任务结果；未完成时返回 202，失败时返回 409
/health	GET	健康检查，返回版本、排队/处理中任务数、最大并发等

解析请求是 multipart 表单，参数在 mineru/cli/api_request.py 中统一定义，这也是节点各配置项的“源头”。关键参数与默认值如下：

参数	默认值	说明
files	—	上传的 PDF/图片/DOCX/PPTX/XLSX 文件
backend	hybrid-engine	解析后端：pipeline（通用、多语言、无幻觉）/ vlm-engine（本地算力高精度，仅中英文）/ vlm-http-client（远端 OpenAI 兼容服务）/ hybrid-engine（本地混合解析）/ hybrid-http-client（远端混合解析）
effort	medium	仅对 hybrid 后端生效：medium 更快（自动关闭图片/图表分析），high 精度更高、耗时更长
parse_method	auto	仅对 pipeline 与 hybrid 后端生效：auto/txt/ocr
lang_list	["ch"]	OCR 语言列表，影响 pipeline 后端 OCR 识别语言
formula_enable / table_enable	true / true	是否启用公式、表格解析
image_analysis	true	是否启用 VLM 与 hybrid 的图片/图表分析（hybrid medium 会强制关闭）
start_page_id / end_page_id	0 / 99999	PDF 解析的起止页码（从 0 开始）
return_md	true	响应中返回 Markdown 内容
response_format_zip	false	以 ZIP 文件（而非 JSON）返回结果
return_original_file	false	仅在 response_format_zip=true 时生效，把处理后的原文件一并打包进 ZIP
client_side_output_generation	false	开启后服务端只返回分阶段的 middle JSON、模型输出与图片，最终 Markdown/content list 由客户端生成

源码中还可以看到几条值得注意的联动逻辑：

• 开启 client_side_output_generation 时，服务端会自动改写返回开关：return_md 置为 False，return_middle_json、return_model_output、return_images 置为 True（见 parse_request_form）；
• return_original_file 只有在 response_format_zip=true 时才会真正生效，否则被忽略；
• 同步接口 /file_parse 内部仍走异步任务管理器：任务入队后等待终态再组装响应，任务失败返回 409，任务管理器异常返回 503（见 parse_pdf）。

服务端启动方式见 mineru/cli/fast_api.py：默认监听 127.0.0.1:8000，支持 --host、--port、--reload、--enable-vlm-preload 等参数；常用服务端环境变量（如 MINERU_API_MAX_CONCURRENT_REQUESTS 默认 3、MINERU_API_TASK_RETENTION_SECONDS 默认 86400 秒、MINERU_API_OUTPUT_ROOT 默认 ./output）说明见 命令行工具文档。生产环境需要对外提供服务时，通常先 docker compose 部署（参考 Docker 部署文档），再把 n8n 节点指向该服务地址。

4. 第三步：按需配置输出

节点/服务端支持多种输出形式，可根据下游用途勾选，对应源码实现见 build_result_dict 与 create_result_zip：

1. JSON 直出（默认）：响应体为 {"backend": ..., "version": ..., "results": {...}}，每个文件的 results 条目按开关包含：
   • md_content：Markdown 全文（return_md=true）；
   • middle_json / model_output / content_list：分别对应 {文件名}_middle.json、{文件名}_model.json、{文件名}_content_list.json；
   • images：抽取出的图片以 data:<mime>;base64,<...> 形式内联返回（return_images=true）。
2. ZIP 打包（response_format_zip=true）：服务端把结果目录打成 ZIP 返回，包内按 文件名/后端子目录/ 组织，包含 .md、_middle.json、_model.json、_content_list.json、_content_list_v2.json、images/ 以及（可选）_origin.* 原始文件。文件级解析结果目录规则由 resolve_parse_dir 决定。

选择建议：下游只做文本处理时保留默认 JSON + return_md 即可；需要保留版面中间结构（做 RAG、二次排版）时开启 return_middle_json；需要图片落地或原文件留档时使用 ZIP 模式。

5. 进阶：在工作流内集成解压（Unzip）功能

当输出选择 ZIP 模式时，解析结果是一个压缩包，需要在 n8n 工作流中再接一个解压节点，把包内的 .md/.json 抽出来供后续节点使用。

推荐直接导入 n8n 提供的 JSON 工作流模板（n8n 界面中选择 Workflows → Import from file/URL，或从模板库导入），模板已经串好“文档 URL → MinerU 节点 → 解压 → 读取结果”的链路，导入后再按自身需求调整即可：

1. 导入 JSON 模板：导入官方工作流模板后，工作流中会包含 MinerU 节点与解压节点。
2. 配置凭证和文档 URL：为 MinerU 节点填入第 3 节所述的凭证（api key），并在文档 URL 输入项填入待解析文档地址。
3. 按需求配置输出：在节点中勾选所需的输出开关（如 Markdown、middle JSON、图片等），与 ZIP 模式配合决定解压后能获得哪些文件。

从服务端源码可以印证这条链路的行为：ZIP 模式下 build_result_response 会把 create_result_zip 放到线程池中异步打包，再以 application/zip 的 FileResponse 返回，文件名形如 {task_id}.zip（见 build_result_response）。n8n 侧的解压节点消费的就是这个 ZIP 流，因此解压后的目录结构与服务端打包结构一一对应，可直接按“文件名/后端目录”定位到具体结果文件。

6. 调试与验证

1. 单节点试跑：先只触发 MinerU 节点，确认凭证有效、文档 URL 可下载。若服务端不可达或参数非法，节点会透传服务端的 4xx/5xx 错误（例如不支持的文件类型返回 400 “Unsupported file type”、未知 backend 返回 400、任务执行失败返回 409，见 save_upload_files 与 parse_pdf）。
2. 健康检查先行：调试前可先请求 /health 端点确认服务端状态。健康响应包含 status、version、queued_tasks、processing_tasks、max_concurrent_requests 等字段（见 health_check）；503 unhealthy 通常意味着任务调度器或清理循环异常。
3. 异步链路验证：若工作流走 /tasks 异步提交，验证三步循环是否成立：提交得 202 + task_id → 轮询 /tasks/{task_id} 直到 completed → 请求 /tasks/{task_id}/result 拉取结果。任务状态流转为 pending → processing → completed/failed，状态机定义见 AsyncParseTask。
4. 超时与容量：长文档解析耗时较长，注意 n8n 节点侧的 HTTP 超时配置，以及服务端的并发上限（MINERU_API_MAX_CONCURRENT_REQUESTS，默认 3）与任务保留时长（MINERU_API_TASK_RETENTION_SECONDS，默认 24 小时，过期任务及其输出目录会被自动清理，见 cleanup_expired_tasks）。

7. 小结

• 安装：在 n8n 社区节点安装界面搜索并安装 n8n-nodes-mineru，即可在工作流中使用 MinerU 解析节点；
• 配置：设置 api key 凭证与文档 URL，通过 backend、effort、parse_method、formula_enable、table_enable 等参数控制解析行为（参数定义见 api_request.py）；
• 输出：按需勾选 Markdown / middle JSON / 模型输出 / 图片 / ZIP 打包等输出项，ZIP 场景用官方 JSON 模板导入带解压节点的工作流；
• 调试：以 /health 与任务状态轮询作为验证手段，结合服务端错误码快速定位问题（实现见 fast_api.py）。

相关延伸阅读：命令行工具使用说明、n8n 节点说明原文、输出文件说明。