unstructured 本地部署指南：把 PDF、Word、HTML 统一变成大模型能吃的元素

一、项目介绍

在搭建 RAG（检索增强生成）、知识库问答或大模型数据流水线时，最耗时、也最容易被低估的环节，往往不是调模型，而是把各种"非结构化"资料——PDF 报告、Word 合同、HTML 页面、邮件、扫描件——清洗成模型可理解、可检索的文本块。很多团队一开始用 pdfplumber、PyPDF2、python-docx 各写一套，最后发现每种文件都要单独适配、版面还原一团糟。unstructured 正是为解决这个"最后一公里"而诞生的开源 Python 库。

根据官方 README 的描述，unstructured 提供了一组开源组件，用于摄取和预处理图像与文本文档，支持 PDF、HTML、Word 等众多格式。它的使用场景围绕"简化并优化面向大语言模型的数据处理工作流"展开：通过模块化函数与连接器组成一套内聚的系统，把异构的非结构化数据转换为结构化输出，从而适配不同平台，高效完成从原始文件到模型输入的转换。

官方同时明确承诺：开源库本身将保持完全免费。如果需要更高质量的输出（例如更精确的表格单元格还原、更少的"幻觉"内容），可以使用其商业版本 Transform API；但仅靠本地部署这套开源代码，已经足以覆盖绝大多数文档解析与入库前处理的需求，非常适合个人开发者与中小团队做私有化数据管道。

与同类工具相比，unstructured 的差异化在于"开箱即用的元素模型"：它不只是把 PDF 转成一大段纯文本，而是在转换时就标注好标题、段落、列表、表格、图片等语义类型，并保留页码、坐标等元数据。这一点对下游 RAG 系统尤为关键——分块时可以按标题切，检索时可以按类型过滤，展示时还能精确回链到原 PDF 的第几页。对于个人开发者，开源版已经足够；只有在表格密集、对准确率要求极高的生产场景，才需要考虑官方的商业解析 API。

二、官方信息

对于正在搭建私有知识库的团队，unstructured 几乎是绕不开的一环：它把五花八门的文件格式收敛成统一的元素模型，让后续的分块、向量化、入库都可以用同一套代码处理。本文将从安装、验证到 API 用法，带你在本地完整跑通这条流水线。

三、项目结构与核心特性

unstructured 的设计哲学可以概括为"自动路由 + 按需安装 + 元素抽象"。理解这三点，就理解了它和传统解析库的区别。

第一，统一分区入口。你不需要为每一种文件类型记忆不同的解析函数，只要调用 unstructured.partition.auto.partition()，库会自动探测文件的 MIME 类型，再把任务分发到对应的分区器（如 partition_pdf、partition_docx）。这意味着同一段代码可以处理混杂了 PDF、Word、邮件的目录。

第二，按文档类型安装的 extras。纯文本、HTML、XML、JSON、邮件不需要任何额外依赖；一旦要处理 PDF、Word、PPT、图片 OCR，再安装对应的可选依赖组。这样既保证了轻量，又避免了一上来就把 poppler、tesseract 全部塞进来。

第三，元素（Element）抽象。解析结果不是一大段字符串，而是一组带类型和元数据的对象：标题（Title）、正文（NarrativeText）、列表项（ListItem）、表格（Table）、图片（Image）等。每个元素都记录了页码、坐标、来源文件等元信息，可以直接送入向量数据库，也可以按类型做过滤。

其他值得关注的特性包括：

• 批量摄取连接器：配套的 unstructured-ingest 项目支持从 S3、Azure、SharePoint、Notion 等来源批量拉取文档并统一处理。
• 开发体验现代化：项目使用 uv 管理依赖与锁定文件，贡献者一条命令即可同步全部开发依赖。
• 多平台镜像：官方 Docker 镜像同时支持 x86_64 与 Apple Silicon，在服务器和 Mac 上都能直接跑。

适用场景

unstructured 最适合三类场景。第一是企业知识库建设：把合同、财报、产品手册统一解析后向量化，让内部助手能基于真实资料回答问题。第二是数据合规归档：把邮件、聊天记录、扫描件结构化入库，便于检索与审计。第三是模型评测数据集构造：把成百上千页的 PDF 自动切成标注好类型的样本，省去人工逐页整理。对中小团队来说，先用开源版跑通流程、评估准确率，再决定是否为高价值文档开启商业解析，是风险最低的路径。

四、环境与版本要求

