企业官网建设流程全解析

AI框架搭建系列之Agent框架-安装文档解析Unstructured并部署FAISS和BGE-M3

摘要：本文基于 LangChain + LangGraph 的 Agent 框架，在 Windows 10 + Python 3.12 环境下搭建 RAG（检索增强生成）数据检索底座。内容涵盖：在 VS Code 中激活虚拟环境、安装文档解析工具 Unstructured 及系统级依赖（Tesseract OCR、Poppler）、部署向量数据库 FAISS 并完成与 LangChain 的 Mock 连通测试，最后部署多语言 Embedding 模型 BGE-M3 并打通真实链路。文中还针对 Windows 下常见的 numpy 版本冲突、c10.dll WinError 1114 等坑位给出了完整解决方案。

目标

基于 LangChain + LangGraph 的 Agent 框架，搭建 RAG（检索增强生成）场景。流程：用户提问 → Agent 检索知识库中的数据 → 生成回答

一、回顾

电脑配置：Win10，Python 3.12，已创建虚拟环境（个人虚拟环境路径）/.venv，已安装 VS Code。安装过程参见系列文章

二、步骤

接下来：安装文档解析 Unstructured，部署 FAISS和BGE-M3模型
在 Windows 10 平台下，使用 VS Code 为 Unstructured 配置环境，需要注意虚拟环境的激活和系统级依赖的安装。
Unstructured：支持 25–50+ 文件格式的非结构化文档解析框架，可将 PDF、Word、HTML、图片等内容转换为结构化文本或 JSON，适用于 RAG、LLM 预处理与数据管道。它提供本地库（unstructured）与云端 API，并能与 LangChain 的 UnstructuredLoader 深度集成。
FAISS（Facebook AI Similarity Search）：高效的向量相似性搜索和聚类工具库，专为处理大规模向量数据而设计。它支持快速的最近邻搜索（k-NN）和密集向量的聚类操作，广泛应用于推荐系统、自然语言处理和计算机视觉等领域。

1. 在 VS Code 中激活虚拟环境

确保 VS Code 正确识别并使用虚拟环境（环境名为 .venv），否则安装的包会进入全局环境。
a. 在 VS Code 中打开项目文件夹 D:(个人虚拟环境路径)\my-agent-framework。项目文件安装过程参见系列文章
b. 按快捷键 Ctrl+Shift+P 打开命令面板，输入并选择 Python: Select Interpreter。
c. 在弹出的列表中，选择带有完整路径的虚拟环境解释器：D:(个人虚拟环境路径)\my-agent-framework.venv\Scripts\python.exe。
选择后，VS Code 右下角状态栏应显示类似 Python 3.12.x (‘.venv’) 的标识。
d. 按 Ctrl+~ 打开内置终端，若终端提示符前自动出现了 (.venv)，则表示环境已成功激活。

2. 安装 Unstructured 及系统级依赖

Unstructured 在解析 PDF 等复杂文档时，高度依赖底层的系统级工具。在 Windows 上，需要手动安装这些依赖：
a. 安装系统级工具
Tesseract OCR（用于图片/扫描件的文本识别）：前往 GitHub 的 UB-Mannheim/tesseract 页面下载 Windows 安装包并安装。

或点击这里 - Tesseract OCR
Tesseract OCR 简体中文和英文语言包：前往下载语言包，将其中的中文和英文语言包放到 Tesseract-OCR-5-5-3 的 tessdata 目录下。或点击这里获取中英文语言包

Poppler（用于 PDF 解析）：前往 GitHub 的 oschwartz10612/poppler-windows 页面下载并解压。或点击这里 - Poppler

b. 配置环境变量
将上述工具安装目录下的对应文件夹（D:\Tesseract-OCR-5-5-3 和 D:\poppler-26.02.0\Library\bin）添加到 Windows 系统的 PATH 环境变量中。
配置完成后，重启 VS Code 使环境变量生效。

c.验证是否安装成功
c.1.验证poppler
在终端输入命令：

pdftotext-v

出现版本号即表示安装成功：

c.2.验证Tesseract-OCR及其语言包
在终端输入查询版本命令：

tesseract.exe-v

在终端输入查询语言命令：

tesseract.exe --list-langs

出现版本号和语言列表即表示安装成功：

d.安装Python包
d.1.在已激活的 VS Code 终端中，执行以下命令安装 Unstructured 及其 PDF 处理扩展：

pipinstall"unstructured[pdf]"

如果需要处理 Word 文档或图片，可以按需追加 :

pipinstall"unstructured[docx]"pipinstall"unstructured[image]"

d.2.验证安装是否成功
在 VS Code 终端中运行以下 Python 测试代码，验证环境配置和解析功能是否正常：

python-c"from unstructured.partition.auto import partition; print('Unstructured 安装成功！')"

注：在 Windows 下，如果运行代码时提示找不到 tesseract 或 pdftotext，大部分原因是没有正确配置 PATH 环境变量，或者配置后没有重启 VS Code 导致终端未读取到新的环境变量。请确保路径中不包含中文或特殊字符，否则可能会导致解释器或外部工具调用失败。

3. 部署 FAISS

