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.6MIT 协议。在虚拟环境里执行安装随后转换任意一个文件# 安装全部格式支持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_clientOpenAI(), llm_modelgpt-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配置。选型参考什么时候该用它什么时候不该用对比维度在线转换器Pandocmarkitdown上手成本打开网页上传安装并配置模板一条 pip 命令输出定位面向文档再排版Markdown版式支持一般面向 LLM 与文本分析图像处理基本不支持丢弃图片或仅留引用元数据提取可选 LLM 描述结构保留排版易断裂支持标题与公式标题、表格、列表、分页标记保留维护状态依赖厂商成熟稳定预览版0.1.6迭代快有三类场景它不合适。第一你需要像素级还原版式、供人阅读的排版件——官方定位是输出给文本分析工具人类可读只是尚可。第二大批量低质量扫描件离线提取效果不满意时应切换云方案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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考