一个为模型、而非为读者打造的转换器
MarkItDown 是微软 AutoGen 团队出的一个 Python 工具,把文件转成 Markdown:PDF、Word、PowerPoint、Excel、图片、音频、HTML、CSV、JSON,甚至 YouTube 链接和 EPUB。README 很诚实、也是你采用前该先记牢的一点,是这份输出的目标受众。这是给大语言模型和文本分析管线用的转换,不是给想要原文忠实复刻的人用的。
这个区分就是选它或不选它的全部理由。Markdown 接近纯文本,带着刚好够用的结构(标题、列表、表格、链接),也是主流模型本就读得流畅、且省 token 的格式。MarkItDown 为此而优化。如果你要的是把一份复杂 PDF 做成像素级忠实、可供人阅读或打印的版本,项目自己会把你指向别处。
它转什么,以及 extras 的坑
格式覆盖很广,但都挡在可选依赖后面。裸装的包在你拉对应 extras 之前,处理不了 PDF 或 Office 文件。最省事的路径是全都装:
pip install 'markitdown[all]'想要更精简的体积,就只装你用得到的:
pip install 'markitdown[pdf, docx, pptx]'这是头一周最常见的绊脚石:装了基础包,喂它一个 PDF,然后纳闷为什么好像不支持。不是不支持,是没选上。可用的 extras 包括 [pdf]、[docx]、[pptx]、[xlsx]、[outlook]、[audio-transcription]、[youtube-transcription] 等等。
用法
命令行里,写到文件或用管道:
markitdown path-to-file.pdf -o document.mdPython 里,API 就是一个类、一次调用:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.xlsx")
print(result.text_content)要给图片和幻灯片做图像描述,你传入一个 LLM client 和 model,而不是靠某个内置的视觉步骤:
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o")
result = md.convert("slide.jpg")
print(result.text_content)多数人忽略的三个转换档位
MarkItDown 不是一个转换器,是三个质量档位,选错了不是浪费钱就是浪费保真度:
- 内置转换器 离线运行,逐格式、在本地算力上跑。免费、私密,也是干净数字文档的正确默认值。
- Azure Document Intelligence 加上云端版面提取,应对扫描 PDF 和复杂表格。按量计费,本地提取把结构搞乱时值得上。
- Azure Content Understanding 是唯一能处理视频的档位,音频质量更高,还能把结构化字段(发票金额、日期)以 YAML front matter 形式输出。同样按每次
convert()调用计费,所以用cu_file_types圈定范围,别把一切都往它那儿路由。
文档里埋着的实用建议:从内置开始,只为本地确实失败的那些格式升级到云档位。
那条别一扫而过的安全提示
MarkItDown 以当前进程的权限做 I/O,跟 open() 或 requests.get() 是一回事。在不可信环境里,这意味着一个恶意输入能够到进程所能够到的一切。维护者的建议是:净化输入,并调用最窄的那个函数,比如 convert_stream() 或 convert_local(),而不是一个宽泛的便捷入口。如果你在服务器上转换用户上传的文件,上线前先读那一节。
markitdown 与其它「文档转文本」工具的对比
| markitdown | docling | unstructured | textract | |
|---|---|---|---|---|
| Stars | 149,717 | 61,296 | 14,876 | 4,609 |
| 输出 | 给 LLM 用的 Markdown | 结构化文档模型 | 给 RAG 用的元素 | 纯文本 |
| 许可 | MIT | MIT | Apache-2.0 | MIT |
| 最适合 | 广格式、快速喂 LLM | 丰富的版面保真 | 企业级摄取管线 | 老式文本提取 |
计数取自 GitHub,截至 2026 年 6 月。Docling 在版面与结构上挖得更深,当文档保真本身是重点时这很要紧。Unstructured 围绕检索管线的分块元素来组织。Textract 是更老的、纯文本的祖辈,MarkItDown 明确拿自己跟它比。MarkItDown 的优势在于广度和速度:几乎能从任何东西里(含音频和 YouTube)以最少配置弄出说得过去的 Markdown。
版本与 issue 区告诉你的事
MarkItDown 仍是 1.0 之前,最新 v0.1.6 发布于 2026 年 5 月,且背着一个庞大的 open issue 数(截至 2026-06 有 826 个)。这是支持这么多格式的代价:每个格式都是它自己的一条长尾边界情况。讨论最热的 open 帖是关于更深的 LLM 集成。把它当成一个快速演进、用途很广的工具,而非一个冻结的标准;如果你依赖精确输出,就钉死你的版本。
相关
要把抽出的 Markdown 喂给本地模型当输入,见 Ollama。想看生态里还有什么在往上爬,浏览每日趋势速报和周报。
FAQ
MarkItDown 适合高保真文档转换吗? 不适合,它自己也这么说。它面向给 LLM 和文本分析用的 Markdown,不是给人看的忠实复刻。那种需求用 Docling 这类专注版面的工具。
为什么我装完处理不了 PDF? 你大概只装了基础包、没装 extras。装 markitdown[all] 或具体的 extras,比如 markitdown[pdf]。
我需要 Azure 订阅吗? 只有 Document Intelligence 和 Content Understanding 这两个档位需要。内置转换器在本地跑、免费。
转换不可信文件安全吗? 要小心才行。它以进程权限做 I/O;在不可信环境里净化输入,并用最窄的 convert_* 函数。