安徽唯一制冷设备有限公司
User Avatar

舟山网站建设淮北网站建设

安徽唯一制冷设备有限公司 2026/09/09 20:03:22

Langchain-Chatchat 0.3.1 Windows本地部署实战指南

在企业对数据安全要求日益严格的今天，如何在不依赖云端服务的前提下，构建一个能理解私有文档内容的智能问答系统？这正是Langchain-Chatchat的价值所在。它将大语言模型（LLM）与本地知识库结合，通过 RAG（检索增强生成）架构实现精准回答，所有处理均在本地完成，彻底规避了敏感信息外泄的风险。

本文基于Windows 11系统，带你从零开始部署Langchain-Chatchat v0.3.1，并结合Xinference实现本地化推理。整个过程采用 Conda 虚拟环境隔离管理，支持 GPU 加速，适合个人开发者或企业内网环境使用。

部署前准备：软硬件建议与关键细节

首先明确一点：这个项目对环境非常“挑剔”，尤其是 Python 版本和 CUDA 兼容性问题稍有不慎就会导致安装失败。

推荐配置清单

组件建议
CPUIntel i5 或以上
内存≥16GB RAM（低于此值可能无法加载7B以上模型）
显卡NVIDIA GPU，推荐 RTX 3060 及以上，显存 ≥8GB
存储≥50GB 可用空间（模型缓存会占用大量磁盘）

⚠️ 注意：官方明确要求Python 3.10，不兼容 3.11+！如果你已经装了新版 Python，请务必通过 Anaconda 创建独立环境。

所需软件：
- Anaconda 或 Miniconda
- Git
- CUDA Toolkit（若使用 GPU）
- HuggingFace CLI（可选，用于手动拉取模型）

构建双环境架构：避免依赖冲突的核心策略

为了避免主程序与模型服务之间的依赖“打架”，我们采用两个独立的 Conda 环境：

  • chatchat：运行 Langchain-Chatchat 主体
  • xinference：托管 LLM 和 Embedding 模型

这种设计不仅提升了稳定性，也便于后期维护和升级。

第一步：创建 chatchat 主环境

打开Anaconda Prompt或 CMD，执行以下命令：

conda create -n chatchat python=3.10 -y 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 -y conda activate xinference
查看你的 CUDA 版本

执行：

nvidia-smi

注意观察输出中的CUDA Version字段（不是 Driver Version）。例如：

CUDA Version: 12.4

这个版本号决定了你要安装哪个 PyTorch 包。前往 PyTorch 官网 找到对应命令。

以 CUDA 12.4 为例：

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

✅ 务必确保 CUDA 版本完全匹配！否则后续会出现CUDA not available或DLL load failed等错误。

安装完成后，再安装 Xinference：

pip install "xinference[all]"

常见坑点：llama-cpp-python编译失败怎么办？

很多 Windows 用户会遇到如下报错：

ERROR: Could not build wheels for llama-cpp-python, which is required to install pyproject.toml-based projects

这是因为该包需要从源码编译，而 Windows 缺少必要的工具链。

解决方案：手动安装预编译 wheel 包

  1. 访问发布页：
    https://github.com/abetlen/llama-cpp-python/releases

  2. 根据你的环境选择合适文件：
    - Python 版本：cp310（对应 Python 3.10）
    - CUDA 版本：如 cu121 / cu124
    - 系统架构：win_amd64

示例文件名：
llama_cpp_python-0.3.4-cp310-cp310-win_amd64.whl

  1. 下载后执行安装：
pip install D:Downloadsllama_cpp_python-0.3.4-cp310-cp310-win_amd64.whl

🔄 替换为你的实际路径。

  1. 成功后再运行：
pip install "xinference[all]"

此时应能顺利完成安装。

测试 Xinference 是否正常工作

启动服务：

xinference-local --host 127.0.0.1 --port 9997

🔥 强烈建议不要用0.0.0.0！Windows 对多网卡绑定较敏感，容易引发地址冲突。

浏览器访问：

👉 http://127.0.0.1:9997

看到控制台页面即表示服务启动成功。

中文用户名导致的日志路径错误？一招解决

如果你的用户名是中文（如C:Users张三xinference），可能会遇到：

ValueError: Unable to configure handler 'file_handler'

原因是 Python 日志模块无法解析非 ASCII 路径。

解法：修改XINFERENCE_HOME环境变量
mkdir D:xinference_home mkdir D:xinference_homelogs set XINFERENCE_HOME=D:xinference_home

💡 此设置仅对当前会话有效。如需永久生效，请在“系统属性 → 高级 → 环境变量”中添加系统变量。

验证：

