MarkItDown 全面指南：用 Python 将 PDF、Office、音视频等多格式文件转换为 Markdown

• 人工智能
• AI 应用
• MCP 服务

MarkItDown 是一个轻量级的 Python 包与命令行工具，用于把各类文件（PDF、PowerPoint、Word、Excel、图片、音频、HTML、ZIP、YouTube 等）统一转换为 Markdown，供 LLM 与文本分析管线索引和消费。本指南以 packages/markitdown/README.md 为核心，结合 核心实现 与 CLI 入口 源码，完整覆盖安装方式、可选依赖、命令行与 Python API、插件体系、Azure 云端转换能力以及安全注意事项。读完本文，你将掌握从本地文件到远程 URI 的多种转换姿势，并理解转换器调度与优先级机制，能够独立搭建一套文档转 Markdown 的处理管线。

MarkItDown 是什么：为什么输出选择 Markdown

MarkItDown 与 textract 定位类似，但更专注于保留文档的重要结构（标题、列表、表格、链接等）并以 Markdown 呈现。输出虽然通常可读、适合人类查看，但其设计目标是被文本分析工具消费——因此它不追求面向人类的高保真文档转换。

选择 Markdown 的根本原因在于：Markdown 非常接近纯文本，标记极少，却能表达关键文档结构；主流 LLM（如 OpenAI 的 GPT-4o）原生"说"Markdown，常在回答中自发使用 Markdown 格式，说明其训练语料中包含了海量 Markdown 文本，理解力强；同时 Markdown 约定高度 token 高效。

当前仓库支持转换的格式（见 根目录 README 与 转换器注册清单）：

• PDF（PdfConverter）
• PowerPoint（PPTX）、Word（DOCX）、Excel（XLSX/XLS）
• 图片（EXIF 元数据与 OCR）
• 音频（EXIF 元数据与语音转写）
• HTML、RSS、Wikipedia、YouTube、Bing SERP、Jupyter Notebook（IPYNB）
• 纯文本类格式（CSV、JSON、XML）
• ZIP 压缩包（迭代解压其中内容）
• Outlook 邮件（MSG）、EPUB
• 以及更多（可通过第三方插件扩展）

环境要求与安装

前置条件

MarkItDown 要求 Python 3.10 或更高版本（pyproject.toml 中声明requires-python = ">=3.10"），建议使用虚拟环境以避免依赖冲突。

标准 Python 创建并激活虚拟环境：

python -m venv .venv source .venv/bin/activate

使用uv：

uv venv --python=3.12 .venv source .venv/bin/activate # 注意：在此虚拟环境中请使用 'uv pip install' 而非 'pip install' 安装包

使用 Anaconda：

conda create -n markitdown python=3.12 conda activate markitdown

从 PyPI 安装

pip install 'markitdown[all]'

[all]会一次性安装全部可选依赖（PDF、DOCX、PPTX、XLSX、XLS、Outlook、音频转写、YouTube 转写、Azure 文档智能等），适合开箱即用。

从源码安装

git clone <本仓库地址> cd markitdown pip install -e 'packages/markitdown[all]'

若已在仓库目录内，也可以直接在 packages/markitdown 子包下执行pip install -e '.[all]'。

命令行（CLI）用法

基础用法

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

使用-o指定输出文件：

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

通过管道传入内容（stdin）：

cat path-to-file.pdf | markitdown

从 CLI 入口 可以看到，markitdown命令还支持以下参数：

其中-x/-m/-c三个提示参数会被组装成一个 StreamInfo 对象（包含 mimetype、extension、charset、filename、local_path、url 字段），在读取 stdin 等无法从路径推断类型的场景下帮助转换器快速识别文件格式。

Python API 用法

基础转换

from markitdown import MarkItDown md = MarkItDown(enable_plugins=False) # 设置为 True 以启用插件 result = md.convert("test.xlsx") print(result.markdown)

convert()返回 DocumentConverterResult 对象，其markdown属性保存转换后的文本，title保存可选标题，text_content是markdown的软弃用别名，str(result)同样返回 Markdown 文本。

面向不同输入源的转换方法族

从源码看，convert()是一个"宽容"的分发入口（源码）：

