Langchain-Chatchat 0.3.1本地部署全指南

Langchain-Chatchat 0.3.1本地部署全指南

在企业知识管理日益智能化的今天，如何构建一个安全、可控、高效的私有问答系统，成为越来越多技术团队关注的核心问题。尤其在数据隐私要求严格的场景下，将敏感文档上传至云端模型显然不可接受。正是在这样的背景下，Langchain-Chatchat应运而生——它不是一个简单的开源项目，而是一套真正落地的本地化 RAG（检索增强生成）解决方案。

基于LangChain框架与主流大语言模型（LLM），Langchain-Chatchat 实现了从文档解析、向量化存储到语义检索和智能生成的完整闭环。支持 TXT、PDF、Word、Excel 等多种格式的知识源输入，所有处理均在本地完成，无需依赖外部 API，彻底杜绝数据泄露风险。无论是企业内部制度查询、技术支持问答，还是培训资料辅助阅读，这套系统都能提供精准且可追溯的回答。

本文以v0.3.1 版本为基础，结合实际部署经验，详细拆解在 Ubuntu 系统上的完整部署流程。涵盖环境准备、模型管理、配置调优、知识库初始化及服务启动等关键环节。Windows 用户也可参考执行，仅需对部分命令做适配调整。

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

环境搭建：从零开始构建推理基础

任何本地大模型应用的成功，都建立在稳定可靠的运行环境之上。Langchain-Chatchat 虽然封装良好，但其背后依赖多个组件协同工作——Python 运行时、GPU 加速库、模型服务框架等，缺一不可。

基础软硬件建议

• 操作系统：Ubuntu 20.04 或 22.04 LTS（长期支持版更稳妥）
• 显卡配置：NVIDIA GPU，驱动版本 ≥ 525，CUDA ≥ 11.8，cuDNN ≥ 8.6
• 内存与显存：建议 RAM ≥ 16GB，显存 ≥ 12GB（用于加载 Qwen、BGE 等中大型模型）
• Python 管理工具：推荐使用 Miniconda 或 Anaconda 创建独立虚拟环境

⚠️ 切记不要直接使用系统全局 Python 环境。不同项目间依赖冲突极为常见，隔离是避免“依赖地狱”的第一道防线。

安装步骤实践

首先创建专用虚拟环境：

conda create -n chatchat python=3.11 conda activate chatchat

Python 3.11 是当前兼容性最佳的选择，多数 LangChain 生态包均已适配。接着配置国内镜像源，大幅提升 pip 安装速度：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

这一步看似微小，但在后续安装数十个依赖包时会节省大量等待时间，尤其是对于网络条件一般的用户。

核心组件安装：选择合适的推理后端

Langchain-Chatchat 的一大优势在于其灵活的后端支持。你可以通过 FastChat、Ollama 或 Xinference 来托管 LLM 和 Embedding 模型。本指南选用Xinference，原因如下：

• 对国产模型（如通义千问、GLM）支持完善；
• 提供图形化界面，便于模型状态监控；
• 支持多实例部署与资源调度；
• 与 Chatchat 集成度高，配置简单。

安装主程序

执行以下命令安装 Langchain-Chatchat 主体及其扩展依赖：

pip install "langchain-chatchat[xinference]" -U

该指令会自动拉取langchain、xinference-client、文档解析库（如 PyPDF2、docx2txt、openpyxl）以及 CPU 版本的 FAISS 向量数据库。如果你拥有 NVIDIA 显卡，强烈建议手动替换为 GPU 加速版本：

pip uninstall faiss-cpu -y pip install faiss-gpu

否则向量检索性能将受到显著影响，尤其是在处理上千页文档时。

安装 Xinference 推理平台

接下来安装 Xinference 本身：

pip install "xinference[all]"

💡重要提示：截至 v0.3.1，Chatchat 与 Xinference 的兼容性存在一定限制。若安装最新版（≥0.14.0），可能出现模型注册失败或无法识别的问题。建议锁定版本：

bash pip install "xinference[all]==0.13.1"

