使用 Unstructured 开源库快速入门指南

引言

本文将介绍如何使用 Unstructured 开源库（GitHub，PyPI）和 Python，在本地开发环境中将 PDF 文件拆分为标准的 Unstructured 文档元素和元数据。这些元素和元数据可用于 RAG（检索增强生成）应用、AI 代理、模型微调等任务。

前提条件

开始之前，你需要：

• Python 虚拟环境管理器：推荐使用虚拟环境管理器来管理代码依赖。本指南使用 uv 和 venv 管理虚拟环境。以下步骤将指导你安装和使用它们，但并非必需。
• Python 3.9 或更高版本：如果需要，可以使用 uv 安装指定版本的 Python。
• PDF 文件：在本地准备一个 PDF 文件。如果没有，可在后续步骤中下载示例文件 layout-parser-paper.pdf。

快速开始

1. 安装 uv

macOS 和 Linux

使用 curl 安装：

curl -fsSL https://get.uv.dev | bash

或使用 wget 安装：

wget -qO- https://astral.sh/uv/install.sh | sh

2. 安装 Python

使用 uv 查看已安装的 Python 版本：

uv python list

如果尚未安装 Python，可以使用 uv 安装。例如，安装 Python 3.12：

uv python install 3.12

3. 创建 uv 项目

导航到你的项目目录，初始化 uv 项目：

uv init

4. 创建和激活虚拟环境

创建虚拟环境

在项目目录下，使用以下命令创建虚拟环境：

# 使用当前的 Python 版本
uv venv

# 或者，指定特定的 Python 版本
uv venv --python 3.12

激活虚拟环境

• macOS 和 Linux：

  # 对于 bash 或 zsh
  source .venv/bin/activate
  
  # 对于 fish
  source .venv/bin/activate.fish
  
  # 对于 csh 或 tcsh
  source .venv/bin/activate.csh
  

随时运行 deactivate 命令退出虚拟环境。

5. 安装 Unstructured 开源库

在激活的虚拟环境中，使用 uv 安装 Unstructured 库：

uv add unstructured

上述命令支持处理纯文本（.txt）、HTML（.html）、XML（.xml）和电子邮件（.eml、.msg、.p7s）文件，无需额外依赖。

如果需要处理其他文件类型，还需要安装相应的依赖。例如，处理 PDF 文件：

uv add "unstructured[pdf]"

可用的文件类型扩展包括：

• all-docs：支持所有文件类型
• csv：仅限 .csv 文件
• docx：支持 .doc 和 .docx 文件
• epub：仅限 .epub 文件
• image：支持 .bmp、.heic、.jpeg、.png 和 .tiff 等图像文件
• md：仅限 .md 文件
• odt：仅限 .odt 文件
• org：仅限 .org 文件
• pdf：仅限 .pdf 文件
• pptx：支持 .ppt 和 .pptx 文件
• rst：仅限 .rst 文件
• rtf：仅限 .rtf 文件
• tsv：仅限 .tsv 文件
• xlsx：支持 .xls 和 .xlsx 文件

你可以同时安装多个扩展，例如：

uv add "unstructured[pdf,docx]"

6. 安装系统依赖

为确保最大兼容性，你还需要安装以下系统依赖：

• libmagic-dev：用于文件类型检测
• poppler-utils 和 tesseract-ocr：用于处理图像和 PDF 文件，以及 tesseract-lang（用于额外的语言支持）
• libreoffice：用于处理 Microsoft Office 文档
• pandoc：用于处理 .epub、.odt 和 .rtf 文件；对于 .rtf 文件，需要 2.14.2 或更高版本

安装方法因操作系统而异，请参考相关文档或操作系统的指南。

7. 下载示例 PDF 文件

下载名为 layout-parser-paper.pdf 的示例 PDF 文件到本地：

示例 PDF 文件下载链接

（你也可以使用其他想要处理的 PDF 文件。）

8. 添加 Python 代码

在项目目录下，创建 main.py 文件，添加以下代码（将 替换为示例 PDF 文件的实际路径）：

from unstructured.partition.pdf import partition_pdf
from unstructured.staging.base import elements_to_json

file_path = ""
base_file_name = "layout-parser-paper"

def main():
    elements = partition_pdf(filename=f"{file_path}/{base_file_name}.pdf")
    elements_to_json(elements=elements, filename=f"{file_path}/{base_file_name}-output.json")

if __name__ == "__main__":
    main()

如果使用其他 PDF 文件，请将 layout-parser-paper 替换为相应的文件名。

9. 运行 Python 代码

使用 uv 运行 main.py 文件：

uv run main.py

运行时间可能需要几分钟，视文件大小和系统性能而定。

10. 查看输出结果

运行成功后，打开与原始 PDF 文件相同目录下的 layout-parser-paper-output.json 文件。使用文本编辑器查看生成的 Unstructured 文档元素和元数据。

后续步骤

• 了解更多分割函数：除了 partition_pdf，Unstructured 库还提供了处理其他文件类型的分割函数，例如 partition_docx、partition_html 等。

• 探索不同的分割策略：根据文档特点，选择合适的分割策略，以获得最佳结果。

• 学习分块、清理和提取功能：使用库中的分块（chunking）、清理（cleaning）、提取（extracting）函数，进一步处理文档元素，满足特定需求。

• 生成向量嵌入：为文档元素的文本生成向量嵌入，用于 RAG 应用、AI 代理、模型微调等。

• 参考更多代码示例：参阅 Unstructured 的 Quick Tour Google Colab 笔记本。

• 使用 Docker 容器：Unstructured 开源库也可以作为 Docker 容器使用，方便部署和管理。

• 探索高级功能：了解 Unstructured Ingest CLI 和 Unstructured Ingest Python 库，了解批量文件处理、远程文件获取、ETL 管道创建等高级功能。

• 了解 Unstructured UI 和 API：它们面向生产环境，具备更高的性能和质量，支持最新的 OCR 和视觉语言模型、先进的分块策略、安全合规、多用户账户管理、作业调度和监控、自托管部署等。

---