microsoft--markitdown/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

MarkItDown

Important

MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 类似，它会访问进程自身能够访问的资源。在不受信任的环境中请对输入进行清理，并调用你的用例所需的最精简的 convert_* 函数（例如 convert_stream() 或 convert_local()）。更多信息请参阅文档的安全注意事项部分。

MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，以便与 LLM（大语言模型）及相关文本分析流水线配合使用。在这方面，它与 textract, 最为相似，但更侧重于将重要的文档结构和内容保留为 Markdown（包括：标题、列表、表格、链接等）。虽然输出结果通常具有合理的可呈现性且易于阅读，但它主要是供文本分析工具使用的——对于面向人类阅读的高保真文档转换场景，可能并非最佳选择。

MarkItDown 目前支持从以下格式转换：

• PDF
• PowerPoint
• Word
• Excel
• 图像（EXIF 元数据和 OCR）
• 音频（EXIF 元数据和语音转录）
• HTML
• 基于文本的格式（CSV、JSON、XML）
• ZIP 文件（遍历内容）
• YouTube URL
• EPub
• ……以及更多！

为什么选择 Markdown？

Markdown 极其接近纯文本，标记和格式极少，但仍能提供一种表示重要文档结构的方式。主流的 LLM，例如 OpenAI 的 GPT-4o，本身就"说" Markdown，并且经常在未经提示的情况下将 Markdown 融入其响应中。这表明它们在海量的 Markdown 格式文本上进行了训练，并对其理解深刻。作为附带好处，Markdown 惯例在 token 效率方面也非常高。

前置条件

MarkItDown 需要 Python 3.10 或更高版本。建议使用虚拟环境以避免依赖冲突。

使用标准 Python 安装，你可以通过以下命令创建并激活虚拟环境：

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

如果使用 uv，可以这样创建虚拟环境：

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment

如果你使用 Anaconda，可以这样创建虚拟环境：

conda create -n markitdown python=3.12
conda activate markitdown

安装

要安装 MarkItDown，使用 pip：pip install 'markitdown[all]'。或者，你也可以从源码安装：

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

使用方法

命令行

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

或使用 -o 来指定输出文件：

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

你也可以通过管道传入内容：

cat path-to-file.pdf | markitdown

可选依赖

MarkItDown 提供可选依赖以激活各种文件格式的支持。在本文档前面部分，我们通过 [all] 选项安装了所有可选依赖。不过，你也可以单独安装它们以获得更精细的控制。例如：

pip install 'markitdown[pdf, docx, pptx]'

将仅安装 PDF、DOCX 和 PPTX 文件所需的依赖。

目前，有以下可选依赖可用：

• [all] 安装所有可选依赖
• [pptx] 安装 PowerPoint 文件所需的依赖
• [docx] 安装 Word 文件所需的依赖
• [xlsx] 安装 Excel 文件所需的依赖
• [xls] 安装旧版 Excel 文件所需的依赖
• [pdf] 安装 PDF 文件所需的依赖
• [outlook] 安装 Outlook 邮件所需的依赖
• [az-doc-intel] 安装 Azure 文档智能所需的依赖
• [az-content-understanding] 安装 Azure 内容理解所需的依赖
• [audio-transcription] 安装 wav 和 mp3 文件音频转录所需的依赖
• [youtube-transcription] 安装获取 YouTube 视频转录所需的依赖

插件

MarkItDown 还支持第三方插件。插件默认处于禁用状态。要列出已安装的插件：

markitdown --list-plugins

要启用插件，使用：

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

要查找可用的插件，请在 GitHub 上搜索标签 #markitdown-plugin。要开发插件，请参阅 packages/markitdown-sample-plugin。

markitdown-ocr 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器增加了 OCR 支持，使用 LLM Vision 从嵌入图像中提取文本——采用与 MarkItDown 已有的图像描述功能相同的 llm_client / llm_model 模式。无需新的机器学习库或二进制依赖。

安装：

pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client

使用方法：

传入与你用于图像描述相同的 llm_client 和 llm_model：

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.text_content)

如果未提供 llm_client，插件仍会加载，但 OCR 会被静默跳过，转而使用标准的内置转换器。

详细文档请参阅 packages/markitdown-ocr/README.md。

Azure 内容理解

Azure 内容理解 提供更高质量的转换，支持结构化字段提取（YAML 前置元数据）、多模态支持（文档、图像、音频、视频）以及可配置的分析器。

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

何时使用内容理解

当你需要超越内置转换器或文档智能集成所提供的功能时，内容理解是理想之选：

