LangChain-Chatchat Windows 本地部署指南

基础环境准备

本文介绍在 Windows 环境下部署 LangChain-Chatchat 的完整流程。建议系统版本为 Windows 10 专业版 22H2 或更高。

硬件与软件要求

操作系统：Windows 10/11
Python 版本：推荐 Python 3.10（需与项目依赖兼容）
CUDA 版本：根据显卡驱动选择，如 CUDA 11.8
Conda 管理工具：推荐使用 Miniconda3 进行环境隔离
硬件配置：建议配备 NVIDIA 显卡（如 RTX 3060 及以上），显存至少 6GB，内存 16GB 以上

安装依赖

创建 Conda 环境

使用 conda 创建并激活独立环境，避免污染全局 Python 环境。

conda create -n Langchain-Chatchat python=3.10
conda activate Langchain-Chatchat

拉取代码仓库

从 GitHub 克隆官方仓库。

git clone https://github.com/chatchat-space/Langchain-Chatchat.git
cd Langchain-Chatchat

安装依赖包

默认依赖包含基本运行环境（FAISS 向量库）。如需使用 Milvus、PG_Vector 等外部向量库，请修改 requirements.txt 取消相应注释后再安装。

pip install -r requirements.txt

按需安装模式

本项目架构分为 LLM 服务、API 服务和 WebUI 服务，可根据实际需求精简安装。

仅运行 LLM 和 API 服务：

pip install -r requirements_api.txt

仅运行 WebUI 服务：

pip install -r requirements_webui.txt

注意：使用 langchain.document_loaders.UnstructuredFileLoader 加载 .docx 等非结构化文件时，可能需要额外安装相关解析库，请参考官方文档补充依赖。

下载模型

模型选择

LangChain-Chatchat 支持多种开源 LLM 与 Embedding 模型。若使用在线 LLM 服务（如 OpenAI API），可跳过本地模型下载步骤。

对于本地离线部署，需下载模型权重。常用模型可从 Hugging Face 获取。

以 RTX 3060 (6G 显存) 为例，推荐配置如下：

LLM 模型：chatglm2-6b-int4
Embedding 模型：moka-ai/m3e-base

下载命令

git clone https://huggingface.co/THUDM/chatglm2-6b-int4
git clone https://huggingface.co/moka-ai/m3e-base

网络优化方案

若网络环境较差，下载速度缓慢，可采用以下策略：

跳过 LFS 对象：仅获取仓库结构，不下载大文件。

GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/THUDM/chatglm2-6b-int4

手动下载参数文件：从镜像站下载模型参数文件，放入本地仓库目录下。

修改配置项

1. 模型相关参数配置

复制模板文件并重命名：

cp configs/model_config.py.example configs/model_config.py

编辑 configs/model_config.py，主要修改以下内容：

本地 LLM 模型路径：确认已下载的模型路径写入 llm_model_dict 中。

llm_model_dict={
    "chatglm2-6b-int4": {
        "local_model_path": "D:\\Langchain-Chatchat\\chatglm2-6b-int4",
        "api_base_url": "http://localhost:8888/v1",
        "api_key": "EMPTY"
    },
}

注：若模板中无对应模型，需手动添加。

在线 LLM 服务接口：如使用类 OpenAI API，需修改 gpt-3.5-turbo 配置。

llm_model_dict={
    "gpt-3.5-turbo": {
        "local_model_path": "gpt-3.5-turbo",
        "api_base_url": "https://api.openai.com/v1",
        "api_key": os.environ.get("OPENAI_API_KEY")
    },
}

指定使用的 LLM 模型名称：

LLM_MODEL = "chatglm2-6b-int4"

Embedding 模型路径：

embedding_model_dict = {
    "m3e-base": "D:\\Langchain-Chatchat\\m3e-base",
}

2. 服务相关参数配置

复制服务配置模板：

cp configs/server_config.py.example configs/server_config.py

编辑 configs/server_config.py，修改服务绑定 IP：

DEFAULT_BIND_HOST = "127.0.0.1"  # 根据实际网络需求修改

知识库初始化

首次运行或更换 Embedding 模型后，需初始化知识库。

python init_database.py --recreate-vs

该命令将重建向量数据库索引，确保检索准确性。

启动服务

1. 启用 LLM 服务

若使用开源模型本地部署，需先启动 LLM 服务。推荐使用多进程脚本启动：

python server/llm_api.py

此脚本将启动 FastChat 服务端，监听默认端口。

2. 启用 API 服务

执行 API 服务脚本：

python server/api.py

启动后可访问 http://localhost:7861/docs 查看 FastAPI 自动生成的接口文档并进行测试。

3. 启用 WebUI 服务

启动 Streamlit 前端界面（默认端口 8501）：

streamlit run webui.py

自定义主题与端口

指定主题颜色：

streamlit run webui.py --theme.base "light" --theme.primaryColor "#165dff"

指定端口号：

streamlit run webui.py --server.port 666

验证与常见问题

服务验证

启动成功后，浏览器访问 http://localhost:8501 即可进入 WebUI 界面。尝试输入问题，观察响应速度及内容准确性。

常见故障排查

显存不足：若运行时报 OOM 错误，请尝试减小 batch size 或更换更小参数量模型（如 int4 量化版）。
端口冲突：若提示端口占用，请在 server_config.py 中修改 DEFAULT_PORT 或 server.port 参数。
模型加载失败：检查 model_config.py 中的路径是否正确，并确保模型文件完整。
向量库连接超时：若使用外部向量库，请检查网络连接及防火墙设置。

总结

完成上述步骤后，LangChain-Chatchat 即可在 Windows 环境下正常运行。用户可通过 WebUI 进行对话交互，或通过 API 集成至其他业务系统。建议定期关注官方仓库更新，以获取最新的功能修复与性能优化。