docs: make Chinese README the default

This commit is contained in:
wehub-resource-sync
2026-07-13 08:58:29 +00:00
parent cfe71e4053
commit 69977fd45a
+104 -113
View File
@@ -1,49 +1,50 @@
<!-- 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
[![PyPI](https://img.shields.io/pypi/v/markitdown.svg)](https://pypi.org/project/markitdown/)
![PyPI - Downloads](https://img.shields.io/pypi/dd/markitdown)
[![Built by AutoGen Team](https://img.shields.io/badge/Built%20by-AutoGen%20Team-blue)](https://github.com/microsoft/autogen)
[![ AutoGen 团队构建](https://img.shields.io/badge/Built%20by-AutoGen%20Team-blue)](https://github.com/microsoft/autogen)
> [!IMPORTANT]
> MarkItDown performs I/O with the privileges of the current process. Like open() or requests.get(), it will access resources that the process itself can access. Sanitize your inputs in untrusted environments, and call the narrowest `convert_*` function needed for your use case (e.g., `convert_stream()`, or `convert_local()`). See the [Security Considerations](#security-considerations) section of the documentation for more information.
> MarkItDown 以当前进程的权限执行 I/O 操作。与 open() requests.get() 类似,它会访问进程自身能够访问的资源。在不受信任的环境中请对输入进行清理,并调用你的用例所需的最精简的 `convert_*` 函数(例如 `convert_stream()` `convert_local()`)。更多信息请参阅文档的[安全注意事项](#security-considerations)部分。
MarkItDown is a lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines. To this end, it is most comparable to [textract](https://github.com/deanmalmgren/textract), but with a focus on preserving important document structure and content as Markdown (including: headings, lists, tables, links, etc.) While the output is often reasonably presentable and human-friendly, it is meant to be consumed by text analysis tools -- and may not be the best option for high-fidelity document conversions for human consumption.
MarkItDown 是一个轻量级 Python 工具,用于将各种文件转换为 Markdown,以便与 LLM(大语言模型)及相关文本分析流水线配合使用。在这方面,它与 [textract](https://github.com/deanmalmgren/textract), 最为相似,但更侧重于将重要的文档结构和内容保留为 Markdown(包括:标题、列表、表格、链接等)。虽然输出结果通常具有合理的可呈现性且易于阅读,但它主要是供文本分析工具使用的——对于面向人类阅读的高保真文档转换场景,可能并非最佳选择。
MarkItDown currently supports the conversion from:
MarkItDown 目前支持从以下格式转换:
- PDF
- PowerPoint
- Word
- Excel
- Images (EXIF metadata and OCR)
- Audio (EXIF metadata and speech transcription)
- 图像(EXIF 元数据和 OCR
- 音频(EXIF 元数据和语音转录)
- HTML
- Text-based formats (CSV, JSON, XML)
- ZIP files (iterates over contents)
- Youtube URLs
- EPubs
- ... and more!
- 基于文本的格式(CSVJSONXML
- ZIP 文件(遍历内容)
- YouTube URL
- EPub
- ……以及更多!
## Why Markdown?
## 为什么选择 Markdown
Markdown is extremely close to plain text, with minimal markup or formatting, but still
provides a way to represent important document structure. Mainstream LLMs, such as
OpenAI's GPT-4o, natively "_speak_" Markdown, and often incorporate Markdown into their
responses unprompted. This suggests that they have been trained on vast amounts of
Markdown-formatted text, and understand it well. As a side benefit, Markdown conventions
are also highly token-efficient.
Markdown 极其接近纯文本,标记和格式极少,但仍能提供一种表示重要文档结构的方式。主流的 LLM,例如 OpenAI 的 GPT-4o,本身就"说" Markdown,并且经常在未经提示的情况下将 Markdown 融入其响应中。这表明它们在海量的 Markdown 格式文本上进行了训练,并对其理解深刻。作为附带好处,Markdown 惯例在 token 效率方面也非常高。
## Prerequisites
MarkItDown requires Python 3.10 or higher. It is recommended to use a virtual environment to avoid dependency conflicts.
## 前置条件
MarkItDown 需要 Python 3.10 或更高版本。建议使用虚拟环境以避免依赖冲突。
With the standard Python installation, you can create and activate a virtual environment using the following commands:
使用标准 Python 安装,你可以通过以下命令创建并激活虚拟环境:
```bash
python -m venv .venv
source .venv/bin/activate
```
If using `uv`, you can create a virtual environment with:
如果使用 `uv`,可以这样创建虚拟环境:
```bash
uv venv --python=3.12 .venv
@@ -51,16 +52,16 @@ source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment
```
If you are using Anaconda, you can create a virtual environment with:
如果你使用 Anaconda,可以这样创建虚拟环境:
```bash
conda create -n markitdown python=3.12
conda activate markitdown
```
## Installation
## 安装
To install MarkItDown, use pip: `pip install 'markitdown[all]'`. Alternatively, you can install it from the source:
要安装 MarkItDown,使用 pip`pip install 'markitdown[all]'`。或者,你也可以从源码安装:
```bash
git clone git@github.com:microsoft/markitdown.git
@@ -68,79 +69,79 @@ cd markitdown
pip install -e 'packages/markitdown[all]'
```
## Usage
## 使用方法
### Command-Line
### 命令行
```bash
markitdown path-to-file.pdf > document.md
```
Or use `-o` to specify the output file:
或使用 `-o` 来指定输出文件:
```bash
markitdown path-to-file.pdf -o document.md
```
You can also pipe content:
你也可以通过管道传入内容:
```bash
cat path-to-file.pdf | markitdown
```
### Optional Dependencies
MarkItDown has optional dependencies for activating various file formats. Earlier in this document, we installed all optional dependencies with the `[all]` option. However, you can also install them individually for more control. For example:
### 可选依赖
MarkItDown 提供可选依赖以激活各种文件格式的支持。在本文档前面部分,我们通过 `[all]` 选项安装了所有可选依赖。不过,你也可以单独安装它们以获得更精细的控制。例如:
```bash
pip install 'markitdown[pdf, docx, pptx]'
```
will install only the dependencies for PDF, DOCX, and PPTX files.
将仅安装 PDFDOCX PPTX 文件所需的依赖。
At the moment, the following optional dependencies are available:
目前,有以下可选依赖可用:
* `[all]` Installs all optional dependencies
* `[pptx]` Installs dependencies for PowerPoint files
* `[docx]` Installs dependencies for Word files
* `[xlsx]` Installs dependencies for Excel files
* `[xls]` Installs dependencies for older Excel files
* `[pdf]` Installs dependencies for PDF files
* `[outlook]` Installs dependencies for Outlook messages
* `[az-doc-intel]` Installs dependencies for Azure Document Intelligence
* `[az-content-understanding]` Installs dependencies for Azure Content Understanding
* `[audio-transcription]` Installs dependencies for audio transcription of wav and mp3 files
* `[youtube-transcription]` Installs dependencies for fetching YouTube video transcription
* `[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 视频转录所需的依赖
### Plugins
### 插件
MarkItDown also supports 3rd-party plugins. Plugins are disabled by default. To list installed plugins:
MarkItDown 还支持第三方插件。插件默认处于禁用状态。要列出已安装的插件:
```bash
markitdown --list-plugins
```
To enable plugins use:
要启用插件,使用:
```bash
markitdown --use-plugins path-to-file.pdf
```
To find available plugins, search GitHub for the hashtag `#markitdown-plugin`. To develop a plugin, see `packages/markitdown-sample-plugin`.
要查找可用的插件,请在 GitHub 上搜索标签 `#markitdown-plugin`。要开发插件,请参阅 `packages/markitdown-sample-plugin`
#### markitdown-ocr Plugin
#### markitdown-ocr 插件
The `markitdown-ocr` plugin adds OCR support to PDF, DOCX, PPTX, and XLSX converters, extracting text from embedded images using LLM Vision — the same `llm_client` / `llm_model` pattern that MarkItDown already uses for image descriptions. No new ML libraries or binary dependencies required.
`markitdown-ocr` 插件为 PDFDOCXPPTX XLSX 转换器增加了 OCR 支持,使用 LLM Vision 从嵌入图像中提取文本——采用与 MarkItDown 已有的图像描述功能相同的 `llm_client` / `llm_model` 模式。无需新的机器学习库或二进制依赖。
**Installation:**
**安装:**
```bash
pip install markitdown-ocr
pip install openai # or any OpenAI-compatible client
```
**Usage:**
**使用方法:**
Pass the same `llm_client` and `llm_model` you would use for image descriptions:
传入与你用于图像描述相同的 `llm_client` `llm_model`
```python
from markitdown import MarkItDown
@@ -155,32 +156,32 @@ result = md.convert("document_with_images.pdf")
print(result.text_content)
```
If no `llm_client` is provided the plugin still loads, but OCR is silently skipped and the standard built-in converter is used instead.
如果未提供 `llm_client`,插件仍会加载,但 OCR 会被静默跳过,转而使用标准的内置转换器。
See [`packages/markitdown-ocr/README.md`](packages/markitdown-ocr/README.md) for detailed documentation.
详细文档请参阅 [`packages/markitdown-ocr/README.md`](packages/markitdown-ocr/README.md)
### Azure Content Understanding
### Azure 内容理解
[Azure Content Understanding](https://learn.microsoft.com/azure/ai-services/content-understanding/) provides higher-quality conversion with structured field extraction (YAML front matter), multi-modal support (documents, images, audio, video), and configurable analyzers.
[Azure 内容理解](https://learn.microsoft.com/azure/ai-services/content-understanding/) 提供更高质量的转换,支持结构化字段提取(YAML 前置元数据)、多模态支持(文档、图像、音频、视频)以及可配置的分析器。
Install: `pip install 'markitdown[az-content-understanding]'`
安装:`pip install 'markitdown[az-content-understanding]'`
#### When to use Content Understanding
#### 何时使用内容理解
Content Understanding is ideal when you need capabilities beyond what built-in or Document Intelligence converters provide:
当你需要超越内置转换器或文档智能集成所提供的功能时,内容理解是理想之选:
- **Audio and video files** — CU is the only option for video, and the higher-quality cloud option for audio. Built-in converters have no video support and only basic audio transcription.
- **Structured field extraction** — [Prebuilt](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers) or [custom-built](https://learn.microsoft.com/azure/ai-services/content-understanding/how-to/customize-analyzer-content-understanding-studio?tabs=portal) analyzers extract domain-specific fields (invoice amounts, receipt dates, contract clauses) serialized as YAML front matter. Neither built-in nor Doc Intel integration exposes fields.
- **Higher-quality document extraction** — Cloud-based layout analysis and OCR for scanned PDFs, complex tables, and multi-page documents.
- **Single API for all modalities** — One `cu_endpoint` handles documents, images, audio, and video with automatic analyzer routing.
- **音频和视频文件** — 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` 即可处理文档、图像、音频和视频,并自动进行分析器路由。
| Capability | Built-in converters | Azure Document Intelligence | Azure Content Understanding |
| 功能 | 内置转换器 | Azure 文档智能 | Azure 内容理解 |
|------------|---------------------|-----------------------------|-----------------------------|
| Document conversion | Offline, format-specific extraction | Cloud layout extraction | Cloud multimodal extraction |
| Structured fields | Not available | Not exposed by this integration | YAML front matter from analyzer fields |
| Custom analyzers | Not available | Not configurable in this integration | Supported with `cu_analyzer_id` |
| Audio and video | Basic audio, no video | Not supported | Audio and video analyzers |
| Cost | Local compute only | Billable Azure API calls | Billable Azure API calls |
| 文档转换 | 离线、按格式提取 | 云端布局提取 | 云端多模态提取 |
| 结构化字段 | 不可用 | 此集成不公开 | 来自分析器字段的 YAML 前置元数据 |
| 自定义分析器 | 不可用 | 此集成中不可配置 | 支持,使用 `cu_analyzer_id` |
| 音频和视频 | 基础音频,不支持视频 | 不支持 | 音频和视频分析器 |
| 成本 | 仅本地计算 | Azure API 调用计费 | Azure API 调用计费 |
**CLI:**
@@ -201,7 +202,7 @@ result = md.convert("call.wav") # audio → prebuilt-audioSearch
print(result.markdown)
```
**With a custom analyzer** (for domain-specific field extraction):
**使用自定义分析器**(用于领域特定字段提取):
```python
md = MarkItDown(
@@ -221,9 +222,9 @@ print(result.markdown)
# ...
```
When `cu_analyzer_id` is set, the converter automatically scopes it to compatible file types based on the analyzer's modality. Incompatible types (e.g., audio files with a document analyzer) auto-route to default prebuilt analyzers.
当设置 ``cu_analyzer_id`` 时,转换器会根据分析器的模态自动将其限定为兼容的文件类型。不兼容的类型(例如,使用文档分析器处理音频文件)会自动路由到默认的预构建分析器。
**Cost note:** Each `convert()` call for a CU-routed format is a billable Azure API call. Use `cu_file_types` to restrict which formats route to CU:
**费用说明:** 每次对 CU 路由格式的 ``convert()`` 调用均为一次计费的 Azure API 调用。使用 ``cu_file_types`` 可限制哪些格式路由到 CU
```python
from markitdown.converters import ContentUnderstandingFileType
@@ -234,21 +235,21 @@ md = MarkItDown(
)
```
More information about Azure Content Understanding can be found [here](https://learn.microsoft.com/azure/ai-services/content-understanding/).
更多关于 Azure Content Understanding 的信息,请参见[此处](https://learn.microsoft.com/azure/ai-services/content-understanding/).)。
### Azure Document Intelligence
To use Microsoft Document Intelligence for conversion:
使用 Microsoft Document Intelligence 进行转换:
```bash
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
```
More information about how to set up an Azure Document Intelligence Resource can be found [here](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/create-document-intelligence-resource?view=doc-intel-4.0.0)
更多关于如何设置 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
Basic usage in Python:
Python 基本用法:
```python
from markitdown import MarkItDown
@@ -258,7 +259,7 @@ result = md.convert("test.xlsx")
print(result.text_content)
```
Document Intelligence conversion in Python:
Python 中的 Document Intelligence 转换:
```python
from markitdown import MarkItDown
@@ -268,7 +269,7 @@ result = md.convert("test.pdf")
print(result.text_content)
```
To use Large Language Models for image descriptions (currently only for pptx and image files), provide `llm_client` and `llm_model`:
如需使用大语言模型生成图片描述(目前仅支持 pptx 和图片文件),请提供 ``llm_client`` 和 ``llm_model``
```python
from markitdown import MarkItDown
@@ -287,74 +288,64 @@ docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
```
## Contributing
## 贡献
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议(CLA),声明您有权且确实授予我们使用您贡献的权利。详情请访问 https://cla.opensource.microsoft.com.。
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.
当您提交拉取请求(Pull Request)时,CLA 机器人会自动判断您是否需要提供 CLA,并适当装饰 PR(例如状态检查、评论)。只需按照机器人提供的说明操作即可。您只需在所有使用我们 CLA 的仓库中执行一次。
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
本项目已采用 [Microsoft 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/).)。更多信息请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/)),或通过 [opencode@microsoft.com](mailto:opencode@microsoft.com) 联系以提出其他问题或意见。
### How to Contribute
### 如何贡献
You can help by looking at issues or helping review PRs. Any issue or PR is welcome, but we have also marked some as 'open for contribution' and 'open for reviewing' to help facilitate community contributions. These are of course just suggestions and you are welcome to contribute in any way you like.
您可以通过查看 Issue 或帮助审核 PR 来提供帮助。任何 Issue PR 都欢迎,但我们也标记了一些"开放供贡献"和"开放供审核"的内容,以方便社区贡献。当然,这些都只是建议,欢迎您以任何方式贡献。
<div align="center">
| | All | Especially Needs Help from Community |
| | 全部 | 特别需要社区帮助 |
| ---------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Issues** | [All Issues](https://github.com/microsoft/markitdown/issues) | [Issues open for contribution](https://github.com/microsoft/markitdown/issues?q=is%3Aissue+is%3Aopen+label%3A%22open+for+contribution%22) |
| **PRs** | [All PRs](https://github.com/microsoft/markitdown/pulls) | [PRs open for reviewing](https://github.com/microsoft/markitdown/pulls?q=is%3Apr+is%3Aopen+label%3A%22open+for+reviewing%22) |
| **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>
### Running Tests and Checks
### 运行测试和检查
- Navigate to the MarkItDown package:
- 进入 MarkItDown 包目录:
```sh
cd packages/markitdown
```
- Install `hatch` in your environment and run tests:
- 在您的环境中安装 ``hatch`` 并运行测试:
```sh
pip install hatch # Other ways of installing hatch: https://hatch.pypa.io/dev/install/
pip install hatch # 安装 hatch 的其他方式:https://hatch.pypa.io/dev/install/
hatch shell
hatch test
```
(Alternative) Use the Devcontainer which has all the dependencies installed:
(备选)使用已安装所有依赖项的 Devcontainer
```sh
# Reopen the project in Devcontainer and run:
# Devcontainer 中重新打开项目,然后运行:
hatch test
```
- Run pre-commit checks before submitting a PR: `pre-commit run --all-files`
- 在提交 PR 前运行 pre-commit 检查:``pre-commit run --all-files``
### Security Considerations
### 安全注意事项
MarkItDown performs I/O with the privileges of the current process. Like `open()` or `requests.get()`, it will access resources that the process itself can access.
MarkItDown 以当前进程的权限执行 I/O 操作。与 ``open()`` ``requests.get()`` 类似,它可以访问进程本身能访问的资源。
**Sanitize your inputs:** Do not pass untrusted input directly to MarkItDown. If any part of the input may be controlled by an untrusted user or system, such as in hosted or server-side applications, it must be validated and restricted before calling MarkItDown. Depending on your environment, this may include restricting file paths, limiting URI schemes and network destinations, and blocking access to private, loopback, link-local, or metadata-service addresses.
**对输入进行消毒:** 不要将不受信任的输入直接传递给 MarkItDown。如果输入的任何部分可能受不受信任的用户或系统控制(例如在托管或服务端应用中),则必须在调用 MarkItDown 之前对其进行验证和限制。根据您的环境,这可能包括限制文件路径、限制 URI 方案和网络目标,以及阻止访问私有地址、环回地址、链路本地地址或元数据服务地址。
**Call only the conversion method you need:** Prefer the narrowest conversion API that fits your use case. MarkItDown's `convert()` method is intentionally permissive and can handle local files, remote URIs, and byte streams. If your application only needs to read local files, call `convert_local()` instead. If you need more control over URI fetching, call `requests.get()` yourself and pass the response object to `convert_response()`. For maximum control, open a stream to the input you want converted and call `convert_stream()`.
**仅调用您需要的转换方法:** 优先使用最适合您用例的最小转换 API。MarkItDown ``convert()`` 方法设计上较为宽松,可以处理本地文件、远程 URI 和字节流。如果您的应用程序只需要读取本地文件,请改用 ``convert_local()``。如果您需要对 URI 获取进行更多控制,请自行调用 ``requests.get()``,并将响应对象传递给 ``convert_response()``。如需最大程度的控制,请打开要转换的输入流,然后调用 ``convert_stream()``
### Contributing 3rd-party Plugins
### 贡献第三方插件
You can also contribute by creating and sharing 3rd party plugins. See `packages/markitdown-sample-plugin` for more details.
您还可以通过创建和分享第三方插件来贡献。更多详情请参见 ``packages/markitdown-sample-plugin``。
## Trademarks
## 商标
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.
本项目可能包含项目、产品或服务的商标或徽标。对 Microsoft 商标或徽标的授权使用必须遵守并遵循 [Microsoft 商标与品牌指南](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).)。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何第三方商标或徽标的使用均须遵守第三方的政策。