这是我们在多次部署中验证过的稳定组合，能有效避免因接口变更导致的服务异常。

模型部署：启动 Xinference 并加载核心模型

现在进入最关键的一步：部署语言模型（LLM）和嵌入模型（Embedding Model）。这两者构成了整个系统的“大脑”与“记忆中枢”。

启动 Xinference 服务

运行以下命令启动主服务：

xinference-local --host 0.0.0.0 --port 9997

成功后访问http://<your-server-ip>:9997即可看到图形化控制台。首次启动可能需要几分钟时间初始化。

🔐 安全提醒：生产环境中请勿暴露0.0.0.0至公网。可通过 Nginx 反向代理并添加 Basic Auth 认证，防止未授权访问。

你也可以设置模型缓存路径，避免重复下载：

MODELSCOPE_CACHE=/data/models xinference-local --host 0.0.0.0 --port 9997

这样所有从 ModelScope 下载的模型都将保存在指定目录，方便管理和迁移。

加载所需模型

系统正常运行至少需要两个模型：

部署 Qwen2-7B-Instruct

1. 打开 Xinference Web UI → “Launch Model” → “Large Language Model”
2. 搜索qwen2，选择qwen2-chat或qwen2-instruct
3. 设置 GPU 数量（根据显存决定，12GB 显存可跑 FP16 全精度；若不足，考虑 INT4 量化版本）
4. 点击“Launch”，系统将自动从 ModelScope 下载模型（国内用户下载速度快）

首次下载耗时较长（约 10~20 分钟），但后续可复用缓存。

部署 bge-m3 嵌入模型

切换到 “Embedding” 类别，搜索bge-m3并部署。该模型在中文语义理解方面表现优异，尤其擅长长文本分块后的向量化表示。

部署完成后，在“Models”列表中确认两个模型均处于Running状态，并记录各自的Model UID——这是后续配置文件中的关键字段。

配置与初始化：让系统“认识”你的模型

完成模型部署后，下一步是告诉 Langchain-Chatchat 如何连接这些模型。这需要通过修改配置文件来实现。

设置根目录环境变量

建议显式指定一个持久化路径用于存储知识库、日志和缓存：

export CHATCHAT_ROOT=/home/ubuntu/chatchat_data

然后创建该目录：

mkdir -p $CHATCHAT_ROOT

✅ 路径应避免包含中文或空格，否则某些 Python 库在路径解析时可能出错。

初始化默认配置

运行初始化命令生成基础配置文件：

chatchat init

此命令会在$CHATCHAT_ROOT/configs/目录下生成多个 YAML 文件，其中最关键的是：

• model_settings.yaml：定义使用的模型名称与连接信息
• basic_settings.yaml：服务绑定地址与端口
• server_config.yaml：API 与 WebUI 的高级参数

修改 model_settings.yaml

编辑该文件，重点更新以下内容：

DEFAULT_LLM_MODEL: qwen2-chat DEFAULT_EMBEDDING_MODEL: bge-m3 LLM_MODEL_CONFIG: qwen2-chat: model_name: qwen2-chat model_type: huggingface server: xinference model_uid: "xxxxxxxxxxxx" # 替换为 Xinference 中的实际值 EMBEDDING_MODEL_CONFIG: bge-m3: model_name: BAAI/bge-m3 model_type: embedding server: xinference model_uid: "yyyyyyyyyyyy" # 替换为实际值

🔁务必核对 model_uid！它是动态生成的唯一标识符，一旦填错，系统将无法定位模型。可在 Xinference UI 的模型详情页找到。

调整 basic_settings.yaml

此文件控制服务监听范围：

DEFAULT_BIND_HOST: 0.0.0.0 API_SERVER: host: 0.0.0.0 port: 7861 WEBUI_SERVER: host: 0.0.0.0 port: 8501

• 若仅本地测试，可设为127.0.0.1
• 若需局域网访问，请确保防火墙开放 7861、8501、9997 三个端口

例如，在 Ubuntu 上启用防火墙规则：

sudo ufw allow 7861/tcp sudo ufw allow 8501/tcp sudo ufw allow 9997/tcp

