Langchain-Chatchat 0.3.1 Windows部署指南

Langchain-Chatchat 0.3.1 Windows 部署实战指南

在企业知识管理日益智能化的今天，如何让内部文档“活起来”，成为员工随问随答的智能助手？一个安全、可控、本地化运行的知识库问答系统显得尤为关键。而 Langchain-Chatchat 正是这一需求下的理想选择——它基于 LangChain 构建，支持私有文档上传与语义检索，所有数据处理均在本地完成，无需依赖云端 API，真正实现数据不出内网。

本文将带你从零开始，在 Windows 11 系统上完整部署 Langchain-Chatchat v0.3.1，并整合 Xinference 作为本地大模型推理后端。整个过程涵盖环境隔离、GPU 加速配置、中文路径避坑、模型部署与知识库构建等核心环节，尤其适合希望搭建离线 RAG（检索增强生成）系统的开发者或技术团队。

---

环境准备：为什么需要两个 Conda 环境？

你可能会问：为什么不直接在一个环境中安装所有依赖？答案是——解耦与稳定性。

Langchain-Chatchat 和 Xinference 虽然协同工作，但它们对 Python 包的版本要求存在潜在冲突。例如，Xinference 对 pydantic、httpx 等库较为敏感，而主程序又可能依赖特定版本的 LangChain 模块。若混装在一起，极易引发“依赖地狱”。

因此，我们采用双环境策略：

• chatchat：运行前端交互逻辑和知识库处理
• xinference：专用于启动本地 LLM 推理服务，支持 GPU 加速

这样既能保证模块职责清晰，也便于后续独立升级与调试。

基础要求一览

项目	推荐配置
操作系统	Windows 10 / 11（64位）
Python 版本	3.10（实测最稳定）
显卡	NVIDIA GPU（CUDA 支持，≥6GB 显存）
存储空间	≥20GB 可用空间（模型文件较大）
包管理工具	Miniconda 或 Anaconda

⚠️ 特别提醒：尽管 Python 3.11+ 已普及，但部分底层包（如 llama-cpp-python）在 Windows 上仍对 3.10 兼容性最佳。为避免编译失败，建议锁定 Python 3.10。

---

第一步：创建虚拟环境并安装核心组件

打开 Anaconda Prompt（以管理员权限运行更佳），执行以下命令。

创建 chatchat 主程序环境

conda create -n chatchat python=3.10
conda activate chatchat

激活后，使用清华镜像源加速安装：

pip install "langchain-chatchat[xinference]" -U -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后验证是否成功：

chatchat --help

如果输出帮助信息，说明主程序已就绪。

---

创建 xinference 推理服务环境

切换回命令行，新建第二个环境：

conda create -n xinference python=3.10
conda activate xinference

安装 PyTorch + CUDA 支持

先查看你的 CUDA 驱动版本：

nvidia-smi

输出中会显示类似：

CUDA Version: 12.7

虽然驱动支持到 12.7，但我们只需选择 PyTorch 官方提供的兼容版本即可。目前推荐使用 CUDA 12.1 版本的 PyTorch：

前往 PyTorch 官网，选择：
- OS: Windows
- Package: Pip
- Language: Python
- Compute Platform: CUDA 12.1

执行如下命令：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

安装完成后测试 GPU 是否可用：

python -c "import torch; print(torch.cuda.is_available())"

预期输出为 True。若返回 False，请检查显卡驱动是否正常、是否有其他进程占用 GPU。

---

安装 Xinference 及其扩展包

继续安装：

pip install "xinference[all]"

但在 Windows 上，这个命令常常卡在 llama-cpp-python 的安装上，因为它需要从源码编译，并启用 CUDA 支持。

---

关键突破：解决 llama-cpp-python 编译难题

这是整个部署中最容易“翻车”的一步。由于 llama-cpp-python 在 PyPI 上没有为 Windows 提供预编译的 CUDA wheel 包，直接 pip 安装往往会失败。

解决方案：手动下载预编译 Wheel 文件

访问 GitHub 发布页获取社区构建好的版本：

