格式转换

文档摄入的第一步是将各类办公文档转换为 Markdown 格式,为后续分片做准备。

支持的格式

格式	转换引擎	说明
PDF	MinerU	专业 PDF 解析,保留排版结构
DOCX	MarkItDown	Microsoft Word 文档
DOC	LibreOffice → MarkItDown	旧版 Word,两步转换
XLSX	MarkItDown	Excel 表格
XLS	LibreOffice → MarkItDown	旧版 Excel
PPTX	MarkItDown	PowerPoint 演示文稿
HTML	MarkItDown	网页文档
TXT	内置处理	纯文本包装为 Markdown
MD	无需转换	直接使用

---

转换引擎对比

MarkItDown

优势:

• 轻量快速,启动快
• Office 格式支持好 (DOCX, XLSX, PPTX)
• 适合格式简单的文档

劣势:

• 不支持 PDF
• 对复杂排版解析能力有限

适用场景: Word、Excel、PPT、HTML 等常规文档

LibreOffice

优势:

• 格式兼容性强
• 支持旧版 Office 格式 (DOC, XLS)
• 开源免费

劣势:

• 需独立部署,占用资源较多
• 转换速度较慢

适用场景: 旧版 Office 文档的两步转换 (DOC→DOCX→MD)

MinerU

优势:

• PDF 解析精度高
• 保留表格、图片、公式结构
• 专为 PDF 设计

劣势:

• 需独立部署,依赖较多
• 仅支持 PDF 格式

适用场景: PDF 文档,尤其是包含表格、公式的技术文档

---

转换路由策略

系统根据文件类型自动选择转换引擎:

// 伪代码 - 转换路由逻辑
if ("pdf".equals(fileType)) {
    // PDF 转 MD - 使用 MinerU
    convertPdfToMd();
} else if ("doc".equals(fileType)) {
    // DOC 需要两步转换: DOC -> DOCX -> MD
    convertDocToMd();
} else if (List.of("docx", "xlsx", "pptx", "xls").contains(fileType)) {
    // Office 格式直接转 MD
    convertOfficeToMd();
} else if (List.of("html", "htm").contains(fileType)) {
    // HTML 转 MD
    convertHtmlToMd();
} else if ("txt".equals(fileType)) {
    // TXT 包装为 Markdown 代码块
    wrapTxtToMd();
} else if ("md".equals(fileType)) {
    // MD 无需转换,直接使用
    skipConversion();
}

DOC 两步转换

旧版 DOC 格式需要先转换为 DOCX,再转换为 MD:

DOC 文件 → LibreOffice → DOCX 文件 → MarkItDown → Markdown 文件

---

转换服务部署

各转换服务独立部署,通过 HTTP API 调用:

配置示例

molandev:
  rag:
    converter:
      # MarkItDown 转换服务
      mark-it-down-url: http://localhost:10996
      # LibreOffice 转换服务
      libre-office-url: http://localhost:10997
      # MinerU 转换服务
      mineru-url: http://localhost:10998
      # 连接超时 (秒)
      connect-timeout: 30
      # 读取超时 (秒)
      read-timeout: 60

部署建议

转换服务	资源需求	是否必需	说明
MarkItDown	低	✅ 必需	处理大部分 Office 格式
LibreOffice	中	⚠️ 可选	仅处理旧版 DOC/XLS
MinerU	中	⚠️ 可选	仅处理 PDF

最小化部署: 如果不上传 PDF 和旧版 Office 文档,可只部署 MarkItDown。

---

转换流程

---

转换结果

转换完成后,会生成以下文件:

文件	说明
原始文件	保留原始格式,用于下载
Markdown 文件	转换结果,用于分片

文档元数据会更新:

{
  "id": 1,
  "title": "分布式锁指南",
  "fileType": "pdf",
  "mdFilePath": "/data/knowledge/1/distributed-lock.md",
  "mdFileSize": 15234,
  "stage": "SPLIT"  // 阶段已更新
}

---

最佳实践

PDF 转换

• 优先使用 MinerU — 对表格、公式、图片支持更好
• 检查转换结果 — 复杂 PDF 可能转换不完整
• 建议上传源文件 — 如有 Markdown 源文件,直接上传

Word 转换

• 建议上传 DOCX 格式 — 避免两步转换,提升速度
• 旧版 DOC 转 DOCX — 可用 Word 另存为 DOCX 后上传

代码文档

• 直接使用 Markdown — 代码文档建议使用 MD 格式
• 使用代码块 — 标注语言,如 ```java

---

下一步

• 了解转换后的 智能分片 算法
• 查看 配置说明 了解转换服务配置