背景介绍

Dify 作为一个开源的 LLM 应用开发平台，其内置的文档提取器在处理某些文件格式时存在局限性。根据 Dify 的官方文档和用户实践，默认的 Dify 解析方案对 .doc(Word 2003 格式) 文件的支持不够完善。使用时可能会出现 UNSTRUCTURED_API_URL and UNSTRUCTURED_API_KEY must be set 的问题。本文将介绍如何通过私有化部署 Unstructured API 来解决这一问题。

解决方案概述

Unstructured.io 提供了一个强大的文档解析 API，支持多种文件格式，包括 .doc、.docx、.pdf 等。通过本地部署 Unstructured API 服务，并将其集成到 Dify 中，可以完美解决 Dify 原生不支持 .doc 文件的问题。

详细部署步骤（两种方式）

1. 自定义部署方式

1.1 拉取 Unstructured API 镜像

docker pull downloads.unstructured.io/unstructured-io/unstructured-api:latest

1.2 运行 Unstructured API 容器

docker run --env HF_ENDPOINT=https://hf-mirror.com \
     --user root \
     -p 8000:8000 \
     -d --rm \
     --name unstructured-api \
     downloads.unstructured.io/unstructured-io/unstructured-api:latest

参数说明：

• HF_ENDPOINT: 指定 Hugging Face 镜像站点，解决国内无法访问的问题
• -p 8000:8000: 将容器端口映射到主机端口
• --rm: 容器退出时自动删除
• --name: 指定容器名称

2. 容器编排方式（推荐）

.env 文件中直接增加如下参数即可

# 启用 unstructured profile
COMPOSE_PROFILES=unstructured

3. 配置 Dify 使用 Unstructured API

修改 Dify 的配置文件 (通常是 .env 文件)，修改以下配置：

# ETL 类型，支持：`dify`、`Unstructured`ETL_TYPE=Unstructured
# Unstructured API 地址和 API key 本地部署API key 可以随便填，并且必须填
UNSTRUCTURED_API_URL=http://unstructured:8000/general/v0/general
UNSTRUCTURED_API_KEY=
SCARF_NO_ANALYTICS=true

高级功能配置（适用于自定义部署）

如果使用容器编排方式下方的内容可以直接忽略。

Unstructured API 支持多种解析策略和高级功能：

1. 大模型加持解析：通过设置 hi_res 参数为 true，可以启用大模型来增强 PDF 解析效果，但会增加响应时间。

2. 请求体示例：

设置 body

设置 header

1. 支持的解析策略：
2. fast: 快速解析模式
3. hi_res: 高精度解析模式 (使用大模型)
4. ocr_only: 仅使用 OCR 技术

详细参数参考：Unstructured-IO官方文档

技术原理

Unstructured API 使用了多种开源库和技术来处理不同格式的文档：

• 对于 .doc 文件：使用 Apache POI 等库进行解析
• 对于 .docx 文件：利用 Python 的 python-docx 模块处理
• 对于 PDF 文件：支持常规解析和大模型增强解析两种模式

注意事项

1. 性能考虑：启用 hi_res 模式会显著增加 API 响应时间，并且仅支持 PDF，建议仅在需要高精度解析时使用。
2. 模型下载：首次调用 API 时会从 Hugging Face 下载所需模型，使用国内镜像可以加速这一过程。
3. 私有化部署优势：本地部署可以确保数据不离开内网，满足金融、医疗等行业的合规要求。
4. 格式支持：Unstructured API 不仅支持 .doc，还支持 .docx、.pdf、.pptx 等多种格式。
5. 自定义容器编排： 创建docker-compose.override.yaml​​文件用于修改和扩展现有配置。当您运行 ​​​​docker-compose up​​​​ 时，Docker Compose 会自动合并 ​​​​docker-compose.yaml​​​​ 和 ​​​​docker-compose.override.yaml​​参考资料)

总结

通过私有化部署 Unstructured API 并将其集成到 Dify 中，可以有效解决 Dify 原生不支持 .doc 文件的问题。这种方法不仅扩展了 Dify 的文件格式支持范围，还通过本地部署保障了数据安全，是企业构建知识库和智能问答系统的理想选择。