unstructured：非结构化文档预处理与结构化转换实践

这段代码跑完后，你会拿到一组 Element 对象。每个对象都有自己的类别，比如 Title、NarrativeText、ListItem、Table 等，也会带上一些元数据。

如果是 PDF，而且你需要更强的版面识别能力，通常会显式指定策略：

from unstructured.partition.pdf import partition_pdf

elements = partition_pdf(filename="example.pdf", strategy="hi_res")

hi_res 更适合复杂 PDF，尤其是包含表格、扫描件或布局比较乱的文档。不过它的代价也更高，对 tesseract、poppler 这类依赖更敏感。

2）清洗：把提取出来的文本收一收

分区拿到的内容不一定能直接用，尤其是来自网页、扫描件或格式复杂的文档时，杂质会比较多。这个时候可以借助 cleaners 做基础清理。

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)

这类清洗适合放在抽取之后、入库之前。比如你可能只想保留纯文本，去掉标点、空白噪声，或者统一大小写，减少后续检索时的干扰。

3）格式化：转成下游更容易消费的结构

如果后面要接 JSON、数据分析，或者直接喂给别的管道，就可以把元素列表转成字典结构。

from unstructured.staging.base import convert_to_dict

elements = partition(filename="example.docx")
json_data = convert_to_dict(elements)
print(json_data[:2])

这样得到的结果更适合存储、传输或者二次加工。它的价值在于：文档内容不再是一整坨字符串，而是带类型、带上下文的结构化数据。

和 LangChain 配合使用

如果你的工作流本来就在 LangChain 里，unstructured 基本可以平滑接上。比较常见的是用 UnstructuredLoader 读取文件，然后交给后面的切片、向量化或问答逻辑。

from langchain_unstructured import UnstructuredLoader

loader = UnstructuredLoader(file_path="example.pdf")
docs = loader.load()
print(docs[0].page_content[:100])

如果走的是 Serverless API，写法会稍有不同，需要传入 API key 和处理策略：

from langchain_unstructured import UnstructuredLoader

loader = UnstructuredLoader(
    file_path="example.pdf",
    api_key="your_api_key",
    strategy="hi_res"
)
docs = loader.load()

这个方案的好处很实际：本地少装很多依赖，处理链路也更统一。对生产环境或者快速原型来说，确实省心不少。

使用 Serverless API

如果你不想把 OCR、PDF 解析、版面分析这些依赖全压在本机上，可以直接调用 unstructured-client 对文件进行处理。

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

这种方式比较适合两类场景：一类是本地环境难以配置齐全，另一类是你希望把文档处理能力放到云端统一管理。

一个更完整的处理链路

如果把前面的步骤串起来，实际项目里通常会是这样的节奏：先解析文档，再做文本清洗，随后转成 JSON，最后交给 RAG 或其他模型任务。

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

# 解析 PDF
elements = partition(filename="sample.pdf", strategy="hi_res")

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

# 转换为 JSON 并保存
json_data = convert_to_dict(cleaned_elements)
with open("output.json", "w", encoding="utf-8") as f:
    json.dump(json_data, f, indent=2, ensure_ascii=False)

# 作为文档加载器接入后续流程
loader = UnstructuredLoader(file_path="sample.pdf", strategy="hi_res")
docs = loader.load()
print(docs[0].page_content[:100])

这类代码的重点不在'每一行都很炫'，而在于管道足够清楚：输入是什么，处理中间做了什么，最终输出给谁。实际项目里，能把这三件事讲明白，后面排错会轻松很多。

需要特别注意的地方

unstructured 很强，但也不是'装上就万事大吉'。有几个点在实战里经常会碰到：

• DOCX 解析有时会把列表项、标题、段落的边界识别得不够理想，后处理很重要
• 大型文档的父子层级关系不一定完整，做上下文拼接时要多留心
• hi_res 策略效果更好，但成本也更高，尤其是表格和扫描件场景
• 本地部署会牵涉到不少系统依赖，环境管理要提前做好

如果只是处理单一格式，装对应的精简依赖通常更稳，也更容易控制体积和启动成本。

适合它的使用场景

从工程实践看，unstructured 最有价值的地方，是把'文档读取'和'文档理解'之间的那道坎降低了。它很适合：

• RAG 知识库构建
• 合同、报告、邮件的结构化抽取
• 多格式文档统一预处理
• OCR + 文档解析一体化流水线
• 本地隐私敏感场景下的文档处理

如果你经常和混合格式文档打交道，unstructured 往往会比单点工具更顺手。它不只是一个解析库，更像是一个围绕文档预处理搭起来的工具箱。

小结

unstructured 的优势很直接：支持格式多、分区能力强、可本地可云端、还能比较自然地接进 LLM/RAG 流程。它最适合用在'先把文档变得可用，再谈后续智能化'的场景里。对于需要稳定处理 PDF、Word、HTML、图片等非结构化内容的项目，它是一个值得放进工具箱里的选择。