unstructured-io--unstructured/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/Unstructured-IO/unstructured) · [上游 README](https://github.com/Unstructured-IO/unstructured/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<h3 align="center">
  <img
    src="https://raw.githubusercontent.com/Unstructured-IO/unstructured/main/img/unstructured_logo.png"
    height="200"
  >
</h3>

<div align="center">

  <a href="https://github.com/Unstructured-IO/unstructured/blob/main/LICENSE.md">![https://pypi.python.org/pypi/unstructured/](https://img.shields.io/pypi/l/unstructured.svg)</a>
  <a href="https://pypi.python.org/pypi/unstructured/">![https://pypi.python.org/pypi/unstructured/](https://img.shields.io/pypi/pyversions/unstructured.svg)</a>
  <a href="https://GitHub.com/unstructured-io/unstructured/graphs/contributors">![https://GitHub.com/unstructured-io/unstructured.js/graphs/contributors](https://img.shields.io/github/contributors/unstructured-io/unstructured)</a>
  <a href="https://github.com/Unstructured-IO/unstructured/blob/main/CODE_OF_CONDUCT.md">![code_of_conduct.md](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg) </a>
  <a href="https://GitHub.com/unstructured-io/unstructured/releases">![https://GitHub.com/unstructured-io/unstructured.js/releases](https://img.shields.io/github/release/unstructured-io/unstructured)</a>
  <a href="https://pypi.python.org/pypi/unstructured/">![https://github.com/Naereen/badges/](https://badgen.net/badge/Open%20Source%20%3F/Yes%21/blue?icon=github)</a>
  [![Downloads](https://static.pepy.tech/badge/unstructured)](https://pepy.tech/project/unstructured)
  [![Downloads](https://static.pepy.tech/badge/unstructured/month)](https://pepy.tech/project/unstructured)
  <a
   href="https://www.phorm.ai/query?projectId=34efc517-2201-4376-af43-40c4b9da3dc5">
	<img src="https://img.shields.io/badge/Phorm-Ask_AI-%23F2777A.svg?&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNSIgaGVpZ2h0PSI0IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik00LjQzIDEuODgyYTEuNDQgMS40NCAwIDAgMS0uMDk4LjQyNmMtLjA1LjEyMy0uMTE1LjIzLS4xOTIuMzIyLS4wNzUuMDktLjE2LjE2NS0uMjU1LjIyNmExLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxMmMtLjA5OS4wMTItLjE5Mi4wMTQtLjI3OS4wMDZsLTEuNTkzLS4xNHYtLjQwNmgxLjY1OGMuMDkuMDAxLjE3LS4xNjkuMjQ2LS4xOTFhLjYwMy42MDMgMCAwIDAgLjItLjEwNi41MjkuNTI5IDAgMCAwIC4xMzgtLjE3LjY1NC42NTQgMCAwIDAgLjA2NS0uMjRsLjAyOC0uMzJhLjkzLjkzIDAgMCAwLS4wMzYtLjI0OS41NjcuNTY3IDAgMCAwLS4xMDMtLjIuNTAyLjUwMiAwIDAgMC0uMTY4LS4xMzguNjA4LjYwOCAwIDAgMC0uMjQtLjA2N0wyLjQzNy43MjkgMS42MjUuNjcxYS4zMjIuMzIyIDAgMCAwLS4yMzIuMDU4LjM3NS4zNzUgMCAwIDAtLjExNi4yMzJsLS4xMTYgMS40NS0uMDU4LjY5Ny0uMDU4Ljc1NEwuNzA1IDRsLS4zNTctLjA3OUwuNjAyLjkwNkMuNjE3LjcyNi42NjMuNTc0LjczOS40NTRhLjk1OC45NTggMCAwIDEgLjI3NC0uMjg1Ljk3MS45NzEgMCAwIDEgLjMzNy0uMTRjLjExOS0uMDI2LjIyNy0uMDM0LjMyNS0uMDI2TDMuMjMyLjE2Yy4xNTkuMDE0LjMzNi4wMy40NTkuMDgyYTEuMTczIDEuMTczIDAgMCAxIC41NDUuNDQ3Yy4wNi4wOTQuMTA5LjE5Mi4xNDQuMjkzYTEuMzkyIDEuMzkyIDAgMCAxIC4wNzguNThsLS4wMjkuMzJaIiBmaWxsPSIjRjI3NzdBIi8+CiAgPHBhdGggZD0iTTQuMDgyIDIuMDA3YTEuNDU1IDEuNDU1IDAgMCAxLS4wOTguNDI3Yy0uMDUuMTI0LS4xMTQuMjMyLS4xOTIuMzI0YTEuMTMgMS4xMyAwIDAgMS0uMjU0LjIyNyAxLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxNGMtLjEuMDEyLS4xOTMuMDE0LS4yOC4wMDZsLTEuNTYtLjEwOC4wMzQtLjQwNi4wMy0uMzQ4IDEuNTU5LjE1NGMuMDkgMCAuMTczLS4wMS4yNDgtLjAzM2EuNjAzLjYwMyAwIDAgMCAuMi0uMTA2LjUzMi41MzIgMCAwIDAgLjEzOS0uMTcyLjY2LjY2IDAgMCAwIC4wNjQtLjI0MWwuMDI5LS4zMjFhLjk0Ljk0IDAgMCAwLS4wMzYtLjI1LjU3LjU3IDAgMCAwLS4xMDMtLjIwMi41MDIuNTAyIDAgMCAwLS4xNjgtLjEzOC42MDUuNjA1IDAgMCAwLS4yNC0uMDY3TDEuMjczLjgyN2MtLjA5NC0uMDA4LS4xNjguMDEtLjIyMS4wNTUtLjA1My4wNDUtLjA4NC4xMTQtLjA5Mi4yMDZMLjcwNSA0IDAgMy45MzhsLjI1NS0yLjkxMUExLjAxIDEuMDEgMCAwIDEgLjM5My41NzIuOTYyLjk2MiAwIDAgMSAuNjY2LjI4NmEuOTcuOTcgMCAwIDEgLjMzOC0uMTRDMS4xMjIuMTIgMS4yMy4xMSAxLjMyOC4xMTlsMS41OTMuMTRjLjE2LjAxNC4zLjA0Ny40MjMuMWExLjE3IDEuMTcgMCAwIDEgLjU0NS40NDhjLjA2MS4wOTUuMTA5LjE5My4xNDQuMjk1YTEuNDA2IDEuNDA2IDAgMCAxIC4wNzcuNTgzbC0uMDI4LjMyMloiIGZpbGw9IndoaXRlIi8+CiAgPHBhdGggZD0iTTQuMDgyIDIuMDA3YTEuNDU1IDEuNDU1IDAgMCAxLS4wOTguNDI3Yy0uMDUuMTI0LS4xMTQuMjMyLS4xOTIuMzI0YTEuMTMgMS4xMyAwIDAgMS0uMjU0LjIyNyAxLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxNGMtLjEuMDEyLS4xOTMuMDE0LS4yOC4wMDZsLTEuNTYtLjEwOC4wMzQtLjQwNi4wMy0uMzQ4IDEuNTU5LjE1NGMuMDkgMCAuMTczLS4wMS4yNDgtLjAzM2EuNjAzLjYwMyAwIDAgMCAuMi0uMTA2LjUzMi41MzIgMCAwIDAgLjEzOS0uMTcyLjY2LjY2IDAgMCAwIC4wNjQtLjI0MWwuMDI5LS4zMjFhLjk0Ljk0IDAgMCAwLS4wMzYtLjI1LjU3LjU3IDAgMCAwLS4xMDMtLjIwMi41MDIuNTAyIDAgMCAwLS4xNjgtLjEzOC42MDUuNjA1IDAgMCAwLS4yNC0uMDY3TDEuMjczLjgyN2MtLjA5NC0uMDA4LS4xNjguMDEtLjIyMS4wNTUtLjA1My4wNDUtLjA4NC4xMTQtLjA5Mi4yMDZMLjcwNSA0IDAgMy45MzhsLjI1NS0yLjkxMUExLjAxIDEuMDEgMCAwIDEgLjM5My41NzIuOTYyLjk2MiAwIDAgMSAuNjY2LjI4NmEuOTcuOTcgMCAwIDEgLjMzOC0uMTRDMS4xMjIuMTIgMS4yMy4xMSAxLjMyOC4xMTlsMS41OTMuMTRjLjE2LjAxNC4zLjA0Ny40MjMuMWExLjE3IDEuMTcgMCAwIDEgLjU0NS40NDhjLjA2MS4wOTUuMTA5LjE5My4xNDQuMjk1YTEuNDA2IDEuNDA2IDAgMCAxIC4wNzcuNTgzbC0uMDI4LjMyMloiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPgo=" />
   </a>

</div>

<div>
  <p align="center">
  <a
  href="https://short.unstructured.io/pzw05l7">
    <img src="https://img.shields.io/badge/JOIN US ON SLACK-4A154B?style=for-the-badge&logo=slack&logoColor=white" />
  </a>
  <a href="https://www.linkedin.com/company/unstructuredio/">
    <img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" />
  </a>
</div>

<h2 align="center">
  <p>面向非结构化数据的开源预处理工具</p>
</h2>

`unstructured` 库提供用于接入与预处理图像和文本文档的开源组件，例如 PDF、HTML、Word 文档，以及[更多格式](https://docs.unstructured.io/open-source/core-functionality/partitioning).。`unstructured` 的用例围绕简化并优化面向 LLM 的数据处理工作流。`unstructured` 的模块化函数与连接器构成一个内聚系统，简化数据接入与预处理，使其可适配不同平台，并能高效地将非结构化数据转换为结构化输出。


## Unstructured Transform MCP — 为你的智能体提供文档处理能力

Unstructured Transform 以 MCP 服务器的形式，将生产级文档处理能力带给智能体。它使智能体能够将 60 多种文件类型转换为结构化数据，可直接用于你的应用、向量数据库以及任意下游流程——通过在当前会话内直接完成文件的解析、增强、分块与嵌入。

### 为智能体配置的步骤

1. **选择你的 MCP 客户端。** Transform 几乎可与任何兼容 MCP 的宿主或智能体框架配合使用——Claude Code、Cursor、Codex CLI 等。

2. **将 Transform MCP 服务器添加**到客户端的 MCP 配置中（可通过 CLI 的 `mcp add` 命令，或客户端的 MCP 设置/配置文件，具体取决于所用工具）。

3. **在客户端提示时完成一次身份验证。** 登录后，Transform 工具会在智能体的下一条消息中可用。

4. **让智能体指向某个文件。** 拖放或引用本地文件或 URL。Transform 支持 60 多种格式（PDF、邮件、图像、扫描件等）。

5. **用自然语言描述你的需求。** 告诉智能体你的意图（例如「解析并分块这份合同，用于向量存储」），Transform 会完成文件的分区、增强、分块与嵌入，并返回可直接使用的结构化数据。

每月 15,000 页免费，超出后每页 3 美分！

📄 完整文档：https://docs.unstructured.io/transform/overview


## Unstructured Pipelines

准备将数据处理流水线推向生产，并使用高级功能？请了解 [Unstructured Platform](https://unstructured.io/enterprise).。除更好的处理性能外，还可使用分块、嵌入，以及图像与表格增强生成，全部可通过低代码 UI 或 API 完成。向我们的销售团队[申请演示](https://unstructured.io/contact)，了解如何开始使用。

## :eight_pointed_black_star: 快速开始

使用 `unstructured` 库有多种方式：
* [在容器中运行该库](https://github.com/Unstructured-IO/unstructured#run-the-library-in-a-container)，或
* 安装该库
    1. [从 PyPI 安装](https://github.com/Unstructured-IO/unstructured#installing-the-library)
    2. [本地开发安装](https://github.com/Unstructured-IO/unstructured#installation-instructions-for-local-development)
* 在 Windows 系统上使用 `conda` 安装时，请参阅[文档](https://unstructured-io.github.io/unstructured/installing.html#installation-with-conda-on-windows)

### 在容器中运行该库

以下说明旨在帮助你使用 Docker 与 `unstructured` 交互并完成上手。
若你的机器上尚未安装 Docker，请参阅[此处](https://docs.docker.com/get-docker/)。

注意：我们构建多平台镜像以同时支持 x86_64 与 Apple silicon 硬件。`docker pull` 应会为你的架构下载对应镜像，但如有需要，也可通过 `--platform` 指定（例如 `--platform linux/amd64`）。

我们会为推送到 `main` 的每次提交构建 Docker 镜像。每个镜像都会打上对应的短提交哈希标签（例如 `fbc7a69`）以及应用版本标签（例如 `0.5.5-dev1`）。我们还会将最新镜像标记为 `latest`。要利用这一点，请从我们的镜像仓库执行 `docker pull`。

```bash
docker pull downloads.unstructured.io/unstructured-io/unstructured:latest
```

拉取完成后，你可以基于该镜像创建容器并进入其 shell。

```bash
# create the container
docker run -dt --name unstructured downloads.unstructured.io/unstructured-io/unstructured:latest

# this will drop you into a bash shell where the Docker image is running
docker exec -it unstructured bash
```

你也可以自行构建 Docker 镜像。请注意，基础镜像是 `wolfi-base`，会定期更新。若在本地构建镜像，`docker-build` 可能因 `wolfi-base` 的上游变更而失败。

若你仅计划解析一种数据类型，可通过注释掉其他数据类型所需的若干包/依赖项来加快镜像构建。请查看 Dockerfile 以了解你的使用场景需要保留哪些行。

```bash
make docker-build

# this will drop you into a bash shell where the Docker image is running
make docker-start-bash
```

进入运行中的容器后，你可以直接在 Python 解释器的交互模式中尝试相关操作。
```bash
# this will drop you into a python console so you can run the below partition functions
python3

>>> from unstructured.partition.pdf import partition_pdf
>>> elements = partition_pdf(filename="example-docs/layout-parser-paper-fast.pdf")

>>> from unstructured.partition.text import partition_text
>>> elements = partition_text(filename="example-docs/fake-text.txt")
```

### 安装该库

请按以下说明安装 `unstructured` 并测试你的安装。

- 使用 `pip install "unstructured[all-docs]"` 安装 Python SDK，以支持所有文档类型
  - 对于纯文本文件、HTML、XML、JSON 以及无需额外依赖的 Email，你可以运行 `pip install unstructured`
  - 要处理其他文档类型，可安装相应文档所需的 extras，例如 `pip install "unstructured[docx,pptx]"`
- 若你的系统上尚未提供以下系统依赖，请先安装。
  具体需要哪些，取决于你要解析的文档类型，未必全部都需要。
    - `libmagic-dev`（文件类型检测）
    - `poppler-utils`（图像与 PDF）
    - `tesseract-ocr`（图像与 PDF；如需额外语言支持，请安装 `tesseract-lang`）
    - `libreoffice`（MS Office 文档）
    - `pandoc` 会通过 `pypandoc-binary` Python 包自动捆绑（无需系统级安装）

- 关于在 Windows 上的安装建议，以及了解其他功能所需的依赖，请参阅[此处](https://unstructured-io.github.io/unstructured/installing.html). 的安装文档。

至此，你应能运行以下代码：

```python
from unstructured.partition.auto import partition

elements = partition(filename="example-docs/eml/fake-email.eml")
print("\n\n".join([str(el) for el in elements]))
```

### 本地开发安装说明

若你计划为该项目贡献代码，以下说明旨在帮助你在本地安装并运行 `unstructured`。

本项目使用 [uv](https://docs.astral.sh/uv/) 进行依赖管理。请先安装它：

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

然后安装所有依赖（base、extras、dev、test 与 lint 组）：

```bash
make install
```

这会运行 `uv sync --locked --all-extras --all-groups`，它会创建虚拟环境并一步完成全部安装。无需手动创建或激活 virtualenv。

若仅需安装特定文档类型的 extras：

```bash
uv sync --extra pdf
uv sync --extra csv --extra docx
```

若在 `pyproject.toml` 中修改了依赖，要更新锁文件，请执行：

```bash
make lock
```

* 可选：
  * 若要在本地安装用于处理图像与 PDF 的 extras，请运行 `uv sync --extra pdf --extra image`。
  * 处理图像文件需要 `tesseract`。安装说明请参阅[此处](https://tesseract-ocr.github.io/tessdoc/Installation.html)。
  * 处理 PDF 文件需要 `tesseract` 与 `poppler`。[pdf2image docs](https://pdf2image.readthedocs.io/en/latest/installation.html) 提供了在各平台上安装 `poppler` 的说明。

此外，若你计划为 `unstructured` 贡献代码，我们提供了一个可选的 `pre-commit` 配置文件，以确保你的代码符合 `unstructured` 中使用的格式化与 lint 标准。
若你不希望在每次提交前自动整理代码变更，可使用 `make check` 查看是否应应用任何 lint 或格式化变更，并使用 `make tidy` 来应用它们。

若使用可选的 `pre-commit`，你只需使用 `pre-commit install` 安装 hooks，因为上文提到的 `make install` 已包含 `pre-commit` 包的安装。最后，若你决定使用 `pre-commit`，也可使用 `pre-commit uninstall` 卸载 hooks。

除在本地操作系统上开发外，我们还提供了一个借助 Docker 搭建开发环境的辅助工具：

```bash
make docker-start-dev
```

这会启动一个 Docker 容器，并将你的本地仓库挂载到 `/mnt/local_unstructured`。该 Docker 镜像可让你无需担心操作系统与仓库及其依赖的兼容性问题即可进行开发。

## :clap: Quick Tour

### 文档

更完整的文档请访问 https://docs.unstructured.io。你也可以在文档页面了解我们的其他产品，包括我们的 SaaS API。

以下是[开源文档页面](https://docs.unstructured.io/open-source/introduction/overview) 中对新用户有帮助的几页：

- [Quick Start](https://docs.unstructured.io/open-source/introduction/quick-start)
- [Using the `unstructured` open source package](https://docs.unstructured.io/open-source/core-functionality/overview)
- [Connectors](https://docs.unstructured.io/open-source/ingest/overview)
- [Concepts](https://docs.unstructured.io/open-source/concepts/document-elements)
- [Integrations](https://docs.unstructured.io/open-source/integrations)


### PDF 文档解析示例

以下示例展示如何开始使用 `unstructured` 库。在 unstructured 中解析文档的最简单方式是使用 `partition` 函数。若使用 `partition` 函数，`unstructured` 会检测文件类型并将其路由到相应的文件专用分区（partitioning）函数。若使用 `partition` 函数，你可能需要按文档类型安装额外依赖。
例如，要安装 docx 依赖，你需要运行 `pip install "unstructured[docx]"`。
更多细节请参阅我们的[安装指南](https://docs.unstructured.io/open-source/installation/full-installation)。

```python
from unstructured.partition.auto import partition

elements = partition("example-docs/layout-parser-paper.pdf")
```

运行 `print("\n\n".join([str(el) for el in elements]))` 可得到输出的字符串表示，形式如下：

```

LayoutParser : A Unified Toolkit for Deep Learning Based Document Image Analysis

Zejiang Shen 1 ( (cid:0) ), Ruochen Zhang 2 , Melissa Dell 3 , Benjamin Charles Germain Lee 4 , Jacob Carlson 3 , and
Weining Li 5

Abstract. Recent advances in document image analysis (DIA) have been primarily driven by the application of neural
networks. Ideally, research outcomes could be easily deployed in production and extended for further investigation.
However, various factors like loosely organized codebases and sophisticated model configurations complicate the easy
reuse of important innovations by a wide audience. Though there have been ongoing efforts to improve reusability and
simplify deep learning (DL) model development in disciplines like natural language processing and computer vision, none
of them are optimized for challenges in the domain of DIA. This represents a major gap in the existing toolkit, as DIA
is central to academic research across a wide range of disciplines in the social sciences and humanities. This paper
introduces LayoutParser, an open-source library for streamlining the usage of DL in DIA research and applications.
The core LayoutParser library comes with a set of simple and intuitive interfaces for applying and customizing DL models
for layout detection, character recognition, and many other document processing tasks. To promote extensibility,
LayoutParser also incorporates a community platform for sharing both pre-trained models and full document digitization
pipelines. We demonstrate that LayoutParser is helpful for both lightweight and large-scale digitization pipelines in
real-word use cases. The library is publicly available at https://layout-parser.github.io

Keywords: Document Image Analysis · Deep Learning · Layout Analysis · Character Recognition · Open Source library ·
Toolkit.

Introduction

Deep Learning(DL)-based approaches are the state-of-the-art for a wide range of document image analysis (DIA) tasks
including document image classification [11,
```

请参阅我们文档中的 [partitioning](https://docs.unstructured.io/open-source/core-functionality/partitioning)
章节，了解完整选项列表以及如何使用特定于文件的分区（partitioning）函数的说明。

## :guardsman: 安全策略

请参阅我们的 [安全策略](https://github.com/Unstructured-IO/unstructured/security/policy) for
了解如何报告安全漏洞的相关信息。

## :bug: 报告 Bug

遇到了 bug？请创建新的 [GitHub issue](https://github.com/Unstructured-IO/unstructured/issues/new/choose) and use our bug 报告模板描述问题。为帮助我们诊断问题，请使用 `python scripts/collect_env.py` 命令收集您系统的环境信息并附在报告中。您的帮助有助于我们持续改进软件——感谢！

## :books: 了解更多

| 章节 | 说明 |
|-|-|
| [Company Website](https://unstructured.io) | Unstructured.io 产品与公司信息 |
| [Documentation](https://docs.unstructured.io/) | 完整 API 文档 |
| [Batch Processing](https://github.com/Unstructured-IO/unstructured-ingest) | 通过 Unstructured 批量摄入文档 |

## :chart_with_upwards_trend: 分析

遥测（Telemetry）默认**关闭**。要选择加入（opt in），请在导入 `unstructured` 之前设置 `UNSTRUCTURED_TELEMETRY_ENABLED=true`（或 `=1`）。要选择退出（opt out），请将 `DO_NOT_TRACK` 或 `SCARF_NO_ANALYTICS` 设置为任意非空值（例如 `true`、`1`、`yes`、`false`、`0`——任意非空字符串均表示退出）；退出设置优先。若不想退出，请取消设置该变量或将其留空。请参阅我们的 [隐私政策](https://unstructured.io/privacy-policy).