MarkItDown：微软开源的文档转 Markdown 工具，喂给 LLM 前的必备一步

这篇教程带你完成什么

从零装好 MarkItDown，写一个批量转换脚本，把一个文件夹里的 PDF、Word、Excel、PPT、图片统统转成干净的 Markdown 落到 out/ 目录，顺手给图片接上 LLM 生成文字描述——这套东西跑通之后，你喂给任何 LLM 或 RAG 管道的文档就已经是统一格式了。

前置条件

• Python 3.10 或更高版本，用 python --version 确认，低于 3.10 装不上。
• pip 能正常访问 PyPI，公司网络需要的话提前配好镜像源。
• 可选：一个 OpenAI 兼容的 API Key，只在需要给图片生成描述那一步用得上。
• 可选：Docker，用于不想污染本地环境时跑单文件转换。
• 磁盘留出几百 MB，markitdown[all] 会一起拉进 PDF、音频转写、YouTube 等一堆可选依赖。

安装部署

第一步：建虚拟环境

cd ~/projects
python -m venv .venv
source .venv/bin/activate
# Windows 用：.venvScriptsactivate

第二步：安装 MarkItDown

先用 [all] 一把梭，把所有格式的支持都装上。等跑通之后再按需瘦身。

pip install "markitdown[all]"

第三步：验证 CLI

markitdown --help

能打印出 usage 就说明命令行入口已经就位，下面开始干活。

第一个 Demo：批量转换整个文件夹

1. 准备输入

这一步要做什么：造一个混合格式的输入目录，把你要处理的文件都丢进去。

mkdir -p demo/in demo/out
# 把你的 report.docx、budget.xlsx、deck.pptx、scan.pdf 拷进 demo/in/

2. 先用 CLI 单文件试一发

这一步要做什么：确认单个文件转换链路是通的，出问题好定位。

markitdown demo/in/report.docx -o demo/out/report.md
head -20 demo/out/report.md

预期输出：标题、段落、表格都变成了 Markdown 语法，表格保留成 | 分隔的形式。如果这一步就报错，别往下走，先看后面的排错表。

3. 写批量脚本

这一步要做什么：用 Python API 遍历目录，逐个转换，单个文件失败不中断整体流程。

# demo/batch.py
from pathlib import Path
from markitdown import MarkItDown

SRC, DST = Path("demo/in"), Path("demo/out")
DST.mkdir(parents=True, exist_ok=True)

md = MarkItDown()  # 默认 enable_plugins=False

for f in sorted(SRC.iterdir()):
    if f.name.startswith(".") or not f.is_file():
        continue
    try:
        result = md.convert(str(f))
    except Exception as e:
        print(f"[skip] {f.name}: {type(e).__name__}: {e}")
        continue
    out = DST / f"{f.stem}.md"
    out.write_text(result.text_content, encoding="utf-8")
    print(f"[ok] {f.name} -> {out.name} ({len(result.text_content)} chars)")

python demo/batch.py

预期输出：每个文件一行 [ok] 加字符数，比如 [ok] report.docx -> report.md (1842 chars)；遇到不支持的格式会打一行 [skip] 并继续。转换结果统一在 result.text_content 里，是个纯字符串。

4. 可选：让 LLM 描述图片

这一步要做什么：图片本身没有文字，MarkItDown 会把 EXIF 提出来，但内容得靠多模态模型描述。传一个 OpenAI 客户端进去即可。

pip install openai

# demo/batch_llm.py
import os
from openai import OpenAI
from markitdown import MarkItDown

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
md = MarkItDown(llm_client=client, llm_model="gpt-4o")

result = md.convert("demo/in/screenshot.png")
print(result.text_content)

预期输出：不再是空字符串，而是一段对该图片内容的自然语言描述。这一步要花钱，批量跑之前先拿单张图确认效果和成本。

配置与调优

按需安装，别一直背着 [all]

生产环境建议只装用得到的 extras，镜像体积和依赖冲突都会小很多：

pip install "markitdown[pdf,docx,pptx,xlsx]"

需要语音转写加 audio-transcription，需要解析 YouTube 链接加 youtube-transcription，扫描件走 Azure 加 az-doc-intel。

用 convert_stream 处理字节流

文件来自网络、对象存储或者已经是内存里的 bytes 时，不用先落盘，直接把流丢进去，注意显式告诉它扩展名：

import io
buf = io.BytesIO(b"...")
result = md.convert_stream(buf, file_extension=".pdf")

插件系统默认是关的

MarkItDown() 默认 enable_plugins=False。装了第三方插件要显式打开 MarkItDown(enable_plugins=True)，否则插件的转换器根本不会被调用，很容易误判成"插件没装好"。

常见坑与排错

下一步

• 接进 MCP 生态：pip install markitdown-mcp，默认 stdio 模式跑 markitdown-mcp；也可以 markitdown-mcp --http --host 127.0.0.1 --port 3001 起个 HTTP 服务，挂到 Claude Desktop 或其他 MCP 客户端里，让模型自己决定什么时候转文档。
• 写自己的插件：仓库里有 sample plugin 可以照着抄，实现一个转换器类注册进去，就能支持你们内部的自研格式，配合 enable_plugins=True 使用。
• 塞进 RAG 管道：把 batch.py 的输出接到分块器和向量库里，或者上 Docker 版 docker run --rm -i markitdown:latest < input.pdf > output.md，做成一个无状态的转换服务。

最后提醒一句：MarkItDown 会以当前进程权限做 I/O，别拿它处理来路不明的文件。