• 传入str且 scheme 为http/https/file/data→ 调用convert_uri()
• 传入本地路径str/Path→ 调用convert_local()
• 传入requests.Response→ 调用convert_response()
• 传入可读的二进制流 → 调用convert_stream()

除convert()外，MarkItDown 还提供更聚焦的转换方法，便于精确控制输入源：

• convert_local(path)：从本地磁盘读取文件
• convert_stream(stream, stream_info=...)：转换任意二进制流；若流不可 seek，会先将整个流读入内存缓冲
• convert_uri(uri)：支持file:、data:、http:、https:四种 scheme；file:URI 的 netloc 必须为空或localhost，HTTP(S) 请求通过内置 requests 会话发出
• convert_response(response)：直接转换requests.Response，会解析Content-Type（mimetype/charset）与Content-Disposition（文件名/扩展名）头辅助类型识别
• convert_url(url)：convert_uri()的别名，未来可能弃用

使用 LLM 为图片生成描述

目前仅 PPTX 与图片文件支持通过大模型生成图像描述，传入llm_client与llm_model：

from markitdown import MarkItDown from openai import OpenAI client = OpenAI(max_retries=5) md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt") result = md.convert("example.jpg") print(result.markdown)

max_retries控制 OpenAI 客户端对可重试错误的自动重试次数（默认 2），设为5时最多尝试六次并带退避。若某次尝试成功则继续正常转换；若客户端在重试耗尽后仍报错或遇到不可重试错误，MarkItDown 会尝试其他可用转换器，只有全部失败才抛出 FileConversionException。这些 LLM 配置（llm_client/llm_model/llm_prompt）与exiftool_path、style_map会在_convert时作为全局选项透传给每个转换器（源码）。

转换器注册与优先级机制

MarkItDown 采用"转换器注册表 + 优先级排序"的调度模型（核心实现）：

• 每个转换器是 DocumentConverter 的子类，需实现accepts()（根据stream_info的 mimetype/extension/url 判断是否接手）与convert()（真正执行转换）。
• 内置转换器默认全部启用（enable_builtins=None时视为启用）；register_converter(converter, priority=...)将转换器插入注册表。
• 默认优先级PRIORITY_SPECIFIC_FILE_FORMAT = 0.0（针对 .docx、.pdf、.xlsx、wikipedia 等具体格式），PRIORITY_GENERIC_FILE_FORMAT = 10.0用于 PlainText、HTML、ZIP 这类"兜底"转换器。数值越小越先尝试，因此具体格式的转换器排在通用转换器之前。
• 转换前按优先级做稳定排序，同优先级下后注册的转换器排在前面；排序在每次_convert调用时进行，因为优先级可能动态变化。
• 每次尝试前会通过magika识别流内容并生成一组StreamInfo猜测（扩展名→MIME 互推、字符集检测），逐条尝试各转换器；任一转换器成功即返回，全部失败则汇总异常并抛出FileConversionException，无转换器接手则抛UnsupportedFormatException。

从 转换器模块 可以看到内置转换器全集：PlainTextConverter、HtmlConverter、RssConverter、WikipediaConverter、YouTubeConverter、IpynbConverter、BingSerpConverter、PdfConverter、DocxConverter、XlsxConverter/XlsConverter、PptxConverter、ImageConverter、AudioConverter、OutlookMsgConverter、ZipConverter、EpubConverter、CsvConverter，以及云端 DocumentIntelligenceConverter、ContentUnderstandingConverter。第三方插件可以注册任意优先级的转换器，例如优先级 9 的插件会运行在 PlainTextConverter 之前、内置具体格式转换器之后。

可选依赖详解

在根 README 与 pyproject.toml 中，MarkItDown 提供以下可选依赖分组，可按需安装以控制体积：

也可组合安装，例如pip install 'markitdown[pdf, docx, pptx]'只安装 PDF、DOCX、PPTX 三类文件的依赖。当转换器所需的可选依赖缺失时，会抛出 MissingDependencyException，错误信息会明确提示应安装哪个[feature]。

插件系统与 markitdown-ocr

插件管理

MarkItDown 支持第三方插件，默认关闭。列出已安装插件：

markitdown --list-plugins

启用插件转换：

markitdown --use-plugins path-to-file.pdf

