如何用 Python 将文档转换为 Markdown 供 AI 使用

如今,引入 LLM 或 AI Agent 的应用通常需要处理报告、PDF、电子表格和演示文稿等不同格式的文档。这些文件各自采用专有的内部结构存储内容,在进入文本驱动的 AI 流程之前,应用往往需要先提取并统一这些内容。将文档转换为 Markdown,可以得到一种一致的、可检视的文本表示,下游组件无需处理格式特定的解析逻辑即可读取、存储和操作这些内容。

本教程演示如何使用 Spire.Office for Python 在 Python 中将 Word、PDF、Excel 和 PowerPoint 文档转换为 Markdown,并将转换结果传入真实的 LLM API 调用完成摘要生成。本文的目标是展示一个实用的预处理工作流——而非声称每个 AI 模型都必须使用 Markdown,或文档转换后自动适用于所有 AI 任务。

快速导航


1. 为什么在 AI 文档处理中使用 Markdown

Markdown 在 AI 文档处理流程中占据着一个实用的位置。它通过轻量级语法表示文档结构:标题变为 # 标记,段落保持纯文本,列表使用 - 或 1. 前缀,表格以管道符保留行列关系。这种表示方式可读性强、易于存储,也便于程序化转换。

文档转换为 Markdown 后,所得文本可以作为多种 AI 任务的输入。LLM 可以对内容进行摘要、提取关键实体、回答相关问题或生成修改版本。检索流程可以将文本索引以支持语义搜索。Agent 可以先阅读 Markdown 了解文档内容,再决定下一步调用哪个工具。

需要区分的是 Markdown 预处理与直接文件输入。部分模型 API 通过多模态端点或专用文档处理功能直接接受原始文件——图片、PDF 或 Office 文档。在这些场景下,Markdown 转换并非必要。Markdown 是一种可选的中间表示,适用于应用受益于可在发送给模型前检视和控制的文本格式的场景。是否使用 Markdown 取决于应用需求,而非一条所有 AI 流程都必须遵循的通用规则。


2. 在 Python 中将文档转换为 Markdown

Spire.Office for Python 是一套独立的 Python 库,无需安装 Microsoft Office 即可创建、读取、编辑和转换 Office 文档。它包含四个组件,分别针对特定的文档格式:

输入格式 组件 pip 包
Word (.doc, .docx) Spire.Doc for Python spire.doc
PDF (.pdf) Spire.PDF for Python spire.pdf
Excel (.xls, .xlsx) Spire.XLS for Python spire.xls
PowerPoint (.ppt, .pptx) Spire.Presentation for Python spire.presentation

按需安装相应的包:

1
pip install spire.doc spire.pdf spire.xls spire.presentation

各组件在不同版本中引入了 Markdown 转换支持。下表列出了本文所用 API 的最低版本:

组件 最低版本 功能
Spire.Doc for Python 12.6.0 FileFormat.Markdown 保存选项
Spire.PDF for Python 11.6.1 PdfToMarkdownConverter 及 MarkdownOptions.IgnoreImage
Spire.XLS for Python 16.4.0 Workbook.SaveToMarkdown() 及 MarkdownOptions
Spire.Presentation for Python 10.11.1 FileFormat.Markdown 保存选项

Spire.Doc 12.6.0、Spire.PDF 11.6.1、Spire.XLS 16.4.0 和 Spire.Presentation 10.11.1 是支持 Markdown 转换的最低版本。建议使用各组件的最新版本。

各组件的 Markdown 转换 API 各不相同。下表汇总了各组件的转换方法:

组件 初始化 / 加载 Markdown 导出方法
Spire.Doc Document.LoadFromFile() Document.SaveToFile(path, FileFormat.Markdown)
Spire.PDF PdfToMarkdownConverter(path) converter.ConvertToMarkdown(outputPath)
Spire.XLS Workbook.LoadFromFile() Workbook.SaveToMarkdown(path, MarkdownOptions)
Spire.Presentation Presentation.LoadFromFile() Presentation.SaveToFile(path, FileFormat.Markdown)

下面的示例实现了一个统一的分发函数,根据文件扩展名将文档路由到相应的转换逻辑。它会验证输入文件、生成输出路径、执行转换,并在出错时给出描述性错误信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
import os
from spire.doc import Document, FileFormat as DocFileFormat
from spire.pdf import PdfToMarkdownConverter
from spire.xls import Workbook, MarkdownOptions as XlsMarkdownOptions
from spire.presentation import Presentation, FileFormat as PresentationFileFormat


