用途
MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，主要面向大语言模型（LLM）和相关文本分析管道。它旨在保留重要的文档结构（标题、列表、表格、链接等），使输出便于文本分析工具消费，而非追求面向人类阅读的高保真文档转换。
主要能力
MarkItDown 支持从以下格式转换：
- 图片（EXIF 元数据与 OCR）
- 音频（EXIF 元数据与语音转写）
- 文本格式（CSV、JSON、XML）
- ZIP 文件（遍历其内容）
- PDF、Word、Excel、PowerPoint、Outlook 邮件等办公文档
- YouTube 视频转写（通过可选依赖）
其输出采用 Markdown 格式，接近纯文本，标记极少，同时能表达文档结构。主流 LLM（如 OpenAI GPT-4o）原生支持 Markdown，且 Markdown 标记具有较高的 token 效率。
使用方式
MarkItDown 需要 Python 3.10 至 3.14。推荐使用虚拟环境以避免依赖冲突。
安装：
pip install 'markitdown[all]'
或从源码安装。
命令行使用：
markitdown path-to-file.pdf > document.md
或使用 -o 指定输出文件：
markitdown path-to-file.pdf -o document.md
也可通过管道输入内容。
Python API 基本用法：
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)
如需使用大语言模型生成图片描述（目前仅支持 pptx 和图片文件），可提供 llm_client 和 llm_model：
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)
max_retries 控制 OpenAI 客户端的自动重试次数（默认 2）；设为 5 时最多尝试六次并带退避。
可选依赖
可用 [all] 安装全部可选依赖，也可按需单独安装：
[all]：安装所有可选依赖[pptx]：PowerPoint 文件依赖[docx]：Word 文件依赖[xlsx]：Excel 文件依赖[xls]：旧版 Excel 文件依赖[pdf]：PDF 文件依赖[outlook]：Outlook 邮件依赖[az-doc-intel]：Azure Document Intelligence 依赖[az-content-understanding]：Azure Content Understanding 依赖[audio-transcription]：wav 和 mp3 音频转写依赖[youtube-transcription]：获取 YouTube 视频转写依赖
例如 pip install 'markitdown[pdf, docx, pptx]' 将仅安装 PDF、DOCX 和 PPTX 的依赖。
插件
MarkItDown 支持第三方插件，默认禁用。列出已安装插件：
markitdown --list-plugins
启用插件：
markitdown --use-plugins path-to-file.pdf
可在 GitHub 搜索标签 #markitdown-plugin 查找可用插件。开发插件可参考 packages/markitdown-sample-plugin。
markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加 OCR 支持，使用 LLM Vision 从嵌入图片中提取文本，采用与 MarkItDown 图片描述相同的 llm_client / llm_model 模式，无需新增 ML 库或二进制依赖。需传入与图片描述相同的 llm_client 和 llm_model；若未提供 llm_client，插件仍会加载，但 OCR 会被静默跳过，转而使用标准内置转换器。详见 packages/markitdown-ocr/README.md。
Azure Content Understanding
提供更高质量的转换，支持结构化字段提取（YAML front matter）、多模态（文档、图片、音频、视频）以及可配置分析器。 安装：
pip install 'markitdown[az-content-understanding]'
适用场景包括：音频与视频文件（内置转换器无视频支持，音频仅有基础转写，CU 是视频的唯一选项，也是更高质量的云端音频选项）；结构化字段提取（预置或自定义分析器提取领域特定字段，如发票金额、收据日期、合同条款，序列化为 YAML front matter）；更高质量的文档提取（针对扫描 PDF、复杂表格和多页文档的云端布局分析与 OCR）；所有模态的统一 API（一个 cu_endpoint 处理文档、图片、音频和视频，自动路由分析器）。
端点也可在环境变量中设置一次，调用方只需 --use-cu。使用自定义分析器（用于领域特定字段提取）时，设置 cu_analyzer_id 后，转换器会根据分析器的模态自动限定兼容文件类型；不兼容类型（如用文档分析器处理音频文件）自动路由到默认预置分析器。
费用提示：对 CU 路由格式的每次 convert() 调用都是一次计费的 Azure API 调用。可使用 cu_file_types 限制哪些格式路由到 CU。更多信息见 Azure Content Understanding 文档。
Azure Document Intelligence
使用 Microsoft Document Intelligence 进行转换。端点也可在环境变量中设置一次，调用方只需 -d。更多设置信息见 Azure Document Intelligence 资源文档。Python 中使用方法：
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)
适用场景
MarkItDown 适合将各类文档转换为 Markdown，以供 LLM 消费或进行文本分析。其输出通常可读且对人类友好，但并非面向人类消费的高保真转换。若需要 web 服务、API 或图形界面，官方建议作为依赖 PyPI 上 markitdown 的独立包或项目来维护。
限制
- 需要 Python 3.10 至 3.14。
- 内置转换器无视频支持，音频仅支持基础转写。
- 输出主要为文本分析工具设计，可能不是高保真文档转换的最佳选择。
- 对 CU 路由格式的每次转换都会产生 Azure API 计费。
- 插件默认禁用。
安全考虑
MarkItDown 以当前进程的权限执行 I/O。与 open() 或 requests.get() 类似，它会访问进程本身可访问的资源。在不可信环境中需对输入进行净化，并调用最窄的 convert_* 函数（如 convert_stream() 或 convert_local()）。不要将不可信输入直接传给 MarkItDown；若输入的任何部分可能由不可信用户或系统控制（如托管或服务端应用），调用前必须验证和限制。根据环境，这可能包括限制文件路径、限制 URI 方案和网络目标、阻止访问私有、环回、链路本地或元数据服务地址。优先使用最窄的转换 API：convert() 方法有意宽松，可处理本地文件、远程 URI 和字节流；若应用只需读取本地文件，请调用 convert_local()；若需更多 URI 获取控制，可自行调用 requests.get() 并将响应对象传给 convert_response()；最大控制可打开输入流并调用 convert_stream()。详见文档中的安全考虑部分。
