MarkItDown Markdown转换快速指南：一条命令转换PDF与办公文档

MarkItDown Markdown转换快速指南一条命令转换PDF与办公文档【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown如果你曾想把一份 PDF 报告或 Word 合同喂给大模型多半碰过这堵墙手工复制文本标题、表格、列表全被打散。MarkItDown 是一个轻量的 Python Markdown 转换工具能把 PDF、Word、PPT、Excel、图片、音频、HTML、EPUB 甚至 ZIP 一次性转成结构化 Markdown。它适合需要给 LLM 准备文档、搭建文本分析管线或只想给办公文档存一份可检索文本的人。Python 3.10 就能跑起来一条markitdown命令的事。 把PDF与办公文档转换成Markdown喂给大模型假设你有一份 40 页的合同 PDF想让大模型挑出付款与违约条款。手工复制的文本表格结构全断、标题也没了markitdown contract.pdf -o contract.md一次性转出标题、列表、表格、链接都保留为 Markdown 结构文件可以直接进模型或向量检索管线。月底要对账时一堆 Excel 流水和 PPT 评审稿也能走命令行批量转换Excel 表格变成 Markdown 表格PPT 输出幻灯片正文与演讲者备注汇总脚本不再依赖手工粘贴。归档素材里的图片和音视频同样能处理图片先输出 EXIF 元数据接上 LLM 客户端还会生成文字描述wav/mp3 走语音转写ZIP 文件直接指过去内容会被逐个转换。⚡ 第一次跑起来安装并转换第一个文档前提是一个 Python 3.10 的解释器建议再建一个虚拟环境避免依赖冲突。直接安装的支线最短python -m venv .venv source .venv/bin/activate pip install markitdown[all] markitdown report.pdf -o report.md打开 report.md标题层级、表格和链接都在。[all]表示装上全部格式的可选依赖。如果你要从源码跑比如准备改代码支线是git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[all]可编辑模式安装后直接改 packages/markitdown/src/markitdown/ 下的转换器就能立刻验证。️ 进阶按任务学按需装依赖、管道输入、让LLM描述图片只装需要的依赖[all]会拉进最重的一组可选依赖。只处理 PDF 和 Word 的话按格式装pip install markitdown[pdf,docx]安装体积明显变小版本冲突也更少。需要 Outlook 邮件或 YouTube 字幕时再补[outlook]、[youtube-transcription]。从管道读取并传格式提示没有扩展名的内容比如 curl 下来的流用-x指定类型还可以传-m指定 MIME 类型、-c指定编码cat scan.pdf | markitdown -x pdf -o scan.md效果是匿名流也能稳定识别出正确格式不用先落一个临时文件。让LLM描述文档里的图片对图片和 PPT 文件构造MarkItDown()时传入llm_client与llm_model比如 OpenAI 客户端加gpt-4o输出会自动带上图片的文字描述llm_prompt可自定义提示词。文档里的图片内容从此变成可检索的文本。启用OCR等第三方插件插件默认不生效先用markitdown --list-plugins看装了哪些再给转换命令加-p启用。比如 markitdown-ocr 插件用 LLM Vision 识别 PDF、DOCX 里嵌图的文字没传llm_client时会自动跳过 OCR退回内置转换器。把扫描文件交给云端服务扫描件本地提取质量差时加-d -e endpoint走 Azure Document Intelligence或--use-cu --cu-endpoint用 Content Understanding。端点参数必传否则直接报错退出注意每次转换都是一次计费的云端 API 调用。 用Docker运行并暴露MCP服务仓库根目录的 Dockerfile 基于 python:3.13-slim预装了 ffmpeg 与 exiftool音频和图片元数据需要入口就是markitdown并以 nobody 用户运行docker build -t markitdown:latest . docker run --rm -i markitdown:latest report.pdf report.md容器里还可以发布 MCP 服务给 Agent 客户端调用pip install markitdown-mcp后直接跑markitdown-mcp走 STDIO或加--http --host 127.0.0.1 --port 3001开 HTTP/SSE。服务只暴露一个工具convert_to_markdown(uri)接受 http、https、file、data 四种 URIHTTP 默认只绑定本机回环地址不要直接暴露到公网。⚙️ 关键CLI参数速查参数类型作用默认值-o, --output字符串输出文件路径写入标准输出-x, --extension字符串stdin 的扩展名提示如pdf自动探测-m, --mime-type字符串MIME 类型提示自动探测-c, --charset字符串字符集提示如UTF-8自动探测-p, --use-plugins开关启用第三方插件关闭--list-plugins开关列出已装插件后退出—--keep-data-uris开关保留 base64 图片数据默认截断-d, --use-docintel开关改用 Document Intelligence需配-e关闭 常见踩坑与修复Python 版本报错→ 要求 3.10低于则装不上或报异常 → 升级解释器或重建虚拟环境某格式 ModuleNotFoundError→ 没装对应可选依赖 →pip install markitdown[pdf]这样按格式补stdin 转换识别错误→ 流没有扩展名格式判断失败 → 加-x pdf或-m application/pdf输出乱码→ 字符编码没探测准 → 加-c UTF-8指定--use-docintel立即报错→ 漏传-e端点参数 → 补上有效的端点地址装了插件没生效→ 插件默认关闭 → 转换命令加-p输出里缺 base64 图片→ data URI 默认被截断 → 加--keep-data-uris服务端传入不可信文件→ 进程以当前用户权限做 I/O存在风险 → 先校验输入并改用convert_local()、convert_stream()等最小接口 核心模块与社区参与转换引擎与 20 格式转换器- PDF、Office、音频、HTML 等处理器packages/markitdown/src/markitdown/converters/OCR 插件- LLM Vision 识别文档内嵌图片文字packages/markitdown-ocr/MCP 服务包- 暴露 convert_to_markdown 工具packages/markitdown-mcp/示例插件- 自己写插件的模板packages/markitdown-sample-plugin/版本更新以 PyPI 上的发布节奏为准问题反馈走仓库的 issue 区想贡献就 fork 后提 PR流程见顶层 README.md 的 Contributing 一节。MarkItDown 的价值在于把「非结构化文件」低成本变成「大模型吃得进去的结构化文本」全程几乎没有配置项。下一步可以就一件事把这篇文章快速上手节的命令跑到你手头卡住的那份文档上看看输出里的表格和标题是否完整。效果确认后再决定要不要接 LLM 客户端或 OCR 插件。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考