插件通过 Python 的markitdown.pluginentry point 组被发现（源码），加载失败时仅告警并跳过。寻找可用插件可搜索#markitdown-plugin标签；编写插件可参考 packages/markitdown-sample-plugin 示例。

markitdown-ocr：为嵌入图片提供 LLM Vision OCR

官方提供了 markitdown-ocr 插件，为 PDF、DOCX、PPTX、XLSX 转换器增加 OCR 能力——从嵌入图片中提取文字，使用的是 MarkItDown 已有的llm_client/llm_model模式，无需新增任何 ML 库或二进制依赖。

安装：

pip install markitdown-ocr pip install openai # 或任意 OpenAI 兼容客户端

使用（Python API）：

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

命令行方式：

markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o

如果未提供llm_client，插件仍然加载，但 OCR 会被静默跳过，回退到标准内置转换器。可通过llm_prompt覆盖默认提取提示词以适配特殊文档，也支持任意 OpenAI 兼容客户端（如AzureOpenAI）。

工作原理（插件源码）：调用MarkItDown(enable_plugins=True, ...)时，MarkItDown 通过markitdown.pluginentry point 发现插件并调用其register_converters()，插件用传入的 kwargs 创建 LLM Vision OCR 服务，并以priority -1.0注册四个 OCR 增强转换器——先于优先级 0.0 的内置转换器执行。转换时：OCR 转换器接手文件 → 提取文档内嵌图片 → 逐张发送给 LLM 提取文字 → 将结果内联插入，保留文档结构与阅读顺序；LLM 调用失败则该图片文字跳过、转换继续。提取出的文本块统一包装为：

*[Image OCR] <extracted text> [End OCR]*

各格式的提取策略：PDF 按位置提取内嵌图片并垂直阅读顺序交错插文，扫描版 PDF（无可用文本的页面）自动按 300 DPI 整页渲染交给 LLM，pdfplumber/pdfminer 打不开的损坏 PDF 会改用 PyMuPDF 渲染兜底；DOCX 通过文档部件关系（doc.part.rels）提取图片，并在 DOCX→HTML→Markdown 管线前注入占位符以保留结构；PPTX 支持图片形状、带图占位形状与分组内图片，先请求描述再以 OCR 兜底；XLSX 按工作表提取图片，根据锚点坐标换算单元格位置，图片统一列在### Images in this sheet:小节下，不混入表格行。

常见问题排查：输出缺少 OCR 文本，最可能是未配置llm_client/llm_model；插件未加载，可运行markitdown --list-plugins确认是否显示ocr；API 报错时插件以警告形式透传并继续转换，请检查 API Key、配额及所选模型是否支持视觉输入。

Azure Content Understanding：云端多模态高保真转换

当内置或 Document Intelligence 转换器能力不足时，可选用 Azure Content Understanding（CU），它提供更高质量的转换，并支持结构化字段提取（输出为 YAML front matter）、多模态（文档、图片、音频、视频）以及可配置分析器。

安装：pip install 'markitdown[az-content-understanding]'

能力对比

CLI 用法

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

端点也可一次性写入环境变量，之后只需--use-cu：

export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>" markitdown path-to-file.pdf --use-cu

Python API（零配置自动路由）

from markitdown import MarkItDown # 零配置——按文件类型自动选择分析器 md = MarkItDown(cu_endpoint="<content_understanding_endpoint>") result = md.convert("report.pdf") # 文档 → prebuilt-documentSearch result = md.convert("meeting.mp4") # 视频 → prebuilt-videoSearch result = md.convert("call.wav") # 音频 → prebuilt-audioSearch print(result.markdown)

自定义分析器（领域字段提取）

md = MarkItDown( cu_endpoint="<content_understanding_endpoint>", cu_analyzer_id="my-invoice-analyzer", ) result = md.convert("invoice.pdf") print(result.markdown) # 输出包含带提取字段的 YAML front matter： # --- # contentType: document # fields: # VendorName: CONTOSO LTD. # InvoiceDate: '2019-11-15' # --- # <!-- page 1 --> # ...

当设置了cu_analyzer_id时，转换器会根据分析器的模态（modality）自动将其限定到兼容的文件类型：文档类分析器可处理文档与图片，音视频分析器只处理对应模态；不兼容的类型自动路由到默认预构建分析器（源码实现）。

限制路由范围以控制成本

