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.pyserver_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 大脑”!
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考