def convert_to_markdown(input_path: str, output_path: str = None) -> str:
"""将 Word、PDF、Excel 或 PowerPoint 文件转换为 Markdown。

Args:
input_path: 源文档路径。
output_path: 输出 .md 文件路径。如果为 None,则使用
输入文件名加 .md 扩展名,保存在同一目录下。

Returns:
生成的 Markdown 文件路径。
"""
if not os.path.isfile(input_path):
raise FileNotFoundError(f"输入文件不存在: {input_path}")

ext = os.path.splitext(input_path)[1].lower()

if output_path is None:
output_path = os.path.splitext(input_path)[0] + ".md"

if ext in (".doc", ".docx"):
# Spire.Doc for Python: 加载并保存为 Markdown
doc = Document()
try:
doc.LoadFromFile(input_path)
doc.SaveToFile(output_path, DocFileFormat.Markdown)
finally:
doc.Close()

elif ext == ".pdf":
# Spire.PDF for Python: 使用 PdfToMarkdownConverter
# IgnoreImage=True 跳过 PDF 中的图片;如果图表或截图
# 包含重要信息,则设为 False。
converter = PdfToMarkdownConverter(input_path)
try:
converter.MarkdownOptions.IgnoreImage = True
converter.ConvertToMarkdown(output_path)
finally:
converter.Dispose()

elif ext in (".xls", ".xlsx"):
# Spire.XLS for Python: 使用 SaveToMarkdown 和 MarkdownOptions
workbook = Workbook()
try:
workbook.LoadFromFile(input_path)
options = XlsMarkdownOptions()
options.SavePicInRelativePath = True
options.SaveHyperlinkAsRef = False
workbook.SaveToMarkdown(output_path, options)
finally:
workbook.Dispose()

elif ext in (".ppt", ".pptx"):
# Spire.Presentation for Python: 加载并保存为 Markdown
presentation = Presentation()
try:
presentation.LoadFromFile(input_path)
presentation.SaveToFile(output_path, PresentationFileFormat.Markdown)
finally:
presentation.Dispose()

else:
raise ValueError(
f"不支持的文件扩展名: {ext}. "
f"支持的格式: .doc, .docx, .pdf, .xls, .xlsx, .ppt, .pptx"
)

return output_path


# 示例用法
if __name__ == "__main__":
result = convert_to_markdown("quarterly_report.docx")
print(f"Markdown 已保存至: {result}")

with open(result, "r", encoding="utf-8") as f:
content = f.read()
print(content[:500]) # 预览前 500 个字符

Word 文档转换后的 Markdown 输出示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Quarterly Financial Report

## Executive Summary

Total revenue for Q3 2025 reached $4.2 million, representing a 12%
increase over the previous quarter.

## Revenue by Region

| Region | Revenue | Growth |
|---|---|---|
| North America | $1.8M | +8% |
| Europe | $1.2M | +15% |
| Asia Pacific | $1.2M | +18% |

Word 报告与其转换后的 Markdown 输出并排展示

各格式的详细转换教程:


3. 将 Markdown 内容发送给 LLM

文档转换为 Markdown 后,所得文本即可作为 LLM 的输入,用于摘要、信息提取或问答等任务。下面的示例将一份商业报告转换为 Markdown,读取结果文件,然后将内容提交给 OpenAI API 并附带任务指令。

运行此示例前,安装 OpenAI Python SDK 并设置 API 密钥环境变量:

1
2
pip install openai
export OPENAI_API_KEY="your-api-key"

以下代码假设上一节的 convert_to_markdown 函数保存在同目录下名为 convert_to_markdown.py 的文件中,或将两段代码合并为同一脚本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import os
from openai import OpenAI

# 步骤 1: 将文档转换为 Markdown
from convert_to_markdown import convert_to_markdown
md_path = convert_to_markdown("business_report.pdf")

# 步骤 2: 读取 Markdown 内容
with open(md_path, "r", encoding="utf-8") as f:
markdown_content = f.read()

# 步骤 3: 构造任务指令并调用 LLM
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

response = client.chat.completions.create(
model="gpt-6-luna",
messages=[
{
"role": "system",
"content": "You are a financial analyst. Read the document "
"and extract the three most important findings."
},
{
"role": "user",
"content": f"Here is the document content in Markdown:\n\n"
f"{markdown_content}\n\n"
f"Provide a concise summary of the key findings."
}
],
max_completion_tokens=1000
)

