wehub-resource-sync
352 lines
15 KiB
Markdown
352 lines
15 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/markitdown) · [上游 README](https://github.com/microsoft/markitdown/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# MarkItDown
|
||
|
||
[](https://pypi.org/project/markitdown/)
|
||
|
||
[](https://github.com/microsoft/autogen)
|
||
|
||
> [!IMPORTANT]
|
||
> MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 类似，它会访问进程自身能够访问的资源。在不受信任的环境中请对输入进行清理，并调用你的用例所需的最精简的 `convert_*` 函数（例如 `convert_stream()` 或 `convert_local()`）。更多信息请参阅文档的[安全注意事项](#security-considerations)部分。
|
||
|
||
MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，以便与 LLM（大语言模型）及相关文本分析流水线配合使用。在这方面，它与 [textract](https://github.com/deanmalmgren/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 安装，你可以通过以下命令创建并激活虚拟环境：
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
如果使用 `uv`，可以这样创建虚拟环境：
|
||
|
||
```bash
|
||
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，可以这样创建虚拟环境：
|
||
|
||
```bash
|
||
conda create -n markitdown python=3.12
|
||
conda activate markitdown
|
||
```
|
||
|
||
## 安装
|
||
|
||
要安装 MarkItDown，使用 pip：`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
|
||
```
|
||
|
||
你也可以通过管道传入内容：
|
||
|
||
```bash
|
||
cat path-to-file.pdf | markitdown
|
||
```
|
||
|
||
### 可选依赖
|
||
MarkItDown 提供可选依赖以激活各种文件格式的支持。在本文档前面部分，我们通过 `[all]` 选项安装了所有可选依赖。不过，你也可以单独安装它们以获得更精细的控制。例如：
|
||
|
||
```bash
|
||
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 还支持第三方插件。插件默认处于禁用状态。要列出已安装的插件：
|
||
|
||
```bash
|
||
markitdown --list-plugins
|
||
```
|
||
|
||
要启用插件，使用：
|
||
|
||
```bash
|
||
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` 模式。无需新的机器学习库或二进制依赖。
|
||
|
||
**安装：**
|
||
|
||
```bash
|
||
pip install markitdown-ocr
|
||
pip install openai # or any OpenAI-compatible client
|
||
```
|
||
|
||
**使用方法：**
|
||
|
||
传入与你用于图像描述相同的 `llm_client` 和 `llm_model`：
|
||
|
||
```python
|
||
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`](packages/markitdown-ocr/README.md)。
|
||
|
||
### Azure 内容理解
|
||
|
||
[Azure 内容理解](https://learn.microsoft.com/azure/ai-services/content-understanding/) 提供更高质量的转换，支持结构化字段提取（YAML 前置元数据）、多模态支持（文档、图像、音频、视频）以及可配置的分析器。
|
||
|
||
安装：`pip install 'markitdown[az-content-understanding]'`
|
||
|
||
#### 何时使用内容理解
|
||
|
||
当你需要超越内置转换器或文档智能集成所提供的功能时，内容理解是理想之选：
|
||
|
||
- **音频和视频文件** — CU（内容理解）是视频的唯一选项，也是音频的更高质量云端选项。内置转换器不支持视频，且仅提供基础的音频转录。
|
||
- **结构化字段提取** — [预置](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers) 或[自定义](https://learn.microsoft.com/azure/ai-services/content-understanding/how-to/customize-analyzer-content-understanding-studio?tabs=portal) 分析器可提取领域特定字段（发票金额、收据日期、合同条款），并以 YAML 前置元数据的形式序列化输出。内置转换器和文档智能集成均不公开字段信息。
|
||
- **更高质量的文档提取** — 基于云端的布局分析和 OCR，适用于扫描版 PDF、复杂表格和多页文档。
|
||
- **所有模态的统一 API** — 一个 `cu_endpoint` 即可处理文档、图像、音频和视频，并自动进行分析器路由。
|
||
|
||
| 功能 | 内置转换器 | Azure 文档智能 | Azure 内容理解 |
|
||
|------------|---------------------|-----------------------------|-----------------------------|
|
||
| 文档转换 | 离线、按格式提取 | 云端布局提取 | 云端多模态提取 |
|
||
| 结构化字段 | 不可用 | 此集成不公开 | 来自分析器字段的 YAML 前置元数据 |
|
||
| 自定义分析器 | 不可用 | 此集成中不可配置 | 支持，使用 `cu_analyzer_id` |
|
||
| 音频和视频 | 基础音频，不支持视频 | 不支持 | 音频和视频分析器 |
|
||
| 成本 | 仅本地计算 | Azure API 调用计费 | Azure API 调用计费 |
|
||
|
||
**CLI:**
|
||
|
||
```bash
|
||
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
|
||
```
|
||
|
||
**Python API:**
|
||
|
||
```python
|
||
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)
|
||
```
|
||
|
||
**使用自定义分析器**（用于领域特定字段提取）：
|
||
|
||
```python
|
||
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：
|
||
|
||
```python
|
||
from markitdown.converters import ContentUnderstandingFileType
|
||
|
||
md = MarkItDown(
|
||
cu_endpoint="<content_understanding_endpoint>",
|
||
cu_file_types=[ContentUnderstandingFileType.PDF], # only PDFs use CU
|
||
)
|
||
```
|
||
|
||
更多关于 Azure Content Understanding 的信息，请参见[此处](https://learn.microsoft.com/azure/ai-services/content-understanding/).)。
|
||
|
||
### Azure Document Intelligence
|
||
|
||
使用 Microsoft Document Intelligence 进行转换：
|
||
|
||
```bash
|
||
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
|
||
```
|
||
|
||
更多关于如何设置 Azure Document Intelligence 资源的信息，请参见[此处](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/create-document-intelligence-resource?view=doc-intel-4.0.0))。
|
||
|
||
### Python API
|
||
|
||
Python 基本用法：
|
||
|
||
```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 转换：
|
||
|
||
```python
|
||
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``：
|
||
|
||
```python
|
||
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
|
||
|
||
```sh
|
||
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 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/).)。更多信息请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/))，或通过 [opencode@microsoft.com](mailto:opencode@microsoft.com) 联系以提出其他问题或意见。
|
||
|
||
### 如何贡献
|
||
|
||
您可以通过查看 Issue 或帮助审核 PR 来提供帮助。任何 Issue 或 PR 都欢迎，但我们也标记了一些"开放供贡献"和"开放供审核"的内容，以方便社区贡献。当然，这些都只是建议，欢迎您以任何方式贡献。
|
||
|
||
<div align="center">
|
||
|
||
| | 全部 | 特别需要社区帮助 |
|
||
| ---------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| **Issues** | [全部 Issues](https://github.com/microsoft/markitdown/issues)) | [开放供贡献的 Issues](https://github.com/microsoft/markitdown/issues?q=is%3Aissue+is%3Aopen+label%3A%22open+for+contribution%22)) |
|
||
| **PRs** | [全部 PRs](https://github.com/microsoft/markitdown/pulls)) | [开放供审核的 PRs](https://github.com/microsoft/markitdown/pulls?q=is%3Apr+is%3Aopen+label%3A%22open+for+reviewing%22)) |
|
||
|
||
</div>
|
||
|
||
### 运行测试和检查
|
||
|
||
- 进入 MarkItDown 包目录：
|
||
|
||
```sh
|
||
cd packages/markitdown
|
||
```
|
||
|
||
- 在您的环境中安装 ``hatch`` 并运行测试：
|
||
|
||
```sh
|
||
pip install hatch # 安装 hatch 的其他方式：https://hatch.pypa.io/dev/install/
|
||
hatch shell
|
||
hatch test
|
||
```
|
||
|
||
（备选）使用已安装所有依赖项的 Devcontainer：
|
||
|
||
```sh
|
||
# 在 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 商标与品牌指南](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).)。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何第三方商标或徽标的使用均须遵守第三方的政策。
|