企业官网建设流程全解析

用 MarkItDown 三步把扫描件变成 AI 能读的 Markdown

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

手头有一批扫描件、发票和会议纪要，需要喂给大模型，但模型读不了二进制文件。MarkItDown 是一个把文件和办公文档转成 Markdown 的 Python 工具，一条命令就能让 PDF、Word、PPT、图片变成 AI 能直接读取的结构化文本。

一张表认识它：是什么、能干什么

MarkItDown 是微软 AutoGen 团队出品的轻量级文档转换工具。它的设计目标不是"把文档排版得好看"，而是"让大模型读得懂文档"。输出的 Markdown 会保留标题、列表、表格、链接等结构，格式接近纯文本、token 消耗也低，适合作为 RAG 或摘要流程的文本预处理环节。

环境准备：两条命令装好

需要 Python 3.10 及以上版本，官方建议用虚拟环境，避免依赖冲突。最小配置如下：

python -m venv .venv && source .venv/bin/activate pip install "markitdown[all]"

[all]会装齐所有格式的依赖。如果你只需要个别格式，把方括号里的内容换成对应格式名即可，比如'markitdown[pdf, docx]'，安装体积会小很多。

要识别图片里的文字，再补装 OCR 插件markitdown-ocr和一个 OpenAI 兼容客户端（如 openai）。插件的实现很薄，机制可以看OCR 插件源码。

核心场景：把扫描版 PDF 转成 Markdown

目的。扫描出来的发票 PDF 通常没有文字层，直接转换会得到空内容或乱码。你要的是一份条目、数字都完整的 Markdown。

操作。带文字层的文档，命令行直接转换即可：

markitdown path-to-file.pdf -o document.md

没有文字层的文档，则启用 OCR 插件并传入视觉模型。命令行在上面的命令后追加--use-plugins --llm-client openai --llm-model gpt-4o；Python 里只需四行：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("scan.pdf").text_content)

你会看到的结果。插件会把页面里的图片逐张交给 LLM，识别出的文字按原位置插回正文，每段识别结果都用*[Image OCR] ... [End OCR]*标记包裹，方便下游区分它和原有文字层。整页都是图片的扫描件，会自动按 300 DPI 渲染成整页图片送去识别；某一张图识别失败时转换不会中断，只是跳过那一段。

仓库的测试用例里有一张小图专门验证 LLM 读图能力：模型被要求报出图中的字符串 "5bda1dd6" 和两个图形的颜色，是判断llm_model参数是否真正生效的简易参照。

图：用于验证 MarkItDown LLM 读图能力的测试图，包含字符串 "5bda1dd6"、红色圆形与蓝色正方形

进阶场景：三张卡片介绍

以上能力都是"装依赖 + 传参数"就能切换，不需要改主转换代码。想自己扩展格式，可参考 sample-plugin 示例。

📌 避坑清单：五种常见情况怎么处理

适用边界：谁该用，什么时候别用

如果你的目的是把文档喂给大模型——RAG 预处理、批量抽文本、生成摘要——MarkItDown 的输出正合适。但它的产物是写给机器读的，排版美观度不如面向人的文档排版工具，要求高保真印刷级还原时别用它。另外，服务端转换来路不明的外部文件时，按官方安全建议改用convert_local()限定输入来源，避免传入不可信路径。

今天就能做：三步完成第一次转换

1. 建好虚拟环境，运行pip install "markitdown[all]"。
2. 挑一份手头的 PDF，命令行执行markitdown document.pdf -o out.md，打开 out.md 检查标题和表格是否保留。
3. 如果是扫描件，再装markitdown-ocr和openai，传入llm_client与llm_model重新转换，确认输出里出现*[Image OCR]*标记块。

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