Langchain-Chatchat本地部署指南

Langchain-Chatchat 本地部署实战指南

在企业知识管理日益智能化的今天，如何让大模型真正“读懂”内部文档，而不是凭空编造答案？这正是检索增强生成（RAG）技术的价值所在。而Langchain-Chatchat，作为中文社区中功能最完整、部署最灵活的开源 RAG 框架之一，正成为越来越多企业和开发者构建私有知识库问答系统的首选。

它不依赖公有云服务，支持将 PDF、Word、PPT 等各类非结构化文档转化为可被语义理解的知识向量，并结合 Qwen、ChatGLM 等主流大模型实现精准问答。更重要的是——整个流程可在本地完成，数据不出内网，安全可控。

本文将带你从零开始，一步步完成 Langchain-Chatchat 的本地部署，涵盖环境准备、模型接入、配置优化和 API 调用等关键环节，尤其适合需要保障数据隐私的企业用户或希望深入掌握 RAG 架构的技术人员。

核心架构与工作流程

Langchain-Chatchat 的本质是一个基于 LangChain 思想实现的本地化 RAG 系统。它的核心逻辑可以概括为：先检索，后生成。

整个过程如下所示：

[原始文档] ↓ 加载 & 解析 [纯文本内容] ↓ 分割为语义段落 [文本片段列表] ↓ 使用 Embedding 模型向量化 [向量数据库存储] ↘ → [用户提问] → 向量化 → 相似度匹配 → Top-K 匹配结果 ↗ [Prompt 构造：问题 + 上下文] ↓ 提交给 LLM 推理引擎 [生成最终回答]

这个看似简单的流程，实则解决了大模型应用中最棘手的问题——幻觉。通过引入外部知识库，系统不再仅靠模型参数记忆来回答问题，而是依据真实文档内容进行推理，显著提升了准确性和可解释性。

举个例子：当你问“公司差旅报销标准是多少？”时，系统会自动从上传的《员工手册》中检索相关段落，再由大模型提炼成简洁回答，而非靠“猜”。

这种设计特别适用于技术支持、制度查询、科研资料辅助等场景，尤其适合那些对信息准确性要求高、又不愿把敏感数据交给第三方平台的组织。

部署前准备：软硬件建议

虽然 Langchain-Chatchat 支持多种运行模式，但为了获得最佳体验，建议根据使用方式合理配置资源。

⚠️ 注意：如果你选择使用云端 API（如阿里百炼、OpenAI），本地只需基础计算能力即可；但如果要完全离线运行，则需下载并加载本地大模型，这对内存和显存要求较高。

完整部署流程详解

1. 创建独立运行环境

强烈建议使用 Conda 来隔离依赖，避免与其他项目冲突。

# 创建名为 chatchat 的 Python 3.10 环境 conda create -n chatchat python=3.10 conda activate chatchat # 升级 pip 并安装主包 pip install --upgrade pip pip install langchain-chatchat -U

📌 小贴士：首次安装可能会较慢，因为会自动拉取transformers、faiss-cpu等大型依赖，请保持网络畅通。

2. 初始化项目目录结构

Langchain-Chatchat 通过环境变量控制根路径，推荐提前设置。

# Linux/macOS 用户 export CHATCHAT_ROOT=/home/user/chatchat_data # Windows 用户（CMD） set CHATCHAT_ROOT=C:\chatchat_data

然后执行初始化命令：

chatchat init

该命令会自动生成以下目录结构：

$CHATCHAT_ROOT/ ├── config/ │ ├── model_settings.yaml # 模型配置文件 │ └── server_config.yaml # 服务端口与模块开关 ├── knowledge_base/ # 文档上传与知识库存放 │ └── samples/ # 示例知识库 ├── models/ # （可选）本地模型缓存 └── database/ # 向量数据库（默认 FAISS）

这套结构清晰明了，便于后期维护和备份。

