简介

MarkItDown 是一个由 Microsoft 开发的 Python 包和命令行工具，用于将各种文件格式转换为 Markdown 格式。其设计目标是便于文档索引和文本分析等场景使用。 资料来源：README.md

MarkItDown 的核心价值主张在于 Markdown 与 LLM 的天然兼容性。主流的大语言模型（如 OpenAI 的 GPT-4o）本身就能很好地理解和生成 Markdown，这种设计选择使得转换后的内容可以被 AI 模型高效处理。 资料来源：README.md

核心功能

MarkItDown 支持多种文件格式的转换，具体包括：

资料来源：README.md

转换器架构

MarkItDown 采用插件化的转换器架构，每个文件格式由对应的转换器（Converter）处理。转换器通过 DocumentConverter 基类定义统一的接口：

• accepts()：判断转换器是否接受给定文件
• convert()：执行实际的格式转换

资料来源：packages/markitdown-sample-plugin/README.md

插件系统

从 v0.1.0 开始，MarkItDown 引入了插件架构，允许第三方开发者扩展支持的格式。插件通过 markitdown.plugin 入口点注册，核心函数为 register_converters()。 资料来源：v0.1.0 发布说明

插件接口版本定义为 __plugin_interface_version__ = 1，当前仅支持版本 1。 资料来源：packages/markitdown-sample-plugin/README.md

安装方式

标准安装

pip install markitdown[all]

[all] 标记安装所有可选依赖，包括完整功能集。 资料来源：README.md

从源码安装

git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e packages/markitdown[all]

前置要求

MarkItDown 需要 Python 3.10 或更高版本。建议使用虚拟环境以避免依赖冲突。 资料来源：README.md

使用方式

命令行接口

MarkItDown 提供命令行工具 markitdown，支持多种调用方式：

# 基本用法
markitdown path-to-file.pdf > document.md

# 从 stdin 读取
cat example.pdf | markitdown

# 指定输出文件
markitdown example.pdf -o example.md

# 指定文件扩展名提示（从 stdin 读取时）
markitdown -x .pdf < example.pdf

资料来源：packages/markitdown/src/markitdown/__main__.py:23-52

Python API

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)

默认情况下插件处于禁用状态。如需启用插件：

md = MarkItDown(enable_plugins=True)

资料来源：README.md

高级功能

LLM 图像描述

MarkItDown 支持使用大语言模型为图像生成描述，适用于 PowerPoint 和图片文件：

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)

资料来源：README.md

Azure Document Intelligence

对于 PDF 文档，可以使用 Azure Document Intelligence 服务获得更高质量的转换：

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

Python API 用法：

from markitdown import MarkItDown

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

资料来源：README.md

Azure Content Understanding

Content Understanding 提供更高质量的转换，支持结构化字段提取（YAML front matter）和多模态处理（文档、图片、音频、视频）。 资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py:1-20

安装方式：

pip install 'markitdown[az-content-understanding]'

使用示例：

from markitdown import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # 只对 PDF 使用 CU
)
result = md.convert("document.pdf")

资料来源：README.md

OCR 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加 OCR 支持，从嵌入图像中提取文本。 资料来源：packages/markitdown-ocr/README.md

安装：

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

使用：

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

OCR 插件工作原理：

1. MarkItDown 通过 markitdown.plugin 入口点发现插件
2. 调用 register_converters()，转发所有参数包括 llm_client 和 llm_model
3. 插件创建 LLMVisionOCRService 并注册四个 OCR 增强转换器（优先级 -1.0，优先于内置转换器的 0.0）

资料来源：packages/markitdown-ocr/README.md

系统架构

转换流程

graph TD
    A[输入文件/URL] --> B[MarkItDown 核心]
    B --> C{文件类型判断}
    C -->|PDF| D[PDFConverter]
    C -->|DOCX| E[DOCXConverter]
    C -->|XLSX| F[XLSXConverter]
    C -->|PPTX| G[PPTXConverter]
    C -->|HTML| H[HTMLConverter]
    C -->|图片| I[ImageConverter]
    C -->|音频| J[AudioConverter]
    C -->|ZIP| K[ZIPConverter]
    C -->|YouTube| L[YouTubeConverter]
    C -->|其他| M[文本转换器]
    
    D --> N[文本提取]
    E --> O[DOCX→HTML→Markdown]
    F --> P[表格处理]
    G --> Q[幻灯片处理]
    H --> R[HTML净化]
    I --> S[EXIF + OCR]
    J --> T[音频处理]
    K --> U[递归遍历]
    L --> V[字幕提取]
    M --> W[纯文本]
    
    N --> X[Markdown 输出]
    O --> X
    P --> X
    Q --> X
    R --> X
    S --> X
    T --> X
    U --> X
    V --> X
    W --> X

插件加载机制

graph TD
    A[MarkItDown 初始化] --> B{enable_plugins=True?}
    B -->|否| C[仅加载内置转换器]
    B -->|是| D[扫描 markitdown.plugin 入口点]
    D --> E[调用 register_converters]
    E --> F[插件转换器注册到转换器列表]
    C --> G[按优先级排序转换器]
    F --> G
    G --> H[文件转换时按序匹配]

CLI 参数说明

资料来源：packages/markitdown/src/markitdown/__main__.py:54-130

依赖分组

MarkItDown 将依赖组织为功能组，用户可以只安装需要的转换器： 资料来源：v0.1.0 发布说明

已知限制与问题

社区反馈的问题

资料来源：Issue #293、Issue #296、Issue #23、Issue #1408、Issue #1894、Issue #1685

安全注意事项

[!IMPORTANT]

MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 一样，它会访问进程本身可以访问的资源。在不受信任的环境中，请对输入进行清理，并调用最窄范围的转换函数（如 convert_stream() 或 convert_local()）。 资料来源：README.md

版本历史

资料来源：发布页面

Docker 支持

MarkItDown 支持通过 Docker 运行：

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

资料来源：README.md

参见

• 插件开发指南 - 如何开发 MarkItDown 插件
• OCR 插件文档 - LLM Vision OCR 插件详细文档
• Azure Document Intelligence 集成 - 使用 Azure AI 服务进行文档转换
• 版本发布页面 - 完整版本历史和变更日志

概述

MarkItDown 支持多种文件格式的转换，涵盖文档、图片、音频、视频以及基于文本的格式。转换器采用插件化架构设计，内置转换器处理核心格式，第三方插件可扩展更多格式支持。

资料来源：packages/markitdown/README.md

支持格式总览

核心支持格式

已知限制

转换器架构

转换器注册机制

MarkItDown 使用动态转换器注册系统，每个文件格式由对应的 DocumentConverter 子类处理。

graph TD
    A[文件输入] --> B[StreamInfo 检测]
    B --> C{文件类型判断}
    C -->|PDF| D[PdfConverter]
    C -->|DOCX| E[DocxConverter]
    C -->|XLSX| F[XlsxConverter]
    C -->|PPTX| G[PptxConverter]
    C -->|图片| H[ImageConverter]
    C -->|HTML| I[HtmlConverter]
    C -->|ZIP| J[ZipConverter]
    C -->|其他| K[通用转换器]
    
    D --> L[Markdown 输出]
    E --> L
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    
    style A fill:#e1f5fe
    style L fill:#c8e6c9

资料来源：packages/markitdown/src/markitdown/converters/__init__.py

DocumentConverter 基类

所有转换器继承自 DocumentConverter 基类，需要实现以下核心方法：

资料来源：packages/markitdown/src/markitdown/__init__.py

文档格式详解

PDF 转换

PDF 转换器使用 pdfminer.six 库提取文本内容。

支持的功能：

• 文本段落提取
• 标题检测（基于字体大小）
• 表格提取（对齐 Markdown 支持）
• 编号列表识别

限制：

• PDF 是可视化格式，结构信息有限
• 表格转换可能不完美（社区反馈 #293）
• 扫描的 PDF 需要 OCR 支持

资料来源：packages/markitdown/src/markitdown/converters/_pdf_converter.py

使用 Azure Document Intelligence 提升 PDF 质量：

from markitdown import MarkItDown

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

Word 文档 (DOCX)

Word 转换器使用 mammoth 库处理 DOCX 文件。

支持的功能：

• 段落和标题提取
• 列表（有序和无序）
• 表格转换
• 图片提取（带描述）
• 数学公式渲染（从 v0.1.2 支持）
• 链接处理

已知问题：

• 无效的 Office Open XML 文件会返回成功状态，但 text_content 包含错误消息
• 仅支持 .docx 格式，不支持旧版 .doc 格式

资料来源：packages/markitdown/src/markitdown/converters/_docx_converter.py

Excel 电子表格 (XLSX)

Excel 转换器将工作表数据转换为 Markdown 表格格式。

输出示例：

## Sheet1
| Column1 | Column2 | Column3 |
|---------|---------|---------|
| data1   | data2   | data3   |
| data4   | data5   | data6   |

特性：

• 多工作表处理
• 保持原始列结构
• 空单元格处理

资料来源：packages/markitdown/src/markitdown/converters/_xlsx_converter.py

PowerPoint 演示文稿 (PPTX)

PowerPoint 转换器提取幻灯片内容和备注。

输出结构：

• 每张幻灯片作为独立章节
• 提取文本内容和形状
• 图片和备注信息

资料来源：packages/markitdown/src/markitdown/converters/_pptx_converter.py

图片与媒体格式

图片转换

图片转换器支持 EXIF 元数据提取和可选的 LLM 描述生成。

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="描述这张图片的内容"
)
result = md.convert("photo.jpg")

支持的图片格式：

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• BMP (.bmp)
• WebP (.webp)

音频转换

音频文件支持 EXIF 元数据提取和语音转录。

