MarkItDown：将文件和办公文档转换为Markdown的Python工具

技术背景

在处理文本分析和与大语言模型（LLM）交互时，将各种文件格式转换为Markdown格式是一项常见需求。Markdown接近纯文本，具有少量标记和格式，能很好地表示重要文档结构，主流LLM如OpenAI的GPT - 4o原生支持Markdown。MarkItDown就是这样一个轻量级Python工具，用于将各种文件转换为Markdown，聚焦于保留重要文档结构和内容。

实现步骤

安装

可以使用pip安装MarkItDown：

pip install 'markitdown[all]'

或者从源代码安装：

git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

命令行使用

将文件转换为Markdown并输出到文件：

markitdown path-to-file.pdf > document.md

也可以使用-o指定输出文件：

markitdown path-to-file.pdf -o document.md

还可以通过管道输入内容：

cat path-to-file.pdf | markitdown

可选依赖安装

可以根据需要单独安装支持不同文件格式的依赖，例如：

pip install 'markitdown[pdf, docx, pptx]'

插件使用

列出已安装的插件：

markitdown --list-plugins

启用插件进行文件转换：

markitdown --use-plugins path-to-file.pdf

使用Azure Document Intelligence进行转换

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

核心代码

Python基本用法

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)  # 设置为True以启用插件
result = md.convert("test.xlsx")
print(result.text_content)

使用Document Intelligence进行转换

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

使用大语言模型进行图像描述

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)

Docker使用

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

最佳实践

• 根据实际需求选择安装可选依赖，避免安装不必要的依赖。
• 在使用插件时，先列出已安装的插件，确保插件可用。
• 在使用Azure Document Intelligence时，确保正确设置端点。

常见问题

版本0.0.1到0.1.0的重大变更

• 依赖现在按可选功能组组织，使用pip install 'markitdown[all]'保持向后兼容。
• convert_stream()现在需要二进制类文件对象，之前版本也接受文本类文件对象。
• DocumentConverter类接口改为从类文件流读取，不再创建临时文件。如果是插件或自定义DocumentConverter的维护者，可能需要更新代码。但如果仅使用MarkItDown类或命令行界面，则无需更改。

贡献代码

• 大多数贡献需要同意贡献者许可协议（CLA），提交拉取请求时，CLA机器人会自动处理。
• 可以通过查看问题或帮助审查拉取请求来贡献代码，项目也标记了一些适合社区贡献和审查的问题和拉取请求。
• 在提交拉取请求前，运行测试和预提交检查：

cd packages/markitdown
pip install hatch
hatch shell
hatch test
pre-commit run --all-files