一条命令把 PPT 变成 LLM 能读懂的 Markdown：markitdown PowerPoint 转换实战

一条命令把 PPT 变成 LLM 能读懂的 Markdown：markitdown PowerPoint 转换实战

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

markitdown 是一个把各类办公文档转换为 Markdown 的 Python 工具，其中 PPTX 转换功能会将 .pptx 里的文本、表格、图表、图片和演讲者备注逐形状处理，输出带幻灯片分隔注释的结构化 Markdown，可以直接喂给 LLM 或 RAG 流水线。下面的内容基于对转换器源码与测试向量的阅读整理，覆盖从安装到关键配置的全部要点。

转换结果长什么样

先看产物，再谈原理。一份包含标题、表格、图表、图片和备注的演示文稿，经过 markitdown 处理后大致是这样的：

<!-- Slide number: 1 --> # 项目季度报告 | 产品 | Q1销售额 | Q2销售额 | 增长率 | |------|----------|----------|--------| | 产品A | $120,000 | $138,000 | 15% | ### Chart: 季度销售趋势 | Category | 产品A | 产品B | |----------|-------|-------| | Q1 | 120000 | 85000 | 产品A最新版本界面截图 ### Notes: 本季度增长率达到15%

几个值得注意的输出约定：

• 每张幻灯片以<!-- Slide number: N -->注释块开头，方便下游按页切分
• 幻灯片标题形状会被提升为#一级标题，其余文本框按原样输出
• 图表统一渲染为### Chart: 标题加一张"类别 × 数据系列"的表格；遇到无法解析的图表类型时，只输出一行[unsupported chart]占位，不会中断整个转换
• 备注（如有）追加在页面末尾，以### Notes:标记
• 图片默认输出为alt形式；alt 文本优先取嵌入文件的描述、LLM 生成的说明，最后才回退到形状名

安装与快速上手

PPTX 支持依赖python-pptx，属于可选依赖，需要显式安装：

pip install 'markitdown[pptx]'

如果还要处理 PDF、Excel 等其它格式，用pip install 'markitdown[all]'一次性装齐。

命令行方式支持文件参数、管道和标准输入三种入口：

markitdown presentation.pptx -o output.md cat presentation.pptx | markitdown -x pptx

注意管道模式下没有扩展名线索，加-x pptx给出提示更稳妥。Python API 更直接，convert()既可接收路径、Path，也可接收二进制流：

from markitdown import MarkItDown result = MarkItDown().convert("presentation.pptx") print(result.text_content)

转换器内部做了哪些事

实现位于packages/markitdown/src/markitdown/converters/_pptx_converter.py，逻辑并不复杂：

1. 用 python-pptx 打开演示文稿，逐页遍历
2. 页面内的形状按top、left坐标排序后再输出——坐标为空的形状排最前，效果是内容大致按"从上到下、从左到右"的阅读顺序出现，而不是 XML 里的创建顺序
3. 组合形状（Group）会递归展开，内部子形状同样参与坐标排序
4. 表格先拼成 HTML 片段，再交给内置的 HtmlConverter 转成 Markdown 表格，因此合并单元格、特殊字符转义都复用同一套逻辑
5. 图表只读取第一个 plot 的类别与系列数值；抛unsupported plot type等异常时降级为占位符文本

两个关键配置

🔧 大部分场景只用默认行为就够，真正会改的是这两个参数。

让 LLM 为图片生成描述。把 OpenAI 兼容客户端传进去即可，幻灯片内嵌的每张图片都会调用chat.completions.create生成说明，并写进 alt 文本；不传llm_prompt时默认提示词是 "Write a detailed caption for this image."：

from openai import OpenAI from markitdown import MarkItDown md = MarkItDown( llm_client=OpenAI(api_key="sk-..."), llm_model="gpt-4o", llm_prompt="用一句话概括这张技术截图的内容", ) result = md.convert("technical.pptx")

上图是仓库测试套件里用于验证 LLM 图片描述的样例图（tests/test_files/test_llm.jpg），测试会断言描述中出现 red、circle、blue、square 等词。

保留 base64 图片数据。默认情况下图片只留占位文件名；开启keep_data_uris=True（命令行对应--keep-data-uris）后，输出会变成alt内嵌形式，适合把 Markdown 做成自包含的单文件。

常见问题速查

需要自己扩展转换逻辑时，可以直接实例化PptxConverter单独调用，或参考packages/markitdown-sample-plugin/的插件骨架注册自定义转换器；插件体系默认关闭，命令行加-p、API 传enable_plugins=True才会加载。

小结

markitdown 对 PPTX 的处理策略是"保结构、不保像素"：标题、表格、图表数据、备注全部落成纯文本，图片默认只留引用、可选 LLM 描述或 base64 内嵌。对于把历史演示文稿变成可检索语料、或者为 Agent 准备上下文这类任务，这套输出格式开箱即用，基本不需要再写清洗脚本。

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