【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

Flutter 三方库 http_cache_hive_store 的鸿蒙化适配指南 - 在鸿蒙系统上构建极致、透明、工业级的 HTTP 二级缓存与 Hive 数据库持久化联动引擎

Flutter 三方库 http_cache_hive_store 的鸿蒙化适配指南 - 在鸿蒙系统上构建极致、透明、工业级的 HTTP 二级缓存与 Hive 数据库持久化联动引擎

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 三方库 http_cache_hive_store 的鸿蒙化适配指南 - 在鸿蒙系统上构建极致、透明、工业级的 HTTP 二级缓存与 Hive 数据库持久化联动引擎 在鸿蒙（OpenHarmony）系统的端云一体化网络架构、针对高频 API 的请求压实（Debounce）或者是需要实现“秒开离线”的网络应用场景中，如何让 http 或 dio 库自动具备缓存能力，并将缓存物理落地到极速的 Hive 非关系型数据库中？http_cache_hive_store 为开发者提供了一套工业级的、基于 Hive 的网络响应持久化缓存方案。本文将深入实战其在鸿蒙端网络响应加速中的应用。 前言 什么是 HTTP

By Ne0inhk
Flutter 三方库 flutter_adaptive_scaffold 的鸿蒙化适配指南 - 掌握一套代码适配全场景终端的自适应架构技术、助力鸿蒙应用构建从手机到平板及折叠屏的极致无缝交互体系

Flutter 三方库 flutter_adaptive_scaffold 的鸿蒙化适配指南 - 掌握一套代码适配全场景终端的自适应架构技术、助力鸿蒙应用构建从手机到平板及折叠屏的极致无缝交互体系

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 三方库 flutter_adaptive_scaffold 的鸿蒙化适配指南 - 掌握一套代码适配全场景终端的自适应架构技术、助力鸿蒙应用构建从手机到平板及折叠屏的极致无缝交互体系 前言 在 OpenHarmony 鸿蒙应用追求“万物互联、全场景覆盖”的伟大进程中，屏幕尺寸的多样性（从 6 英寸手机到 12 英寸平板，再到 2D/3D 模式切换的折叠屏）是每一位 UI 开发者必须正面迎接的挑战。如何在不为每种设备重写 UI 的前提下，实现导航栏自动从“底部”平滑流转到“侧边”？如何在宽屏模式下自动开启“双栏（Master-Detail）”布局？flutter_adaptive_scaffold 作为一个由 Flutter

By Ne0inhk
AIGC | Midjourney使用指南，直接拿捏~

AIGC | Midjourney使用指南，直接拿捏~

目录 前言：第一篇ZEEKLOG博客，还请各位大佬多多指教！！ 一、认识Midjourney 二、Midjourney算法原理 三、Midjourney基本操作指南 1、安装 2、使用演示及基本分区讲解 3、命令解析 4、后缀解析 总结：     前言：第一篇ZEEKLOG博客，还请各位大佬多多指教！！   一、认识Midjourney   Midjourney是由David Holz 2022年3月推出的一款AI制图工具。处于聊天软件discord中，主要功能涵盖图像生成、风格化、变体生成、图生图等，且提供高级工具精细控制生成过程。 使用上需创建账户、获邀请后通过Discord频道输入文字提示来操作。相比于SD(stable diffusion) MJ随机性更大，细节处理精度不够。 二、Midjourney算法原理   MJ基于深度学习中的生成对抗网络（GAN）和扩散模型等技术。 * 生成对抗网络（GAN）：由生成器和判别器组成。生成器的任务是根据输入的随机噪声和文本描述等信息，生成尽可能逼真的图像；

By Ne0inhk
Flutter 三方库 objectbox_generator — 自动化构建鸿蒙极速 NoSQL 数据库映射（适配鸿蒙 HarmonyOS Next ohos）

Flutter 三方库 objectbox_generator — 自动化构建鸿蒙极速 NoSQL 数据库映射（适配鸿蒙 HarmonyOS Next ohos）

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net。 Flutter 三方库 objectbox_generator — 自动化构建鸿蒙极速 NoSQL 数据库映射（适配鸿蒙 HarmonyOS Next ohos） 在高性能移动应用开发中，本地数据的持久化存储效率往往是决定用户感知流畅度的木桶短板。传统的 SQLite 虽然结构化程度高，但在处理大规模对象关系映射（ORM）时，复杂的 SQL 拼接和反射解析往往会成为性能瓶颈。 ObjectBox 作为一个专为移动设备打造的、跨平台的超高速 NoSQL 数据库，已经成为了许多追求极致体验开发者的首选。而在 Flutter for OpenHarmony 开发中，配合 objectbox_generator，我们可以通过注解驱动的自动化流程，掌握这套高性能数据库的核心用法。 ⚠️ 鸿蒙适配现状提示：截至本文撰写时，ObjectBox 的 Dart 插件尚未提供官方的 OpenHarmony

By Ne0inhk