markitdown：强大的文件转 Markdown 工具

1. markitdown简介

markitdown是由微软团队开发的 Python 包和命令行工具，它专注于将多种文件格式转换为 Markdown。与其他类似工具（如 textract）相比，markitdown更注重保留重要的文档结构和内容，如标题、列表、表格、链接等。虽然其输出通常对人类也有一定的可读性，但主要设计目的是供文本分析工具使用，而非用于高保真度的人类可读文档转换。

目前，markitdown支持多种文件格式，包括但不限于：

• PDF
• PowerPoint
• Word
• Excel
• 图像（包含 EXIF 元数据和 OCR）
• 音频（包含 EXIF 元数据和语音转录）
• HTML
• 基于文本的格式（如 CSV、JSON、XML）
• ZIP 文件（递归处理内部文件）
• Youtube 链接
• EPUBs

2. 为什么选择 Markdown

Markdown 是一种轻量级标记语言，它非常接近纯文本，只有少量的标记和格式，但能够有效地表示重要的文档结构。主流的大语言模型，如 OpenAI 的 GPT - 4o，原生支持 Markdown，并且常常在响应中自动使用 Markdown 格式。这表明它们在大量的 Markdown 文本上进行了训练，对 Markdown 有很好的理解。此外，Markdown 约定在处理时具有较高的令牌效率。

3. 安装

markitdown可以通过多种方式安装，以下是两种常见的安装方法：

3.1 通过 PyPI 安装

使用 pip 安装所有可选依赖：

pip install 'markitdown[all]'

3.2 从源代码安装

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

4. 使用方法

4.1 命令行使用

4.1.1 基本转换

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

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

或者使用 -o 选项指定输出文件：

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

4.1.2 管道输入

可以通过管道将文件内容传递给 markitdown：

cat path-to-file.pdf | markitdown

4.2 可选依赖

markitdown具有可选依赖，用于激活不同的文件格式支持。可以根据需要单独安装这些依赖，以获得更精细的控制。例如，安装 PDF、DOCX 和 PPTX 文件的依赖：

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

目前可用的可选依赖如下：

• [all]：安装所有可选依赖
• [pptx]：安装 PowerPoint 文件的依赖
• [docx]：安装 Word 文件的依赖
• [xlsx]：安装 Excel 文件的依赖
• [xls]：安装旧版 Excel 文件的依赖
• [pdf]：安装 PDF 文件的依赖
• [outlook]：安装 Outlook 邮件的依赖
• [az-doc-intel]：安装 Azure Document Intelligence 的依赖
• [audio-transcription]：安装音频转录（wav 和 mp3 文件）的依赖
• [youtube-transcription]：安装获取 YouTube 视频转录的依赖

4.3 插件使用

markitdown支持第三方插件，插件默认是禁用的。

4.3.1 列出已安装的插件

markitdown --list-plugins

4.3.2 启用插件

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

要查找可用的插件，可以在 GitHub 上搜索 #markitdown-plugin 标签。开发插件的详细信息可以参考 packages/markitdown-sample-plugin。

4.4 Azure Document Intelligence 使用

要使用 Microsoft Document Intelligence 进行转换，可以使用以下命令：

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

更多关于设置 Azure Document Intelligence 资源的信息可以参考 这里。

4.5 Python API 使用

4.5.1 基本使用

from markitdown import MarkItDown

# 禁用插件
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

4.5.2 使用 Document Intelligence 进行转换

from markitdown import MarkItDown

# 指定 Document Intelligence 端点
md = MarkItDown(docintel_endpoint="")
result = md.convert("test.pdf")
print(result.text_content)

4.5.3 使用大语言模型生成图像描述

from markitdown import MarkItDown
from openai import OpenAI

# 创建 OpenAI 客户端
client = OpenAI()
# 指定 LLM 客户端和模型
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

4.6 Docker 使用

可以使用 Docker 来运行 MarkItDown：

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

5. 功能模块详解

5.1 内置转换器

markitdown提供了多种内置转换器，用于处理不同类型的文件。这些转换器在 markitdown 类的 enable_builtins 方法中注册。以下是部分内置转换器的示例代码：

# markitdown/packages/markitdown/src/markitdown/_markitdown.py
def enable_builtins(self, **kwargs) -> None:
    if not self._builtins_enabled:
        # 注册转换器
        self.register_converter(
            PlainTextConverter(), priority=PRIORITY_GENERIC_FILE_FORMAT
        )
        self.register_converter(
            ZipConverter(markitdown=self), priority=PRIORITY_GENERIC_FILE_FORMAT
        )
        self.register_converter(
            HtmlConverter(), priority=PRIORITY_GENERIC_FILE_FORMAT
        )
        # 其他转换器...
        self._builtins_enabled = True
    else:
        warn("Built-in converters are already enabled.", RuntimeWarning)

5.2 插件系统

markitdown的插件系统允许开发者扩展其功能。插件通过 entry_points 机制加载，开发者可以创建自定义的 DocumentConverter 并在插件中注册。以下是一个简单的插件示例：

# markitdown/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py
from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo

class RtfConverter(DocumentConverter):
    def __init__(
        self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT
    ):
        super().__init__(priority=priority)

    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        mimetype = (stream_info.mimetype or "").lower()
        extension = (stream_info.extension or "").lower()

        if extension in ACCEPTED_FILE_EXTENSIONS:
            return True

        for prefix in ACCEPTED_MIME_TYPE_PREFIXES:
            if mimetype.startswith(prefix):
                return True

        return False

def register_converters(markitdown: MarkItDown, **kwargs):
    markitdown.register_converter(RtfConverter())

在 pyproject.toml 中配置插件的入口点：

[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"

5.3 MCP 服务器

markitdown提供了一个 MCP（Model Context Protocol）服务器，用于与 LLM 应用（如 Claude Desktop）集成。markitdown-mcp 包提供了一个轻量级的 STDIO 和 SSE MCP 服务器，暴露了一个工具 convert_to_markdown(uri)，其中 uri 可以是任何 http:、https:、file: 或 data: URI。

5.3.1 运行 MCP 服务器

markitdown-mcp

或者使用 SSE 模式：

markitdown-mcp --sse --host 127.0.0.1 --port 3001

5.3.2 在 Docker 中运行

docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest

---

markitdown是一个功能强大且灵活的工具，它为将各种文件格式转换为 Markdown 提供了便捷的解决方案。通过其丰富的内置转换器、插件系统和 MCP 服务器，markitdown能够满足不同场景下的需求。无论是使用命令行工具、Python API 还是 Docker，都可以轻松地将文件转换为适合文本分析的 Markdown 格式。
markitdown github地址