Junki Space

Menu

Junki
Junki
Published on 2025-09-11 / 25 Visits
0
0

解决 Dify 无法解析 .doc 文件：私有化部署 Unstructured API

#LLM

在 LLM 应用开发领域，Dify 作为开源的开发平台，凭借其灵活的功能和易用性，成为众多开发者构建 AI 应用的首选工具。然而，在实际使用过程中，不少用户发现 Dify 内置的文档提取器在处理特定文件格式时存在明显局限性，其中Word 2003 格式（.doc 文件）的支持问题尤为突出 —— 当尝试解析这类文件时，频繁出现 “UNSTRUCTURED_API_URL and UNSTRUCTURED_API_KEY must be set” 的错误提示，导致文档内容无法正常提取，给基于 Dify 的应用开发带来了阻碍。

针对这一问题，我们可以借助 Unstructured.io 提供的强大文档解析能力来解决。Unstructured.io 推出的文档解析 API，支持包括.doc、.docx、.pdf、.txt 在内的数十种文件格式，解析精度和兼容性远超 Dify 原生方案。而通过私有化部署 Unstructured API，不仅能避免依赖外部公共 API 带来的稳定性风险和数据安全隐患，还能实现与 Dify 的无缝集成，彻底解决.doc 文件解析难题。接下来，本文将详细介绍具体的部署和配置步骤。

一、容器编排部署 Unstructured API（推荐方案）

容器化部署具有环境一致性强、配置简单、启停灵活等优势，也是 Dify 官方推荐的 Unstructured API 部署方式。如果你的 Dify 是通过 Docker Compose 部署的（这是 Dify 最常见的部署方式），只需通过修改配置文件即可快速启用 Unstructured 服务，无需额外安装复杂依赖。

具体操作步骤如下：

  1. 找到 Dify 的环境配置文件：在 Dify 的部署目录中，找到名为.env的文件（该文件是 Dify 的核心环境配置文件，所有关键参数均在此处设置）。如果是首次部署，可能需要先复制.env.example文件并命名为.env。

  2. 添加 Unstructured 服务启用参数：打开.env文件，在任意空白位置添加以下配置项：

# 启用 unstructured profile（用于启动Unstructured相关容器）

COMPOSE_PROFILES=unstructured

这里的COMPOSE_PROFILES=unstructured是关键参数，它会告诉 Docker Compose 在启动 Dify 服务时，同时启动 Unstructured API 所需的容器（包括 Unstructured 服务本身及相关依赖）。

  1. 重启 Dify 服务：保存.env文件后，在 Dify 部署目录下执行以下命令，重启 Docker Compose 服务，使配置生效：
# 停止当前运行的服务（若已启动）

docker-compose down

# 启动服务（并后台运行）

docker-compose up -d

重启完成后，Unstructured API 服务会自动在本地启动，默认监听 8000 端口。你可以通过执行docker ps命令，查看是否存在名为dify-unstructured的容器（容器状态为Up即表示启动成功）。

二、配置 Dify 连接本地 Unstructured API

启用 Unstructured 服务后，还需要修改 Dify 的配置，让 Dify 知道要使用本地部署的 Unstructured API 来处理文档解析，而不是默认的原生方案。同样是通过修改 Dify 的.env文件实现，具体步骤如下：

  1. 打开 Dify 的.env 文件：再次找到并编辑 Dify 部署目录下的.env文件。

  2. 修改 ETL 类型及 Unstructured API 参数：在文件中找到与文档解析相关的配置项（若没有则直接添加），并修改为以下内容：

# ETL 类型：指定Dify使用Unstructured进行文档提取（默认是dify）

ETL_TYPE=Unstructured

# Unstructured API 地址：本地部署时使用容器间网络地址（无需修改）

UNSTRUCTURED_API_URL=http://unstructured:8000/general/v0/general

# Unstructured API Key：本地私有化部署时可任意填写（但必须填写，不能为空）

