MarkItDown：将各类文档转换为Markdown的高效工具

发表于 阅读次数： Waline： 本文字数： 1.9k 阅读时长 ≈ 7 分钟
MarkItDown是一款由微软AutoGen团队开发的轻量级Python工具，支持多种文件格式转Markdown，保留文档结构，适合LLM分析。了解更多！

这篇文章是由我跟 AI（大模型）共同创作的，大致的流程是我在写代码的时候用到了这个模块，在 IDE 中通过 AI（Github Copilot/cursor 等）已经关于这个话题有了一个比较深入的交流，AI 和我都阅读了相关的代码，然后让它写成一个博客。我会人工 review 这个博客，修改其中不合理或者不正确的地方。

我发现这么做可以加深我对相关技术栈的印象和理解，但是这好像也不太符合独立博客的调性，所以我为了这一类博客加了一个特定的 tag：AI共创，如果你不喜欢这一类文章，就请忽略带有这个tag 的文章。

什么是MarkItDown？

MarkItDown是由微软AutoGen团队开发的轻量级Python工具，专注于将各种文件格式转换为Markdown。与其他文本提取工具相比，它的特点在于能够保留文档的重要结构和内容元素（如标题、列表、表格和链接等），使转换后的内容更加适合大模型(LLM)处理和文本分析。

为什么选择Markdown格式？

Markdown格式接近纯文本，标记语法简洁，但能够表达重要的文档结构。主流LLM（如GPT-4o）原生”理解”Markdown，这表明它们已经在大量Markdown格式文本上进行过训练。此外，Markdown语法在token效率方面也有明显优势，这对于需要节约API调用成本的场景非常友好。

支持的文件格式

MarkItDown支持多种文件格式转换，包括：

  • 办公文档：PDF、Word、PowerPoint、Excel
  • 图像：提取EXIF元数据并进行OCR识别
  • 音频：提取EXIF元数据和语音转录
  • 网页：HTML转换
  • 文本文件：CSV、JSON、XML
  • 压缩文件：ZIP（遍历内容）
  • 在线资源：YouTube视频字幕（这是我觉得最强大的地方）
  • 电子书：EPUB

安装配置

环境准备

MarkItDown需要Python 3.10或更高版本。建议使用虚拟环境避免依赖冲突：

1
2
3
4
5
6
7
8
9
10
11
# 标准Python安装
python -m venv .venv
source .venv/bin/activate

# 或使用uv
uv venv --python=3.12 .venv
source .venv/bin/activate

# 或使用Anaconda
conda create -n markitdown python=3.12
conda activate markitdown

安装方式

最简单的方法是通过pip安装全部功能：

1
pip install 'markitdown[all]'

或者从源代码安装：

1
2
3
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

按需安装依赖

如果只需要部分功能，可以选择性安装依赖：

1
2
3
pip install 'markitdown[pdf,docx,pptx]'

# 个人建议可以直接使用[all]

当前可用的选项包括：

  • [pdf]：PDF文件支持
  • [docx]：Word文档支持
  • [pptx]：PowerPoint文件支持
  • [xlsx]：Excel文件支持
  • [xls]：旧版Excel文件支持
  • [outlook]：Outlook邮件支持
  • [az-doc-intel]：Azure文档智能服务支持
  • [audio-transcription]：音频文件转录支持
  • [youtube-transcription]：YouTube视频转录支持
  • [all]：安装所有可选依赖

命令行使用案例

基础用法

将PDF文件转换为Markdown并输出到控制台：

1
markitdown 产品说明书.pdf > 产品说明书.md

指定输出文件：

1
markitdown 会议记录.pptx -o 会议记录.md

通过管道传输内容：

1
cat 报表数据.xlsx | markitdown > 报表数据.md

实际案例：处理项目文档

假设我们有一个包含多种格式文档的项目文件夹，需要将所有文档转换为Markdown以便LLM分析：