在 Windows 10 平台下部署 FAISS，由于底层 C++ 编译环境的差异，直接使用 pip 安装易遇到依赖缺失或版本冲突的问题。这里越过 GPU 部分，直接尝试安装 faiss-cpu 版本：

1. 安装faiss-cpu和numpy
   faiss-cpu 1.8.0 已兼容 Python 3.12，可以在已激活的 .venv 虚拟环境中尝试直接安装。numpy 1.26.4 广泛兼容 Python 3.9 到 3.12：

pipinstallfaiss-cpu==1.8.0numpy==1.26.4

安装完成后，在 VS Code 终端中运行以下代码验证环境是否正常（在项目 include 目录下新建 test_faiss.py）：

importfaissimportsysimportnumpyasnpprint(f"Python 版本:{sys.version_info}")print(f"FAISS 版本:{faiss.__version__}")print(f"numpy 版本:{np.__version__}")# 测试基础索引创建test_index=faiss.IndexFlatL2(128)print(f"基础索引创建成功，是否已训练：{test_index.is_trained}")#应输出版本号和True

如果能正常输出版本号且 is_trained 为 True，则说明部署成功。
注：版本冲突警告：faiss-cpu 和 faiss-gpu 不可同时安装。如果之前安装过 GPU 版本导致冲突，请先卸载（pip uninstall faiss-gpu），再安装 CPU 版本。
关于 GPU 加速：如果有 NVIDIA 显卡并希望启用 GPU 加速，请勿直接使用 pip install faiss-gpu，这在 Windows 下大概率会因元数据不一致而失败。在系统中配置好 CUDA 环境变量后，通过 conda 安装指定 CUDA 版本的 GPU 包（例如 conda install -c conda-forge faiss-gpu cudatoolkit=11.8）。
内存要求：FAISS 纯本地运行，万级向量无压力。如果RAG 知识库达到百万级向量，请确保电脑内存分配在 8GB 以上。

2. 进行FAISS与LangChain交互的Mock 测试（模拟测试）
   RAG（检索增强生成）工程实践中，在部署庞大且耗时的 Embedding 模型（BGE-M3）之前，先用一个轻量级的 Mock 对象跑通 LangChain 与 FAISS 的交互逻辑，能极大提高开发效率，避免在模型加载上浪费时间。LangChain 提供了一个专门的 FakeEmbeddings 类，它可以生成固定维度的假向量。
   以下是不调用 BGE-M3 跑通 FAISS 的代码示例：

a.安装必要的 LangChain 基础包
在 .venv 终端中执行：

pipinstalllangchain-core langchain-community langchain-text-splitters

注：若出现numpy模块自行升级的情况，为避免后续模块版本冲突，请强制进行numpy版本降级，其余自行升级的模块降级模式参考numpy：

pipinstallnumpy==1.26.4

b. 运行Mock 测试代码
在 VS Code 中创建 test_faiss_mock.py 并运行：

fromlangchain_core.documentsimportDocumentfromlangchain_community.vectorstoresimportFAISSfromlangchain_core.embeddingsimportFakeEmbeddings#1.准备测试数据texts=["LangGraph 是 LangChain 团队推出的用于构建有状态 Agent 的框架。","BGE-M3 是目前表现非常优秀的开源多语言 Embedding 模型。","FastAPI 是一个用于构建高性能 RESTful API 的现代 Python 框架。"]documents=[Document(page_content=text)fortextintexts]# 2.使用FakeEmbeddings 模拟向量化（size 设为 1024 ,与 BGE-M3 默认维度一致）#这样无需下载几个GB的模型文件，也能测试FAISS的增删改查fake_embeddings=FakeEmbeddings(size=1024)#将数据写入本地FAISS索引vectorstore=FAISS.from_documents(documents,fake_embeddings)#测试相似度检索query="什么是FastAPI框架"results=vectorstore.similarity_search(query,k=1)print(f"检索到的内容：{results[0].page_content}")print("LangChain + FAISS 链路连通性测试成功！")

注：LangChain 与 FAISS 的交互Mock测试可确认 FAISS 的 DLL 加载、NumPy 版本降级（1.26.4）在 Windows 环境中是否正常。如果这一步报错，可以确定是 FAISS 或 LangChain 的环境配置问题。

4. 部署 BGE-M3 模型

BGE-M3 是一个多语言、多功能（支持稠密、稀疏、多向量检索）的优秀模型，但在 Windows 环境下部署与 LangChain 对接，需要注意模型下载和依赖冲突。
BGE-M3 部署指南：
a.1. 安装必要的依赖包
在 .venv 终端中，安装 sentence-transformers（Hugging Face 官方的模型加载库）以及 LangChain 对应的 HuggingFace 集成包：

pipinstallsentence-transformers==6.0.0 pipinstalllangchain-huggingface==1.2.2

注：模块更新迭代较快，注意更新依赖

a.2. 解决潜在的依赖冲突
sentence-transformers 内部依赖 transformers 库，它在安装时极有可能将之前降级好的 numpy 重新拉回 2.x 版本，导致 FAISS 再次崩溃。
在安装完成后，再次执行一次降级命令：

