Dify知识库-支持的文档类型与处理流程分析

概述

Dify知识库系统支持多种数据源和文档格式的导入，通过统一的ExtractProcessor架构处理不同类型的文档。本文档详细分析了所有支持的文档类型、处理方式以及各自的特点。

支持的数据源类型

1. 文件上传 (FILE)

通过Web界面或API直接上传文件到系统

2. Notion集成 (NOTION)

连接Notion工作空间，导入页面和数据库内容

3. 网站抓取 (WEBSITE)

抓取网站内容，支持多种抓取服务

详细文档格式支持

一、文档类文件

1. PDF文件 (.pdf)

• 处理器: PdfExtractor
• 依赖库: pypdfium2==4.30.0
• 特点:
  • 支持缓存机制避免重复解析
  • 逐页提取文本内容
  • 生成页码元数据
• 处理流程: 标准PDF→文本提取→缓存存储
• 限制: 不支持复杂布局和图片提取（需要Unstructured API）

2. Word文档 (.docx)

• 处理器: WordExtractor
• 依赖库: python-docx
• 特点:
  • 支持图片提取和转换为Markdown
  • 处理表格并转换为Markdown格式
  • 支持超链接识别
  • 图片自动上传到文件存储系统
• 处理流程:

  DOCX文件 → 提取图片 → 转换为Markdown → 处理表格 → 生成Document
  

3. Word文档 (.doc) - 仅Unstructured

• 处理器: UnstructuredWordExtractor
• 依赖: Unstructured API
• 特点: 需要第三方API处理旧版Word格式
• 限制: 必须配置Unstructured API

4. PowerPoint演示文稿 (.pptx)

• 处理器: UnstructuredPPTXExtractor
• 依赖库: unstructured
• 特点:
  • 支持本地和API两种处理方式
  • 按页面提取内容
  • 保持页面结构
• 处理流程:

  PPTX → 分页解析 → 文本提取 → 按页组织内容
  

5. PowerPoint演示文稿 (.ppt) - 仅Unstructured

• 处理器: UnstructuredPPTExtractor
• 依赖: Unstructured API (必需)
• 特点: 旧版PPT格式必须通过API处理

二、表格类文件

1. Excel文件 (.xlsx, .xls)

• 处理器: ExcelExtractor
• 依赖库: openpyxl (xlsx), xlrd (xls), pandas
• 特点:
  • 逐行处理每个工作表
  • 支持超链接提取
  • 自动跳过空行
  • 输出JSON格式的键值对
• 处理流程:

  Excel → 工作表遍历 → 行数据提取 → 键值对组装 → Document生成
  

• 输出格式: "列名":"值";"列名":"值"

2. CSV文件 (.csv)

• 处理器: CSVExtractor
• 依赖库: pandas
• 特点:
  • 自动编码检测
  • 按行处理数据
  • 输出结构化数据
• 处理流程:

  CSV → 编码检测 → pandas读取 → 行数据提取 → Document生成
  

三、文本类文件

1. 纯文本文件 (.txt)

• 处理器: TextExtractor
• 特点:
  • 自动编码检测
  • 支持多种字符编码
  • 保持原始格式
• 编码支持: UTF-8, GBK, Big5, CP1252等

2. Markdown文件 (.md, .markdown, .mdx)

• 处理器: MarkdownExtractor / UnstructuredMarkdownExtractor
• 特点:
  • 保持Markdown格式
  • 自动编码检测
  • 支持扩展语法
• 双引擎:
  • 默认: 直接文本读取
  • Unstructured: API增强处理

3. HTML文件 (.htm, .html)

• 处理器: HtmlExtractor
• 依赖库: BeautifulSoup4
• 特点:
  • 提取纯文本内容
  • 去除HTML标签
  • 保持文档结构

4. XML文件 (.xml) - 仅Unstructured

• 处理器: UnstructuredXmlExtractor
• 依赖: Unstructured API
• 特点: 结构化XML数据提取

四、电子邮件文件

1. Outlook邮件 (.msg) - 仅Unstructured

• 处理器: UnstructuredMsgExtractor
• 依赖: Unstructured API
• 特点: 提取邮件正文、附件信息

2. 标准邮件 (.eml)

• 处理器: UnstructuredEmailExtractor
• 特点:
  • 支持本地和API处理
  • 提取邮件头信息
  • 处理邮件正文

五、电子书格式

1. EPUB电子书 (.epub)

• 处理器: UnstructuredEpubExtractor
• 特点:
  • 支持本地和API处理
  • 章节结构提取
  • 文本内容整理

六、Notion集成

1. Notion页面

• 处理器: NotionExtractor
• 支持类型:
  • 单页面 (page)
  • 数据库 (database)
• 特点:
  • 实时同步最后编辑时间
  • 支持富文本格式
  • 表格转Markdown
  • 层级结构保持
• API版本: 2022-06-28

2. Notion数据库

• 处理方式:
  • 提取所有页面记录
  • 属性值格式化
  • 支持多选、选择等字段类型
  • 生成行级别的Document

七、网站内容抓取

1. Firecrawl服务

• 处理器: FirecrawlWebExtractor
• 模式:
  • crawl: 爬取整个网站
  • scrape: 抓取单个页面
