【Python】unstructured 库：处理和预处理非结构化数据（如 PDF、Word 文档、HTML、图片等），转换为结构化格式

unstructured 是一个 Python 开源库，设计用于处理和预处理非结构化数据（如 PDF、Word 文档、HTML、图片等），将其转换为结构化格式，方便下游机器学习（ML）或大语言模型（LLM）任务。它提供模块化的组件（称为“bricks”），支持文档分区、清理和格式化，广泛应用于数据管道、RAG（Retrieval-Augmented Generation）系统和文档分析。

以下是对 unstructured 库的详细介绍，包括其功能、用法和实际应用，结合近期信息（截至 2025）。

---

1. unstructured 库的作用

• 非结构化数据处理：将复杂文档（如 PDF、DOCX、HTML）拆分为结构化元素（如标题、段落、列表、表格）。
• 模块化设计：提供分区（partitioning）、清理（cleaning）和格式化（staging）组件，灵活构建数据处理管道。
• 多格式支持：支持 25+ 文件类型，包括 TXT、PDF、DOCX、PPTX、HTML、JPG、PNG、EML、CSV、EPUB 等。
• AI/LLM 集成：优化数据预处理，生成 LLM 友好的 JSON 格式，适用于 RAG、数据标注和模型训练。
• 本地和云端支持：提供本地处理和 Serverless API（需 API 密钥），兼顾性能和易用性。
• 开源与商业产品：核心库开源（Apache 2 许可证），另有付费 API 和平台增强功能。

近期动态：

• 最新版本（截至 2025-03-19）：0.16.17，提供更高效的预处理性能。
• 新增 Serverless API，支持更快、更适合生产环境的处理。
• 与 LangChain 集成，通过 UnstructuredLoader 简化数据加载。

---

2. 安装与环境要求

• Python 版本：支持 Python 3.8+（推荐 3.9+）。
• 核心依赖：
  • beautifulsoup4：HTML 解析。
  • lxml：XML 处理。
  • nltk：文本处理。
  • 可选：tesseract（OCR）、poppler（PDF 处理）、pandoc（EPUB/RTF）。
• 安装命令：
  • 基本安装（不含 PDF/图片处理）：

    pip install unstructured
    

  • 完整安装（含本地推理依赖，如 PDF 和图片处理）：

    pip install "unstructured[local-inference]"
    

  • 特定文档类型（如 DOCX）：

    pip install "unstructured[docx]"
    

  • 使用 Serverless API：

    pip install unstructured-client
    

• 系统依赖（本地处理 PDF/图片）：
  • Tesseract：用于 OCR，安装指南：https://tesseract-ocr.github.io/。
  • Poppler：PDF 处理，参考 pdf2image 文档：https://pdf2image.readthedocs.io/。
  • Pandoc：处理 EPUB、RTF 等，需版本 2.14.2+。
  • libmagic：文件类型检测（Linux/Mac 需安装）。

    # Mac
    brew install libmagic
    # Ubuntu
    sudo apt-get install libmagic1
    

• 验证安装：

  import unstructured
  print(unstructured.__version__)  # 示例输出: 0.16.17
  

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

• 可自定义 Dockerfile，注释不需要的依赖以加速构建。

---

3. 核心功能与用法

unstructured 的核心是通过“bricks”处理文档，分为分区、清理和格式化三大类。以下是主要功能和示例。

3.1 分区（Partitioning Bricks）

将文档拆分为结构化元素（如标题、段落、表格），支持自动文件类型检测。

from unstructured.partition.auto import partition

# 解析 PDF 文件
elements = partition(filename="example.pdf")
for element in elements[:5]:
    print(f"{element.category}: {element.text}")

输出示例：

Title: Introduction
NarrativeText: This is the first paragraph...
ListItem: - Item 1

说明：

• partition 自动检测文件类型，调用特定分区函数（如 partition_pdf、partition_docx）。
• 支持的文件类型：TXT、PDF、DOCX、PPTX、HTML、JPG、PNG、EML、CSV、EPUB 等。
• 返回 Element 对象列表，包含类别（Title、NarrativeText、ListItem、Table 等）和元数据。

特定文件类型分区：

from unstructured.partition.pdf import partition_pdf

# 高分辨率解析（包含表格）
elements = partition_pdf(filename="example.pdf", strategy="hi_res")

说明：

• strategy="hi_res" 使用计算机视觉和 OCR 提取表格，适合复杂 PDF。
• 需安装 tesseract 和 poppler。