1
2
3
4
5
6
7
8
9
10
11
12
# 批量转换脚本示例
#!/bin/bash
mkdir -p markdown_output
for file in project_docs/*; do
  filename=$(basename -- "$file")
  extension="${filename##*.}"
  filename="${filename%.*}"
  if [[ "$extension" == "pdf" || "$extension" == "docx" || "$extension" == "pptx" || "$extension" == "xlsx" ]]; then
    echo "处理文件: $file"
    markitdown "$file" -o "markdown_output/${filename}.md"
  fi
done

使用Azure文档智能服务

对于复杂的PDF文档，可以利用Azure文档智能服务提高转换质量（这一部分对于使用了 Azure 的人来说还是比较有用的，我们公司有使用 Azure，我体验过，还不错）：

1
2
3
4
5
6
# 首先设置Azure Document Intelligence终端节点
export AZURE_DOC_INTEL_ENDPOINT="https://your-resource-name.cognitiveservices.azure.com/"
export AZURE_DOC_INTEL_KEY="your-api-key"

# 使用Azure服务进行转换
markitdown complex_report.pdf -o report.md -d -e "$AZURE_DOC_INTEL_ENDPOINT"

Python API使用

基本用法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from markitdown import MarkItDown

# 创建MarkItDown实例
md = MarkItDown()

# 转换文件
result = md.convert("季度财报.xlsx")

# 打印或处理结果
print(result.text_content)

# 保存结果到文件
with open("财报.md", "w", encoding="utf-8") as f:
    f.write(result.text_content)

大模型集成

MarkItDown提供了与大模型(LLM)集成的强大功能，特别是在处理图像数据时。这种集成允许工具自动生成图像描述，丰富转换后的Markdown内容。

OpenAI兼容API支持

从源代码分析可以看出，MarkItDown的LLM集成采用了标准的OpenAI API格式，这意味着它不仅支持OpenAI官方客户端，还支持任何实现OpenAI兼容API的模型服务：

1
2
3
4
5
6
7
8
9
10
11
12
from markitdown import MarkItDown
from openai import OpenAI

# 初始化OpenAI客户端
client = OpenAI(api_key="your-api-key")

# 创建集成LLM功能的MarkItDown实例
md = MarkItDown(llm_client=client, llm_model="gpt-4o")

# 处理图像文件
result = md.convert("产品照片.jpg")
print(result.text_content)

兼容模型服务

MarkItDown内部实现使用标准OpenAI API调用格式，因此支持：

  1. 官方OpenAI服务：使用GPT-4o、GPT-4、GPT-3.5等官方OpenAI模型
  2. Azure OpenAI服务：通过Azure部署的OpenAI兼容模型
  3. 本地部署模型：如使用LocalAI等服务本地部署的开源模型
  4. OpenAI API兼容服务：如LiteLLM、llamafile服务器等提供OpenAI兼容接口的服务

这种设计使得MarkItDown具有极强的灵活性，可以根据用户的需求和预算选择不同的模型提供商。

使用其他模型的示例

1
2
3
4
5
6
7
8
9
10
11
# 使用Azure OpenAI服务
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key="your-azure-openai-key",  
    api_version="2023-05-15",
    azure_endpoint="https://your-resource-name.openai.azure.com"
)

md = MarkItDown(llm_client=client, llm_model="your-deployment-name")
result = md.convert("图片.png")
1
2
3
4
5
6
7
8
9
10
# 使用本地模型或第三方兼容服务
from openai import OpenAI

client = OpenAI(
    api_key="任意值",  # 某些本地服务不校验API密钥
    base_url="http://localhost:8000/v1"  # 指向本地服务
)

md = MarkItDown(llm_client=client, llm_model="local-model-id")
result = md.convert("图表.jpg")

模型要求

要与MarkItDown兼容，LLM服务需要满足以下条件：

  • 实现OpenAI兼容的聊天完成API
  • 支持多模态输入（文本+图像）
  • 响应格式与OpenAI的chat.completions.create()方法一致

使用场景

MarkItDown的实用场景包括：

  1. 知识库构建：批量将各种格式的文档转换为统一的Markdown格式，便于知识库管理
  2. 文档智能分析：将文档转换后喂给LLM进行文本摘要、情感分析或关键信息提取
  3. 内容迁移：将旧系统的文档迁移到基于Markdown的新系统
  4. 多模态数据处理：处理图像和音频文件，结合LLM提供更丰富的内容理解
  5. 文档自动化工作流：作为自动化流程的一部分，将非结构化文档转换为结构化数据

总结

MarkItDown为处理各种文件格式提供了强大而灵活的解决方案，尤其适合与LLM集成使用。它的优势包括：

  • 支持多种文件格式
  • 保留文档结构和格式
  • 提供简单直观的CLI和Python API
  • 可与任何兼容OpenAI API格式的模型无缝集成
  • 可与Azure服务无缝集成

通过掌握MarkItDown，我们可以更高效地处理文档转换任务，为下游的NLP和AI应用提供优质的文本输入。无论是个人项目还是企业级应用，MarkItDown都是连接各类文档和现代AI工具的有力桥梁。