• 输出: 清理后的Markdown格式
• 元数据: URL、标题、描述

2. WaterCrawl服务

• 处理器: WaterCrawlWebExtractor
• 特点: 类似Firecrawl的网页抓取服务

3. Jina Reader

• 处理器: JinaReaderWebExtractor
• 特点: 多模态内容处理，支持图片和文本

ETL处理引擎对比

默认引擎 vs Unstructured引擎

文档类型	默认引擎	Unstructured引擎	主要差异
PDF	pypdfium2	Unstructured API	复杂布局、表格、图片支持
DOCX	python-docx	-	默认已支持图片和表格
DOC	❌	✅	仅API支持
PPTX	unstructured本地	Unstructured API	API提供更好解析
PPT	❌	✅	仅API支持
Markdown	文本读取	Unstructured API	API提供结构化解析
Excel	openpyxl/pandas	-	默认已足够
TXT	编码检测	-	默认已足够
XML	❌	✅	仅API支持
MSG	❌	✅	仅API支持
EML	unstructured本地	Unstructured API	两种方式都支持
EPUB	unstructured本地	Unstructured API	两种方式都支持

引擎选择逻辑

etl_type = dify_config.ETL_TYPE  # "Unstructured" 或 "default"

if etl_type == "Unstructured":
    # 优先使用Unstructured API
    if file_extension == ".pdf":
        extractor = PdfExtractor(file_path)  # 仍使用本地处理
    elif file_extension == ".doc":
        extractor = UnstructuredWordExtractor(file_path, api_url, api_key)
    # ... 其他格式
else:
    # 使用默认本地处理
    if file_extension == ".pdf":
        extractor = PdfExtractor(file_path)
    elif file_extension == ".docx":
        extractor = WordExtractor(file_path, tenant_id, user_id)
    # ... 其他格式

文档处理流程对比

1. 简单文本类文档 (TXT, MD, HTML)

文件上传 → 编码检测 → 文本读取 → Document生成 → 分割 → 向量化

特点: 处理简单，无复杂结构

2. 结构化文档 (Word, PDF)

文件上传 → 结构解析 → 图片处理 → 表格转换 → Markdown生成 → Document生成 → 分割 → 向量化

特点: 需要保持格式和结构

3. 表格类文档 (Excel, CSV)

文件上传 → 表格解析 → 行级处理 → 键值对生成 → Document生成 → 分割 → 向量化

特点: 按行生成Document，结构化数据

4. 外部数据源 (Notion, Website)

API连接 → 内容获取 → 结构化处理 → Document生成 → 分割 → 向量化

特点: 需要API认证和网络连接

5. 多媒体文档 (PPT, EPUB)

文件上传 → 页面/章节解析 → 内容提取 → 结构保持 → Document生成 → 分割 → 向量化

特点: 需要保持页面或章节结构

配置要求

基础配置

# 文件大小限制
UPLOAD_FILE_SIZE_LIMIT = 50 * 1024 * 1024  # 50MB

# 支持的文件类型
SUPPORTED_FILE_EXTENSIONS = [
    '.pdf', '.docx', '.doc', '.pptx', '.ppt', 
    '.xlsx', '.xls', '.csv', '.txt', '.md', 
    '.html', '.xml', '.msg', '.eml', '.epub'
]

Unstructured API配置

ETL_TYPE = "Unstructured"
UNSTRUCTURED_API_URL = "https://api.unstructured.io/general/v0/general"
UNSTRUCTURED_API_KEY = "your-api-key"

Notion集成配置

NOTION_INTEGRATION_TOKEN = "your-notion-token"
# 或使用数据源凭证管理

网站抓取配置

# Firecrawl
FIRECRAWL_API_KEY = "your-firecrawl-key"

# Jina Reader
JINA_READER_API_KEY = "your-jina-key"

性能优化建议

1. 缓存策略

• PDF提取结果缓存（基于文件修改时间）
• Notion内容增量更新
• 网站抓取结果缓存

2. 并发处理

• 大文件分块处理
• 多工作进程并行处理
• 异步任务队列

3. 内存管理

• 大文件流式处理
• 及时释放临时文件
• 图片压缩和优化

4. 错误恢复

• API调用失败回退到本地处理
• 部分失败时的断点续传
• 详细的错误日志记录

扩展性设计

新文档类型支持

1. 继承BaseExtractor类
2. 实现extract()方法
3. 在ExtractProcessor中注册新格式
4. 添加文件类型检测逻辑

新数据源支持

1. 在DatasourceType中添加新类型
2. 实现对应的提取器
3. 在ExtractProcessor.extract()中添加处理逻辑
4. 配置相关的API参数

总结

Dify知识库系统通过统一的提取器架构支持了18+种文档格式和3种主要数据源类型，具备以下特点：

1. 格式覆盖全面: 从简单文本到复杂多媒体文档
2. 双引擎架构: 本地处理 + 云API增强
3. 结构保持: 表格、图片、链接等格式转换
4. 扩展性强: 插件化的提取器架构
5. 性能优化: 缓存、并发、流式处理
6. 容错性好: 多级回退和错误恢复机制

这种设计使得Dify能够处理企业级应用中的各种文档类型，为构建高质量的知识库提供了坚实的基础。