• 音频和视频文件 — CU（内容理解）是视频的唯一选项，也是音频的更高质量云端选项。内置转换器不支持视频，且仅提供基础的音频转录。
• 结构化字段提取 — 预置 或自定义 分析器可提取领域特定字段（发票金额、收据日期、合同条款），并以 YAML 前置元数据的形式序列化输出。内置转换器和文档智能集成均不公开字段信息。
• 更高质量的文档提取 — 基于云端的布局分析和 OCR，适用于扫描版 PDF、复杂表格和多页文档。
• 所有模态的统一 API — 一个 cu_endpoint 即可处理文档、图像、音频和视频，并自动进行分析器路由。

功能	内置转换器	Azure 文档智能	Azure 内容理解
文档转换	离线、按格式提取	云端布局提取	云端多模态提取
结构化字段	不可用	此集成不公开	来自分析器字段的 YAML 前置元数据
自定义分析器	不可用	此集成中不可配置	支持，使用 cu_analyzer_id
音频和视频	基础音频，不支持视频	不支持	音频和视频分析器
成本	仅本地计算	Azure API 调用计费	Azure API 调用计费

CLI:

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

Python API:

from markitdown import MarkItDown

# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → 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)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

当设置 cu_analyzer_id 时，转换器会根据分析器的模态自动将其限定为兼容的文件类型。不兼容的类型（例如，使用文档分析器处理音频文件）会自动路由到默认的预构建分析器。

费用说明： 每次对 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],  # only PDFs use CU
)

更多关于 Azure Content Understanding 的信息，请参见此处.)。

Azure Document Intelligence

使用 Microsoft Document Intelligence 进行转换：

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

更多关于如何设置 Azure Document Intelligence 资源的信息，请参见此处)。

Python API

Python 基本用法：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

Python 中的 Document Intelligence 转换：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

如需使用大语言模型生成图片描述（目前仅支持 pptx 和图片文件），请提供 llm_client 和 llm_model：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Docker

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

贡献

本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权且确实授予我们使用您贡献的权利。详情请访问 https://cla.opensource.microsoft.com.。

当您提交拉取请求（Pull Request）时，CLA 机器人会自动判断您是否需要提供 CLA，并适当装饰 PR（例如状态检查、评论）。只需按照机器人提供的说明操作即可。您只需在所有使用我们 CLA 的仓库中执行一次。

本项目已采用 Microsoft 开放源代码行为准则.)。更多信息请参阅行为准则常见问题解答)，或通过 opencode@microsoft.com 联系以提出其他问题或意见。

如何贡献

您可以通过查看 Issue 或帮助审核 PR 来提供帮助。任何 Issue 或 PR 都欢迎，但我们也标记了一些"开放供贡献"和"开放供审核"的内容，以方便社区贡献。当然，这些都只是建议，欢迎您以任何方式贡献。

	全部	特别需要社区帮助
Issues	全部 Issues)	开放供贡献的 Issues)
PRs	全部 PRs)	开放供审核的 PRs)

运行测试和检查

• 进入 MarkItDown 包目录：

  cd packages/markitdown
  

• 在您的环境中安装 hatch 并运行测试：

  pip install hatch  # 安装 hatch 的其他方式：https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  

  （备选）使用已安装所有依赖项的 Devcontainer：

  # 在 Devcontainer 中重新打开项目，然后运行：
  hatch test
  

• 在提交 PR 前运行 pre-commit 检查：pre-commit run --all-files

安全注意事项

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

对输入进行消毒： 不要将不受信任的输入直接传递给 MarkItDown。如果输入的任何部分可能受不受信任的用户或系统控制（例如在托管或服务端应用中），则必须在调用 MarkItDown 之前对其进行验证和限制。根据您的环境，这可能包括限制文件路径、限制 URI 方案和网络目标，以及阻止访问私有地址、环回地址、链路本地地址或元数据服务地址。

仅调用您需要的转换方法： 优先使用最适合您用例的最小转换 API。MarkItDown 的 convert() 方法设计上较为宽松，可以处理本地文件、远程 URI 和字节流。如果您的应用程序只需要读取本地文件，请改用 convert_local()。如果您需要对 URI 获取进行更多控制，请自行调用 requests.get()，并将响应对象传递给 convert_response()。如需最大程度的控制，请打开要转换的输入流，然后调用 convert_stream()。

贡献第三方插件

您还可以通过创建和分享第三方插件来贡献。更多详情请参见 packages/markitdown-sample-plugin。

商标

本项目可能包含项目、产品或服务的商标或徽标。对 Microsoft 商标或徽标的授权使用必须遵守并遵循 Microsoft 商标与品牌指南.)。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何第三方商标或徽标的使用均须遵守第三方的政策。