WSL2 下本地部署 Langchain-Chatchat 实战指南
在企业知识管理日益智能化的今天，如何安全、高效地构建一个基于私有文档的 AI 问答系统，成了不少开发者和技术团队关注的重点。而 Langchain-Chatchat 正是当前开源生态中最具代表性的解决方案之一——它支持将 PDF、Word、TXT 等本地文件转化为可检索的知识库，并通过大语言模型实现自然语言问答，全程数据不离本地，完美契合对隐私和合规性要求较高的场景。
本文将以Windows + WSL2为环境基础，带你从零开始完成一次完整的 Langchain-Chatchat 部署。过程中不仅涵盖核心操作步骤，还会穿插实际经验与避坑建议，帮助你少走弯路，一次成功。
要让这套系统在本地稳定运行，首先要打好底层基础。WSL2（Windows Subsystem for Linux 2）作为连接 Windows 与 Linux 生态的桥梁，提供了接近原生 Linux 的开发体验，尤其适合 Python 类项目的部署。但它的配置并不总是“开箱即用”，有几个关键点必须提前确认。
首先是操作系统版本。推荐使用Windows 11或Windows 10 21H2 及以上版本。老版本可能缺少必要的内核组件，导致无法启用 WSL2 功能。你可以按下Win + R输入winver快速查看当前系统信息。
接下来是 CPU 虚拟化支持。别小看这一步——WSL2 实际上是在一个轻量级虚拟机中运行 Linux 内核，因此 Intel VT-x 或 AMD-V 技术必须开启。打开任务管理器 → “性能”标签页，就能看到“虚拟化”状态是否为“已启用”。如果显示未启用，需要重启电脑进入 BIOS/UEFI 设置，在高级选项中找到相关开关并打开。不同品牌主板的术语略有差异，比如 ASUS 主板可能叫 SVM Mode，联想或戴尔机器则通常直接标注为 Virtualization Technology。
一切准备就绪后，以管理员身份打开 PowerShell，执行：
wsl --install这条命令会自动安装 WSL 所需的所有组件，并默认安装 Ubuntu 发行版。如果你遇到“命令不存在”的提示，说明系统尚未启用 WSL 功能，需先手动激活：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart重启之后再运行wsl --install即可。
安装完成后，系统会引导你创建用户名和密码，这是你在 WSL2 中的 Linux 用户凭证，请妥善记住。
为了确保后续运行效率最大化，建议将 WSL2 默认版本设为 v2：
wsl --set-default-version 2并通过以下命令检查当前已安装的发行版及其版本：
wsl --list --verbose若已有实例仍为 v1，可用如下命令单独升级：
wsl --set-version Ubuntu 2默认情况下，WSL2 的虚拟硬盘存储在 C 盘下的 AppData 目录中，长期使用容易挤占系统空间。推荐将其迁移到其他磁盘，例如 D:\。迁移流程其实很简单，只需三步导出-卸载-重新导入：
# 导出当前系统 wsl --export Ubuntu D:\wsl-ubuntu.tar # 卸载原实例 wsl --unregister Ubuntu # 重新导入到新路径 wsl --import Ubuntu D:\WSL\Ubuntu D:\wsl-ubuntu.tar --version 2导入后还需要设置默认用户，否则登录时会提示找不到 home 目录：
ubuntu config --default-user your_username至此，你的 WSL2 环境已经干净整洁地安家在非系统盘上了。
进入 WSL 终端后第一件事，就是更换软件源为国内镜像，否则apt update的速度可能会让你怀疑人生。备份原始配置：
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak然后编辑文件：
sudo nano /etc/apt/sources.list替换为阿里云提供的 Ubuntu 22.04（jammy）镜像源：
deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse保存退出后立即更新包索引：
sudo apt update && sudo apt upgrade -y另一个常被忽略但至关重要的工具是git-lfs，它是处理大文件的核心依赖。Langchain-Chatchat 项目中的模型权重往往通过 Git LFS 托管，不装这个，克隆仓库时只会得到占位符。
安装非常简单：
sudo apt install git-lfs -y git lfs install --global顺带一提，如果你有 NVIDIA 显卡，强烈建议配置 CUDA 支持。虽然项目可以在纯 CPU 模式下运行，但 embedding 向量化和模型推理阶段的性能差距可达数倍之多。
你需要做的包括：
- 安装最新版NVIDIA 驱动
- 下载并安装CUDA Toolkit for WSL
- 推荐使用 GeForce Experience 自动检测更新
完成后在 WSL 终端执行：
nvidia-smi如果能看到 GPU 型号、显存占用等信息，说明驱动已正常工作。
现在我们正式进入 Langchain-Chatchat 的部署环节。
Python 环境管理推荐使用 Conda，尤其是面对复杂依赖时，它可以有效避免版本冲突带来的“玄学问题”。你可以选择安装 Anaconda 或更轻量的 Miniconda。安装完成后，通过 Anaconda Navigator 创建一个独立环境：
- 名称：
chatchat - Python 版本：
3.10（目前兼容性最好）
创建完成后，点击右侧 ▶️ 图标 → Open Terminal，进入该环境。此时命令行前缀应显示(chatchat)，表示环境已激活。
先升级 pip：
pip install --upgrade pip接着切换到 WSL2 的 home 目录，建立工作区：
cd ~ mkdir projects && cd projects从 GitHub 克隆项目源码，注意加上--recursive参数以包含所有子模块：
git clone --recursive https://github.com/chatchat-space/Langchain-Chatchat.git进入项目目录后安装依赖：
cd Langchain-Chatchat pip install -r requirements.txt首次安装耗时较长，视网络状况可能需要 5~15 分钟。如果某些包（如faiss-gpu、sentence-transformers）安装失败，可以尝试更换为清华 PyPI 镜像源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple模型部分是整个系统的核心。Langchain-Chatchat 支持多种主流中文模型，这里以两个典型为例：
| 类型 | 模型 | 平台 |
|---|---|---|
| 对话模型 | chatglm3-6b | ModelScope |
| Embedding 模型 | bge-large-zh-v1.5 | ModelScope |
在项目根目录创建模型文件夹：
mkdir models && cd models确保已全局启用 Git LFS，然后依次克隆模型仓库：
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⚠️ 注意：ModelScope 上的部分模型为私有仓库，需登录账号并在 Settings → Access Tokens 中生成令牌，再通过git lfs pull或配置凭据助手完成下载。
这两个模型合计约 15GB，建议保持稳定的网络连接。
模型到位后，下一步是配置参数。项目中configs/目录下的.example文件是模板，不能直接运行。好在作者提供了一个便捷脚本：
python copy_config_example.py执行后会自动生成settings.py、model_config.py等可执行配置文件。
重点修改configs/model_config.py中的模型路径。使用文本编辑器打开：
nano configs/model_config.py找到类似以下字段：
MODEL_PATH = { "chatglm3-6b": "/home/your_user/projects/Langchain-Chatchat/models/chatglm3-6b", "bge-large-zh-v1.5": "/home/your_user/projects/Langchain-Chatchat/models/bge-large-zh-v1.5" }这里的路径必须是 WSL2 内部的绝对路径，不能写成/mnt/c/...这样的 Windows 挂载路径。最稳妥的方式是进入对应模型目录，用pwd命令获取准确路径：
cd models/chatglm3-6b pwd复制输出结果粘贴至配置文件即可。同时务必检查模型名称拼写是否一致，特别是大小写敏感问题。
准备工作全部完成后，就可以初始化知识向量库了。这是首次运行的关键一步，作用是将文档切片并通过 embedding 模型转换为向量，存入 FAISS 或 Chroma 数据库。
执行命令：
python init_database.py --recreate-vs--recreate-vs表示强制重建，清除旧数据。这对于第一次部署非常必要，避免残留缓存引发异常。
该过程资源消耗较大：
- CPU 占用率接近满载
- 内存消耗 8~16GB（取决于文档数量）
- 若启用 GPU，显存占用约 4~6GB
持续时间一般在 5~10 分钟之间，风扇狂转属于正常现象。完成后会在data/vectordb目录生成对应的向量数据库文件。
最后一步，启动服务：
python startup.py -a-a参数表示同时启动 API 服务（基于 FastAPI）和 Web UI（基于 Streamlit）。默认监听地址为：
- API：
http://0.0.0.0:7861 - Web UI：
http://0.0.0.0:8501
但由于 WSL2 的网络隔离机制，你不能直接在浏览器访问0.0.0.0地址。正确的做法是使用 Windows 主机的回环地址：
打开浏览器，输入：
http://127.0.0.1:8501稍等片刻，即可看到 Langchain-Chatchat 的 Web 界面加载成功。首次启动较慢，因为需要加载大模型到内存，请耐心等待。
在整个部署过程中，有几个常见问题值得特别提醒：
打不开 8501 端口？
检查 Windows 防火墙是否阻止了端口转发。可尝试执行wsl --shutdown关闭所有 WSL 实例，然后重新启动项目。embedding 模型加载失败？
多半是路径错误或模型文件不完整。请确认目标文件夹中是否存在config.json、pytorch_model.bin和tokenizer.model等关键文件。想换 Qwen、Baichuan 或其他模型？
完全支持！只需在model_config.py中添加新模型路径，并在 Web UI 的模型选择下拉菜单中切换即可。只要模型格式符合 HuggingFace 或 ModelScope 标准结构，基本都能无缝接入。如何添加自己的文档？
将 PDF、Word、Markdown 等文件放入data/knowledge_base/default目录，然后再次运行init_database.py重新构建向量库即可。增量更新时无需加--recreate-vs。
总结一下，这次部署的核心要点可以归纳为几个关键词：环境隔离、路径正确、模型完整、访问方式适配。使用 Conda 管理 Python 环境能极大降低依赖冲突风险；坚持使用 WSL 内部路径而非/mnt/c挂载路径，可避免权限和性能问题；而通过127.0.0.1访问 Web UI，则是绕过 WSL2 网络限制的标准解法。
当你看到那个简洁的聊天界面出现在浏览器中，上传一份公司手册并成功提问“我们的休假政策是什么？”时，那种成就感是难以言喻的。更重要的是，这一切都在你的本地设备上完成，没有一丝数据外泄的风险。
Langchain-Chatchat 不只是一个技术玩具，它正在成为越来越多企业和个人构建专属 AI 助手的起点。而 WSL2 则为我们提供了一条平滑过渡到 Linux 开发世界的路径，无需双系统，也不必折腾虚拟机。
🌐 项目地址：https://github.com/chatchat-space/Langchain-Chatchat
📚 官方文档：https://chatchat.readthedocs.io
现在，轮到你动手打造属于自己的智能知识引擎了。Happy Chating! 💬
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