依赖要求：

• Linux 系统需要安装 ffmpeg 或 avconv
• 缺少时会产生 RuntimeWarning

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

⚠️ 社区反馈：Linux 环境下缺少 ffmpeg 会触发 RuntimeWarning，影响用户体验。相关问题：#1685

基于文本的格式

HTML 与 Wikipedia

HTML 转换器使用 BeautifulSoup 解析网页内容。

特殊处理：

• Wikipedia 页面使用专门的 WikipediaConverter
• 提取主文档内容，排除侧边栏和导航

graph LR
    A[HTML 输入] --> B{是否为 Wikipedia?}
    B -->|是| C[WikipediaConverter]
    B -->|否| D[HtmlConverter]
    C --> E[提取主内容]
    D --> F[完整 HTML 处理]
    E --> G[Markdown 输出]
    F --> G

资料来源：packages/markitdown/src/markitdown/converters/_wikipedia_converter.py

CSV 转换

CSV 文件直接转换为 Markdown 表格格式。

md = MarkItDown()
result = md.convert("data.csv")
# 输出 Markdown 表格

JSON 和 XML

结构化数据格式转换为易读的文本表示。

RSS 和 Atom

订阅源格式转换为 Markdown，支持 .rss、.atom 和 .xml 扩展名。

资料来源：packages/markitdown/src/markitdown/converters/_rss_converter.py

ZIP 文件处理

ZIP 转换器递归处理压缩包内的所有文件。

处理流程：

graph TD
    A[ZIP 文件] --> B[提取到临时目录]
    B --> C{遍历文件}
    C -->|文件| D[根据扩展名选择转换器]
    C -->|完成| E[合并结果]
    D --> F[PDF/DOCX/图片/...]
    F --> C
    E --> G[Markdown 输出]
    
    style A fill:#fff3e0
    style G fill:#c8e6c9

输出格式：

Content from the zip file `example.zip`:

## File: docs/readme.txt
[文件内容]

## File: images/example.jpg
ImageSize: 1920x1080
DateTimeOriginal: 2024-02-15 14:30:00

## File: data/report.xlsx
[Excel 内容]

资料来源：packages/markitdown/src/markitdown/converters/_zip_converter.py

Azure 集成

Azure Document Intelligence

使用 Azure AI 服务提升文档转换质量：

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

优势：

• 更高质量的布局分析
• 更准确的表格提取
• OCR 支持

Azure Content Understanding

从 v0.1.5 开始支持，提供更高级的多模态提取：

from markitdown import MarkItDown, ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],
)

支持的文件类型：

• PDF 文档
• 图片
• 音频文件
• 视频文件

OCR 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 添加 OCR 功能。

安装：

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

使用：

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")

命令行使用：

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

⚠️ 社区反馈：CLI 参数 --llm-client 和 --llm-model 在某些版本中可能未被识别，请确保使用最新版。相关问题：#1897

资料来源：packages/markitdown-ocr/README.md

插件扩展

插件架构

MarkItDown 支持通过插件扩展支持的格式。插件使用 markitdown.plugin 入口点注册。

开发示例：

from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo

class RtfConverter(DocumentConverter):
    def __init__(self, priority=DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT):
        super().__init__(priority=priority)

    def accepts(self, file_stream, stream_info, **kwargs) -> bool:
        return stream_info.extension == ".rtf"

    def convert(self, file_stream, stream_info, **kwargs) -> DocumentConverterResult:
        # 实现转换逻辑
        raise NotImplementedError()

__plugin_interface_version__ = 1

def register_converters(markitdown: MarkItDown, **kwargs):
    markitdown.register_converter(RtfConverter())

pyproject.toml 配置：

[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"

资料来源：packages/markitdown-sample-plugin/README.md

列出已安装插件

markitdown --list-plugins

输出示例：

Installed MarkItDown 3rd-party Plugins:

  * markitdown-ocr   (package: markitdown_ocr)

常见问题

为什么 PDF 转换质量不如预期？

PDF 是可视化格式，许多结构信息（如语义标题、表格边界）需要通过启发式方法推断。从 v0.1.5 开始，表格提取有所改进，使用对齐 Markdown 格式。相关讨论：#293, #296

如何转换 .doc 文件？

MarkItDown 不支持旧版 .doc 格式，仅支持基于 Office Open XML 的 .docx 格式。建议将 .doc 文件在 Microsoft Word 中另存为 .docx 后转换。相关讨论：#23

Jupyter Notebook 转换失败怎么办？

如果 Jupyter Notebook 文件包含非 ASCII 字符，转换可能因 UnicodeDecodeError 失败。这是已知的 bug，参见 #1894。

Office Open XML 文件显示成功但内容为错误消息？

对于无效的 DOCX/XLSX/PPTX 文件，MarkItDown 可能返回成功状态但 text_content 包含 "This is not a valid Office Open XML file." 消息。相关讨论：#1408

安装选项

MarkItDown 提供模块化安装，可按需选择功能：

# 仅核心功能
pip install markitdown

# 包含所有功能
pip install markitdown[all]

# 按功能组安装
pip install markitdown[docx]      # Word 支持
pip install markitdown[xlsx]      # Excel 支持
pip install markitdown[pptx]      # PowerPoint 支持
pip install markitdown[pdf]        # PDF 支持
pip install markitdown[image]      # 图片支持
pip install markitdown[audio]      # 音频支持
pip install markitdown[az-doc-intel]  # Azure Document Intelligence
pip install markitdown[az-content-understanding]  # Azure Content Understanding

相关链接

• 项目主页
• OCR 插件文档
• 插件开发指南
• Azure Document Intelligence 配置
• Azure Content Understanding

概述

MarkItDown 是一个轻量级的 Python 工具库，用于将各种文件格式转换为 Markdown 格式，专为 LLM 和相关文本分析管道设计。该项目的核心架构采用插件式转换器模式，允许通过统一的接口扩展支持的文件格式。资料来源：README.md:1-20

MarkItDown 的设计理念强调：

• 统一的转换接口：所有转换器都继承自 DocumentConverter 基类
• 插件可扩展性：支持第三方开发者创建自定义转换器
• 灵活的依赖管理：依赖项按功能分组，支持选择性安装
• 多后端支持：内置转换器、云服务集成（Azure Document Intelligence、Azure Content Understanding）

核心组件

MarkItDown 的核心架构由以下主要组件构成：

MarkItDown 主类

MarkItDown 类是整个系统的入口点，负责：

• 管理所有内置和插件转换器的注册
• 路由文件到合适的转换器
• 协调 LLM 客户端配置
• 处理 URI 转换（本地文件、URL、数据 URI）

from markitdown import MarkItDown

md = MarkItDown(
    enable_plugins=True,        # 启用第三方插件
    llm_client=OpenAI(),        # LLM 客户端用于图像描述
    llm_model="gpt-4o",        # LLM 模型名称
    docintel_endpoint="...",    # Azure Document Intelligence 端点
    cu_endpoint="..."          # Azure Content Understanding 端点
)

资料来源：packages/markitdown/src/markitdown/_markitdown.py

DocumentConverter 基类

所有转换器必须继承 DocumentConverter 基类，该类定义了转换器的基本接口：

转换器优先级定义：

• PRIORITY_MAXIMUM = 1000：最高优先级
• PRIORITY_SPECIFIC_FILE_FORMAT = 500：特定文件格式
• PRIORITY_DEFAULT = 0：默认优先级
• PRIORITY_MINIMUM = -1000：最低优先级

资料来源：packages/markitdown/src/markitdown/_base_converter.py

StreamInfo 数据模型

StreamInfo 存储文件流元信息，用于转换器的 accepts() 方法判断文件类型：

@dataclass
class StreamInfo:
    url: Optional[str] = None           # 源 URL
    extension: Optional[str] = None     # 文件扩展名
    mimetype: Optional[str] = None       # MIME 类型
    charset: Optional[str] = None        # 字符编码

资料来源：packages/markitdown/src/markitdown/_stream_info.py

转换器体系

MarkItDown 内置了针对多种文件格式的转换器，采用分层架构处理不同类型的文档。

内置转换器

资料来源：README.md:40-55

内置转换器的注册流程

graph TD
    A[MarkItDown.__init__] --> B[注册内置转换器]
    B --> C[加载 _converters 目录下的所有转换器]
    C --> D{enable_plugins?}
    D -->|是| E[通过 entry_points 加载第三方插件]
    D -->|否| F[跳过插件加载]
    E --> G[调用 register_converters 钩子]
    G --> H[注册插件提供的转换器]
    F --> I[返回 MarkItDown 实例]
    H --> I

插件机制

MarkItDown 的插件系统基于 Python 的 entry_points 机制实现，允许第三方开发者扩展支持的格式。

插件接口版本

当前支持的插件接口版本为 __plugin_interface_version__ = 1，定义在插件包的根级别。

插件开发规范

开发 MarkItDown 插件需要：

1. 创建 DocumentConverter 子类
2. 实现 register_converters() 函数
3. 配置 pyproject.toml entry point

# 示例：RTF 转换器插件
__plugin_interface_version__ = 1

def register_converters(markitdown: MarkItDown, **kwargs):
    markitdown.register_converter(RtfConverter())

Entry point 配置：

[project.entry-points."markitdown.plugin"]
my_plugin = "my_plugin_package"

资料来源：packages/markitdown-sample-plugin/README.md

markitdown-ocr 插件示例

markitdown-ocr 是官方提供的 OCR 增强插件，展示了完整的插件开发模式：

graph LR
    A[PDF/DOCX/PPTX/XLSX] --> B[markitdown-ocr 插件]
    B --> C{llm_client 提供?}
    C -->|是| D[使用 LLM Vision OCR]
    C -->|否| E[回退到内置转换器]
    D --> F[提取嵌入图像文本]
    E --> G[标准文本提取]

该插件的工作流程：

1. MarkItDown 发现插件通过 markitdown.plugin entry point
2. 调用 register_converters() 并传递 llm_client 和 llm_model
3. 创建 LLMVisionOCRService 执行 OCR
4. 使用优先级覆盖内置转换器

资料来源：packages/markitdown-ocr/README.md

工作流程

转换请求处理流程

sequenceDiagram
    participant 用户
    participant MarkItDown
    participant ConverterRegistry
    participant Converter
    
    用户->>MarkItDown: convert(uri)
    MarkItDown->>MarkItDown: convert_uri(uri)
    MarkItDown->>MarkItDown: _get_file_info(uri)
    MarkItDown->>ConverterRegistry: 遍历注册转换器
    ConverterRegistry->>Converter: accepts(stream_info)
    Converter-->>ConverterRegistry: bool
    ConverterRegistry->>MarkItDown: 返回匹配的转换器
    MarkItDown->>Converter: convert(stream, stream_info, **kwargs)
    Converter-->>MarkItDown: DocumentConverterResult
    MarkItDown-->>用户: 返回结果

文件类型检测顺序

转换器的 accepts() 方法按注册顺序被调用，第一个返回 True 的转换器将被使用。检测逻辑基于：

1. 文件扩展名：stream_info.extension
2. MIME 类型：stream_info.mimetype
3. 文件内容检测：部分转换器会读取文件流进行内容分析
4. URL 模式：如 WikipediaConverter 依赖 URL 匹配

例如，RssConverter 的 accepts() 方法首先检查精确的 MIME 类型和扩展名，然后对 XML 文件进行深度内容检测：

def accepts(self, file_stream, stream_info, **kwargs):
    mimetype = (stream_info.mimetype or "").lower()
    extension = (stream_info.extension or "").lower()
    
    # 精确匹配
    if extension in PRECISE_FILE_EXTENSIONS:
        return True
    for prefix in PRECISE_MIME_TYPE_PREFIXES:
        if mimetype.startswith(prefix):
            return True
    
    # XML 文件需要内容检测
    if extension in CANDIDATE_FILE_EXTENSIONS:
        return self._check_xml(file_stream)

资料来源：packages/markitdown/src/markitdown/converters/_rss_converter.py

Azure 集成

MarkItDown 支持两种 Azure AI 服务集成，用于高质量文档转换。

Azure Document Intelligence

适用于 PDF 和 Office 文档的云端解析：

md = MarkItDown(docintel_endpoint="<endpoint>")
result = md.convert("document.pdf")

CLI 用法：

markitdown document.pdf -d -e "<document_intelligence_endpoint>"

Azure Content Understanding

提供更高质量的多模态提取，支持结构化字段提取（YAML front matter）：

from markitdown import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],
)

