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 加速

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

基础要求一览

⚠️ 特别提醒：尽管 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，填写参数：

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

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

部署 BGE-M3（Embedding 模型）

同样方式添加 Embedding 模型：

点击 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 输出固定维度向量

推荐组合：

只需在 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 助手之路上越走越远。当第一句基于私有文档的回答从屏幕弹出时，你会明白：真正的智能，始于可控的数据，终于无限的可能。