3. 接入大模型服务：以 OneAPI + 阿里百炼为例

为了让系统具备“大脑”，我们需要为其接入一个可用的大语言模型。这里推荐一种常见且灵活的方式：使用 OneAPI 作为中间层，对接阿里云百炼平台。

第一步：获取百炼 API 密钥

1. 访问 阿里云百炼平台
2. 登录后开通服务（新用户通常赠送免费额度）
3. 进入「API Key 管理」→ 创建新的密钥对
4. 保存好AccessKey ID和Secret

百炼平台提供了多个 Qwen 系列模型，包括：
-qwen-turbo：响应快，适合实时对话
-qwen-plus：精度更高，适合复杂任务
-text-embedding-v1：专用于文本向量化

第二步：部署 OneAPI 服务（Docker）

OneAPI 是一个通用的大模型 API 聚合网关，支持统一调用不同厂商的模型。

mkdir -p /opt/one-api && cd /opt/one-api chmod 777 . docker run --name one-api -d \ -p 3000:3000 \ -e TZ=Asia/Shanghai \ -v $(pwd):/data \ justsong/one-api:latest

启动成功后，访问 http://localhost:3000/login
初始账号：root，密码：123456

第三步：添加百炼渠道

登录 OneAPI 后操作如下：

1. 左侧菜单 →「渠道管理」→「添加渠道」
2. 厂商选择：Alibaba Cloud (Tongyi)或Bailian
3. 输入名称（如qwen-turbo-channel）
4. 填写 AccessKey 和 SecretKey
5. 测试连接成功后提交

确保启用以下模型：
-qwen-turbo
-text-embedding-v1

第四步：创建 API Token

进入「令牌管理」→「创建令牌」：
- 设置有效期为“永久”
- 额度设为较大值（如 1,000,000 tokens）
- 勾选可用模型范围（包含上述两个模型）
- 复制生成的 token（后续要用）

4. 配置模型参数：修改model_settings.yaml

编辑$CHATCHAT_ROOT/config/model_settings.yaml文件，关键字段如下：

DEFAULT_LLM_MODEL: qwen-turbo DEFAULT_EMBEDDING_MODEL: text-embedding-v1 HISTORY_LEN: 3 TEMPERATURE: 0.7 MODEL_PLATFORMS: - platform_name: oneapi platform_type: oneapi api_base_url: http://127.0.0.1:3000/v1 api_key: sk-AaBbCcDdEeFfGgHhIiJjKkLlMmNn # 替换为你自己的 token api_proxy: '' api_concurrencies: 5 auto_detect_model: false llm_models: - qwen-turbo - qwen-plus embed_models: - text-embedding-v1 text2image_models: [] image2text_models: []

🔐 安全提醒：api_key属于敏感信息，切勿提交到 Git 仓库或日志输出中。生产环境中建议通过环境变量注入。

5. 启动服务并重建知识库索引

首次部署前，建议清空示例文档，避免因文件过多导致初始化耗时过长。

# 清空默认知识库内容 rm -rf $CHATCHAT_ROOT/knowledge_base/samples/content/* # 重建向量索引 chatchat kb -r # 启动所有服务（Web UI + API） chatchat start -a

常见问题排查：

• 若提示httpx版本冲突：
  bash pip uninstall httpx -y pip install httpx==0.27.2

• 若端口被占用，可修改server_config.yaml：
  yaml web_ui: host: 0.0.0.0 port: 8501 api: host: 0.0.0.0 port: 7861

启动成功后，你会看到类似输出：

INFO: Application startup complete. Web UI: http://0.0.0.0:8501 API Docs: http://localhost:7861/docs

实际使用与功能演示

Web 界面操作

打开浏览器访问：http://localhost:8501

主要功能包括：

