Open-Source Pre-Processing Tools for Unstructured Data

The unstructured library provides open-source components for ingesting and pre-processing images and text documents, such as PDFs, HTML, Word docs, and many more. The use cases of unstructured revolve around streamlining and optimizing the data processing workflow for LLMs. unstructured modular functions and connectors form a cohesive system that simplifies data ingestion and pre-processing, making it adaptable to different platforms and efficient in transforming unstructured data into structured outputs.

Try the Unstructured Platform Product

Ready to move your data processing pipeline to production, and take advantage of advanced features? Check out Unstructured Platform. In addition to better processing performance, take advantage of chunking, embedding, and image and table enrichment generation, all from a low code UI or an API. Request a demo from our sales team to learn more about how to get started.

:eight_pointed_black_star: Quick Start

There are several ways to use the unstructured library:

• Run the library in a container or
• Install the library
  1. Install from PyPI
  2. Install for local development
• For installation with conda on Windows system, please refer to the documentation

在容器中运行该库

以下说明旨在帮助您使用 Docker 与 unstructured 进行交互。如果您尚未在本地安装 Docker，请参阅 此处。

注意：我们构建了多平台镜像，以支持 x86_64 和 Apple Silicon 硬件。docker pull 应会下载适合您架构的镜像，但如有需要，您也可以通过 --platform 参数指定（例如 --platform linux/amd64）。

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

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

拉取完成后，您可以基于此镜像创建一个容器，并进入该容器的 Shell。

# 创建容器
docker run -dt --name unstructured downloads.unstructured.io/unstructured-io/unstructured:latest

# 这将带您进入正在运行 Docker 镜像的 Bash Shell
docker exec -it unstructured bash

您也可以自行构建 Docker 镜像。请注意，基础镜像是 wolfi-base，它会定期更新。如果您在本地构建镜像，由于 wolfi-base 的上游变更，docker build 可能会失败。

如果您只打算解析一种类型的数据，可以通过注释掉其他数据类型所需的某些包或依赖项来加快镜像构建速度。请参考 Dockerfile，了解哪些行对您的用例是必要的。

make docker-build

# 这将带您进入正在运行 Docker 镜像的 Bash Shell
make docker-start-bash

进入运行中的容器后，您可以直接在 Python 解释器的交互模式下尝试操作。

# 这将带您进入 Python 控制台，以便运行下面的分区函数
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 和电子邮件，您可以直接运行 pip install unstructured。
  • 若要处理其他类型的文档，可以安装这些文档所需的附加组件，例如 pip install "unstructured[docx,pptx]"。

• 如果您的系统尚未安装以下系统依赖项，请进行安装。根据您解析的文档类型，可能并不需要全部依赖项：

  • libmagic-dev（文件类型检测）
  • poppler-utils（图像和 PDF）
  • tesseract-ocr（图像和 PDF；安装 tesseract-lang 可获得额外的语言支持）
  • libreoffice（MS Office 文档）
  • pandoc 会通过 pypandoc-binary Python 包自动打包，无需单独安装。

• 关于如何在 Windows 上安装以及了解其他功能的依赖项，请参阅安装文档 此处。

此时，您应该能够运行以下代码：

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 进行依赖管理。请先安装它：

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

然后安装所有依赖项（基础、附加、开发、测试和 lint 组）：

make install

这会运行 uv sync --locked --all-extras --all-groups，从而一步创建虚拟环境并安装所有内容。无需手动创建或激活虚拟环境。

如果仅需安装特定文档类型的附加组件：

uv sync --extra pdf
uv sync --extra csv --extra docx

在更改 pyproject.toml 中的依赖项后，更新锁定文件：

make lock

• 可选：
  • 要在本地安装用于处理图像和 PDF 的附加组件，可运行 uv sync --extra pdf --extra image。
  • 处理图像文件时，需要 tesseract。安装说明请参见 此处。
  • 处理 PDF 文件时，需要 tesseract 和 poppler。pdf2image 文档 提供了在不同平台上安装 poppler 的说明。

此外，如果您计划为 unstructured 做出贡献，我们还提供了一个可选的 pre-commit 配置文件，以确保您的代码符合 unstructured 中使用的格式和 lint 标准。如果您不希望每次提交前自动整理代码，可以使用 make check 来查看是否需要进行 lint 或格式化调整，并使用 make tidy 来应用这些调整。

如果使用可选的 pre-commit，只需运行 pre-commit install 即可安装钩子，因为 pre-commit 包已在上述 make install 中一并安装。最后，如果您决定使用 pre-commit，也可以通过 pre-commit uninstall 来卸载这些钩子。

除了在本地操作系统中开发之外，我们还提供了一个辅助工具，即使用 Docker 提供开发环境：

make docker-start-dev

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

:clap: 快速游览

文档

如需更全面的文档，请访问 https://docs.unstructured.io 。您还可以在文档页面上了解更多关于我们其他产品的信息，包括我们的 SaaS API。

以下是 开源文档页面 中对新用户有帮助的一些页面：

• 快速入门
• 使用 unstructured 开源软件包
• 连接器
• 概念
• 集成

PDF 文档解析示例

以下示例展示了如何开始使用 unstructured 库。在 unstructured 中解析文档最简单的方式是使用 partition 函数。如果使用 partition 函数，unstructured 会自动检测文件类型，并将其路由到相应的特定于文件类型的分割函数。如果您使用 partition 函数，可能需要根据文档类型安装额外的依赖项。 例如，要安装 docx 的依赖项，您需要运行 pip install "unstructured[docx]"。 更多详细信息请参阅我们的 安装指南。

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：基于深度学习的文档图像分析统一工具包

