WSL2下本地部署Langchain-Chatchat全记录

WSL2下本地部署Langchain-Chatchat全记录

在企业级AI应用日益普及的今天，越来越多团队开始关注“数据不出内网”的私有化智能问答系统。开源项目Langchain-Chatchat正是这一需求的理想解决方案——它支持文档上传、语义检索与本地推理，完全避免敏感信息外泄。而要在Windows环境下稳定运行这套系统，WSL2（Windows Subsystem for Linux 2）成为了关键桥梁。

本文将带你从零开始，在 WSL2 中完成 Langchain-Chatchat 的完整部署。整个过程涵盖环境搭建、模型下载、配置调优和启动验证，尤其适合对 Linux 和 Python 有一定基础但尚未接触过 AI 本地部署的开发者。

系统准备：为什么非得用 WSL2？

直接在 Windows 上跑 Langchain-Chatchat 并非不可能，但你会频繁遭遇路径分隔符错误、权限问题、shell 脚本兼容性崩溃以及 pip 包冲突等问题。相比之下，WSL2 提供了一个轻量级却功能完整的 Linux 内核环境，既能访问 Windows 文件系统，又能原生运行 Unix 工具链，是目前最稳妥的选择。

建议使用Windows 11，其对 WSL2 的集成更为成熟，自动处理了多数驱动和网络配置问题。如果你还在用 Win10，也完全可行，只需手动启用虚拟化支持即可。

启用 CPU 虚拟化

WSL2 基于 Hyper-V 架构，依赖硬件级虚拟化技术（Intel VT-x 或 AMD-V）。若未开启，安装时会报错或性能极低。

进入 BIOS 设置（重启按 F2/Del），找到类似 “Advanced → CPU Configuration” 的选项，启用Intel Virtualization Technology或SVM Mode。

验证是否已开启：

systeminfo | findstr /C:"虚拟机监视器模式扩展"

输出为“是”，表示成功。

安装 WSL2 与 Ubuntu 发行版

以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu

这条命令会自动完成以下动作：
- 安装 WSL 组件
- 设置默认版本为 WSL2
- 下载并安装 Ubuntu LTS（通常是 22.04）

安装完成后，系统会提示你创建用户名和密码，请务必记住。之后可通过wsl命令随时进入该环境。

确认当前实例版本：

wsl --list --verbose

输出应显示 VERSION 列为2。

⚠️ 注意：部分旧系统可能默认使用 WSL1，需手动升级：

powershell wsl --set-version Ubuntu 2

推荐操作：迁移 WSL 实例至非系统盘

Ubuntu 默认安装在 C:\Users...\AppData\Local\Packages 下，长期使用可能占用数十 GB 空间。如果你的 C 盘容量紧张，建议迁移到 D 盘或其他分区。

流程如下（以迁移到D:\wsl\ubuntu为例）：

# 先关闭所有 WSL 实例 wsl --shutdown # 导出当前系统为 tar 包 wsl --export Ubuntu D:\wsl\ubuntu.tar # 卸载原实例 wsl --unregister Ubuntu # 重新导入到指定路径 wsl --import Ubuntu D:\wsl\ubuntu D:\wsl\ubuntu.tar --version 2 # 删除临时文件 del D:\wsl\ubuntu.tar

此后，你可以通过资源管理器访问\\wsl$\Ubuntu查看 Linux 文件系统。

更换 APT 源为国内镜像

Ubuntu 官方源在国外，更新软件包速度慢。切换为阿里云镜像可显著提升体验。

编辑源列表文件：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo vim /etc/apt/sources.list

替换内容为适用于 Ubuntu 22.04 (jammy) 的阿里云源：

deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse

保存后更新索引：

sudo apt update && sudo apt upgrade -y

安装 Git LFS 支持大模型下载

Langchain-Chatchat 的模型仓库包含大量二进制权重文件（如.bin,.safetensors），普通 git 无法拉取这些大文件。必须借助Git LFS（Large File Storage）。

安装命令：

sudo apt install git-lfs -y git lfs install

这一步至关重要，否则克隆模型时只会得到占位符，导致后续加载失败。

NVIDIA 用户注意：GPU 驱动配置

如果你希望利用 GPU 加速模型推理（尤其是生成响应阶段），NVIDIA 显卡用户需要额外配置 CUDA 支持。

主机端

前往 NVIDIA 官网 安装最新驱动，推荐通过 GeForce Experience 自动更新，确保包含 WSL 兼容的 CUDA 组件。

WSL2 端

安装完成后，在 WSL2 终端中执行：

nvidia-smi

如果能看到显卡型号、驱动版本和 CUDA 版本信息，说明 GPU 已就绪。

✅ 成功标志：无报错，输出显存占用和进程状态
❌ 失败常见原因：主机未安装支持 WSL 的驱动 / WSL2 未正确初始化 GPU 子系统

一旦成功，后续安装 PyTorch 时可以选择cu118版本以启用 GPU 加速。

使用 Conda 创建独立 Python 环境

Langchain-Chatchat 对依赖库版本极为敏感，特别是 PyTorch、Transformers 和 LangChain 的组合容易因版本不匹配导致崩溃。因此，强烈建议使用虚拟环境进行隔离。

推荐使用Anaconda，不仅提供强大的包管理能力，还有图形化工具降低入门门槛。

安装 Anaconda（Windows 端）