初始化知识库：构建专属“记忆”

没有知识库的问答系统就像无源之水。Langchain-Chatchat 默认自带一个示例库samples，可用于验证流程是否通畅。

执行重建命令

chatchat kb -r

参数说明：
--r表示 rebuild，清除旧索引并重新构建
- 可选-n <kb_name>指定特定知识库

首次运行时，系统会：
1. 扫描knowledge_base/samples/content/目录下的测试文档
2. 使用bge-m3进行文本切片与向量化
3. 存储至 FAISS 数据库

成功输出类似如下：

---------------------------------------------------------------------------------------------------- 知识库名称 ：samples 知识库类型 ：faiss 向量模型 ：bge-m3 知识库路径 ：/home/ubuntu/chatchat_data/knowledge_base/samples 文件总数量 ：47 入库文件数 ：42 知识条目数 ：740 用时 ：0:02:18.345120 ---------------------------------------------------------------------------------------------------- 总计用时 ：0:02:22.109876

📁 自建知识库？只需新建目录knowledge_base/your_kb/content/，放入自有文档，再执行：

bash chatchat kb -n your_kb -r

即可完成专属知识库构建。

启动服务：启动全流程引擎

一切就绪后，启动完整服务栈：

chatchat start -a

• start：启动所有必要服务
• -a：自动补全缺失组件（如 API Server、WebUI）

启动过程包括：
1. 检查模型连接状态（通过 Xinference Client）
2. 启动 FastAPI 后端（端口 7861）
3. 启动 Streamlit 前端（端口 8501）

最终提示：

✔️ Chatchat 已成功启动！ 🌐 访问 WebUI：http://<your-ip>:8501 🔌 API 文档：http://<your-ip>:7861/docs

打开浏览器访问对应地址，即可进入交互界面。

功能演示与典型使用场景

进入 WebUI 后，你会看到简洁直观的操作面板。

主要功能一览

示例：查询公司政策

假设你已导入《员工手册.docx》至名为hr_policy的知识库。

提问：“出差住宿标准是多少？”

系统行为：
1. 使用bge-m3对问题编码
2. 在hr_policy的 FAISS 索引中检索最相关段落
3. 将上下文送入Qwen2-7B-Instruct生成结构化回答

结果不仅准确，还能点击“查看来源”跳转到原文片段，极大提升可信度。

常见问题排查与优化建议

即使流程清晰，部署过程中仍可能遇到各种“坑”。以下是我们在实战中总结的高频问题与应对策略。

❌ 模型找不到？检查 UID 与服务状态

现象：提示Model not found
原因：model_uid填写错误或模型未运行
解决方法：
- 登录http://<ip>:9997确认模型 Running
- 复制正确的 UID 到model_settings.yaml
- 重启 Chatchat 服务使配置生效

❌ 嵌入模型不可用？

现象：知识库构建时报错Embedding model not available
排查步骤：

# 查看模型列表 xinference list # 检查服务是否存活 ps aux | grep xinference

确保EMBEDDING_MODEL_CONFIG中的server: xinference正确无误。

❌ WebUI 打不开？

可能原因：
- 防火墙未放行 8501 端口
-WEBUI_SERVER.host设为127.0.0.1
- Streamlit 缺失依赖或启动失败

调试命令：

netstat -tulnp | grep 8501 tail -f $CHATCHAT_ROOT/logs/webui.log

日志往往能揭示具体错误原因。

性能优化实战建议

特别是当知识库规模超过 1GB 时，建议尽早迁移到 Milvus 这类专业向量数据库，避免 FAISS 内存溢出。

Langchain-Chatchat v0.3.1 不只是一个开源项目，更是一种“数据主权回归”的实践路径。它让我们能够在不牺牲效率的前提下，完全掌控自己的知识资产。随着 RAG 技术的不断演进，这类本地化智能系统将在金融、医疗、法律等高敏感领域发挥更大价值。

与其等待通用 AI 解决所有问题，不如动手搭建属于你自己的智能知识引擎——毕竟，最懂你业务的，永远是你自己。