• Python 环境（建议 3.10 及以上；具体支持的 Python 版本请以 PyPI 页面 的版本徽章与官方安装文档为准）。
• 系统级依赖（按要解析的文档类型按需安装，并非全部必需）：
• libmagic-dev：用于文件类型自动探测，是 partition_auto 的基础；
• poppler-utils：PDF 与图像渲染，pdf2image 依赖它；
• tesseract-ocr（以及 tesseract-lang）：扫描版图片与 PDF 的 OCR 文字识别，装语言包可支持中文等多语言；
• libreoffice：把老旧的 MS Office 文档转换为可解析格式；
• pandoc：通过 pypandoc-binary Python 包自动打包，一般无需单独安装系统 pandoc。
• 如果选择 Docker 方式，则上述系统依赖全部已封装在镜像内，无需手动配置。

提示：不同文档类型所需依赖不同。如果你的业务只处理结构化导出的 PDF，可以不装 libreoffice；如果只解析 HTML 与邮件，则连 poppler 都用不上。按 extras 精安装可以显著降低环境体积。

五、本地部署步骤

方式一：pip 安装（最常用）

# 1. 新建并激活虚拟环境，避免污染系统 Python
python -m venv .venv
source .venv/bin/activate      # Windows 下执行 .venv\Scripts\activate

# 2. 安装支持所有文档类型的完整版（含 pdf、docx、pptx、image 等 extras）
pip install "unstructured[all-docs]"

如果你只需要处理纯文本、HTML、XML、JSON 或邮件，完全可以只装基础版：

pip install unstructured

若只处理特定格式，例如 docx 与 pptx，可以更精确：

pip install "unstructured[docx,pptx]"

在 Ubuntu / Debian 上安装所需系统依赖：

sudo apt-get update
sudo apt-get install -y libmagic-dev poppler-utils tesseract-ocr tesseract-lang libreoffice

方式二：Docker 运行（最省心）

官方为每次推送到 main 的代码构建多平台镜像，并打上短 commit hash 与版本号标签，最新镜像也会标记为 latest：

# 拉取镜像
docker pull downloads.unstructured.io/unstructured-io/unstructured:latest

# 创建容器并进入 bash
docker run -dt --name unstructured downloads.unstructured.io/unstructured-io/unstructured:latest
docker exec -it unstructured bash

进入容器后可以直接打开 Python 交互环境验证：

python3
>>> from unstructured.partition.pdf import partition_pdf
>>> elements = partition_pdf(filename="example-docs/layout-parser-paper-fast.pdf")
>>> from unstructured.partition.text import partition_text
>>> elements = partition_text(filename="example-docs/fake-text.txt")

如果你更愿意自己构建镜像（例如裁剪掉用不到的文档依赖），可以克隆仓库后使用 make docker-build 与 make docker-start-bash；注意基础镜像是 wolfi-base，上游更新可能导致本地构建偶发失败。

启动验证

新建 test_parse.py：

from unstructured.partition.auto import partition

# 自动识别文件类型并分区，无需关心后缀
elements = partition(filename="example-docs/eml/fake-email.eml")

# 用空行连接，打印每个元素的文本
print("\n\n".join([str(el) for el in elements]))

运行：

python test_parse.py

如果终端输出了分段后的标题、正文、列表，说明部署成功。每个 element 都带有类别（Title、NarrativeText、Table 等）与元数据，可直接用于向量化入库。

关于隐私：unstructured 默认会向 packages.unstructured.io 发送极轻量的使用统计（一次库加载、以及每次顶层分区调用的版本与平台信息），绝不包含文档内容、文件名或路径。如需完全离线，在导入前设置环境变量 DO_NOT_TRACK=1 或 SCARF_NO_ANALYTICS=1 即可关闭。

排错思路

第一次跑通后，最常见的问题是"解析结果不对"而不是"装不上"。如果 PDF 提取出来是乱序、缺字，多半是扫描件没走 OCR——确认安装了 tesseract-ocr，并在分区时选择 strategy="hi_res"。如果表格变成了一行挤在一起的文本，说明没有开启 infer_table_structure。如果内存报错，往往是一次读入了过大的文件，改成按页处理或降低并发即可。

另一个容易被忽略的细节是元数据。每个 element 都带有 metadata，里面有来源文件名、页码、坐标系等信息，RAG 入库时建议一并保存，这样回答时才能给出"出自第几页"的引用。调试阶段可以多打印几个 element 的 category 与 metadata，确认管线符合预期后再接下游。

六、API 用法与示例

最常用的是自动分区：

from unstructured.partition.auto import partition

elements = partition("example-docs/layout-parser-paper.pdf")

针对 PDF，也可以显式调用分区器并控制版面策略：