支持的格式路由：

• 文档：PDF、DOCX、PPTX、XLSX
• 图像：JPEG、PNG、GIF、BMP
• 音频：MP3、WAV、M4A
• 视频：MP4、MOV

资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py

命令行接口

MarkItDown 提供完整的 CLI 功能，入口点位于 __main__.py：

CLI 参数说明

资料来源：packages/markitdown/src/markitdown/__main__.py:30-120

CLI 初始化流程

graph TD
    A[markitdown 命令] --> B[argparse 解析参数]
    B --> C{--list-plugins?}
    C -->|是| D[列出插件并退出]
    C -->|否| E{--use-docintel?}
    E -->|是| F[创建 MarkItDown<br/>docintel_endpoint]
    E -->|否| G{--use-cu?}
    G -->|是| H[创建 MarkItDown<br/>cu_endpoint + cu_file_types]
    G -->|否| I[创建 MarkItDown<br/>enable_plugins]
    F --> J[执行转换]
    H --> J
    I --> J

安全考虑

[!IMPORTANT]

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

在不受信任的环境中使用时，建议：

• 对输入进行清理：验证文件来源和类型
• 使用最窄的转换方法：如 convert_stream() 或 convert_local()
• 限制文件访问：确保进程权限范围最小化

常见问题与已知限制

社区反馈的架构相关问题

架构限制说明

1. PDF 转换：基础 PDF 转换输出纯文本，非结构化 Markdown。对于表格、页眉页脚等结构化内容支持有限。
2. .doc 格式：仅支持 .docx，不支持旧版 .doc 格式。
3. 音频转换：依赖 ffmpeg，在 Linux 系统上可能需要额外安装。

相关文档

• 安装指南 — MarkItDown 安装与依赖管理
• 插件开发 — 第三方插件开发教程
• Azure 集成 — Azure AI 服务配置
• CLI 参考 — 命令行工具完整参考
• API 参考 — Python API 详细文档

概述

MarkItDown 的转换器系统（Converter System）是一个基于插件架构的文档转换框架，负责将各种格式的文档转换为 Markdown 格式。该系统采用优先级驱动的选择机制，允许内置转换器和第三方插件动态注册自己的文档转换器。

转换器系统的核心设计理念：

• 模块化：每种文档格式由独立的转换器类处理
• 可扩展性：通过插件机制支持第三方转换器
• 优先级机制：插件可以替换或覆盖内置转换器
• 流式处理：支持从文件流、URL、本地路径等多种来源读取文档

资料来源：packages/markitdown/src/markitdown/_base_converter.py:1-50

系统要求

Python 版本要求

MarkItDown 要求 Python 3.10 或更高版本。项目代码中使用了类型提示和现代 Python 特性，低于 3.10 的版本无法正常运行。

# 检查 Python 版本
python3 --version

操作系统兼容性

MarkItDown 支持以下操作系统：

⚠️ 注意：在 Linux 系统上使用音频功能时，如果未安装 ffmpeg 或 avconv，可能会收到 RuntimeWarning 警告。建议安装 ffmpeg 以避免此问题。资料来源：github.com/microsoft/markitdown/issues/1685

安装方法

方法一：通过 pip 安装（推荐）

#### 安装完整版本（包含所有功能）

pip install markitdown[all]

完整安装包含所有内置转换器和可选依赖项，包括：

• PDF 转换器
• PowerPoint 转换器
• Word 转换器
• Excel 转换器
• 图片转换器（包含 EXIF 元数据和 OCR）
• 音频转换器（包含语音转录）
• Azure Document Intelligence 集成
• Azure Content Understanding 集成

#### 安装基础版本

pip install markitdown

基础安装仅包含核心功能和最常用的转换器。

#### 按需安装特定功能

MarkItDown 将依赖项组织为功能组，可以选择性安装所需的转换器和功能：

资料来源：packages/markitdown/pyproject.toml

方法二：从源码安装

对于需要最新功能或希望参与开发的用户，可以从源码安装：

# 克隆仓库
git clone [email protected]:microsoft/markitdown.git
cd markitdown

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或: .venv\Scripts\activate  # Windows

# 安装为可编辑模式
pip install -e packages/markitdown[all]

如果使用 uv 工具管理虚拟环境：

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e packages/markitdown[all]

方法三：Docker 部署

MarkItDown 提供官方 Docker 镜像，支持无依赖安装：

# 构建镜像
docker build -t markitdown:latest .

# 使用 Docker 运行
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Docker 方式适合在不希望安装 Python 依赖的环境中快速部署使用。

资料来源：Dockerfile

插件系统安装

MarkItDown 支持通过插件扩展功能。插件通过 markitdown.plugin 入口点组进行注册。

官方 OCR 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加 OCR 支持，使用 LLM Vision 从嵌入式图片中提取文本。

安装步骤：

# 安装插件
pip install markitdown-ocr

# 安装 OpenAI 兼容客户端（用于 LLM 调用）
pip install openai

使用方法：

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

或者在 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.text_content)

⚠️ 已知问题：在某些情况下，CLI 参数组合可能未被正确识别。例如，运行 markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o 时可能出现"Unrecognized Arguments"错误。资料来源：github.com/microsoft/markitdown/issues/1897

自定义插件开发

MarkItDown 提供了示例插件项目 markitdown-sample-plugin，展示了如何开发自定义转换器：

1. 实现 DocumentConverter 子类
2. 导出 __plugin_interface_version__ 变量
3. 实现 register_converters() 函数
4. 在 pyproject.toml 中配置入口点

[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"

资料来源：packages/markitdown-sample-plugin/README.md

查看已安装插件

markitdown --list-plugins

此命令列出所有已安装的第三方插件，帮助用户了解可用的扩展功能。

命令行配置

常用 CLI 参数

MarkItDown CLI 提供多种参数用于控制转换行为：

资料来源：packages/markitdown/src/markitdown/__main__.py:1-100

CLI 使用示例

#### 基本转换

# 从文件转换
markitdown example.pdf > output.md

# 指定输出文件
markitdown example.xlsx -o spreadsheet.md

# 从标准输入读取
cat example.docx | markitdown > output.md

#### 使用 Azure Document Intelligence

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

#### 使用 Azure Content Understanding

markitdown document.pdf -o output.md --use-cu --cu-endpoint "<content_understanding_endpoint>"

#### 使用插件

# 列出插件
markitdown --list-plugins

# 启用插件进行转换
markitdown --use-plugins document_with_images.pdf --llm-client openai --llm-model gpt-4o

Python API 配置

基础配置

MarkItDown 的核心配置通过 MarkItDown 类的构造函数完成：

from markitdown import MarkItDown

# 基础使用
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

完整配置选项

资料来源：packages/markitdown/src/markitdown/__main__.py

使用 LLM 进行图片描述

MarkItDown 支持使用 LLM 为图片生成描述（目前支持 pptx 和图片文件）：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="可选的自定义提示词"
)
result = md.convert("example.jpg")
print(result.text_content)