🔗 https://github.com/abetlen/llama-cpp-python/releases

查找符合你环境的 .whl 文件，例如：

llama_cpp_python-0.3.4-cp310-cp310-win_amd64.whl

其中：
- cp310 表示 Python 3.10
- win_amd64 是 Windows 64 位系统
- 若未标注 “cpu-only”，通常已启用 CUDA 支持

下载后保存至本地（如 D:\downloads\），然后执行：

pip install D:\downloads\llama_cpp_python-0.3.4-cp310-cp310-win_amd64.whl

安装成功后再运行：

pip install "xinference[all]"

此时应能顺利通过。

---

启动 Xinference 服务前的重要设置

执行以下命令启动服务：

xinference-local --host 127.0.0.1 --port 9997

但如果你的用户名包含中文字符（如 C:\Users\张伟），很可能会遇到如下错误：

ValueError: Unable to configure handler 'file_handler'

这是因为 Python 日志模块无法正确解析非 ASCII 路径。

根治之道：自定义 XINFERENCE_HOME

解决方案是将默认工作目录重定向到不含中文的路径：

mkdir D:\xinference_logs
mkdir D:\xinference_logs\logs
set XINFERENCE_HOME=D:\xinference_logs

确认设置生效：

echo %XINFERENCE_HOME%

输出应为 D:\xinference_logs。

此后每次进入 xinference 环境都需重新设置该变量。为了避免重复操作，建议将其写入批处理脚本。

---

模型部署：在 Web 界面中启动 LLM 与 Embedding 模型

保持 xinference 环境运行，浏览器访问：

👉 http://127.0.0.1:9997

你会看到 Xinference 的图形化控制台。

部署 Qwen2.5-Instruct（LLM）

点击左上角 Launch Model → LLM，填写参数：

参数	值
Model Type	LLM
Model Format	GGUF 或 HuggingFace
Model Name	qwen2.5-instruct
Model Size	7B 或 14B（根据显存选择）
Quantization	q4_k_m（推荐，精度与速度平衡）
GPUs	auto
Host	127.0.0.1
Port	自动分配

💡 小技巧：如果网络较慢，可以提前用梯子拉取模型，或把本地已下载的 GGUF 文件拖入界面加载。

点击 Launch 后等待模型加载完成。成功后会在“Running Models”列表中出现。

---

部署 BGE-M3（Embedding 模型）

同样方式添加 Embedding 模型：

参数	值
Model Type	Embedding
Model Name	BAAI/bge-m3
Dimension	1024
Max Length	8192

点击 Launch 即可。

✅ BGE-M3 是当前最强的开源多向量检索模型之一，支持 dense、sparse 和 hybrid 检索模式，特别适合复杂语义匹配场景。

---

配置 Langchain-Chatchat 并连接模型服务

回到 chatchat 环境，初始化项目结构：

conda activate chatchat
chatchat init

该命令会在当前目录生成 configs/, data/, knowledge_base/ 等文件夹。

📂 默认知识库存放路径为 knowledge_base/sample/content/，你可以将 PDF、Word、TXT 等文档放入其中。

---

修改模型配置文件

编辑 configs/model_settings.yaml，确保 LLM 和 Embedding 模型地址指向 Xinference：

llm_model_dict:
  qwen2.5-instruct:
    model_name: qwen2.5-instruct
    server_address: http://127.0.0.1:9997
    local_model_path: null
    deployment_name: null

embedding_model_dict:
  bge-m3:
    model_name: BAAI/bge-m3
    server_address: http://127.0.0.1:9997
    local_model_path: null

🔍 注意事项：
- model_name 必须与 Xinference 中部署的名称完全一致（区分大小写）
- 地址必须是 http://127.0.0.1:9997，不能写成 localhost 或 0.0.0.0

---

构建知识库：让文档“被理解”

将你的私有文档复制到：

knowledge_base/sample/content/

支持格式包括 .txt, .pdf, .docx, .md, .pptx 等。

然后执行重建命令：

chatchat kb -r

-r 表示 rebuild，首次运行必须加上。程序将自动完成以下流程：