前往 Anaconda官网 下载 Windows 安装包，双击运行，全程默认选项即可。

安装后你将获得：
- Anaconda Navigator 图形界面
- conda 命令行工具
- Jupyter Notebook / VSCode 集成

创建专用环境chatchat-env

打开 Anaconda Navigator → Environments → Create：

• Name:chatchat-env
• Python Version:3.10（当前兼容性最佳）

等待创建完成，点击绿色“▶️”按钮启动环境，并打开终端。

此时命令行前缀应显示(chatchat-env)，表示已激活。

升级 pip：

pip install --upgrade pip

克隆项目代码到 WSL2

确保你在(chatchat-env)环境中，执行：

cd ~ mkdir lang && cd lang git clone --recursive https://github.com/chatchat-space/Langchain-Chatchat.git

其中--recursive参数非常重要，用于同时拉取子模块（如 FastChat、LangChain 等依赖项），遗漏会导致后续导入失败。

安装项目依赖

进入项目目录：

cd Langchain-Chatchat pip install -r requirements.txt

主要耗时包包括：
-torch（PyTorch）
-transformers
-langchain
-faiss-cpu（或faiss-gpu若启用了 CUDA）

网络不稳定时可使用清华源加速：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

安装完成后检查关键版本：

python -c "import torch; print(torch.__version__)" python -c "import transformers; print(transformers.__version__)"

建议版本范围：
- torch ≥ 2.0
- transformers ≥ 4.35

下载本地大模型

Langchain-Chatchat 的核心能力依赖两个模型：
1.基座语言模型：负责回答生成，推荐chatglm3-6b
2.Embedding 模型：用于文档向量化编码，推荐bge-large-zh-v1.5

两者均针对中文优化，社区广泛采用。

使用 ModelScope 魔搭平台高效下载

相比 HuggingFace 国内访问缓慢，ModelScope 提供更快的下载速度（实测可达 50MB/s）。

创建模型目录并进入：

mkdir models && cd models git lfs install

分别克隆两个模型：

git clone https://www.modelscope.cn/ZhipuAI/chatglm3-6b.git git clone https://www.modelscope.cn/AI-ModelScope/bge-large-zh-v1.5.git

⚠️ 注意：不要重命名模型文件夹！否则需同步修改配置路径。

配置核心参数文件

批量生成 .py 配置文件

项目中许多配置是以.example结尾的模板文件，需复制为.py才能被加载。

项目自带脚本可一键完成：

cd ~/lang/Langchain-Chatchat python copy_config_example.py

执行后，configs/目录下的*.example文件会被复制为同名.py文件，例如：

• model_config.py.example→model_config.py
• server_config.py.example→server_config.py

❗ 必须执行此步，否则启动时报错找不到模块！

修改模型路径

编辑configs/model_config.py：

vim configs/model_config.py

找到MODEL_PATH字典，修改为实际路径：

MODEL_PATH = { "chatglm3-6b": "/home/yourname/lang/models/chatglm3-6b", "bge-large-zh-v1.5": "/home/yourname/lang/models/bge-large-zh-v1.5" }

📌 关键点：
- 替换yourname为你自己的 WSL 用户名
- 使用正斜杠/，不要混用\
- 路径必须绝对准确，不能多空格或拼写错误

初始化向量知识库

首次运行前必须初始化数据库，让 Embedding 模型对默认文档进行向量化处理。

执行命令：

python init_database.py --recreate-vs

观察现象：
- CPU 占用飙升（文本分块与编码）
- 内存快速上升（建议至少 16GB RAM）
- 若有 GPU，显存开始分配
- 终端持续输出日志，表示正在处理文档

⏱️ 耗时约5–8 分钟，取决于硬件性能。

✅ 成功标志：最后输出Vector store initialized.

启动 Web 服务

一切就绪后，启动主程序：

python startup.py -a

参数-a表示启动所有服务（API + Web UI）。

等待数分钟后，看到以下日志即表示成功：

INFO: Uvicorn running on http://0.0.0.0:8000 INFO: Started reloader process [xxxxx] Streamlit app starting... Welcome to Streamlit. Access your app at: http://localhost:8501

🟢 打开浏览器访问：
👉 http://127.0.0.1:8501

❗ 注意：http://0.0.0.0:8501无法访问，必须使用127.0.0.1或localhost

首次加载可能较慢（需加载模型到内存），耐心等待几分钟。页面出现后即可上传 PDF、TXT、Word 等文档，测试语义检索与问答功能。

总结与延伸建议

Langchain-Chatchat 是当前开源领域中最成熟的本地知识库问答框架之一。通过本次部署，我们实现了：
- 数据完全本地化，保障信息安全
- 支持多种格式文档解析与向量化
- 可扩展性强，便于二次开发
- 兼容 CPU/GPU 推理，适配不同硬件条件

对于企业用户而言，这套系统非常适合用于：
- 内部知识库建设
- 私有客服机器人训练
- 敏感文档智能检索
- 合规场景下的 AI 助手部署

下一步建议：
1. 将自有文档放入knowledge_base/test目录
2. 重新运行python init_database.py --recreate-vs更新向量库
3. 测试多轮对话与上下文理解能力
4. 根据业务需求调整模型或前端界面

只要按步骤操作，即使你是 AI 部署新手，也能顺利完成整套流程。祝你顺利打造属于自己的“本地 AI 大脑”！