使用 Azure Document Intelligence

from markitdown import MarkItDown

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

使用 Azure Content Understanding

from markitdown import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # 仅 PDF 使用 CU
)
result = md.convert("document.pdf")
print(result.text_content)

环境变量配置

MCP 服务器环境变量

当 MarkItDown 作为 MCP 服务器运行时，可以从环境变量读取配置：

export MARKITDOWN_ENABLE_PLUGINS=1
markitdown --server

虚拟环境配置

创建虚拟环境

强烈建议使用虚拟环境来安装 MarkItDown，以避免依赖冲突：

使用标准 Python：

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate  # Windows

使用 uv 工具：

uv venv --python 3.12 .venv
source .venv/bin/activate

在虚拟环境中安装

# 激活虚拟环境后
pip install markitdown[all]

# 或使用 uv
uv pip install markitdown[all]

依赖项说明

核心依赖

MarkItDown 的核心功能依赖于以下包：

可选依赖组

在 pyproject.toml 中定义的可选依赖组：

[project.optional-dependencies]
pdf = ["pdfminer.six", "pdfplumber", "pymupdf"]
office = ["mammoth", "python-pptx", "openpyxl"]
image = ["Pillow", "exif"]
audio = ["pydub", "SpeechRecognition"]
html = ["beautifulsoup4", "html5lib"]
epub = ["ebooklib"]
doc-intel = ["azure-ai-formrecognizer"]
az-cu = ["azure-ai-contentunderstanding"]
all = [
    "pdfminer.six",
    "pdfplumber",
    "pymupdf",
    "mammoth",
    "python-pptx",
    "openpyxl",
    "Pillow",
    "exif",
    "pydub",
    "SpeechRecognition",
    "beautifulsoup4",
    "html5lib",
    "ebooklib",
    "azure-ai-formrecognizer",
    "azure-ai-contentunderstanding",
]

资料来源：packages/markitdown/pyproject.toml

常见配置问题与解决方案

问题一：CLI 参数识别错误

问题描述：运行 markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o 时出现"Unrecognized Arguments"错误。

解决方案：确保使用正确的参数格式。某些参数组合可能需要通过环境变量或 Python API 设置。

资料来源：github.com/microsoft/markitdown/issues/1897

问题二：Linux 系统缺少 ffmpeg

问题描述：在 Linux 系统上运行时出现 RuntimeWarning: Couldn't find ffmpeg or avconv 警告。

解决方案：安装 ffmpeg

# Debian/Ubuntu
sudo apt-get install ffmpeg

# Fedora
sudo dnf install ffmpeg

# macOS
brew install ffmpeg

资料来源：github.com/microsoft/markitdown/issues/1685

问题三：非 ASCII 文件名处理

问题描述：处理包含非 ASCII 字符文件名的文件时可能出现 UnicodeDecodeError。

解决方案：确保 Python 运行环境使用 UTF-8 编码：

export PYTHONIOENCODING=utf-8

问题四：Azure 服务认证

问题描述：使用 Azure Document Intelligence 或 Content Understanding 时认证失败。

解决方案：可以通过多种方式配置凭据：

# 使用密钥
from azure.core.credentials import AzureKeyCredential

md = MarkItDown(
    docintel_endpoint="<endpoint>",
    docintel_key="<key>"  # 或通过 AzureKeyCredential
)

# 使用 DefaultAzureCredential（自动从环境读取）
from azure.identity import DefaultAzureCredential

安全注意事项

[!IMPORTANT]

MarkItDown 会以当前进程的权限执行 I/O 操作。就像 open() 或 requests.get() 一样，它将访问进程本身可以访问的资源。在不受信任的环境中，请务必对输入进行清理，并调用最窄的 convert_* 函数（如 convert_stream() 或 convert_local()）以降低安全风险。

安全最佳实践

1. 最小权限原则：在受控环境中运行，不要以管理员权限运行 MarkItDown
2. 输入验证：在使用前验证所有文件输入
3. 选择合适的转换方法：

• convert_stream() - 最安全，适合处理不可信输入
• convert_local() - 用于本地文件
• convert_uri() - 用于 URI 资源
• convert() - 通用方法，自动检测资源类型

升级与迁移

从旧版本升级

pip install --upgrade markitdown[all]

版本 0.1.x 重要变更

相关文档

• README 主页
• markitdown-ocr 插件文档
• 自定义插件开发指南
• Azure Document Intelligence 集成
• 支持的转换器列表

概述

MarkItDown CLI 是用户与 MarkItDown 交互的主要方式之一。通过命令行，用户可以：

• 将本地文件转换为 Markdown 格式
• 从标准输入读取内容进行转换
• 支持多种文件格式的自动识别
• 集成 Azure Document Intelligence 进行高级文档处理
• 集成 Azure Content Understanding 进行多模态内容提取
• 启用第三方插件扩展功能
• 配置 LLM 客户端用于图像描述和 OCR 功能

graph TD
    A[用户执行 markitdown 命令] --> B{是否指定文件名?}
    B -->|是| C[读取本地文件]
    B -->|否| D[从 stdin 读取]
    C --> E[识别文件类型]
    D --> E
    E --> F[选择合适的转换器]
    F --> G[执行转换]
    G --> H[输出 Markdown]

基本语法

MarkItDown CLI 的基本语法如下：

markitdown [选项] [文件名]

如果未指定文件名，MarkItDown 将从标准输入（stdin）读取内容。转换结果默认输出到标准输出（stdout）。

资料来源：packages/markitdown/src/markitdown/__main__.py:27-40

输入方式

MarkItDown 支持多种输入方式：

命令行选项

全局选项

资料来源：packages/markitdown/src/markitdown/__main__.py:51-80

插件相关选项

#### 列出已安装的插件

markitdown --list-plugins

输出示例：

Installed MarkItDown 3rd-party Plugins:

  * markitdown-ocr      (package: markitdown_ocr)

Use the -p (or --use-plugins) option to enable 3rd-party plugins.

如果没有安装任何插件，将显示：

Installed MarkItDown 3rd-party Plugins:

  * No 3rd-party plugins installed.

Find plugins by searching for the hashtag #markitdown-plugin on GitHub.

资料来源：packages/markitdown/src/markitdown/__main__.py:115-135

Azure Document Intelligence 选项

#### 使用 Document Intelligence 的完整示例

markitdown path-to-file.pdf -d -e "https://your-resource.cognitiveservices.azure.com/"

注意：使用 Document Intelligence 时必须同时指定文件名。

资料来源：packages/markitdown/src/markitdown/__main__.py:137-155

Azure Content Understanding 选项

#### 使用 Content Understanding 的完整示例

markitdown path-to-file.pdf --use-cu --cu-endpoint "https://your-resource.cognitiveservices.azure.com/"

可以通过环境变量 MARKITDOWN_CU_ENDPOINT 和 MARKITDOWN_CU_FILE_TYPES 设置默认值。

资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py:1-30

LLM 相关选项

这些选项主要用于配置图像描述和 OCR 功能（通过 markitdown-ocr 插件）。

#### 使用 LLM 进行图像描述和 OCR

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

⚠️ 注意：根据社区反馈（Issue #1897），--llm-client、--llm-model 和 --llm-prompt 选项在当前版本中可能未被正确注册到 argparse。如果遇到"unrecognized arguments"错误，请确保使用正确版本的 MarkItDown，或考虑通过 Python API 使用这些功能。

资料来源：packages/markitdown-ocr/README.md

常见使用场景

基本文件转换

# PDF 转换
markitdown document.pdf > output.md

# Word 文档转换
markitdown document.docx -o output.md

# PowerPoint 转换
markitdown presentation.pptx -o output.md

# Excel 转换
markitdown spreadsheet.xlsx -o output.md

使用管道输入

当需要从其他命令获取输入时：

# 从 curl 获取网页内容
curl -s https://example.com/page.html | markitdown -x html > output.md

# 从 gzip 解压的 PDF
gzip -dc document.pdf.gz | markitdown -x pdf > output.md

结合 Azure 服务使用

# 使用 Document Intelligence 进行 PDF 转换
markitdown document.pdf -d -e "https://your-resource.cognitiveservices.azure.com/" -o output.md

# 使用 Content Understanding 进行多模态转换
markitdown audio.mp3 --use-cu --cu-endpoint "https://your-resource.cognitiveservices.azure.com/" -o output.md

使用插件

# 列出可用插件
markitdown --list-plugins

# 启用插件进行 OCR
markitdown scanned.pdf --use-plugins --llm-client openai --llm-model gpt-4o -o output.md

Docker 使用

MarkItDown 也可以通过 Docker 运行，这对于在没有 Python 环境的系统上使用很有帮助。

构建 Docker 镜像

docker build -t markitdown:latest .

运行 Docker 容器

# 基本用法
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

# 指定文件
docker run --rm -v /path/to/files:/data markitdown:latest /data/document.pdf > output.md

注意：Docker 镜像可能不包含所有可选依赖（如 ffmpeg），在使用音频转换功能时可能需要扩展基础镜像。

退出码

MarkItDown CLI 使用以下退出码：

错误处理

缺少必需参数

如果使用需要端点的功能（如 Document Intelligence）但未提供端点：

Error: Document Intelligence Endpoint is required when using Document Intelligence.

如果未提供文件名：

Error: Filename is required when using Document Intelligence.

不支持的格式

当尝试转换不支持的文件格式时，MarkItDown 会输出友好的错误信息：

Error: Unsupported file format: .xyz

文件不存在

markitdown nonexistent.pdf
# Error: [Errno 2] No such file or directory: 'nonexistent.pdf'

环境变量