echo %XINFERENCE_HOME%

输出应为：

D:xinference_home

之后再启动xinference-local即可绕过路径问题。

启动模型服务：让大模型跑起来

每次使用前记得激活环境并设置路径：

conda activate xinference set XINFERENCE_HOME=D:xinference_home xinference-local --host 127.0.0.1 --port 9997

等待服务启动后，进入网页控制台。

部署 LLM 模型（以 Qwen2.5-Instruct 为例）

  1. 点击左侧“Launch Model”
  2. 选择“Large Language Model”
  3. 填写参数：
    -Model Type:qwen
    -Model Name:qwen2.5-instruct
    -Model Size (in B): 如 7B
    -Quantization: 推荐q4_k_m（平衡性能与显存）
    -GPU Count: 设置可用数量（如 1）
    -Replica: 1
  4. 点击火箭图标启动

⏱ 首次加载较慢，耐心等待几分钟。模型越大、硬盘越慢，耗时越长。

部署成功后，在Running Models列表可见实例。

部署 Embedding 模型（推荐 BGE-M3）

RAG 的核心在于向量化检索，因此高质量的 Embedding 模型至关重要。

  1. 返回 Launch 页面
  2. 选择“Embedding”
  3. 配置如下：
    -Model:bge-m3
    -Device:cuda（启用 GPU 加速）
    -Maximum Length:8192（支持长文本分块）
  4. 启动

📦 若提示无法下载，可能是网络限制。建议提前用 HuggingFace CLI 手动拉取：

huggingface-cli download BAAI/bge-m3 --local-dir bge-m3

然后在 Xinference 中选择本地目录加载。

部署成功后，可在运行列表中看到bge-m3实例。

配置 Langchain-Chatchat：打通前后端连接

初始化项目结构

确保已激活chatchat环境：

conda activate chatchat

执行初始化：

chatchat init

该命令会在当前目录生成.chatchat/文件夹，包含：

.chatchat/ ├── config/ │ ├── model_settings.yaml │ └── settings.yaml ├── knowledge_base/ │ └── default/ └── models/

无需克隆 GitHub 仓库即可运行，非常适合快速体验。

修改模型配置：填入正确的 UID

编辑config/model_settings.yaml，找到 LLM 配置段落：

- model_name: qwen2.5-instruct model_type: llm langchain_provider: xinference server_url: http://127.0.0.1:9997 model_uid: your-model-uid-here

以及 Embedding 部分：

- model_name: bge-m3 model_type: embedding langchain_provider: xinference server_url: http://127.0.0.1:9997 model_uid: your-embedding-uid

🔍model_uid在 Xinference 控制台的 “Running Models” 表格第一列显示。

保存文件。

构建知识库索引：让 AI “读懂”你的文档

将私有文档放入knowledge_base/default/目录下（支持 .txt, .pdf, .docx, .md 等格式）。

执行向量化处理：

chatchat kb -r

-r表示重建知识库（rebuild）

日志输出示例：

[INFO] Building vector store for knowledge base: default [INFO] Found 5 documents to process... [INFO] Document parsing completed. [INFO] Text splitting finished: 128 chunks generated. [INFO] Embedding generation started... [INFO] Vector store saved successfully.

当出现最后一行提示时，表示知识库构建完成。

启动 Web 服务：开启对话之旅

最后一步：

chatchat start -a

-a自动打开浏览器并监听所有接口

成功后终端输出：

Running on local URL: http://127.0.0.1:8778 Running on external URL: http://<your-ip>:8778

浏览器跳转至：

👉 http://127.0.0.1:8778

界面功能一览：
- 左侧选择知识库
- 中间为对话区
- 右上角切换模型

尝试提问：“请根据知识库内容介绍公司产品”，系统将结合你上传的文档进行回答。

常见问题排查与优化建议

错误1：httpx版本过高导致连接失败

现象：启动时报错AttributeError: module 'httpx' has no attribute 'AsyncClient'

原因：Langchain 当前版本依赖旧版httpx接口。

解决方法：

pip install httpx==0.27.2

✅ 建议锁定此版本，避免未来更新破坏兼容性。

错误2：模型连接超时或返回空响应

检查项：
- Xinference 是否正在运行？
-model_uid是否填写正确？
- 防火墙是否阻止了 9997 端口？
- GPU 显存是否足够？可用nvidia-smi查看

建议重启 Xinference 并重新部署模型。

错误3：知识库未生效或为空

确认：
- 文档是否已放入knowledge_base/default/？
- 是否执行了chatchat kb -r？
- 向量化过程中是否有报错？