from unstructured.partition.pdf import partition_pdf

elements = partition_pdf(
    filename="report.pdf",
    strategy="fast",             # 轻量快速；扫描件或复杂版面改用 "hi_res"
    infer_table_structure=True,  # 尝试识别表格结构
)

for el in elements:
    # el.category 给出元素类型，el.text 为纯文本
    print(el.category, "->", el.text[:80])

处理纯文本：

from unstructured.partition.text import partition_text

elements = partition_text(filename="note.txt")

分区完成后，通常会把元素序列化后送入向量库或下游系统。官方还提供了 elements_to_json 等辅助函数，便于持久化。完整的分区参数列表、各类文件支持的选项，请参考官方文档的 partitioning 章节；集成第三方框架（如 LangChain、LlamaIndex）的方式则见 integrations。

在 RAG 流水线中的典型位置

很多人把 unstructured 用在检索增强生成（RAG）的最前端：用户扔进来一份 PDF 合同或一堆网页快照，unstructured 先把它们切成带类型的元素，再按标题层级做分块（chunking），最后把文本和元数据一起写入向量库。这样做的好处是，检索时不仅能拿到文本，还能知道这段文字来自第几页、是不是表格、是不是列表项，从而让大模型在回答时给出更可靠的引用。

一个常见的进阶姿势是先 partition 再按类别过滤：丢掉纯页码、页眉页脚这类噪声元素，把 Table 元素单独转成 Markdown 或 HTML 喂给专门的表格处理模型。官方文档中的文档元素一节对每种元素类型都有说明，建议接入前通读一遍。

如果要处理一整个对象存储里的历史文件，单线程调用 partition 会很慢。这时可以配合 unstructured-ingest 的连接器批量拉取，再用多进程并行分区，最后统一入库。需要注意的是，OCR 与 hi_res 版面识别非常吃 CPU，建议先在小样本上测速度与准确率，再决定是否全量启用。

七、常见问题 FAQ

Q1：安装后调用 partition_pdf 报"无法识别文件类型"或缺少共享库？
A：这通常是因为没有安装对应文档类型的 extras 或系统依赖。处理 PDF 需要 pip install "unstructured[pdf]"，并确保已安装 poppler-utils；扫描版 PDF 还需要 tesseract-ocr。按报错提示补齐依赖即可。

Q2：表格解析效果不理想、文字乱序？
A：默认的 fast 策略较轻量。对表格密集、多栏排版的文档，改用 strategy="hi_res" 并开启 infer_table_structure=True，版面还原会明显改善；若仍达不到生产要求，可评估官方的 Transform 商业 API，它在表格单元格与文字准确率上更高。

Q3：Windows 上安装 poppler / libreoffice 很麻烦怎么办？
A：官方 README 建议 Windows 用户参考安装文档中关于 conda 与分步依赖的说明；最省事的方式是直接使用官方 Docker 镜像，把系统依赖问题全部留给容器。

Q4：想给项目贡献代码，本地开发环境怎么搭？
A：项目使用 uv。先安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh），然后在仓库根目录执行 make install，它会运行 uv sync --locked --all-extras --all-groups，自动创建虚拟环境并装好基础、extras、开发、测试与 lint 全部依赖。

Q5：能不能在内网/离线环境长期运行？
A：可以。库本身在本地完成解析，唯一的网络行为是可选的使用统计；设置 DO_NOT_TRACK=1 后即可完全离线。批量处理时建议搭配 unstructured-ingest 做目录遍历与断点续跑，并把结果统一写入对象存储或向量库。

小结

把 unstructured 跑起来其实只需要两条命令：装包、调 partition。真正的工作量在于后面的调优——根据你的文档类型选对 extras、在速度与版面准确率之间取舍、把元素按业务需要分块入库。建议先用小批量真实文档试跑，观察哪些元素被误识别、表格是否还原正确，再决定是否开启 hi_res 或引入商业 API。对于刚接触 RAG 的团队，这套开源工具已经能覆盖从 PDF 到向量库的大部分预处理工作。随着文档量增长，建议把解析参数、分块策略、元素过滤规则都写成可配置的流水线，而不是散落在脚本里；这样后续调整时只需改配置，不必动代码。

相关链接

• 仓库：github.com/Unstructured-IO/unstructured
• 开源文档：docs.unstructured.io/open-source
• 批量摄取：unstructured-ingest
• PyPI：pypi.org/project/unstructured
• 安装指南：unstructured-io.github.io/unstructured/installing.html
• 隐私政策：unstructured.io/privacy