3.2 清理（Cleaning Bricks）

移除无关内容，如样板文本、标点或句段碎片。

from unstructured.cleaners.core import clean, remove_punctuation

text = "Hello, World!!! This is a test..."
cleaned_text = clean(text, lowercase=True)  # 转换为小写并清理
cleaned_text = remove_punctuation(cleaned_text)  # 移除标点
print(cleaned_text)  # 输出: hello world this is a test

说明：

• 支持清理操作：小写转换、移除标点、删除样板文本等。
• 可与分区结果结合，处理提取的 Element 文本。

3.3 格式化（Staging Bricks）

将数据格式化为下游任务的输入，如 JSON 或 LLM 训练数据。

from unstructured.staging.base import convert_to_dict

# 转换为 JSON
elements = partition(filename="example.docx")
json_data = convert_to_dict(elements)
print(json_data[:2])  # 输出前两个元素

输出示例：

[
  {"type": "Title", "text": "Introduction", "metadata": {...}},
  {"type": "NarrativeText", "text": "This is the first paragraph...", "metadata": {...}}
]

说明：

• convert_to_dict 将元素列表转为 JSON，适合 LLM 或数据分析。
• 支持其他格式化函数，如 stage_for_transformers（Hugging Face 集成）。

3.4 LangChain 集成

与 LangChain 配合，通过 UnstructuredLoader 加载文档。

from langchain_unstructured import UnstructuredLoader

# 本地加载
loader = UnstructuredLoader(file_path="example.pdf")
docs = loader.load()
print(docs[0].page_content[:100])  # 输出提取的文本

# 使用 Serverless API
loader = UnstructuredLoader(
    file_path="example.pdf",
    api_key="your_api_key",
    strategy="hi_res"
)
docs = loader.load()

说明：

• 本地加载需安装 unstructured 和 langchain_unstructured 。
• Serverless API 需安装unstructured-client 和 langchain_unstructured ，以及 API 密钥（可从 https://unstructured.io/ 获取）。
• 支持多种文件类型加载器，如 UnstructuredCSVLoader、UnstructuredHTMLLoader 等。

3.5 使用 Serverless API

通过 API 进行高效处理，减少本地依赖。

from unstructured_client import UnstructuredClient

client = UnstructuredClient(api_key_auth="your_api_key")
with open("example.pdf", "rb") as f:
    response = client.general.partition(file=f, strategy="hi_res")
print(response.elements[:2])

说明：

• 需安装 unstructured-client。
• Serverless API 提供更高性能，适合生产环境。

3.6 Docker 部署

在 Docker 容器中运行 unstructured。

# 在容器内运行 Python 脚本
from unstructured.partition.auto import partition

elements = partition(filename="/data/example.pdf")
print([str(el) for el in elements[:5]])

说明：

• 使用官方 Docker 镜像，简化环境配置。
• 支持多平台（x86_64 和 Apple Silicon）。

---

4. 性能与特点

• 高效性：模块化设计，灵活组合处理步骤。
• 多格式支持：覆盖常见文档和图片格式，减少格式转换需求。
• 易用性：partition 函数一键解析，降低学习曲线。
• 社区支持：活跃的 GitHub 仓库（6K+ 星，截至 2024）。
• 局限性：
  • DOCX 解析可能误识列表项为标题或段落。
  • 大型文档缺乏父子关系标注，影响 LLM 上下文理解。
  • 本地处理需安装较多依赖（如 tesseract、poppler）。
• 隐私与分析：
  • 包含轻量级分析“ping”，可通过设置环境变量 DO_NOT_TRACK=true 禁用。
  • 另可设置 SCARF_NO_ANALYTICS=true 禁用 Scarf 统计。

与替代方案对比：

• python-docx/pdfplumber：专注于单一格式，功能有限。
• LangChain 内置加载器：依赖 unstructured，但封装更简单。
• extractous：号称比 unstructured 快 25 倍，支持类似格式，但生态较新。

---

5. 实际应用场景

• RAG 系统：将文档转为 JSON，供 LLM 检索和生成。
• 数据预处理：为 ML 模型准备训练数据（如文本分类、NER）。
• 文档分析：提取合同、报告中的关键信息。
• 内容提取：从网页、邮件或 PDF 中提取结构化内容。
• 个人 AI 助手：本地处理笔记和文档，保护隐私。

示例（RAG 管道）：

from unstructured.partition.auto import partition
from unstructured.staging.base import convert_to_dict
from langchain_unstructured import UnstructuredLoader
import json

