MinerU 集成 Coze（扣子）实战：用 parse_file 插件为智能体与工作流接入文档解析能力

本文以 MinerU 官方文档 docs/zh/usage/plugin/Coze.md 为主体，讲解如何在字节跳动的零代码 AI 应用开发平台 Coze（扣子）中接入 MinerU 插件：既可以把 MinerU 作为插件直接挂到智能体上，也可以构建"文件输入 → MinerU 解析 → 文本输出"的标准化工作流。读完后，你将掌握 parse_file 工具的完整配置步骤、API key 的填写与隐藏方法，并能对照 MinerU 仓库源码理解插件背后解析服务的接口协议、表单参数与输出结构，从而在自己的 Agentic 工作流中可靠地调用文档解析能力。

一、Coze 平台与 MinerU 插件

Coze（中文版名称：扣子）是字节跳动推出的零代码 AI 应用开发平台。无论用户是否有编程经验，都可以通过该平台快速创建各种类型的聊天机器人、智能体、AI 应用和插件，并将其部署在社交平台和即时聊天应用程序中。

MinerU 是一个将 PDF 与 Office 文档转换为 LLM 就绪的 Markdown/JSON 的开源项目。目前 MinerU 插件已在 Coze 插件商店上线，通过其强大的文档解析能力，为在 Coze 中搭建智能体与工作流的用户提供文档解析能力，加快 AI 应用的开发。使用入口有两个：

• Coze（扣子）官网开发平台（coze.cn）；
• Coze 插件商店中的 MinerU 插件页面（商店内搜索 "MinerU" 即可找到）。

在 Coze 中有两种典型用法：一是智能体直接挂载插件，让 Agent 在对话中按需调用文档解析；二是工作流编排，把 MinerU 节点固定进流水线，实现"上传文件即得到解析文本"的确定性流程。下文分别给出完整操作步骤。

二、智能体集成：给 Agent 装上 parse_file 工具

2.1 创建智能体

进入 Coze 开发平台（coze.cn）后，按以下路径创建一个空智能体：

工作空间 → 项目开发 → 创建 → 创建智能体 → 创建 → 输入项目名

2.2 添加 MinerU 插件

在智能体编辑页执行：

插件配置 → 添加 插件 → 搜索 MinerU

随后添加 parse_file 工具（在线版）：

2.3 配置参数并填写 API key

选择 MinerU 插件 → 编辑参数 → 填写 api key。这里使用的是在线版服务凭据，官方文档特别提示：

记得关闭 url 和 token 显示

即在完成配置后，关闭界面中 url 与 token 的明文展示，避免敏感凭据在截图、录屏或分享页面中泄露。

2.4 调试智能体

配置完成后，在右侧调试面板中上传一个 PDF 文档，让智能体调用 parse_file 工具验证解析效果：

三、工作流集成：构建文件输入到解析输出的确定性流水线

用工作流的方式使用 MinerU，适合需要稳定输入输出契约的场景。完整步骤如下。

3.1 创建工作流并添加 MinerU 插件

工作流 → 创建工作流

接着执行：工作流插件配置 → 添加 插件 → 搜索 MinerU → 添加。

同样地，选择 MinerU 插件 → 编辑参数 → 填写 api key。

3.2 连接开始节点与 MinerU 节点

选择开始节点 → 配置 input 类型为文件类型 → 连接到 mineru 节点。这样工作流的入口就是一个可直接接收文档文件的参数。

3.3 配置结束节点输出

选择结束节点 → 连接到 mineru 节点 → 配置 output 输出为 mineru 节点的 parse_file.text。至此，工作流的输出字段就是文档解析后的 Markdown 文本，可被下游节点（LLM 总结、RAG 检索等）直接消费。

3.4 试运行、发布与调试

• 上传文件 → 试运行：上传一个真实文档，验证整条链路能返回解析文本。
• 发布 → 添加到当前智能体：将工作流发布后挂载到已有的智能体上，让 Agent 通过该工作流触发解析。
• 移除 mineru 插件 → 调试：如果智能体此前直接挂载过 MinerU 插件，建议先移除，再通过调试面板验证"仅经由工作流"这一条路径行为一致，避免插件直连与工作流两条链路互相干扰。

四、插件背后的解析服务：从 MinerU 源码看接口协议

Coze 插件的 parse_file 工具最终对接的是 MinerU 的在线解析服务（也可对接自部署的 MinerU API 服务）。理解仓库中的 API 实现，有助于弄清插件"文件进、文本出"背后的真实行为。

4.1 服务入口与核心端点

MinerU 的 HTTP 服务实现在 mineru/cli/fast_api.py 中，基于 FastAPI 提供以下端点：