UNSTRUCTURED_API_KEY=your_custom_key_123

# 禁用Scarf分析（避免Unstructured服务向外部发送使用数据，可选配置）

SCARF_NO_ANALYTICS=true

这里需要重点说明几个参数：

  • ETL_TYPE=Unstructured：这是切换文档解析方案的核心参数，将其设置为Unstructured后，Dify 会自动将所有文档解析请求转发给 Unstructured API。

  • UNSTRUCTURED_API_URL：本地部署时，由于 Dify 和 Unstructured 服务在同一 Docker 网络中，可直接使用容器名unstructured作为地址（无需填写localhost或具体 IP），端口默认是 8000，路径/general/v0/general是 Unstructured API 的通用解析接口地址，无需修改。

  • UNSTRUCTURED_API_KEY：公共 Unstructured API 需要真实的 API Key，但私有化部署时该参数仅作校验用，可任意填写（例如123456、dify_unstructured_key等），但不能留空，否则会出现之前的 Key 缺失错误。

  1. 再次重启 Dify 服务：配置修改完成后，需要再次重启 Dify 服务，确保新的文档解析配置生效。执行以下命令：
docker-compose down && docker-compose up -d

三、验证配置是否生效

配置完成后，我们可以通过 Dify 的实际功能来验证.doc 文件解析是否正常工作，具体验证步骤如下：

  1. 登录 Dify 平台：打开 Dify 的 Web 界面，使用管理员或普通用户账号登录。

  2. 创建 / 进入应用：新建一个 “文档问答” 类应用（或进入已有的应用），在应用的 “知识库” 模块中，点击 “上传文档” 按钮。

  3. 上传.doc 格式文件：选择一个 Word 2003 格式（.doc 后缀）的文件进行上传，观察上传和解析过程是否正常 —— 如果之前的配置正确，文件会顺利完成上传，且不会出现 “UNSTRUCTURED_API_URL and UNSTRUCTURED_API_KEY must be set” 的错误。

  4. 验证解析结果：文档上传完成后，点击文档名称进入详情页，查看 “文档内容” 模块，确认文档中的文字、表格、图片说明等内容是否被完整解析（Unstructured 会自动保留文档的结构，如段落分隔、标题层级等）。若内容完整显示，则说明配置已成功生效。

四、常见问题与注意事项

  1. Unstructured 容器启动失败怎么办？

  • 首先检查.env文件中是否正确设置了COMPOSE_PROFILES=unstructured；

  • 执行docker-compose logs unstructured查看容器日志，定位错误原因（常见原因包括端口占用、网络问题等，若 8000 端口被占用，可在docker-compose.yml中修改 Unstructured 服务的端口映射）。

  1. 填写 UNSTRUCTURED_API_KEY 后仍报错？

  • 确认 Key 没有留空（即使是本地部署，也必须填写任意字符）；

  • 检查UNSTRUCTURED_API_URL是否正确（本地部署时不可修改为localhost:8000，必须使用http://unstructured:8000/...）。

  1. 除了.doc 文件，还能解析其他格式吗？
  • 是的，Unstructured API 支持多种格式，包括.docx、.pdf、.ppt、.xlsx、.csv 等，配置完成后，Dify 会自动使用 Unstructured 解析所有支持的文件格式，解析效果比原生方案更优。

通过以上步骤，我们成功通过私有化部署 Unstructured API，解决了 Dify 原生不支持.doc 文件解析的问题。这一方案不仅兼顾了稳定性和数据安全性，还拓展了 Dify 的文档处理能力，为后续基于 Dify 开发更强大的 AI 应用（如文档问答、知识管理系统等）奠定了基础。如果在部署过程中遇到其他问题，可参考 Dify 官方文档或 Unstructured.io 的部署指南，也可在 Dify 的 GitHub Issues 或社区中寻求帮助。

Cursor 实践经验分享（持续更新）

Comment