# 步骤 4: 读取并显示响应
summary = response.choices[0].message.content
print("=== LLM 摘要 ===")
print(summary)

在这个工作流中,Spire.Office for Python 负责文档转换,OpenAI API 负责 AI 分析。Spire.Office 是一个文档处理库,而非 AI Agent 框架——它产出的是供 LLM 或 Agent 管道消费的 Markdown 文本。如果需要完整的文档处理 Agent,可以尝试 Spire.Agent.Office。

一个需要注意的问题是输入长度。LLM 有上下文窗口限制,长文档转换出的 Markdown 可能超出模型的最大输入长度。此时,应用需要将 Markdown 拆分为较小的块或选择性检索相关段落后再发送给模型。langchain-text-splitters 等库或自定义拆分逻辑可以处理这一步骤。


4. 在 AI Agent 和 RAG 工作流中使用 Markdown

转换步骤产出的 Markdown 可以作为更大规模 AI 工作流的输入。两种常见模式是 AI Agent 和检索增强生成(RAG)。

对于 AI Agent,应用可以将转换后的 Markdown 作为上下文暴露给 Agent,供其在决定下一步操作前阅读。例如,一个客服 Agent 可能接收客户合同的 Markdown,回答有关续约条款、付款计划或终止条件的问题。Agent 将 Markdown 视为可读上下文,而非结构化的数据库查询。

对于 RAG,Markdown 内容被拆分为块,每个块嵌入为向量表示,向量存储在索引中。当用户提出问题时,系统检索最相关的块并将其连同查询一起传递给 LLM。Markdown 基于分节的结构——标题、段落和表格——可以为文档分块提供有意义的边界。基于标题的分块有助于保留上下文,但检索质量取决于文档本身和整体检索配置。

文档转换为 Markdown 供 LLM、AI Agent 和 RAG 使用的工作流

将文档转换为 Markdown 本身并不构成一个完整的 Agent 或 RAG 系统。向量数据库、嵌入模型、编排框架、工具调用协议和检索排序都是独立的下游组件。转换步骤产出文本输入,管道的其余部分决定如何使用这些文本。


5. 在 AI 处理前验证 Markdown

转换后的 Markdown 质量直接影响下游 AI 结果的质量。如果转换丢失了结构、错误表示了数据或遗漏了内容,LLM 或 Agent 将基于不正确或不完整的上下文工作。在依赖转换后的 Markdown 执行重要任务之前,应检查以下几个常见问题区域:

  • 标题层级与段落顺序。 确保各级标题(#、##、###)正确反映原始文档的结构,段落按正确顺序排列。
  • 表格的行、列和数值。 验证行列关系是否保留,数字、日期和货币值是否与源文档一致。如果财务表格的对齐关系丢失,LLM 可能基于错误的关联生成摘要——例如将营收数字归到错误的区域。
  • 图片、链接和复杂布局。 Markdown 无法表示所有视觉元素。图片可能被省略或替换为文件路径引用。多栏布局、文本框和嵌入对象可能无法在转换后保持原有形式。
  • 扫描版 PDF。 如果源 PDF 包含的是扫描图像而非嵌入文本,转换可能产生空白或近乎空白的输出。此时需要在 Markdown 转换之前或替代其执行 OCR 步骤。
  • 长文档。 验证整个文档都已转换,而非仅有第一节。对于超出模型上下文窗口的文档,确认 Markdown 可以拆分为有意义的块而不会截断表格或将标题与内容分离。

转换并不保证完美保留每个视觉或语义特征。Markdown 输出是一种中间表示,而非原始文档的精确副本。在将转换后的文本传递给 AI 模型之前进行审查,是防止错误传播到摘要、提取或 Agent 决策中的实用步骤。


6. 总结

本文完整演示了 Python 中面向 AI 应用的文档转 Markdown 预处理工作流。整个过程分为三个阶段:使用 Spire.Office for Python 将支持的文档格式(Word、PDF、Excel、PowerPoint)转换为 Markdown,验证转换输出的结构准确性,然后将 Markdown 内容传递给相应的 AI 处理组件——无论是 LLM API 调用、Agent 上下文还是 RAG 分块管道。

Markdown 是为 AI 应用准备文档内容的一种有用方式,而非每个模型都必须使用的输入格式。是否将文档转换为 Markdown,取决于应用是否受益于一种可检视、可存储、可控制的文本中间表示。更多详情,请访问 Spire.Office for Python 产品页或下载页面。