每次 CU 路由格式的convert()调用都是一次可计费的 Azure API 调用。可用cu_file_types限制哪些格式走 CU：

from markitdown.converters import ContentUnderstandingFileType md = MarkItDown( cu_endpoint="<content_understanding_endpoint>", cu_file_types=[ContentUnderstandingFileType.PDF], # 仅 PDF 使用 CU )

从 ContentUnderstandingFileType 枚举 可见支持的格式：文档类（pdf/docx/pptx/xlsx/html/txt/md/rtf/xml）、邮件（eml/msg）、图片（jpeg/png/bmp/tiff/heif）、视频（mp4/m4v/mov/avi/mkv/webm/flv/wmv）、音频（wav/mp3/m4a/flac/ogg/aac/wma）。认证上，未显式传入credential时依次尝试AZURE_API_KEY环境变量与DefaultAzureCredential。

Azure Document Intelligence

使用 Microsoft Document Intelligence 进行转换（CLI）：

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

端点也可写入环境变量，之后只需-d：

export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>" markitdown path-to-file.pdf -o document.md -d

Python API：

from markitdown import MarkItDown md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>") result = md.convert("test.pdf") print(result.markdown)

从 DocumentIntelligenceConverter 源码 可以看到实现要点：

• 构造参数支持endpoint、api_version、credential、file_types（枚举见 DocumentIntelligenceFileType，覆盖 docx/pptx/xlsx/html/pdf/jpeg/png/bmp/tiff）；accepts()依据扩展名与 MIME 前缀判断。
• 转换调用begin_analyze_document(model_id="prebuilt-layout", ...)，输出内容格式固定为markdown（源码中因 SDK 枚举导入 bug 暂用字符串常量替代）。
• 针对 PDF/图片等可 OCR 类型启用FORMULAS（公式提取）、OCR_HIGH_RESOLUTION（高分辨率 OCR）、STYLE_FONT（字体样式提取）三个分析特性；office 类文件（docx/pptx/xlsx/html）不支持 OCR 特性，返回空列表。
• 最后会剥离 Doc Intelligence 生成的<!--...-->注释，再返回 Markdown。

认证与 CU 一致：未提供credential时优先读AZURE_API_KEY，否则回退DefaultAzureCredential。

Docker 使用

仓库根目录提供 Dockerfile，可构建镜像并运行：

docker build -t markitdown:latest . docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

安全注意事项

MarkItDown 以当前进程的权限执行 I/O，与open()或requests.get()类似，会访问进程本身能访问的资源。因此：

1. 净化输入：不要把不可信输入直接交给 MarkItDown。在托管或服务端场景中，如果输入的任一部分可能受不可信用户或系统控制，必须先验证和限制——包括限制文件路径、限定 URI scheme 与网络目标、阻断对私有地址、loopback、link-local 或云元数据服务地址的访问。
2. 只调用你需要的转换方法：优先使用最窄的转换 API。convert()是有意宽松的入口，能处理本地文件、远程 URI 和字节流；若只需读本地文件，调用convert_local()；若需更多控制 URI 抓取，自行requests.get()后把响应对象传给convert_response()；需要最大控制时，自行打开输入流并调用convert_stream()。

详细说明参见 根目录 README 的安全章节。

运行测试与参与开发

若想验证实现或参与贡献，可进入包目录并使用hatch运行测试（详见 README）：

cd packages/markitdown pip install hatch hatch shell hatch test

提交 PR 前运行pre-commit run --all-files。仓库内还提供了大量针对各转换器的测试用例（如 test_cli_vectors.py、test_docx_math.py、test_pdf_tables.py 等），可作为理解各格式转换行为的参考。

小结

MarkItDown 以"转换为 Markdown 供 LLM 与文本分析消费"为设计目标，提供了覆盖绝大多数常见办公与媒体格式的内置转换器、按优先级调度的转换器注册机制、可插拔的第三方插件体系，以及可选的 Azure Document Intelligence 与 Content Understanding 云端高保真方案。实际使用时，按格式安装对应可选依赖、按输入源选择最窄的转换方法（convert_local/convert_stream/convert_uri/convert_response）、在不可信环境严格控制输入，即可搭建一条稳健、可扩展的文档转 Markdown 管线。

• 人工智能
• AI 应用
• MCP 服务