MarkItDown：文件转换为Markdown的Python工具
技术背景
在处理各种文件并用于大语言模型（LLM）和相关文本分析管道时，需要将文件内容转换为易于处理的格式。Markdown 接近纯文本，有少量标记或格式，能表示重要文档结构，主流 LLM 如 OpenAI 的 GPT - 4o 能很好地理解 Markdown，且 Markdown 约定具有高度的标记效率。MarkItDown 就是这样一个轻量级的 Python 工具，用于将各种文件转换为 Markdown。
实现步骤
安装
- 使用 pip 安装：
pip install 'markitdown[all]'。 - 从源码安装：
1
2
3
| git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
|
命令行使用
- 转换文件并输出到文件：
markitdown path - to - file.pdf > document.md - 指定输出文件：
markitdown path - to - file.pdf -o document.md - 通过管道输入内容：
cat path - to - file.pdf | markitdown
可选依赖安装
可以根据需要单独安装支持特定文件格式的依赖，例如：
1
| pip install 'markitdown[pdf, docx, pptx]'
|
插件使用
- 列出已安装插件：
markitdown --list - plugins - 启用插件进行文件转换：
markitdown --use - plugins path - to - file.pdf
使用 Azure Document Intelligence 进行转换
1
| markitdown path - to - file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
|
Docker 使用
1
2
| docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your - file.pdf > output.md
|
核心代码
Python API 基本使用
1
2
3
4
5
| from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)
|
使用 Document Intelligence 进行转换
1
2
3
4
5
| from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)
|
使用大语言模型进行图像描述
1
2
3
4
5
6
7
| from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)
|
最佳实践
- 若需要处理多种文件格式，建议安装
markitdown[all] 以获取完整的功能支持。 - 在开发插件时，参考
packages/markitdown - sample - plugin 中的示例代码。 - 在提交代码前，运行
pre - commit run --all - files 进行检查，确保代码符合规范。
常见问题
版本 0.0.1 到 0.1.0 的重大更改
- 依赖项现在按可选功能组组织，使用
pip install 'markitdown[all]' 可保持向后兼容。 convert_stream() 现在需要二进制文件类对象，之前版本也接受文本文件类对象。DocumentConverter 类接口改为从类文件流读取，不再创建临时文件。若你是插件或自定义 DocumentConverter 的维护者，可能需要更新代码；若仅使用 MarkItDown 类或命令行界面，则无需更改。