沈泽江 1 ( (cid:0) ), 张若晨 2 , 梅丽莎·戴尔 3 , 本杰明·查尔斯·热姆·李 4 , 雅各布·卡尔森 3 , 和 李伟宁 5

摘要。近年来，文档图像分析（DIA）领域的进步主要得益于神经网络的应用。理想情况下，研究成果应能轻松部署到生产环境中，并为进一步研究提供扩展性。然而，代码库组织松散、模型配置复杂等多种因素，使得重要创新难以被广泛用户群体重复使用。尽管自然语言处理和计算机视觉等领域一直在努力提高可复用性并简化深度学习（DL）模型开发，但这些方法并未针对 DIA 领域的挑战进行优化。这构成了现有工具集中的一个重大缺口，因为 DIA 在社会科学和人文学科的众多研究领域中占据核心地位。本文介绍了 LayoutParser，一个开源库，旨在简化深度学习在 DIA 研究和应用中的使用。LayoutParser 核心库提供了一组简单直观的接口，用于应用和定制深度学习模型，以实现版面检测、字符识别以及许多其他文档处理任务。为促进扩展性，LayoutParser 还整合了一个社区平台，用于共享预训练模型和完整的文档数字化流水线。我们证明了 LayoutParser 对于实际应用场景中的轻量级和大规模数字化流水线均有所帮助。该库已在 https://layout-parser.github.io 上公开发布。

关键词：文档图像分析 · 深度学习 · 版面分析 · 字符识别 · 开源库 · 工具包。

引言

基于深度学习（DL）的方法已成为多种文档图像分析（DIA）任务的最先进手段，包括文档图像分类 [11,

有关完整选项列表及如何使用特定于文件类型的分割函数的说明，请参阅我们文档中的 分割 部分。

:guardsman: 安全政策

有关如何报告安全漏洞的信息，请参阅我们的 安全政策。

:bug: 报告错误

遇到错误了吗？请创建一个新的 GitHub 问题，并使用我们的错误报告模板描述问题。为了帮助我们诊断问题，请使用 python scripts/collect_env.py 命令收集您的系统环境信息，并将其包含在报告中。您的帮助将有助于我们不断改进软件——感谢您！

:books: 了解更多

版块	描述
公司官网	Unstructured.io 产品及公司信息
文档	完整的 API 文档
批量处理	通过 Unstructured 批量导入文档

:chart_with_upwards_trend: 分析

遥测功能 默认关闭。如需启用，请在导入 unstructured 之前设置 UNSTRUCTURED_TELEMETRY_ENABLED=true（或 =1）。如需禁用，请将 DO_NOT_TRACK 或 SCARF_NO_ANALYTICS 设置为任意非空值（例如 true、1、yes、false、0——任何非空字符串都会禁用遥测功能）；禁用优先于启用。如果您不想禁用遥测功能，可以不设置该变量或将其留空。详情请参阅我们的 隐私政策。

Unstructured 快速上手指南

unstructured 是一个开源的非结构化数据预处理工具库，专为大语言模型（LLM）设计。它能高效地将 PDF、HTML、Word 文档、图片等非结构化数据转换为结构化输出，简化数据摄入和清洗流程。

环境准备

在开始之前，请确保您的系统满足以下要求并安装了必要的系统依赖。根据您的使用场景（处理的文件类型），可能需要安装不同的依赖包。

系统要求

• Python 3.8+
• 操作系统：Linux, macOS, Windows (Windows 用户建议参考官方文档使用 Conda 或 Docker)

前置系统依赖

如果您计划处理多种文档格式（如 PDF、图片、Office 文档），请在安装 Python 包前先安装以下系统级依赖：

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y libmagic-dev poppler-utils tesseract-ocr libreoffice pandoc
# 如需更多语言支持，可安装 tesseract-lang

macOS (使用 Homebrew):

brew install libmagic poppler tesseract libreoffice pandoc

注意：

• libmagic-dev: 用于文件类型检测
• poppler-utils: 用于处理图片和 PDF
• tesseract-ocr: 用于 OCR 文字识别（图片和 PDF）
• libreoffice: 用于处理 MS Office 文档
• pandoc: Python 包 pypandoc-binary 会自动捆绑，通常无需手动安装系统版。

安装步骤

您可以选择直接通过 PyPI 安装，或使用 Docker 容器运行。

方式一：使用 Pip 安装（推荐）

1. 全功能安装 支持所有文档类型（PDF, Word, PPT, 图片等）：

pip install "unstructured[all-docs]"

2. 按需安装 如果仅处理纯文本、HTML、JSON 或邮件，无需额外依赖：

pip install unstructured

如果只需处理特定格式（例如仅 Word 和 PPT）：

pip install "unstructured[docx,pptx]"

方式二：使用 Docker 运行

如果您希望避免配置系统依赖，可以直接拉取官方镜像：

# 拉取最新镜像
docker pull downloads.unstructured.io/unstructured-io/unstructured:latest

# 创建并启动容器
docker run -dt --name unstructured downloads.unstructured.io/unstructured-io/unstructured:latest

# 进入容器交互界面
docker exec -it unstructured bash

基本使用

安装完成后，您可以使用 partition 函数自动识别文件类型并进行解析。以下是最简单的使用示例：

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

针对特定文件类型的用法

您也可以直接调用特定格式的解析函数：

# 解析 PDF
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")

解析后的 elements 对象包含文档的结构化块（如标题、段落、表格等），可直接用于后续的 LLM 嵌入或向量数据库存储。