pipinstallnumpy==1.26.4

部分依赖模块参考配置：

pipinstallml-dtypes==0.5.4scipy==1.17.1 opencv-python==4.9.0.80 unstructured-inference==1.0.5

b. 进行 BGE-M3 模型下载。新建 BGE_download.py:

importosfromhuggingface_hubimporthf_hub_download#设置镜像源os.environ['HF_ENDPOINT']='https://hf-mirror.com'print("start downloading BGE-M3...")files=["config.json","pytorch_model.bin",#（唯一权重大文件，约 2.3G）"special_tokens_map.json","tokenizer.json","tokenizer_config.json","sentence_bert_config.json"#（分词词汇表，BGE‑M3 没有 vocab.txt）]os.makedirs("models/bge-m3",exist_ok=True)forfileinfiles:print(f"正在下载：{file}")hf_hub_download(repo_id="BAAI/bge-m3",filename=file,local_dir="models/bge-m3",local_dir_use_symlinks=False,#不使用符号链接，直接复制文件resume_download=True#支持断点续传)print("done.")

如果报错SSL: UNEXPECTED_EOF_WHILE_READING EOF occurred in violation of protocol说明 Windows 环境网络 / 代理 / 杀毒 / 系统 SSL 证书导致 httpx 访问镜像站 SSL 握手异常。则点击国内bge-m3镜像网站，按照上述代码里列出的文件名，下载到对应目录(\my-agent-framework\models\bge-m3)。

c. 进行 BGE-M3 与 FAISS 交互测试：

fromlangchain_core.documentsimportDocumentfromlangchain_community.vectorstoresimportFAISSfromlangchain_huggingfaceimportHuggingFaceEmbeddings#初始化真实的BGE-M3 Embedding模型embeddings=HuggingFaceEmbeddings(model_name=r"D:\my-agent-framework\models\bge-m3",#配置本地模型路径（请根据实际存放路径修改）model_kwargs={"device":"cpu"},#Windows下若未配置CUDA请使用cpuencode_kwargs={"normalize_embeddings":True}#BGE系列模型强烈建议开启归一化)#3.准备测试数据texts=["LangGraph 是 LangChain 团队推出的用于构建有状态 Agent 的框架。","BGE-M3 是目前表现非常优秀的开源多语言 Embedding 模型。","FastAPI 是一个用于构建高性能 RESTful API 的现代 Python 框架。"]documents=[Document(page_content=text)fortextintexts]# 4.使用真实向量写入FAISSprint("正在将文本转化为向量并写入FAISS,请稍候...")vectorstore=FAISS.from_documents(documents,embeddings)# 5.测试相似度检索query="什么是FastAPI框架"results=vectorstore.similarity_search(query,k=1)print(f"检索到的内容：{results[0].page_content}")print("BGE-M3 + FAISS 真实链路连通性测试成功！")

此处 Windows 遇到 c10.dll WinError 1114 异常：OSError: [WinError 1114] 动态链接库 (DLL) 初始化例程失败。 Error loading "D:(项目目录)\my-agent-framework.venv\Lib\site-packages\torch\lib\c10.dll" or one of its dependencies.

PyTorch 在 Windows 加载失败，属于 torch 底层 DLL 故障。该故障常见 4 种原因：

1. 当前 PyTorch CUDA 版本和本机显卡驱动不兼容
2. 虚拟环境里 torch 文件损坏、安装不全
3. 缺少微软 VC++ 运行库
4. CPU only / CUDA 版本装反，导致 c10.dll 加载失败

方案一：卸载现有 torch，重装 CPU 版本
先彻底删掉旧的pytorch全套

pip uninstall torch torchvision torchaudio –y

再安装CPU专用版本 pytorch（无cuda，适配BGE M3，numpy1.26.4兼容）

pipinstalltorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

安装完成后先单独测试 torch 能不能加载成功：

python-c"import torch;print('torch版本：',torch.__version__)"

方案二：下载安装 Microsoft Visual C++ Redistributable 2015 2022 x64 后，重启电脑，再验证是否可以成功加载torch。

注：1.首次运行时，真实模型加载和向量化会较慢，不建议中途强制停止。
2.BGE-M3 的默认输出维度是 1024，FAISS 会自动适应这个维度，无需像之前 Mock 测试那样手动指定 size。
3.GPU 加速（可选）：如果有 NVIDIA 显卡且安装了 CUDA 和 PyTorch GPU 版本，可以将 model_kwargs={“device”: “cpu”} 改为 model_kwargs={“device”: “cuda”}，向量化速度将提升数倍。

当终端成功输出“BGE-M3 + FAISS 真实链路连通性测试成功！” 后，数据检索底座就已经彻底搭建完毕了。

总结：

本文在 Windows 10 + Python 3.12 环境下，基于 LangChain + LangGraph 搭建了 RAG 数据检索底座。通过激活虚拟环境、安装 Unstructured 及系统级依赖、部署 FAISS 向量库，并完成与 BGE-M3 模型的真实链路连通测试，最终实现了文档解析、向量化存储与相似度检索的完整流程，为后续 Agent 应用奠定了数据基础。