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

Ne0inhk

— 9 min read

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/图片）：

验证安装：

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

libmagic：文件类型检测（Linux/Mac 需安装）。

# Mac brew install libmagic # Ubuntusudoapt-getinstall libmagic1

使用 Serverless API：

pip install unstructured-client

特定文档类型（如 DOCX）：

pip install"unstructured[docx]"

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

pip install"unstructured[local-inference]"

基本安装（不含 PDF/图片处理）：

pip install unstructured

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")withopen("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)# 保存为 JSONwithopen("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)withopen("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. 资源与文档

Read more

【超详细】Ubuntu 安装终极指南：详解硬盘分区方案与实践

【超详细】Ubuntu 安装终极指南：详解硬盘分区方案与实践

Ubuntu 安装终极指南：详解硬盘分区方案与实践 在安装 Ubuntu 操作系统时，合理的硬盘分区方案是确保系统稳定、高效运行，并方便日后维护的关键。本文将为你详细解析不同的分区策略，并提供具体示例和操作注意事项，帮助你根据自身需求，为你的Ubuntu系统构建一个最适合的硬盘布局。 一、理解 Ubuntu 分区的核心概念 在深入分区方案之前，我们先来了解几个重要的概念： * 文件系统 (File System)：文件系统是操作系统用来组织和存储文件的方法。对于 Linux 系统，ext4 是目前最常用且推荐的文件系统，它提供了良好的性能和稳定性。 * 挂载点 (Mount Point)：在 Linux 中，所有存储设备和分区都必须“挂载”到文件系统树的一个特定目录上，这个目录就是挂载点。例如，根目录 / 是整个文件系统的起点。 * 主分区 (Primary Partition) 与 逻辑分区 (Logical Partition)： * 主分区：

By Ne0inhk

Win10安装WSL2全攻略：Ubuntu 20.04 部署至F盘并彻底解决网络连接问题

参考链接：全网最全Win10/11系统下WSL2+Ubuntu20.04的全流程安装指南（两种支持安装至 D 盘方式）_win10安装wsl2-ZEEKLOG博客 前言 WSL2（Windows Subsystem for Linux 2）是 Windows 提供的一种轻量级 Linux 运行环境，具备完整的 Linux 内核，并支持更好的文件系统性能和兼容性。它允许用户在 Windows 系统中运行 Linux 命令行工具和应用程序，而无需安装虚拟机或双系统。 一、安装 WSL2 1. 启用 Windows 子系统（WSL）功能 快捷键“win+x”打开PowerShell（管理员模式），在 PowerShell（管理员模式）中运行： dism.

By Ne0inhk
WSL 安装 Ubuntu

WSL 安装 Ubuntu

系统使用windows 11 启用 Windows 虚拟化和 Linux 子系统功能 * 打开 “启用或关闭 Windows功能”，找到并勾选以下选项 (完成后需重启)： * Virtual Machine Platform * Hyper-V * 适用于 Linux 的 Windows 子系统 更新 WSL 打开终端，输入更新命令： wsl --install -d Ubuntu 如果是第一次使用 wsl，可能会下载 wsl 安装包，使用命令行的方式下载速度可能很慢，可以点击这里 手动下载 WSL 离线包并安装。 安装 Ubuntu 22.04 在终端中输入命令： wsl --install -d Ubuntu-22.04 等待下载并安装，

By Ne0inhk