MarkItDown CLI 支持以下环境变量：

# 通过环境变量启用插件
export MARKITDOWN_ENABLE_PLUGINS=1
markitdown document.pdf -o output.md

资料来源：v0.1.3 Release Notes

与 Python API 的对比

对于需要精细控制或自定义转换逻辑的场景，建议使用 Python API。

故障排除

RuntimeWarning: Couldn't find ffmpeg or avconv

在 Linux 系统上运行 MarkItDown 时，如果看到以下警告：

RuntimeWarning: Couldn't find ffmpeg or avconv

这是因为 pydub 依赖需要 ffmpeg 来处理音频文件。解决方案：

```bash # Debian/Ubuntu sudo apt-get install ffmpeg

1. 安装 ffmpeg：

# macOS brew install ffmpeg ```

1. 或者忽略警告继续使用（音频功能将不可用）

资料来源：Issue #1685

unrecognized arguments 错误

如果在运行以下命令时遇到"unrecognized arguments"错误：

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

这可能是因为某些 LLM 相关参数在 argparse 中未正确注册。作为临时解决方案，可以使用 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.pdf")
print(result.text_content)

资料来源：Issue #1897

非 ASCII 文件名问题

在处理包含非 ASCII 字符（如法语音符）的文件名时，可能会遇到 UnicodeDecodeError。这是因为 IpynbConverter.accepts() 方法在检测文件类型时尝试解码文件流。

资料来源：Issue #1894

参见

• Python API 使用指南
• 插件开发指南
• 支持的格式
• Azure 集成
• 安全注意事项

概述

MarkItDown 的 Python API 以 MarkItDown 类为核心，提供了多种转换入口方法，支持从文件路径、URL、文件流等不同来源读取文档，并将其转换为 Markdown 格式。API 设计遵循"按需使用"原则，开发者可以根据实际场景选择最合适的转换方法。

资料来源：packages/markitdown/src/markitdown/_markitdown.py:1-100

核心类

MarkItDown 类

MarkItDown 是整个 API 的主入口类，负责管理转换器注册、处理文档转换请求、以及协调各种插件和服务。

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.markdown)

资料来源：packages/markitdown/src/markitdown/_markitdown.py:40-80

#### 构造函数参数

资料来源：packages/markitdown/src/markitdown/_markitdown.py:40-80

DocumentConverterResult 类

转换结果的容器类，封装了 Markdown 文本和可选的文档元数据。

@dataclass
class DocumentConverterResult:
    markdown: str                          # 转换后的 Markdown 文本
    title: Optional[str] = None           # 文档标题

属性说明：

资料来源：packages/markitdown/src/markitdown/_base_converter.py:10-45

StreamInfo 类

StreamInfo 用于传递文件流的元信息，帮助转换器识别文件类型和编码。

@dataclass
class StreamInfo:
    url: Optional[str] = None             # 来源 URL
    extension: Optional[str] = None       # 文件扩展名（如 ".pdf"）
    mimetype: Optional[str] = None         # MIME 类型
    charset: Optional[str] = None          # 字符编码（如 "utf-8"）

资料来源：packages/markitdown/src/markitdown/_stream_info.py:1-30

转换方法

MarkItDown 提供了多个转换方法，从不同来源读取文档：

graph TD
    A[MarkItDown 转换入口] --> B[convert]
    A --> C[convert_local]
    A --> D[convert_uri]
    A --> E[convert_stream]
    
    B --> F[路径/URL/文件对象]
    C --> G[本地文件路径]
    D --> H[URI 字符串]
    E --> I[文件流 + StreamInfo]
    
    F --> J[自动路由]
    G --> J
    H --> J
    I --> J
    
    J --> K[选择合适的 Converter]
    K --> L[执行转换]
    L --> M[返回 DocumentConverterResult]

convert() 方法

通用转换方法，自动根据输入类型选择最佳处理方式。

from markitdown import MarkItDown

md = MarkItDown()

# 从本地文件转换
result = md.convert("document.pdf")

# 从 URL 转换
result = md.convert("https://example.com/document.docx")

# 从文件对象转换
with open("document.pdf", "rb") as f:
    result = md.convert(f)

资料来源：packages/markitdown/src/markitdown/_markitdown.py:100-200

convert_local() 方法

仅用于本地文件系统路径的转换方法。在不受信任的环境中使用此方法更安全，因为它限制了可以访问的资源范围。

md = MarkItDown()
result = md.convert_local("/path/to/document.pdf")

资料来源：packages/markitdown/src/markitdown/_markitdown.py:200-250

convert_uri() 方法

用于处理 URI 字符串的转换方法，支持 file URI 和 data URI。

md = MarkItDown()

# 文件 URI
result = md.convert_uri("file:///path/to/document.pdf")

# Data URI（Base64 编码）
result = md.convert_uri("data:text/plain;base64,SGVsbG8gV29ybGQ=")

# 远程 URL（v0.1.1+）
result = md.convert_uri("https://example.com/document.pdf")

注意：convert_url() 在 v0.1.1 中被重命名为 convert_uri，但仍保留为别名以保持向后兼容。

资料来源：packages/markitdown/src/markitdown/_markitdown.py:250-300 资料来源：packages/markitdown/src/markitdown/_uri_utils.py:1-50

convert_stream() 方法

最低级别的转换方法，直接接收文件流和流元信息。

from markitdown import MarkItDown
from markitdown._stream_info import StreamInfo

md = MarkItDown()

with open("document.pdf", "rb") as f:
    stream_info = StreamInfo(
        extension=".pdf",
        mimetype="application/pdf"
    )
    result = md.convert_stream(f, stream_info)

此方法最适合需要自定义流元信息的场景，或在处理内存中的二进制数据时使用。

资料来源：packages/markitdown/src/markitdown/_markitdown.py:300-350

插件系统

MarkItDown 支持通过插件扩展功能，插件通过 entry_points 机制注册。

启用插件

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")  # 插件将被自动调用

列出已安装插件

markitdown --list-plugins

插件开发

开发者可以创建自定义转换器插件：

# packages/markitdown-sample-plugin/README.md
from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo

class RtfConverter(DocumentConverter):
    def __init__(self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT):
        super().__init__(priority=priority)

    def accepts(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs) -> bool:
        # 检查文件是否为 RTF 格式
        return stream_info.extension == ".rtf"

    def convert(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs) -> DocumentConverterResult:
        # 实现转换逻辑
        return DocumentConverterResult(markdown="# Converted RTF Content")

插件需要在 pyproject.toml 中声明入口点：

[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"

资料来源：packages/markitdown-sample-plugin/README.md:1-100

LLM 集成

MarkItDown 支持使用 LLM 进行图像描述和 OCR（光学字符识别）。

基本用法

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

# 转换图像文件
result = md.convert("image.png")
print(result.markdown)

自定义提示词

md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Extract all text from this image, preserving table structure."
)

兼容的 LLM 客户端

支持任何遵循 OpenAI API 的客户端：

from openai import AzureOpenAI

client = AzureOpenAI(
    api_key="your-api-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_version="2024-02-01"
)

md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

资料来源：packages/markitdown/src/markitdown/_markitdown.py:40-80

Azure 集成

Azure Document Intelligence

使用 Azure Document Intelligence 进行高质量文档转换：

from markitdown import MarkItDown

md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/",
    docintel_api_key="your-api-key"
)

result = md.convert("document.pdf")
print(result.markdown)

支持的格式：

资料来源：packages/markitdown/src/markitdown/converters/_doc_intel_converter.py:1-80

Azure Content Understanding

提供更高级的多模态提取功能：

from markitdown import MarkItDown
from markitdown.converters._doc_intel_converter import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="https://your-resource.cognitiveservices.azure.com/",
    cu_file_types=[ContentUnderstandingFileType.PDF]  # 仅对 PDF 使用 CU
)

result = md.convert("document.pdf")
print(result.markdown)

资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py:1-100

转换器架构

MarkItDown 使用转换器链模式处理不同文件格式：

graph LR
    A[输入文件] --> B[StreamInfo 提取]
    B --> C{文件类型检测}
    
    C -->|PDF| D[PdfConverter]
    C -->|DOCX| E[DocxConverter]
    C -->|PPTX| F[PptxConverter]
    C -->|XLSX| G[XlsxConverter]
    C -->|HTML| H[WikipediaConverter]
    C -->|RSS| I[RSSConverter]
    C -->|其他| Z[未知格式处理]
    
    D --> J[DocumentConverterResult]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    Z --> J

内置转换器

资料来源：packages/markitdown/src/markitdown/converters/_pdf_converter.py:1-50

常见问题与限制

已知的社区问题

#### 非 ASCII 文件的 UnicodeDecodeError

IpynbConverter.accepts() 方法在处理包含非 ASCII 字符的文件时可能抛出 UnicodeDecodeError，导致整个转换管道崩溃。

资料来源：https://github.com/microsoft/markitdown/issues/1894

临时解决方案：

try:
    result = md.convert("notebook.ipynb")
except UnicodeDecodeError:
    # 使用替代方法处理
    pass

#### Office Open XML 无效文件处理

当转换无效的 DOCX、XLSX 或 PPTX 文件时，MarkItDown 返回成功结果，但 text_content 中包含错误消息 "This is not a valid Office Open XML file."，而不是抛出异常。

资料来源：https://github.com/microsoft/markitdown/issues/1408

检测方法：

result = md.convert("invalid_file.docx")
if "not a valid Office Open XML" in result.markdown:
    print("Warning: Invalid file format")

#### Linux 上的 pydub 警告

在 Linux 系统上运行时，如果系统中没有安装 ffmpeg 或 avconv，pydub 会触发 RuntimeWarning，可能导致音频转换功能失败。

资料来源：https://github.com/microsoft/markitdown/issues/1685

PDF 转换限制

PDF 转换功能在处理以下内容时存在已知限制：

• 复杂表格结构可能无法正确提取（参见 issue #293）
• PDF 不是真正的 Markdown 格式，转换结果为纯文本（参见 issue #296）
• PDF 不支持 .doc 格式，只支持 .docx（参见 issue #23）

资料来源：https://github.com/microsoft/markitdown/issues/293 资料来源：https://github.com/microsoft/markitdown/issues/296

安全考虑

重要提示：MarkItDown 使用当前进程的权限执行 I/O 操作。像 open() 或 requests.get() 一样，它会访问进程本身可以访问的资源。在不受信任的环境中使用时，请务必对输入进行清理，并调用最窄的 convert_* 方法（如 convert_stream() 或 convert_local()）。

资料来源：packages/markitdown/README.md:1-30

完整示例

基本文档转换

from markitdown import MarkItDown

md = MarkItDown()

# 转换多种格式
files = ["document.pdf", "report.docx", "slides.pptx", "data.xlsx"]

for file_path in files:
    try:
        result = md.convert(file_path)
        print(f"=== {file_path} ===")
        print(result.markdown[:500])  # 打印前 500 字符
        print()
    except Exception as e:
        print(f"Error converting {file_path}: {e}")

使用 LLM 进行图像描述

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()

md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail."
)

result = md.convert("screenshot.png")
print(result.markdown)

批量处理与插件

from markitdown import MarkItDown
import glob

# 启用插件支持
md = MarkItDown(enable_plugins=True)

# 查找所有文档
documents = glob.glob("documents/*")

for doc_path in documents:
    result = md.convert(doc_path)
    
    # 保存结果
    output_path = doc_path.rsplit(".", 1)[0] + ".md"
    with open(output_path, "w", encoding="utf-8") as f:
        f.write(result.markdown)
    
    print(f"Converted: {doc_path} -> {output_path}")

使用 Azure Document Intelligence

import os
from markitdown import MarkItDown

# 从环境变量读取配置
endpoint = os.environ.get("DOCINTEL_ENDPOINT")
api_key = os.environ.get("DOCINTEL_API_KEY")

md = MarkItDown(
    docintel_endpoint=endpoint,
    docintel_api_key=api_key
)

result = md.convert("scanned_document.pdf")
print(result.markdown)

另请参阅

• 命令行界面文档 - CLI 使用方法和参数说明
• 插件开发指南 - 如何开发自定义转换器插件
• Azure 集成指南 - Azure Document Intelligence 和 Content Understanding 配置
• 支持的格式列表 - 完整支持的文件格式说明

概述

MarkItDown 的插件系统是自 v0.1.0 版本引入的重要架构特性，旨在允许第三方开发者扩展 MarkItDown 的文档转换能力。该系统通过标准化的入口点（Entry Points）机制实现插件的自动发现和注册，使开发者无需修改 MarkItDown 核心代码即可添加新的文件格式支持或替换内置转换器。

插件系统的核心价值在于：

• 可扩展性：支持添加任意新的文件格式转换器
• 模块化：将功能代码与核心库分离
• 灵活性：插件可以选择替换或增强内置转换器
• 解耦性：插件通过标准接口与 MarkItDown 核心通信

资料来源：v0.1.0 Release Notes

架构设计

整体架构图

graph TD
    A[用户代码 / CLI] --> B[MarkItDown 核心]
    B --> C[转换器注册表]
    C --> D[内置转换器集合]
    C --> E[第三方插件转换器]
    
    F[插件发现机制] --> E
    F --> |entry_points| G[已安装插件包]
    
    H[LLM 客户端] --> E
    I[其他配置参数] --> B
    
    style F fill:#f9f,stroke:#333
    style E fill:#ff9,stroke:#333

核心组件

转换器优先级机制

MarkItDown 使用优先级机制来决定使用哪个转换器处理文件。内置转换器遵循以下优先级规则：

class DocumentConverter:
    # 优先级常量
    PRIORITY_MAXIMUM = float("inf")      # 最高优先级
    PRIORITY_DEFAULT = 0.0               # 默认优先级
    PRIORITY_SPECIFIC_FILE_FORMAT = -1.0 # 特定文件格式
    PRIORITY_AMBIGUOUS_FILE_FORMAT = -2.0 # 模糊文件格式
    PRIORITY_FALLBACK = -10.0            # 回退转换器

插件转换器可以使用自定义优先级。当多个转换器都接受同一文件时，优先级最高的转换器将被选中。

资料来源：_base_converter.py

插件接口规范

DocumentConverter 基类

所有插件必须继承 DocumentConverter 基类并实现以下核心方法：

from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
from typing import BinaryIO, Any

class YourConverter(DocumentConverter):
    def __init__(self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT):
        super().__init__(priority=priority)

    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        """
        判断此转换器是否接受给定文件流
        返回 True 表示可以处理此文件
        """
        # 检查文件格式
        extension = stream_info.extension.lower()
        mimetype = stream_info.mimetype or ""
        
        if extension == ".yourext":
            return True
        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        """
        执行文件到 Markdown 的转换
        """
        # 实现转换逻辑
        markdown_content = "..."
        return DocumentConverterResult(
            text_content=markdown_content,
            title=None,
            authors=[],
            images=[]
        )

资料来源：packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py

插件注册函数

每个插件包必须导出 register_converters 函数，MarkItDown 在初始化时会调用此函数注册转换器：

from markitdown import MarkItDown

def register_converters(markitdown: MarkItDown, **kwargs):
    """
    在 MarkItDown 实例创建时调用，用于注册插件提供的转换器
    
    Args:
        markitdown: MarkItDown 实例
        **kwargs: 传递给 MarkItDown 的参数（llm_client, llm_model 等）
    """
    markitdown.register_converter(YourConverter())

插件接口版本

插件必须声明其使用的接口版本：

# 当前支持的版本为 1
__plugin_interface_version__ = 1

资料来源：packages/markitdown-sample-plugin/README.md

入口点配置

插件包需要在 pyproject.toml 中配置入口点，以便 MarkItDown 能够自动发现：

[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"

其中：

• "markitdown.plugin" 是固定的入口点组名
• sample_plugin 是插件标识符，可自定义
• markitdown_sample_plugin 是包含插件代码的包名

资料来源：packages/markitdown-sample-plugin/pyproject.toml

使用方式

CLI 使用

# 列出已安装的插件
markitdown --list-plugins

# 启用插件进行转换
markitdown --use-plugins document.pdf

Python API 使用

from markitdown import MarkItDown

# 启用插件支持
md = MarkItDown(enable_plugins=True)

# 转换文件
result = md.convert("document.pdf")
print(result.text_content)

传递 LLM 客户端参数

插件可以接收通过 MarkItDown 构造函数传递的 LLM 相关参数：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
    llm_prompt="自定义提示词"  # 可选
)

result = md.convert("document.pdf")

资料来源：_markitdown.py

官方插件示例

markitdown-ocr 插件

markitdown-ocr 是官方提供的 OCR 插件，展示了如何利用 LLM Vision 能力增强内置转换器：

资料来源：packages/markitdown-ocr/README.md

插件开发指南

开发流程

graph LR
    A[创建插件包结构] --> B[实现 DocumentConverter]
    B --> C[配置入口点]
    C --> D[安装插件]
    D --> E[测试插件]
    E --> F{发布分享?}
    F -->|是| G[发布到 PyPI]
    F -->|否| H[内部使用]

完整示例

以下是一个完整的 RTF 文件转换器插件示例：

# markitdown_sample_plugin/_plugin.py
from typing import BinaryIO, Any
from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo

__plugin_interface_version__ = 1

class RtfConverter(DocumentConverter):
    def __init__(self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT):
        super().__init__(priority=priority)

    def accepts(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> bool:
        return stream_info.extension == ".rtf"

    def convert(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> DocumentConverterResult:
        content = file_stream.read().decode("utf-8", errors="ignore")
        # 实际实现中需要 RTF 解析逻辑
        return DocumentConverterResult(text_content=f"# RTF Document\n\n{content}")

def register_converters(markitdown: MarkItDown, **kwargs):
    markitdown.register_converter(RtfConverter())

资料来源：packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py

安装本地插件

# 进入插件目录
cd packages/markitdown-sample-plugin

# 以开发模式安装
pip install -e .

# 验证插件是否已注册
markitdown --list-plugins

常见问题

CLI 参数未识别错误

问题描述：使用 --llm-client 和 --llm-model 参数时报 "Unrecognized Arguments" 错误。

原因：这些参数是插件参数，不在 MarkItDown CLI 的内置参数列表中。参数由插件的 register_converters 函数接收。

解决方案：目前 CLI 层面对插件参数的支持有限，建议通过 Python API 使用这些参数：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o"
)

资料来源：Issue #1897

插件未被发现

排查步骤：

1. 确认入口点配置正确
2. 检查包是否已正确安装：pip show your-plugin
3. 验证插件代码无语法错误
4. 确认 enable_plugins=True 已设置

安全考虑

[!IMPORTANT]

MarkItDown 以当前进程的权限执行 I/O 操作。在不受信任的环境中使用时，请对输入进行清理，并使用最窄的 convert_* 函数（如 convert_stream() 或 convert_local()）。

插件系统额外引入以下安全考量：

配置参数参考

MarkItDown 构造函数参数

CLI 参数

资料来源：__main__.py

See Also

• 项目主文档
• 快速开始指南
• 支持的文档格式
• Azure Content Understanding 集成
• markitdown-ocr 插件文档
• 示例插件源码

概述

markitdown-ocr 是 MarkItDown 的官方插件包，通过 LLM Vision 技术为 PDF、DOCX、PPTX 和 XLSX 文件中的嵌入式图像提供 OCR（光学字符识别）支持。该插件利用 MarkItDown 已有的 llm_client 和 llm_model 参数模式，无需引入新的机器学习库或二进制依赖项，即可实现图像文字提取功能。

资料来源：packages/markitdown-ocr/README.md

功能特性

资料来源：packages/markitdown-ocr/README.md

系统架构

组件关系图

graph TD
    A[MarkItDown 实例] -->|enable_plugins=True| B[插件发现机制]
    B -->|entry_points| C[markitdown-ocr 插件]
    C -->|register_converters| D[OCR 增强型转换器注册]
    
    D --> E[PdfConverterWithOCR]
    D --> F[DocxConverterWithOCR]
    D --> G[PptxConverterWithOCR]
    D --> H[XlsxConverterWithOCR]
    
    E --> I[LLMVisionOCRService]
    F --> I
    G --> I
    H --> I
    
    I -->|llm_client| J[OpenAI 兼容客户端]
    I -->|llm_model| K[GPT-4o 等模型]
    
    L[文档文件] -->|转换请求| E
    L -->|转换请求| F
    L -->|转换请求| G
    L -->|转换请求| H
    
    E -->|优先级 -1.0| M[内置转换器 优先级 0.0]
    F --> M
    G --> M
    H --> M

工作流程

sequenceDiagram
    participant User as 用户
    participant MD as MarkItDown
    participant Plugin as OCR 插件
    participant OCR as LLMVisionOCRService
    participant LLM as LLM API
    
    User->>MD: MarkItDown(enable_plugins=True,<br/>llm_client=..., llm_model=...)
    MD->>Plugin: 发现并加载插件
    Plugin->>Plugin: register_converters()
    Note over Plugin: 创建 OCR 增强型转换器<br/>优先级设为 -1.0
    
    User->>MD: convert(document.pdf)
    MD->>Plugin: 选择优先级最高的转换器
    Plugin->>OCR: 处理文档
    OCR->>OCR: 提取嵌入式图像
    
    alt 有嵌入式图像
        OCR->>LLM: 发送图像 + 提取提示
        LLM-->>OCR: 返回提取的文本
        OCR-->>Plugin: 文本内容
    else 扫描件 PDF
        OCR->>OCR: 300 DPI 渲染页面
        OCR->>LLM: 发送全页图像
        LLM-->>OCR: 返回提取的文本
    end
    
    Plugin-->>MD: DocumentConverterResult
    MD-->>User: Markdown 输出

安装指南

前置条件

• Python 3.10 或更高版本
• MarkItDown 已安装：pip install markitdown
• OpenAI 兼容的 LLM 客户端

安装步骤

# 安装 markitdown-ocr 插件
pip install markitdown-ocr

# 安装 OpenAI 客户端（或其他兼容客户端）
pip install openai

资料来源：packages/markitdown-ocr/README.md

使用方法

命令行接口

使用插件时，需要同时启用插件并配置 LLM 参数：

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

[!IMPORTANT]

CLI 参数 --llm-client 和 --llm-model 需要明确指定，否则插件会静默跳过 OCR 流程，回退到标准内置转换器。

资料来源：packages/markitdown-ocr/README.md

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

资料来源：packages/markitdown-ocr/README.md

#### 自定义提示词

对于专业文档，可以覆盖默认的提取提示词：

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
    llm_prompt="Extract all text from this image, preserving table structure.",
)

result = md.convert("document_with_tables.pdf")

#### Azure OpenAI 兼容客户端

插件支持任何遵循 OpenAI API 规范的客户端：

from openai import AzureOpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=AzureOpenAI(
        api_key="your-api-key",
        azure_endpoint="https://your-resource.openai.azure.com/",
        api_version="2024-02-01",
    ),
    llm_model="gpt-4o",
)

result = md.convert("document_with_images.pdf")

支持的文件格式

PDF

DOCX

资料来源：packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py

PPTX 和 XLSX

插件注册机制

markitdown-ocr 通过 Python entry point 机制注册为 MarkItDown 插件。包在 pyproject.toml 中定义入口点：

[project.entry-points."markitdown.plugin"]
markitdown_ocr = "markitdown_ocr"

当 MarkItDown(enable_plugins=True, ...) 被调用时：

1. MarkItDown 通过 markitdown.plugin entry point 组发现插件
2. 调用 register_converters()，转发所有 kwargs（包括 llm_client 和 llm_model）
3. 插件创建 LLMVisionOCRService
4. 四个 OCR 增强型转换器以 优先级 -1.0 注册——在优先级 0.0 的内置转换器之前

资料来源：packages/markitdown-sample-plugin/README.md

常见问题与故障排除

问题一：命令行参数未被识别

问题描述：运行 markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o 时报错"Unrecognized Arguments"。

原因：README 中的 CLI 示例参数可能与当前版本不匹配。请查阅 markitdown --help 获取支持的实际参数列表。

资料来源：社区 Issue #1897

问题二：RuntimeWarning 关于 ffmpeg

问题描述：在 Linux 系统上运行时出现 RuntimeWarning: Couldn't find ffmpeg or avconv。

说明：此警告来自 pydub 依赖项，与 markitdown-ocr 插件本身无关，但可能影响音频转文字功能。

资料来源：社区 Issue #1685

问题三：OCR 未执行

检查清单：

1. 确认已安装 markitdown-ocr：pip show markitdown-ocr
2. 确认启用了插件：--use-plugins
3. 确认提供了 llm_client 和 llm_model
4. 如未提供 llm_client，插件会静默跳过 OCR，回退到标准转换器

问题四：Office Open XML 文件转换异常

问题描述：转换无效的 DOCX、XLSX 或 PPTX 文件时返回成功，但 text_content 中包含 "This is not a valid Office Open XML file." 字符串。

说明：这是已知行为——MarkItDown 对无效文件返回成功结果而非抛出异常，难以与真正的成功结果区分。

资料来源：社区 Issue #1408

安全注意事项

[!IMPORTANT]

MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 一样，它会访问进程本身可访问的资源。在不受信任的环境中，请对输入进行清理，并调用最窄的 convert_* 函数（如 convert_stream() 或 convert_local()）以满足使用需求。

配置参数参考

MarkItDown 构造函数参数

OCR 插件行为配置

技术实现细节

DOCX 转换器的占位符机制

DocxConverterWithOCR 在处理图像时使用占位符令牌，确保 mammoth 库不会破坏 OCR 标记：

# 占位符注入到 HTML，防止 mammoth 转义
_PLACEHOLDER = "MARKITDOWNOCRBLOCK{}"

资料来源：packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py

优先级机制

MarkItDown 选择优先级最高（数值最大）的转换器处理文件，因此 OCR 插件的优先级设为 -1.0，确保先于内置转换器尝试处理。

扩展阅读

• MarkItDown 主文档 — 核心功能和使用指南
• 插件开发指南 — 开发自定义转换器插件
• Azure Content Understanding 集成 — 云端高级文档理解服务
• Azure Document Intelligence — Azure AI 文档智能服务

概述

MarkItDown 提供了与 Microsoft Azure 服务的深度集成，通过 Azure Document Intelligence 和 Azure Content Understanding 两个转换器实现高质量的文档提取。这两个服务主要面向需要云端处理能力的企业用户，特别是在处理复杂文档结构、扫描件、以及多模态内容（音频、视频）时提供更优的转换效果。

Azure 服务集成的核心价值在于：

• 云端布局分析：利用 Azure 的机器学习模型进行文档布局识别
• 结构化字段提取：从文档中提取特定领域的结构化数据
• 多模态支持：处理音频、视频等非传统文档格式
• OCR 增强：对扫描 PDF 和图片中的文字进行识别

资料来源：README.md

架构设计

转换器层次结构

MarkItDown 采用插件化的转换器架构，Azure 服务作为特定的高优先级转换器实现。架构如下：

graph TD
    A[MarkItDown.convert] --> B{检测文件类型}
    B --> C[内置转换器]
    B --> D[Document Intelligence]
    B --> E[Content Understanding]
    
    C --> F[本地处理]
    D --> G[Azure Doc Intel API]
    E --> H[Azure CU API]
    
    G --> I[Markdown 输出]
    H --> I
    
    style D fill:#0078d4,color:#fff
    style E fill:#0078d4,color:#fff

依赖加载机制

MarkItDown 使用延迟依赖加载模式处理 Azure SDK，当缺少依赖时不会直接失败，而是在实际调用时抛出明确的错误信息。

graph LR
    A[导入模块] --> B{azure.ai.contentunderstanding 可用?}
    B -->|是| C[加载 ContentUnderstandingClient]
    B -->|否| D[保存异常信息]
    D --> E[记录 MissingDependencyException]
    C --> F[初始化转换器]
    E --> G[运行时检测]

资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py:1-40

Azure Document Intelligence 集成

功能概述

Azure Document Intelligence（原 Form Recognizer）提供基于云的文档分析服务，能够识别文档布局、提取键值对、表格和选择标记。MarkItDown 通过 _doc_intel_converter.py 实现了与该服务的集成。

主要支持能力：

• 文档布局分析
• 表格提取
• 键值对提取
• 多语言文档支持

安装配置

需要安装相关依赖包：

pip install 'markitdown[az-doc-intel]'

命令行使用

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

其中 -d 参数启用 Document Intelligence，-e 参数指定服务端点。

资料来源：README.md

Python API 使用

from markitdown import MarkItDown

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

身份验证配置

Document Intelligence 支持多种身份验证凭据：

资料来源：packages/markitdown/src/markitdown/converters/_doc_intel_converter.py

Azure Content Understanding 集成

功能概述

Azure Content Understanding 是更高级的云端服务，提供多模态文档处理能力，支持文档、图片、音频和视频的统一处理。该服务通过结构化分析器（Analyzer）实现领域特定的字段提取，结果以 YAML 前置matter 格式输出。

资料来源：packages/markitdown/src/markitdown/converters/_cu_converter.py:1-30

安装配置

pip install 'markitdown[az-content-understanding]'

支持的文件类型与分析器映射

Content Understanding 服务根据文件类型自动选择合适的分析器：

命令行使用

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

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)

#### 使用自定义分析器

from markitdown import MarkItDown, ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # 仅 PDF 使用 CU
)
result = md.convert("document.pdf")
print(result.markdown)

资料来源：README.md

输出格式

Content Understanding 的输出包含两部分：

1. YAML 前置matter：包含分析器提取的结构化字段
2. Markdown 主体内容：文档的降级格式表示

Pitfall Log / 踩坑日志

项目：microsoft/markitdown

摘要：发现 30 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux。

1. 安装坑 · 来源证据：[Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f70b2e3ea5ed47418a4aeb9ef27230f9 | https://github.com/microsoft/markitdown/issues/1685 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 运行坑 · 来源证据：Unrecognized Arguments Error in markitdown CLI for undocumented arguments

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Unrecognized Arguments Error in markitdown CLI for undocumented arguments
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_252ef0d45ac040688ffa066bc1b64ba0 | https://github.com/microsoft/markitdown/issues/1897 | 来源类型 github_issue 暴露的待验证使用条件。

3. 维护坑 · 来源证据：bug: DOCX math converter crashes when oMath element is missing in malformed equations

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：bug: DOCX math converter crashes when oMath element is missing in malformed equations
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6e08b71ee29f46a98e6825a5d5b11e6e | https://github.com/microsoft/markitdown/issues/1979 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 维护坑 · 来源证据：bug: DOCX math converter crashes with NotImplementedError on unknown functions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：bug: DOCX math converter crashes with NotImplementedError on unknown functions
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_439f22f47a524773808819148caadca5 | https://github.com/microsoft/markitdown/issues/1982 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 失败模式：installation: Office Open XML: Invalid Files Return Success with Error Message Instead of Exception

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Office Open XML: Invalid Files Return Success with Error Message Instead of Exception
• 对用户的影响：Developers may fail before the first successful local run: Office Open XML: Invalid Files Return Success with Error Message Instead of Exception
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Office Open XML: Invalid Files Return Success with Error Message Instead of Exception. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_087a8a7b6538b2ce2b065ade73c555af | https://github.com/microsoft/markitdown/issues/1408 | Office Open XML: Invalid Files Return Success with Error Message Instead of Exception

6. 安装坑 · 失败模式：installation: Support for .doc extensions

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Support for .doc extensions
• 对用户的影响：Developers may fail before the first successful local run: Support for .doc extensions
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Support for .doc extensions. Context: Observed when using windows, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_d5a467d012987779306cb5c50725275b | https://github.com/microsoft/markitdown/issues/23 | Support for .doc extensions

7. 安装坑 · 失败模式：installation: [Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux
• 对用户的影响：Developers may fail before the first successful local run: [Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux. Context: Observed when using python, windows, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_1f9167a15a1eec72c8f79514f1b70b76 | https://github.com/microsoft/markitdown/issues/1685 | [Bug]: RuntimeWarning from pydub: "Couldn't find ffmpeg or avconv" on Linux

8. 安装坑 · 失败模式：installation: v0.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.0. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_1d5ae6ee21225356f45c36c20024dccd | https://github.com/microsoft/markitdown/releases/tag/v0.1.0 | v0.1.0

9. 安装坑 · 来源证据：Office Open XML: Invalid Files Return Success with Error Message Instead of Exception

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Office Open XML: Invalid Files Return Success with Error Message Instead of Exception
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_734e117518a3496eb3779e5f22b600b5 | https://github.com/microsoft/markitdown/issues/1408 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安装坑 · 来源证据：bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_77597bea6262485b9609d8fc5f50a69a | https://github.com/microsoft/markitdown/issues/1894 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 配置坑 · 失败模式：configuration: Enhancement: Add MCP server support for document processing

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Enhancement: Add MCP server support for document processing
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Enhancement: Add MCP server support for document processing
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Enhancement: Add MCP server support for document processing. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_969d5f508051e086435b78736eae3e88 | https://github.com/microsoft/markitdown/issues/2004 | Enhancement: Add MCP server support for document processing

12. 配置坑 · 失败模式：configuration: v0.1.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.1.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.2
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.2. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_076605feea6e0b4830282709121d3c90 | https://github.com/microsoft/markitdown/releases/tag/v0.1.2 | v0.1.2

13. 配置坑 · 失败模式：configuration: v0.1.2a1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.1.2a1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.2a1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.2a1. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_22fa2fa9d8ed93f594844ce5550fc4d8 | https://github.com/microsoft/markitdown/releases/tag/v0.1.2a1 | v0.1.2a1

14. 配置坑 · 来源证据：Enhancement: Add MCP server support for document processing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Add MCP server support for document processing
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_94fcd5bbf87541d1ab988bae7c501a95 | https://github.com/microsoft/markitdown/issues/2004 | 来源类型 github_issue 暴露的待验证使用条件。

15. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:888092115 | https://github.com/microsoft/markitdown | README/documentation is current enough for a first validation pass.

16. 运行坑 · 失败模式：runtime: bug: DOCX math converter crashes when oMath element is missing in malformed equations

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: bug: DOCX math converter crashes when oMath element is missing in malformed equations
• 对用户的影响：Developers may hit a documented source-backed failure mode: bug: DOCX math converter crashes when oMath element is missing in malformed equations
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: DOCX math converter crashes when oMath element is missing in malformed equations. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2d85aabe3c00f8d53d781ac03dd69f62 | https://github.com/microsoft/markitdown/issues/1979 | bug: DOCX math converter crashes when oMath element is missing in malformed equations

17. 运行坑 · 失败模式：runtime: bug: DOCX math converter crashes with NotImplementedError on unknown functions

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: bug: DOCX math converter crashes with NotImplementedError on unknown functions
• 对用户的影响：Developers may hit a documented source-backed failure mode: bug: DOCX math converter crashes with NotImplementedError on unknown functions
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: DOCX math converter crashes with NotImplementedError on unknown functions. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_3ca154355492e590afae4917a8e9c7af | https://github.com/microsoft/markitdown/issues/1982 | bug: DOCX math converter crashes with NotImplementedError on unknown functions

18. 运行坑 · 失败模式：runtime: bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)
• 对用户的影响：Developers may hit a documented source-backed failure mode: bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.). Context: Observed when using python, windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2603b970a28eceb8da6246b000a927d3 | https://github.com/microsoft/markitdown/issues/1894 | bug: IpynbConverter.accepts() raises UnicodeDecodeError on non-ASCII files (French PDFs, etc.)

19. 运行坑 · 失败模式：runtime: v0.1.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.1.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.3
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.3. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_994386694bb3b31fb731336f58573ff3 | https://github.com/microsoft/markitdown/releases/tag/v0.1.3 | v0.1.3

20. 运行坑 · 失败模式：runtime: v0.1.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.1.5
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.5
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.5. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_38cc2743269efc75c24242abb0e2746c | https://github.com/microsoft/markitdown/releases/tag/v0.1.5 | v0.1.5

21. 运行坑 · 来源证据：Timeout needed

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Timeout needed
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ba28a1cc5c004225b80d2ef380e51a77 | https://github.com/microsoft/markitdown/issues/2000 | 来源类型 github_issue 暴露的待验证使用条件。

22. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:888092115 | https://github.com/microsoft/markitdown | last_activity_observed missing

23. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:888092115 | https://github.com/microsoft/markitdown | no_demo; severity=medium

24. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:888092115 | https://github.com/microsoft/markitdown | no_demo; severity=medium

25. 能力坑 · 失败模式：conceptual: Unrecognized Arguments Error in markitdown CLI for undocumented arguments

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Unrecognized Arguments Error in markitdown CLI for undocumented arguments
• 对用户的影响：Developers may hit a documented source-backed failure mode: Unrecognized Arguments Error in markitdown CLI for undocumented arguments
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_d7ddfa04bce33d2ca53c58ce9f0265c0 | https://github.com/microsoft/markitdown/issues/1897 | Unrecognized Arguments Error in markitdown CLI for undocumented arguments

26. 运行坑 · 失败模式：performance: Timeout needed

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Timeout needed
• 对用户的影响：Developers may hit a documented source-backed failure mode: Timeout needed
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Timeout needed. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_acdf8e881ef175760bcc59b92eae1aef | https://github.com/microsoft/markitdown/issues/2000 | Timeout needed

27. 运行坑 · 失败模式：performance: Version 0.1.6

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Version 0.1.6
• 对用户的影响：Upgrade or migration may change expected behavior: Version 0.1.6
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Version 0.1.6. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_037f240b8fd9da8ecfc973a1f7eae18c | https://github.com/microsoft/markitdown/releases/tag/v0.1.6 | Version 0.1.6

28. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:888092115 | https://github.com/microsoft/markitdown | issue_or_pr_quality=unknown

29. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:888092115 | https://github.com/microsoft/markitdown | release_recency=unknown

30. 维护坑 · 失败模式：maintenance: Version 0.1.5b1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Version 0.1.5b1
• 对用户的影响：Upgrade or migration may change expected behavior: Version 0.1.5b1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Version 0.1.5b1. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_fe15b901250727fa3263b3b5af451b94 | https://github.com/microsoft/markitdown/releases/tag/v0.1.5b1 | Version 0.1.5b1