前段时间做内部知识库整理手头堆了两百多份 PDF、Word、PPT还有不少扫描件。传统做法是先人工转文本再手工清洗格式三五份没问题几百份直接劝退。后来在 GitHub 上翻到微软开源的 MarkItDown实测两天原来预期一个星期的活压缩到半天。这篇就把这个工具的安装、用法、原理和踩坑记录完整过一遍。MarkItDown 是一个把多种常见格式统一转换成 Markdown 的开源命令行 / Python 工具目前支持 PDF、Word、Excel、PowerPoint、HTML、CSV、JSON、XML还能配合 OCR 处理图片、配合语音识别转写音频格式覆盖二十来种。它解决的核心问题很直白大模型和 RAG 应用只能高效理解纯文本和 Markdown而日常工作碰到的办公文档、网页、扫描件并不直接可用。不管你是搭知识库、给大模型喂数据还是做内容归档这个工具都值得放进工具箱尤其推荐给 NLP 工程、后端开发和内容运营的同学。1. 为什么文件格式成了“文档转文本”的最大障碍先聊聊这个工具出现的背景理解了背景你才知道它解决了什么痛点也才知道什么场景下该找它。1.1 大模型吃不下 PDF技术含量在“解析”而不是“读取”很多人以为 PDF 转文本就是把文件读出来实际上 PDF 并不是一种“流式文本”格式它记录的是一堆对象的绘制指令文字在这页的哪个坐标、字体什么字号、这张图放在哪。你拿一个普通文件读取函数去读 PDF读出来的可能是乱码也可能什么都读不到。更麻烦的是办公文档的“语义结构”和“视觉排版”是两套东西。一个 Excel 表格里的“销售额”列在转换时可能被拆得七零八落一个 PPT 里的标题、正文、批注如果不做专门解析转出来的文本会丢失层级关系。大模型要是不认文档结构回答问题时就会把标题当正文、把表格当普通文字流知识库的检索效果和答案质量都会崩。所以 MarkItDown 这类工具的核心价值不在于“能读文件”而在于“能把文件里人类的阅读结构转成机器能理解的 Markdown 结构”。标题还是标题列表还是列表表格还是表格超链接和图片描述都能保留下来这是普通文本提取做不到的。1.2 为什么选 Markdown 作为统一下游格式你可能会问直接把文档转成纯文本不就行了吗Markdown 多出来的几个符号有什么了不起纯文本确实“能读”但它丢了上下文。比如文档里有三级标题、加粗、超链接、表格纯文本一扁平化层次信息全没了。而 Markdown 用非常轻量的符号保留了这些语义#表示标题层级|表示表格边界[]()表示链接**表示强调。对大模型来说这些符号本身也是一种“语法提示”它能据此判断文本之间的关系从而提升信息抽取和问答的准确率。另外 Markdown 是纯文本存储传输都轻主流的向量数据库切分工具比如 LangChain 的 MarkdownHeaderTextSplitter对它天然友好。所以 MarkItDown 选择 Markdown 作为统一输出不是随便定的它是为了整个 LLM 数据链路服务的。1.3 谁需要这个工具什么场景最值得用我自己的使用经验里最有价值的是这几类场景RAG 知识库建设把公司内部文档、产品说明书、技术文档批量转成 Markdown再切片进向量库这是目前最典型的需求。模型训练数据清洗攒了一批网页、PDF想抽出来做微调数据或评测集MarkItDown 能统一格式。内容平台迁移把旧博客、帮助中心、Wiki 导出的 HTML 一次性转成 Markdown方便换系统或重新发布。格式归档很多旧文件格式随着软件更新可能会打不开转成 Markdown 至少内容永远可读、可 diff、可搜索。如果你是上面这四类人之一可以接着往下看如果只是偶尔转一两个文件也不亏装好之后一行命令就能用。2. 安装和环境准备这个工具是纯 Python 写的安装方式比较简单但有些格式的依赖是“可选”的你得按需装否则能装不能用这也是新手最容易踩的坑。2.1 环境要求MarkItDown 要求 Python 3.9 以上的环境我在 Windows 和 Linux 上都跑过Windows 下注意 Python 要勾选“Add Python to PATH”否则命令行里执行不了pip。建议新建一个虚拟环境再装避免和系统里的其他包打架。我一般这么操作python -m venv md_env # Windows md_env\Scripts\activate # macOS / Linux source md_env/bin/activate2.2 pip 安装基础版和全家桶怎么选最简单的安装是pip install markitdown但注意这个基础版只带比较轻量的依赖能直接处理 HTML、CSV、JSON、XML、TXT 这些纯结构化格式。想解析 PDF、Office 三件套、音频、图片就需要装对应的扩展包。官方提供了几个可选依赖组常用的是这些安装命令支持格式pip install markitdown[pdf]PDFpip install markitdown[docx]Word 文档pip install markitdown[xlsx]Excel 工作簿pip install markitdown[pptx]PPT 演示文稿pip install markitdown[audio]WAV、MP3 等音频转写pip install markitdown[all]上面所有格式一次搞定我个人的建议是不确定自己以后要转什么格式就直接装markitdown[all]省得之后用到某个格式才发现缺依赖。唯一提醒的是它的音频转写依赖SpeechRecognition和pydub在有些 Linux 环境上还需要额外装 FFmpeg这个后面第 5 节细说。2.3 验证安装是否成功装完后先看一眼命令行工具是否可用markitdown --help能弹出帮助信息就算成了。再拿一个最简单的文本文件做冒烟测试echo Hello MarkItDown test.txt markitdown test.txt如果输出Hello MarkItDown说明基础链路是通的。接下来再拿你想用的格式实际转一下比如 PDF才能确认可选依赖都装齐了。提示markitdown[all]安装包比较大因为要拉 pdfminer.six、mammoth、openpyxl、python-pptx 一整套解析库。在公司内网环境如果下载慢可以考虑只装你实际需要的扩展组避免无谓等待。3. 核心能力拆解格式支持与两种使用方式这部分我把支持格式、命令行用法、Python API 逐个讲清楚。你可以把这一节当速查手册以后用到直接翻。3.1 支持格式一览下表是我实际测过或者看过源码确认能支持的格式注意同一种格式在不同版本里行为可能有差异用前最好升级到最新版格式扩展名默认依赖我的使用评价PDF.pdfpdfminer.six文本型 PDF 效果不错扫描型要靠 LLM / OCRWord.docxmammoth标题、列表、表格恢复得比较完整PowerPoint.pptxpython-pptx每张幻灯片的标题会转成二级标题正文按层级保留Excel.xlsxopenpyxl每个工作表转成表格表头保留HTML.html/.htm内置能抽正文、保留标题和链接CSV / JSON / XML / YAML多种内置转为代码块或表格保真度很高图片.jpg/.jpeg/.png配置 LLM需要 OpenAI 兼容接口做视觉理解或用文档智能 OCR音频.wav/.mp3/.m4aSpeechRecognition依赖语音识别服务转写结果不保证 100% 准确压缩包.zip内置自动解压并转换包内所有文件EPUB.epub内置电子书转 Markdown 结构清晰日历 / 联系人.ics/.vcf内置结构化转列表适合数据迁移需要额外提一句老的.xls、.doc、.ppt这些 Office 97-2003 格式MarkItDown 本身不直接支持官方推荐先通过 LibreOffice 无损转成新格式再交给它处理。我试过一堆十几年前的老合同这一套流程确实可行。3.2 命令行一组命令搞定日常转换命令行是 MarkItDown 最常用的入口核心就三个动作指定输入文件、指定输出文件、执行。# 直接在终端输出转换结果 markitdown report.pdf # 输出到指定 Markdown 文件 markitdown report.pdf -o report.md # 处理 Word 文档 markitdown 产品说明.docx -o 产品说明.md # 处理 HTML 网页 markitdown https://example.com/article -o article.md没错新版 MarkItDown 还支持直接传 URL会自动抓取网页内容再转 Markdown做网页存档非常方便。用命令行做“单文件转换”是最省事的但也要注意两点一是命令默认把输出打印到标准输出如果你在 PowerShell 或 cmd 里想重定向成文件直接用-o参数而不是用符号避免编码问题二是文件路径里有中文或空格时最好加引号包起来不同系统对路径解析的规则不一样。3.3 Python API嵌入自己的业务代码命令行适合手工操作一旦要批量处理或者集成到服务里就得用 Python API。MarkItDown 的 Python 接口设计得极为简洁核心就三个环节构造转换器、调用 convert、读结果。from markitdown import MarkItDown # 创建转换器 md MarkItDown() # 转换文件返回一个转换结果对象 result md.convert(data/产品手册.pdf) # 拿到 Markdown 文本 markdown_text result.text_content # 存到文件 with open(output.md, w, encodingutf-8) as f: f.write(markdown_text)这里有一个细节值得展开result.text_content是最终转换完的 Markdown 字符串。如果你做的是管道任务拿到这个字符串后可以直接切片、清洗、向量化不需要中间落地成文件省了一轮 IO。需要注意的一点是convert()方法支持传文件路径也支持传流对象。读取已经打开的文件流时需要对应的流实现read()方法并返回bytes。比如你从 S3 或 HTTP 接口下载文件后不想落盘直接转换就可以构造一个 BytesIO 流传进去能省下大文件的磁盘空间。3.4 图片识别和音频转写带一点“AI”味道的高级能力MarkItDown 不只是转文档它还能处理图片和音频但这两块的配置稍微复杂一点。图片转 Markdown有两种方案一是配置视觉大模型把图片交给 LLM 描述二是配合文档智能服务做 OCR。视觉模型的接入方式走 OpenAI 兼容接口官方示例大致是这样from openai import OpenAI from markitdown import MarkItDown client OpenAI() # 这里可以替换成任意 OpenAI 兼容服务的 client md MarkItDown(llm_clientclient, llm_modelgpt-4o) result md.convert(scale_diagram.png) print(result.text_content)只要你有任意一个兼容 OpenAI Chat Completions 接口的服务商把llm_client和llm_model换掉就行。图片里的文字、图表结构、甚至场景描述都会以 Markdown 的形式输出效果比自己跑传统 OCR 好不少。唯一的代价是每张图会调一次模型有成本和延迟不适合大批量场景。音频转写则用speech_recognition这个参数开启md MarkItDown(speech_recognitionTrue) result md.convert(meeting_recording.mp3)默认走的是 Google Web Speech 之类的远程识别服务识别质量受音频质量影响很大中文、方言、多人说话的场景效果一般。如果对准确率要求高建议先把音频切段、降噪再送入识别。这块我没法保证哪种方案绝对最优因为和你用的识别后端强相关建议拿一小段真实音频先试效果再决定。4. 实操记录把一份 PDF 转成干净 Markdown理论讲再多不如动手跑一遍。这一节我以“产品说明书 PDF”为例从准备文件到批量转换完整展示一遍实操过程。4.1 准备测试文档我拿了一份大约 30 页的产品说明书里面包含多级标题、表格、图片说明和几个页脚。这种文档很典型既不能直接复制粘贴有表格分层又不想花钱买商业 OCR 工具。准备工作就这么三步把文件放到工作目录比如docs/产品说明书.pdf确认虚拟环境已激活确认已安装 PDF 相关的依赖pip install markitdown[pdf]4.2 命令行转换从零到一先用命令行跑一遍看看基础效果markitdown docs/产品说明书.pdf -o docs/产品说明书.md命令执行完工作目录里多了一个.md文件。打开后你会看到类似这样的结构# 产品说明书 ## 第一章 安全注意事项 - 请勿在雨中使用设备 - 使用前请阅读本章 ## 第二章 技术参数 | 参数 | 数值 | | --- | --- | | 电压 | 220V | | 功率 | 1500W |第一感觉是标题结构保留了表格也保留了和原来的文档层级基本对得上。比起我过去用 pdfminer 直接抽取文本得到一大坨无差别字符这个可读性强太多了。4.3 写个 Python 脚本做批量转换命令行一次只能转一个文件批量几十上百个文件时就得写脚本。这里我提供一个可以直接抄作业的版本from pathlib import Path from markitdown import MarkItDown INPUT_DIR Path(docs) OUTPUT_DIR Path(output) OUTPUT_DIR.mkdir(exist_okTrue) md MarkItDown() for src in INPUT_DIR.glob(*.pdf): result md.convert(str(src)) out_path OUTPUT_DIR / f{src.stem}.md out_path.write_text(result.text_content, encodingutf-8) print(f[OK] {src.name} - {out_path.name})这个脚本做了三件事遍历目录下的 PDF、逐个转换、按同名输出到 output 目录。你只需要改INPUT_DIR里的*.pdf为*.docx或者*.xlsx就能变成别的格式的批量转换器。我实际用的版本还会加一个异常捕获防止单个文档解析失败导致整个批处理中断。这是实战经验非常必要因为真实的办公文档五花八门保不准哪份就带了损坏的流for src in INPUT_DIR.glob(*): if src.suffix.lower() not in {.pdf, .docx, .pptx, .xlsx}: continue try: result md.convert(str(src)) out_path OUTPUT_DIR / f{src.stem}.md out_path.write_text(result.text_content, encodingutf-8) print(f[OK] {src.name}) except Exception as e: print(f[FAIL] {src.name}: {e})4.4 转换效果怎么验收转换完不是万事大吉一定要抽检。我的验收标准有三条标题层级目测前 10 行确认一级标题、二级标题没有丢失或串级。表格完整性随机挑一个含表格的页面数一下列数和行数看有没有错位。乱码检查用脚本搜索是否存在大量\ufffd或空白字符尤其是中文文档。我遇到过最坑的情况是某个 PDF 的页眉页脚被识别成正文每一页都重复一段公司名称。虽然不影响内容语义但会让检索时的 chunk 出现大量重复片段浪费 token 还影响精确度。对这种情况我的办法是在批量脚本后面加一步正则清洗把页眉页脚模式去掉再入库。5. 常见问题与排查技巧用了这么久我把踩过的坑整理成了一份速查表按频率从高到低排序。5.1 安装时报错magic库装不上MarkItDown 的元数据识别依赖python-magic在 Windows 上经常会报编译错误。解决办法是装 Windows 预编译版本pip install python-magic-binLinux 上如果报libmagic找不到用包管理器装一下系统库即可。这个坑我在 Windows 上必踩提前装好能省十分钟。5.2 转换出来的中文是乱码如果你的 PDF 是文本型的但转换结果出现乱码大概率有两个原因一是 PDF 内嵌字体使用了自定义编码pdfminer 解析不到位二是终端编码问题Windows 下 cmd 的默认编码是 GBK直接打印 UTF-8 内容会显示乱码。第二个原因最常见解决办法是用-o输出到文件再用支持 UTF-8 的编辑器打开。如果是第一种只能改用图像识别路线先把 PDF 页面渲染成图片再让 MarkItDown 走视觉模型识别。效率低一点但能保住内容。5.3 表格识别错乱列对不齐文本型 PDF 的表格识别是老大难问题。MarkItDown 用的是 pdfminer 提取文本流如果原表格在视觉上用了多个文本框拼出来的“伪表格”它未必能还原成规整的 Markdown 表格。我的建议分两层如果只是偶尔遇到直接用 Python 拿到结果后做正则修复如果批量遇到考虑用文档智能Document Intelligence那套方案替代基础 PDF 转换它对复杂表格的支持好得多。顺便说一句Word 和 Excel 转表格的效果远好于 PDF因为源文件本身保留了结构信息。5.4 大文件转换卡死或内存占用高300 页以上的 PDF 在单线程下转换会明显变慢。我测试过一份 500 页的书稿耗时接近两分钟内存占用也偏高。优化方案有三个一是先压缩或拆分 PDF 再转二是只转指定页码范围用 PyPDF2 等工具先切分之后并行处理三是给批量脚本加并发控制比如用concurrent.futures.ThreadPoolExecutor把文件拆到多线程跑。这里加个小提醒并发虽好但要留意解析库是否线程安全实测中 pdfminer 在不同线程里处理不同文件没出问题但保险起见还是控制在线程数 4-6 个以内。问题常见原因快速解法安装报错python-magic 编译失败Windows 装 python-magic-bin中文乱码终端编码 / 字体编码用 -o 输出文件复杂 PDF 走图片识别表格错乱PDF 无真实表格结构改用文档智能方案或 Word 源文件大文件卡顿单线程解析拆分 PDF、并发转换音频识别不准远程识别服务限制切段、降噪、换识别后端6. 进阶玩法与集成技巧工具本身很简单真正有价值的是怎么把它嵌进你的工作流。这里分享几个我实际在用的组合方案。6.1 在 RAG 知识库中的定位我的知识库处理链路是原始文档 → MarkItDown 转换 → 按标题切片 → 向量化 → 检索。MarkItDown 处在最前面负责把“人死亡格式”变成“机器友好格式”。为什么这一环重要因为后面的切片、向量化效果完全取决于输入质量。你用 MarkdownHeaderTextSplitter 这种工具时它要识别#、##标题来保持语义边界如果你输入的是没有标题结构的纯文本切片就会把完整段落砍断检索时召回的相关性就差了。如果你已经在用 Dify、FastGPT 这类平台很多内置的文档加载器其实底层就是类似 MarkItDown 的思路。但自建流程的好处是可控、可调、无资源限制尤其当你有一批特殊格式文件时自己写脚本灵活得多。6.2 配合 LangChain 使用LangChain 里可以用MarkdownTextSplitter直接处理 MarkItDown 的输出。整个串联代码非常短from langchain_text_splitters import MarkdownHeaderTextSplitter from markitdown import MarkItDown md_doc MarkItDown().convert(产品手册.pdf).text_content splitter MarkdownHeaderTextSplitter( headers_to_split_on[(#, Header 1), (##, Header 2)], strip_headersFalse, ) chunks splitter.split_text(md_doc) for chunk in chunks: print(chunk.page_content[:200])这段代码把 PDF 先转成 Markdown再按二级标题切成多个语义块每块可以直接拿去向量化。相比不分结构的文本切块上下文完整度高了不止一个档次。6.3 自定义转换与插件扩展MarkItDown 也支持针对特定格式做扩展。你可以在自己的代码里注册自定义解析器或者直接修改转换结果的后处理逻辑。我的实际做法是写一个函数接收text_content然后做针对性的清理和格式化比如去掉重复页眉、统一英文左右空格、修复特殊字符。这类后处理逻辑在真实项目中比任何模型参数都管用因为你的文档特征自己是清楚的。6.4 我的几条效率经验最后分享几条自己摸索出来的效率经验都不复杂但很实在优先用 Word/HTML 源文件。同一份内容从 docx 转出来的 Markdown 质量远好于从 PDF 转出来的。所以能拿到源文件就不折腾 PDF这是最高效的“技巧”。把转换脚本做成定时任务。公司内部的知识库每周都有新文档我写了个脚本监控目录新文件落地后自动转换并增量入库省掉了人工触发。保留转换日志。批量转换时把成功、失败的文件名都打出来并落盘第二天再处理失败的。别急着删原始文件至少保留一周方便回溯。我在实际使用中的一个很深的体会是MarkItDown 这种工具看起来只是一个“格式转换器”但在 LLM 落地项目里它往往是数据质量和项目天花板的关键一环。很多人把精力都花在调模型、调提示词上却忽略了输入文档的结构化程度。文档转得干净后面的一切都顺文档转得稀烂再好的模型也救不回来。最后再分享一个小技巧如果你手头有大量历史 HTML 页面要处理先用命令行把 HTML 批量转换成 Markdown再用 Git 做版本管理。因为 Markdown 是纯文本每一次站内更新都能用git diff看到内容变化比维护几十个 HTML 文件舒服太多了。这个用法是我在做内容归档时发现的意外收获希望也能帮到你。