• 知识库管理
• 新建/删除知识库
• 拖拽上传文档（支持 PDF、DOCX、TXT、MD、PPTX 等）
• 查看文档解析状态与分块情况
• 对话界面
• 选择目标知识库
• 输入问题，查看回答及引用来源
• 支持多轮对话上下文记忆
• 模型切换
• 可动态更换 LLM 或 Embedding 模型
• 调整 temperature、top_p 等生成参数

界面简洁直观，非技术人员也能快速上手。

API 接口调用

对于系统集成需求，Langchain-Chatchat 提供了完整的 RESTful API，Swagger 文档地址为：http://localhost:7861/docs

查询知识库列表

GET http://localhost:7861/knowledge_base/list_knowledge_bases

上传文档示例

curl -X POST "http://localhost:7861/knowledge_base/upload_file" \ -H "accept: application/json" \ -F "knowledge_base_name=samples" \ -F "file=@./manual.pdf"

发起问答请求

curl -X POST "http://localhost:7861/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-turbo", "messages": [{"role": "user", "content": "如何重置系统密码？"}], "knowledge_base_name": "samples" }'

返回结果将包含模型回答、引用的上下文片段以及来源文档信息，便于审计和追溯。

高阶配置技巧

1. 切换为本地 Embedding 模型（实现离线运行）

如果你追求彻底的数据自主权，可以替换掉云端的text-embedding-v1，改用 HuggingFace 上的开源中文嵌入模型。

推荐两款高性能中文 Embedding 模型：
- BAAI/bge-large-zh-v1.5
- moka-ai/m3e-base

修改配置文件即可无缝切换：

DEFAULT_EMBEDDING_MODEL: bge-large-zh-v1.5 LLM_MODEL_CONFIG: embed_model: model: BAAI/bge-large-zh-v1.5 device: cuda # 若有 GPU，提升速度

首次运行时会自动下载模型（约 1.5GB），之后即可完全离线使用。

💡 实践建议：对于中文场景，bge-large-zh-v1.5在多个基准测试中表现优于通用英文模型，尤其擅长处理专业术语和长句匹配。

2. 使用 Xinference 部署本地大模型

想要连 LLM 也本地化？试试 Xinference，它能帮你轻松部署 Qwen、ChatGLM、Llama 等主流开源模型。

安装与启动：

pip install xinference xinference-local start -H 0.0.0.0 -p 9997

启动后访问 Web UI 注册模型，例如加载Qwen-7B-Chat。

然后在model_settings.yaml中调整平台配置：

platform_type: xinference api_base_url: http://127.0.0.1:9997/v1

此时系统就会调用本地运行的 Qwen 模型，真正实现“数据不出局域网”的全链路私有化部署。

📌 注意事项：
- 本地运行 7B 级别模型至少需要 16GB 显存（INT4 量化）
- 推理延迟相比云端略高，但胜在可控性强

写在最后：为什么选择 Langchain-Chatchat？

经过多年的迭代，Langchain-Chatchat 已经不再是简单的 Demo 项目，而是一个真正可用于生产环境的企业级工具。其优势不仅体现在功能完整性上，更在于对中文场景的深度适配和灵活的部署策略。

总结几个核心价值点：

• ✅数据安全优先：所有文档处理均在本地完成，无需上传至任何第三方平台。
• ✅双模自由切换：既可用云端高性能 API 快速上线，也可逐步过渡到全本地部署。
• ✅生态兼容性强：支持 FAISS、Milvus、PGVector 等多种向量库，适配 Xinference、OneAPI 等主流模型服务平台。
• ✅开放接口设计：提供标准 API，易于与 OA、CRM、客服系统等现有平台集成。
• ✅活跃社区支持：GitHub 更新频繁，Issue 响应及时，文档持续完善。

无论你是想搭建一个内部技术支持机器人，还是为企业构建专属的 AI 助手，Langchain-Chatchat 都是一个值得信赖的技术底座。

未来，随着更多轻量化模型和高效向量算法的出现，这类本地化 RAG 系统将在更多行业中落地生根。而现在，正是动手实践的最佳时机。