1. 文档加载与文本提取（PDF 使用 PyMuPDF，Word 使用 python-docx）
2. 文本分块（chunk size 默认 512，overlap 150）
3. 调用 BGE-M3 生成向量嵌入
4. 存入本地向量数据库（默认 Chroma）

运行结束后提示：

Successfully saved embeddings for knowledge base: sample

即表示知识库构建成功。

---

启动 Web UI：开启智能问答之旅

最后一步：

chatchat start -a

-a 表示监听所有接口，等价于 --host 0.0.0.0 --port 7860。

浏览器访问：

👉 http://127.0.0.1:7860

你应该看到一个简洁的聊天界面。

尝试提问：“介绍一下你自己”，如果收到基于你上传文档的回答，说明整个链路已打通！

---

常见问题排查清单

❌ ModuleNotFoundError: No module named ‘httpx’

原因：新版 xinference 或 openai 依赖 httpx>=1.0，但 langchain-chatchat 当前仅兼容 0.27.x。

解决方案：

pip install httpx==0.27.2

这是一个典型的版本冲突案例，务必锁定此版本。

---

❌ ConnectionRefusedError: [WinError 10061]

连接被拒绝，常见原因有三：

1. Xinference 服务未启动？
2. model_settings.yaml 中地址拼错？
3. 模型尚未在 Xinference 中运行？

快速验证方法：浏览器访问
👉 http://127.0.0.1:9997/v1/models

若返回 JSON 列表且包含你部署的模型，则说明服务正常。

---

❌ CUDA out of memory

显存不足时的应对策略：

• 更换小模型（如 7B 替代 14B）
• 使用更低量化等级（如 q3_k_m）
• 关闭浏览器硬件加速、游戏等 GPU 占用程序
• 在任务管理器中结束 python.exe 进程释放显存

---

✅ 如何更换其他模型？

Langchain-Chatchat 支持任意可通过 Xinference 加载的模型，只要满足：

• LLM 支持 Chat Template（能调用 apply_chat_template）
• Embedding 输出固定维度向量

推荐组合：

类型	推荐模型
LLM	Qwen2.5, DeepSeek-V2, Llama3-Chinese
Embedding	bge-m3, text2vec-large-chinese

只需在 Xinference 中部署新模型，并在 model_settings.yaml 中更新名称即可。

---

效率提升：编写一键启动脚本

为了省去每次都要手动激活环境和设置变量的麻烦，建议创建两个 .bat 批处理脚本。

start_xinference.bat

@echo off
call conda activate xinference
set XINFERENCE_HOME=D:\xinference_logs
echo Starting Xinference on http://127.0.0.1:9997
xinference-local --host 127.0.0.1 --port 9997
pause

start_chatchat.bat

@echo off
call conda activate chatchat
echo Starting Chatchat Web UI on http://127.0.0.1:7860
chatchat start -a
pause

双击即可快速启动，极大提升日常调试效率。

---

总结与展望

通过以上步骤，你已经成功搭建了一套完整的本地化 RAG 系统：

• 使用 Xinference 实现了本地大模型推理
• 通过 Langchain-Chatchat 构建了可搜索的知识库
• 所有环节均可离线运行，保障数据隐私

这套架构不仅适用于个人知识管理，也可扩展为企业级应用：

• 接入企业微信/钉钉机器人，实现即时答疑
• 添加语音识别与合成模块，打造“听得懂、说得出”的 AI 助手
• 开发多租户管理系统，支持不同部门独立维护知识库

更重要的是，这一切都建立在开源生态之上。你可以自由定制、深度优化，而不受任何商业 API 的限制。

未来，随着更多轻量化模型的涌现（如 Qwen2.5-3B、Phi-3-mini），这类本地智能系统将在边缘设备、中小企业乃至教育领域发挥更大价值。

---

📌 GitHub 项目地址：https://github.com/chatchat-space/Langchain-Chatchat

愿你在构建属于自己的 AI 助手之路上越走越远。当第一句基于私有文档的回答从屏幕弹出时，你会明白：真正的智能，始于可控的数据，终于无限的可能。