# 解析文档
elements = partition(filename="report.pdf", strategy="hi_res")
json_data = convert_to_dict(elements)

# 保存为 JSON
with open("output.json", "w") as f:
    json.dump(json_data, f, indent=2)

# 加载到 LangChain
loader = UnstructuredLoader(file_path="report.pdf")
docs = loader.load()

# 假设使用 LLM 进行问答
from langchain.llms import OpenAI
llm = OpenAI(api_key="your_openai_key")
response = llm(f"Summarize: {docs[0].page_content[:500]}")
print(response)

说明：

• 解析 PDF，提取结构化元素并保存为 JSON。
• 使用 LangChain 加载数据，结合 LLM 进行总结。

---

6. 部署与扩展

• 本地运行：
  • 安装依赖后直接运行 Python 脚本。
  • 使用 pyenv 管理虚拟环境，推荐 Python 3.8.15。
• Docker 部署：
  • 拉取官方镜像或构建自定义镜像，适合生产环境。
• Serverless API：
  • 注册 API 密钥，调用 unstructured-client 处理文件。
  • 适合快速原型或大规模处理。
• 贡献与调试：
  • 提交 bug 使用 scripts/collect_env.py 收集环境信息。
  • GitHub 仓库：https://github.com/Unstructured-IO/unstructured。

---

7. 注意事项

• 依赖管理：
  • 本地处理 PDF/图片需安装 tesseract 和 poppler，否则报错。
  • 使用 pip install "unstructured[all-docs]" 安装所有文档类型依赖。
• 性能优化：
  • 对于单一文件类型，安装特定依赖（如 unstructured[docx]）减少开销。
  • 使用 strategy="hi_res" 提取表格，但计算成本较高。
• 局限性：
  • DOCX 列表项可能被误识别为标题，需后处理验证。
  • 缺少父子关系标注，需手动解析上下文。
• 隐私：
  • 禁用分析 ping：export DO_NOT_TRACK=true 或 SCARF_NO_ANALYTICS=true。
• 替代工具：
  • extractous：更快的替代，支持类似格式，但社区较小。
  • LayoutParser：专注于文档图像分析，适合复杂布局。

---

8. 综合示例

以下是一个综合示例，展示分区、清理、格式化和 LangChain 集成：

from unstructured.partition.auto import partition
from unstructured.cleaners.core import clean, remove_punctuation
from unstructured.staging.base import convert_to_dict
from langchain_unstructured import UnstructuredLoader
import json

# 配置日志（使用 loguru）
from loguru import logger
logger.add("app.log", rotation="1 MB", level="INFO")

# 解析 PDF
logger.info("Starting PDF processing")
try:
    elements = partition(filename="sample.pdf", strategy="hi_res")
except Exception as e:
    logger.exception("Failed to process PDF")
    raise

# 清理文本
cleaned_elements = []
for element in elements:
    text = clean(element.text, lowercase=True)
    text = remove_punctuation(text)
    cleaned_elements.append({"type": element.category, "text": text})
logger.info("Text cleaning completed")

# 转换为 JSON
json_data = convert_to_dict(cleaned_elements)
with open("output.json", "w") as f:
    json.dump(json_data, f, indent=2)
logger.info("JSON output saved")

# LangChain 集成
loader = UnstructuredLoader(file_path="sample.pdf", strategy="hi_res")
docs = loader.load()
logger.info(f"Loaded {len(docs)} documents")

# 打印前 100 个字符
print(docs[0].page_content[:100])

输出示例（app.log）：

2025-05-09T01:33:56.123 | INFO     | Starting PDF processing
2025-05-09T01:33:57.124 | INFO     | Text cleaning completed
2025-05-09T01:33:57.125 | INFO     | JSON output saved
2025-05-09T01:33:57.126 | INFO     | Loaded 1 documents

说明：

• 使用 partition 解析 PDF，hi_res 策略提取表格。
• 清理文本，移除标点并转换为小写。
• 保存为 JSON，供下游任务使用。
• 通过 LangChain 加载文档，记录日志。

---

9. 资源与文档

• 官方文档：https://docs.unstructured.io/
• GitHub 仓库：https://github.com/Unstructured-IO/unstructured
• PyPI 页面：https://pypi.org/project/unstructured/
• LangChain 集成：https://python.langchain.com/docs/integrations/document_loaders/unstructured/
• 社区支持：Unstructured Slack 社区（https://unstructured.io/community）
• 官方快速入门：https://docs.unstructured.io/open-source/introduction/quick-start