MarkItDown 实战教程：把 20 余种文件转成 LLM 能读的 Markdown

MarkItDown 实战教程：把 20 余种文件转成 LLM 能读的 Markdown

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

给企业做文档问答系统时，第一步总是要把散落的 PDF、PPT 变成模型能读的文字。手工复制粘贴会丢表格和标题层级，图片最后只剩一堆文件名。MarkItDown 是一个轻量 Python 工具，一条命令就能把 PDF、PPT、Word、Excel、音频、网页等 20 余种格式转成 Markdown，标题、表格、列表结构原样保留。

快速上手：一条命令安装并转换一个文件

MarkItDown 要求 Python 3.10 以上，当前版本 0.1.6，MIT 协议。在虚拟环境里执行安装，随后转换任意一个文件：

# 安装全部格式支持（Python 3.10+） pip install 'markitdown[all]' # 一条命令把 PPT 转成 Markdown，输出到文件 markitdown presentation.pptx -o output.md

如果你只处理 PDF 和 Word，可以改成pip install 'markitdown[pdf, docx, pptx]'这种组合，依赖树最小。官方提供的 extras 共 10 组，包括[pdf]、[pptx]、[xlsx]、[xls]、[docx]、[outlook]、[audio-transcription]、[youtube-transcription]、[az-doc-intel]、[az-content-understanding]。需要改源码时，克隆仓库（https://link.gitcode.com/i/a4df9e4629ef0dd08f015bee7ad4b774）后执行pip install -e 'packages/markitdown[all]'即可。

运行后，输出以幻灯片注释<!-- Slide number: 1 -->开头，后面依次是每页的标题、正文和表格。命令行还支持管道输入：cat file.pdf | markitdown，从标准输入读取且类型无法推断时，用-x指定扩展名、-m指定 MIME 类型作为提示。同一能力在 Python 里直接调用：

from markitdown import MarkItDown md = MarkItDown() result = md.convert("report.xlsx") print(result.text_content) # 得到 Markdown 文本

MarkItDown 如何识别格式并保留结构

自动识别与转换器路由

工具内部先用 magika 内容指纹库识别文件流，再结合扩展名和 MIME 类型做匹配。每个内置转换器都声明自己接受的扩展名与 MIME 前缀，并按优先级注册：具体格式转换器（如 .pdf、.docx）优先级 0.0，通用兜底转换器（如 text/*）优先级 10.0，按升序取第一个命中的接管。这意味着你只需要把文件丢给convert()，不用关心它具体是什么格式。

逐页保留结构

以 PPT 转换为例，PptxConverter 按顺序遍历幻灯片：每页开头写入<!-- Slide number: N -->注释，标题映射成 Markdown 标题，表格转成 Markdown 表格语法，图片输出原有的 alt 文本。原文件的分页边界在输出里依然存在，下游工具可以按页重新定位内容。

LLM 图像描述

图片是多数转换工具最弱的一环。MarkItDown 允许你传入任意 OpenAI 兼容客户端：它把图片读成 base64 拼成 data URI，带上 prompt 发给 chat.completions，把返回的描述写进输出。默认 prompt 是让模型"为这张图写一段详细描述"，用llm_prompt参数可以覆盖。该能力目前覆盖 pptx 和图片文件。

图：仓库里用于测试 LLM 图像描述的示例图，包含一个红色圆形、一个蓝色方形和一句给模型的描述提示，接入 LLM 后 MarkItDown 会为这类图生成文字描述

实战演练：PDF 转 Markdown 与带图像描述的 PPT

场景一：学术论文 PDF 转 Markdown

输入是一份带标题、作者块、插图、摘要和脚注的论文 PDF。安装pip install 'markitdown[pdf]'后执行markitdown paper.pdf -o paper.md。产出中，标题、摘要和章节标题分别映射成不同层级的#，摘要成为连续段落，图表区域保留说明性文字。原始页面结构基本完整，可以直接作为 RAG 系统做切分的语料来源。

图：仓库 PDF 转换测试使用的样张论文，转换后标题、摘要、图表与脚注的结构会被还原为 Markdown

场景二：给 PPT 开启图像描述

输入是一份带图表和截图的产品材料。接入 LLM 客户端后这样调用：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown( llm_client=OpenAI(), llm_model="gpt-4o", ) print(md.convert("deck_with_images.pptx").text_content)

输出里不再是"这里有一张图"，而是每张图后面跟上一两句模型生成的描述，说明图中出现了什么形状、什么颜色。视觉内容就此变成文本，LLM 能参与理解。材料里的表格则转成 Markdown 表格行，可以直接被下游程序提取。

进阶用法：批量转换、系统集成与 Docker 容器化

批量任务思路很直接：遍历目标目录拿到文件清单，对每个文件调用markitdown 文件 -o 输出路径，把成功与失败写入日志。不需要复杂编排，一个 shell 循环加状态码判断就能完成几百个文件的转换。

集成进服务时注意安全设计：convert()同时支持本地文件、远程 URI 和字节流，官方建议按场景调用最窄的接口——本地文件用convert_local()，字节流用convert_stream()，大文档走流式可以避免把全部内容驻留内存；需要自己控制抓取时，先执行requests.get()再把响应对象传给convert_response()。输入可能来自不可信用户时，先校验文件路径与网络目标再转换。

容器化开箱即用：仓库根目录的 Dockerfile 基于 python:3.13-slim-bullseye，预装 ffmpeg 和 exiftool（分别用于音频处理和元数据提取），默认以非 root 用户运行。

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

需要扩展格式时看插件系统：安装后用markitdown --list-plugins查看已装插件，转换时加--use-plugins启用。官方的 markitdown-ocr 插件会给 PDF、DOCX、PPTX、XLSX 转换器增加 OCR 能力，从内嵌图片里提取文字，沿用的正是同一套llm_client/llm_model配置。

选型参考：什么时候该用它，什么时候不该用

有三类场景它不合适。第一，你需要像素级还原版式、供人阅读的排版件——官方定位是输出给文本分析工具，人类可读只是"尚可"。第二，大批量低质量扫描件，离线提取效果不满意时应切换云方案：CLI 加-d -e "<endpoint>"走 Azure Document Intelligence，或加--use-cu --cu-endpoint "<endpoint>"走 Content Understanding，后者还支持 YAML front matter 结构化字段抽取与音视频文件。第三，团队技术栈完全非 Python 时，其插件体系与高级参数都围绕 Python 设计，用 CLI 或 Docker 可以，深度集成不建议。

小结与下一步

MarkItDown 把一件事做透：把各种格式的文档变成结构保留、token 友好的 Markdown，直接喂给 LLM 流水线。如果你正在搭 RAG 系统或做文档批量预处理，今天就可以pip install 'markitdown[all]'，先把手头最难的一个文件跑一遍，看看输出结构是否符合预期。

关键资源：仓库地址（git clone 后源码安装）

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown