## 项目概述

MarkItDown 是微软开发的一个轻量级 Python 工具，用于将各种文件格式（如 PDF、Office 文档、图片、音频等）转换为 Markdown 格式，以便于大型语言模型（LLM）和文本分析管道使用。它旨在保留文档的重要结构（如标题、列表、表格、链接等），输出适合机器消费的 Markdown 文本。

## 核心功能

- 支持多种文件格式转换：PDF、PowerPoint、Word、Excel、图片（EXIF 元数据和 OCR）、音频（EXIF 元数据和语音转录）、HTML、文本格式（CSV、JSON、XML）、ZIP 文件、YouTube 链接、EPUB 等。
- 提供命令行工具和 Python API。
- 支持可选依赖，按需安装特定格式的转换支持。
- 支持第三方插件扩展，例如 OCR 插件。
- 集成 Azure 内容理解（Content Understanding）和 Azure 文档智能（Document Intelligence），提供更高质量的云转换服务。
- 支持使用 LLM 进行图像描述（如 GPT-4o）。
- 提供 Docker 镜像，便于容器化部署。

## 适用与不适用场景

**适用场景：**
- 需要将文档转换为 Markdown 以用于 LLM 提示或文本分析。
- 批量转换办公文档、PDF、图片等。
- 需要从文档中提取结构化信息（通过 Azure 内容理解）。
- 在自动化管道中集成文档转换功能。

**不适用场景：**
- 需要高保真度的文档转换供人类阅读（输出可能不够美观）。
- 处理不受信任的输入时未进行适当的安全隔离（存在安全风险）。
- 需要实时转换大量视频或音频（可能需要云服务）。

## 技术架构与依赖

- 语言：Python 3.10+。
- 依赖：核心依赖较少，可选依赖按需安装，如 `[pdf]`、`[docx]`、`[pptx]`、`[xlsx]`、`[audio-transcription]` 等。
- 集成：支持 OpenAI 客户端、Azure 内容理解、Azure 文档智能。
- 插件机制：支持第三方插件，通过 `#markitdown-plugin` 标签发现。

## 安装与快速开始

**安装：**
```bash
pip install 'markitdown[all]'
```
或从源码安装：
```bash
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
```

**快速开始（命令行）：**
```bash
markitdown path-to-file.pdf > document.md
```
或使用 `-o` 指定输出文件：
```bash
markitdown path-to-file.pdf -o document.md
```

**快速开始（Python）：**
```python
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)
```

## 典型使用方法

**使用 Azure 内容理解：**
```python
from markitdown import MarkItDown
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")
print(result.markdown)
```

**使用 LLM 进行图像描述：**
```python
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)
```

**使用 Docker：**
```sh
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
```

## 配置与部署要点

- 环境变量：Azure 端点等可通过参数传递，也可设置环境变量（具体变量名未在文档中明确，建议参考官方文档）。
- 安全配置：在不受信任的环境中，应限制输入来源，使用 `convert_local()` 或 `convert_stream()` 等窄化 API。
- 插件配置：默认禁用插件，需通过 `--use-plugins` 或 `enable_plugins=True` 启用。
- 部署：可使用 Docker 容器化，或作为 Python 库集成到应用中。

## 限制、风险与许可证

- **限制：** 输出可能不适合人类阅读；部分格式（如视频）需要云服务支持；依赖可选安装，需注意依赖冲突。
- **风险：** 安全风险：执行 I/O 操作时可能访问敏感资源，需对输入进行消毒；云服务调用可能产生费用。
- **许可证：** MIT 许可证。

## 官方链接

- GitHub 仓库：https://github.com/microsoft/markitdown
- PyPI 页面：https://pypi.org/project/markitdown/
- 最新版本：v0.1.7（发布于 2026-07-29）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README（https://github.com/microsoft/markitdown）
- 分析时间：2026-07-29