端点	方法	作用
/file_parse	POST	同步解析：提交文件并在同一响应中等待、返回最终解析结果
/tasks	POST	提交异步解析任务，立即返回 202 与任务信息
/tasks/{task_id}	GET	查询任务状态（pending / processing / completed / failed）
/tasks/{task_id}/result	GET	下载任务结果（JSON 或 ZIP）
/health	GET	健康检查，返回协议版本与并发上限等元信息

其中任务状态机在源码中定义为 TASK_PENDING / TASK_PROCESSING / TASK_COMPLETED / TASK_FAILED，异步任务按提交顺序排队，/health 端点会校验协议版本与并发配置——客户端侧的 mineru/cli/api_client.py 中 validate_server_health_payload 会检查 protocol_version 与 mineru/cli/api_protocol.py 中定义的 API_PROTOCOL_VERSION = 2 是否一致，默认最大并发请求数为 DEFAULT_MAX_CONCURRENT_REQUESTS = 3。

4.2 表单参数与默认值

Coze 插件的 parse_file 参数映射到 API 的 multipart 表单，参数定义集中在 mineru/cli/api_request.py 的 parse_request_form 中，主要参数与默认值如下：

参数	默认值	说明
files	必填	支持上传 PDF、图片（png/jpeg/jp2/webp/gif/bmp/jpg/tiff）以及 DOCX、PPTX、XLSX 文件，扩展名校验见 mineru/cli/common.py 中的 pdf_suffixes / image_suffixes / office_suffixes
lang_list	["ch"]	OCR 语言列表，与文件数量不一致时会用首个语言补齐
backend	hybrid-engine	可选 pipeline、vlm-engine、vlm-http-client、hybrid-engine、hybrid-http-client，默认值定义见 mineru/cli/backend_options.py 的 DEFAULT_BACKEND
effort	medium	仅对 hybrid 后端生效，可选 medium / high；medium 更快但禁用图像/图表分析，high 精度更高、耗时更长
parse_method	auto	仅对 pipeline 与 hybrid 后端生效，可选 auto / txt / ocr
formula_enable / table_enable	true	是否启用公式、表格解析
image_analysis	true	是否启用图像/图表分析（hybrid 的 medium effort 会自动关闭）
return_md	true	返回 Markdown 内容
return_middle_json / return_model_output / return_content_list / return_images	false	按需返回中间 JSON、模型输出、内容列表与抽取图片
response_format_zip	false	以 ZIP 代替 JSON 返回结果
start_page_id / end_page_id	0 / 99999	PDF 解析页范围（从 0 开始）

parse_request_form 会对非法的 backend、effort、parse_method、lang_list 直接抛出 400 错误（见 validate_parse_backend 等函数），这也解释了插件侧为什么对取值有严格约束。

4.3 输出结构与 parse_file.text 的来源

解析完成后，服务端在 build_result_dict（mineru/cli/fast_api.py）中按返回开关组装结果：return_md 为真时读取 {文件名}.md 并放入 md_content 字段，其余分别对应 _middle.json、_model.json、_content_list.json 与 images/ 目录下 base64 编码的图片。Coze 工作流中结束节点引用的 parse_file.text，对应的就是这条链路上产出的 Markdown 文本——这也是为什么文档建议把工作流输出直接映射到 parse_file.text：它是面向下游 LLM 最"就绪"的表示形式。

五、实践建议

1. 凭据安全：填写 API key 后按官方文档提示关闭 url 与 token 的显示；插件参数中不要把明文密钥写进智能体的公开描述里。
2. 两种接入方式按场景选择：对话型 Agent 建议直接挂载 parse_file 插件（灵活，可按轮次调用）；批量、稳定契约的场景建议走工作流（输入文件、输出 parse_file.text，便于被其他节点串联）。
3. 排查解析行为时对照源码：Coze 侧只是参数透传，具体"为什么某类文件解析慢/快""为什么输出里没有公式"等问题，可回到 parse_method、backend、effort、formula_enable、table_enable 这些表单参数对照 mineru/cli/api_request.py 的定义逐项检查。
4. 注意适用范围：parse_method 仅对 pipeline 与 hybrid 后端生效，effort 仅对 hybrid 后端生效，这是源码中 Swagger 描述明确标注的约束，配置时无需对这些不生效的组合做额外设置。

通过本文，你可以完整复现在 Coze 中为智能体和工作流接入 MinerU 文档解析能力的两种路径，并且理解了 parse_file 工具背后由 MinerU FastAPI 服务提供的端点、参数与输出协议——这正是把复杂文档接入 LLM 工作流的关键一环。