可在.chatchat/configs/local_embed_config.json中调整分块策略，比如增大chunk_size提高上下文完整性。

进阶技巧：提升性能与部署效率

模型选型推荐

类型推荐模型优势
LLMQwen2.5-Instruct / InternLM2 / Yi-Coder中文能力强，响应流畅
EmbeddingBGE-M3 / text2vec-large-chinese支持多语言、混合检索

BGE-M3 尤其强大，支持密集、稀疏、多向量三种模式，召回率更高。

性能优化技巧

  • 使用量化模型（如q4_k_m）降低显存占用
  • 关闭后台程序释放内存
  • 将模型缓存迁移到 SSD 提升加载速度
  • 在settings.yaml中调整chunk_size（建议 512~1024）和overlap（建议 50~100）提高语义连贯性

持久化部署建议

  • 编写.bat脚本自动化启动流程
  • 配置 Windows 计划任务实现开机自启
  • 结合 Nginx 做反向代理，对外提供 HTTPS 服务
  • 使用 Docker 封装环境（适用于团队协作）

一键启动脚本模板

为了简化操作，可创建批处理脚本自动启动双服务：

@echo off echo 正在启动 Xinference 服务... start cmd /k "conda activate xinference && set XINFERENCE_HOME=D:xinference_home && xinference-local --host 127.0.0.1 --port 9997" timeout /t 10 echo 正在启动 Langchain-Chatchat... start cmd /k "conda activate chatchat && chatchat start -a" echo 启动完成，请访问 http://127.0.0.1:8778 pause

保存为start_chatchat.bat，双击即可一键运行。

这种高度集成的本地化 AI 架构，正逐渐成为企业构建私有知识助手的标准范式。它不仅保障了数据主权，也为离线场景下的智能化应用打开了新可能。只要按照上述步骤操作，即使没有深度学习背景的开发者，也能在一小时内完成部署，真正拥有一个属于自己的“本地大脑”。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈，一经查实，立即删除！

兰州网站建设宁波市网站建设

文章目录具体实现截图主要技术与实现手段关于我本系统开发思路java类核心代码部分展示结论源码lw获取/同行可拿货,招校园代理 ：文章底部获取博主联系方式！具体实现截图同行可

2026/06/30 12:10:59

大型门户网站建设广州企业网站建设

深入探索 Web 服务：从创建到客户端调用1. 运行应用程序在运行应用程序时，需要运行多个副本，每个副本使用自己的配置文件版本。具体操作步骤如下：1. 按下 F6 重建解决方案，修复可能存在的编译器问

2026/06/30 13:50:07

东莞网站建设房地产网站建设

第一章：Open-AutoGLM官方KEY限时开放？(稀缺资源抢夺战打响)近期，开源社区迎来一场突如其来的资源争夺战——Open-AutoGLM项目组意外宣布

2026/06/30 11:00:23

行业网站建设哈尔滨网站建设

还在为错过Epic Games每周免费游戏而烦恼吗？这款智能领取小帮手将彻底解放您的双手，让您轻松获取每一款免费游戏，构建专属游戏库从未如此简单！

2026/06/30 14:05:38

衡水网站建设徐汇网站建设

博客写作素材：用M2FP生成AI绘画人物结构指导图🧩 M2FP 多人人体解析服务在AI绘画创作过程中，准确理解人物姿态与身体结构是提升作品质量的关键。然而&

2026/06/30 11:38:56

贵州网站建设淘宝网站建设

TypeScript (简称 TS) 和 JavaScript (简称 JS) 都是用于编写Web应用程序的语言，它们的区别在于：1.类型不同JS:一种脚本语言࿰

2026/06/30 10:21:49

辽宁网站建设网站建设建设

学术写作中难免遇到重复率过高的问题，现代人工智能技术为此提供了多种智能解决方案。通过对比测试发现，目前市场上有六种效果显著的智能降重系统，能够有效帮助研究者解

2026/06/30 12:10:59

怎样网站建设优秀网站建设

ControlNet深度解析：从技术原理到实战性能的全面测评【免费下载链接】ControlNetLet us control diffusion models!项目地址: https:/

2026/06/30 12:19:00

免费网站建设廊坊网站建设

Qwen3-VL在STEM与数学推理中的卓越表现：多模态因果分析实战在智能教育平台日益普及的今天，一个现实问题反复浮现：学生上传了一道附带手绘图的几何题截图&

2026/06/30 11:02:53

长沙网站建设公司黄石网站建设

快速体验打开 InsCode(快马)平台 https://www.inscode.net输入框内输入如下内容：创建一个基于AI的Git辅助工具，能够自动生成有意义的提交信息

2026/06/30 12:27:31