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

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

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文以 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 提供以下端点：

其中任务状态机在源码中定义为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中，主要参数与默认值如下：

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 工作流的关键一环。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU