Langchain-Chatchat 服务端部署指南：从安装、初始化配置到知识库构建与服务启动

Langchain-Chatchat（原 Langchain-ChatGLM）是一个基于 ChatGLM、Qwen、Llama 等大语言模型与 Langchain 应用框架的开源、可离线部署的 RAG 与 Agent 应用项目。本文基于仓库中 libs/chatchat-server/README_en.md 的完整内容展开，并结合 chatchat/cli.py、chatchat/settings.py 等源码，系统讲解项目安装、数据目录与 YAML 配置初始化、知识库向量库重建，以及 API Server 与 WebUI 双进程服务的启动方式，读完即可独立完成一次完整的离线 RAG 服务部署。

项目定位与核心能力

Langchain-Chatchat 的核心目标是建立一套对中文场景与开源模型友好、可离线运行的本地知识库问答解决方案。其 RAG 流程为：加载文件 → 读取文本 → 文本分割 → 文本向量化 → 问句向量化 → 在向量库中检索出与问句最相似的 top-k 文本 → 将检索结果与问题共同注入 prompt → 提交给 LLM 生成回答。

项目实现原理如下图所示：

从文档处理的角度看，整体数据流如下：

0.3.x 版本在 LLM 对话、知识库对话、搜索引擎对话之外，还统一了 File RAG（支持 BM25+KNN 混合检索）、数据库对话（Text2SQL）、多模态图片对话、文生图、Agent 工具调用等能力，详细功能对照可参考根目录 README.md 中的「0.3.x 版本功能一览」。模型接入侧，项目通过 Xinference、LocalAI、Ollama、FastChat 等本地模型加载框架接入 GLM-4-Chat、Qwen2-Instruct、Llama3 等开源模型，同时兼容 OpenAI SDK 协议的各类在线 API。

项目安装

1. 通过 PyPI 安装（推荐）

pip install langchain-chatchat

# 如果使用 xinference 提供模型 API：
# pip install langchain-chatchat[xinference]

# 从旧版本升级时，建议重新执行 init 以更新 yaml 配置模板：
# pip install -U langchain-chatchat
# chatchat init

安装 langchain-chatchat 后，会注册一个名为 chatchat 的命令行入口，其指向 chatchat/cli.py 中的 main 命令组（在 pyproject.toml 中声明为 chatchat = 'chatchat.cli:main'）。

需要注意两点（原文档明确标注）：

• 虚拟环境隔离：Chatchat 应放置在独立的虚拟环境中（conda、venv、virtualenv 等），避免与业务项目依赖冲突。
• 已知问题：langchain-chatchat 与 xinference 不能安装在同一个环境中，否则可能导致部分插件出现 bug（如文件上传问题）。因此推荐为模型服务与 Chatchat 分别创建环境。

从 pyproject.toml 可以看到，Python 版本要求为 >=3.10,<3.12,!=3.9.7，核心依赖锁定在 langchain 0.1.17、langchain-community 0.0.36、fastapi ~0.109.2、streamlit 1.34.0、faiss-cpu ~1.7.4、SQLAlchemy ~2.0.25 等版本；可选依赖 xinference、zhipuai 以 extras 形式提供，与上述 pip install langchain-chatchat[xinference] 的用法对应。

2. 源码安装

除 PyPI 外，也可以从源码启动。源码配置方式便于定位 bug 和修改基础设施，但项目方并不建议初学者使用此方式，开发部署细节可参考 开发指南。

3. Docker 部署

docker pull chatimage/chatchat:0.3.1.2-2024-0720

docker pull ccr.ccs.tencentyun.com/chatchat/chatchat:0.3.1.2-2024-0720 # 国内镜像

项目方强烈建议使用 docker compose 进行部署，详细说明见 Docker 部署指南；仓库根目录下的 Dockerfile 可作为自定义镜像构建的参考。

4. AutoDL 镜像

项目提供 AutoDL 镜像（0.3.0 版本），其中使用的代码已更新至本项目 v0.3.0 版本，适合在 GPU 云主机上一键体验。

初始化数据目录与 YAML 配置

项目运行需要独立的数据目录来存放知识库、SQLite 数据库、日志等。通过环境变量 CHATCHAT_ROOT 指定数据根路径（不设置时默认使用当前目录），随后执行 chatchat init 生成全部默认配置：

# 设置数据存储根路径
# 未设置时使用当前目录
export CHATCHAT_ROOT=/path/to/chatchat_data
# 初始化数据目录与 yaml 配置模板
chatchat init

CHATCHAT_ROOT 下会生成什么

在 chatchat/settings.py 中可以看到 CHATCHAT_ROOT = Path(os.environ.get("CHATCHAT_ROOT", ".")).resolve()，即所有数据路径均相对该变量解析。chatchat init 执行的 init 命令 会依次完成：

1. 调用 BasicSettings.make_dirs() 创建全部数据目录（data/、data/logs/、data/media/{image,audio,video}、data/temp/、data/knowledge_base/）；
2. 将内置的示例知识库 samples 目录（含大模型技术文档、Excel/CSV 样例等）复制到 CHATCHAT_ROOT/data/knowledge_base/samples；
3. 调用 create_tables() 初始化知识库 SQLite 数据库；
4. 生成全部 YAML 配置模板文件。

初始化后可在 CHATCHAT_ROOT（或当前目录）下找到 *_settings.yaml 系列文件。从 Settings.createl_all_templates() 的源码结构看，模板共 5 个：

配置文件	对应配置类	主要内容
basic_settings.yaml	BasicSettings	日志开关 log_verbose、HTTPX_DEFAULT_TIMEOUT、知识库路径 KB_ROOT_PATH、数据库 SQLALCHEMY_DATABASE_URI、跨域开关 OPEN_CROSS_DOMAIN、API/WebUI 服务地址端口
kb_settings.yaml	KBSettings	默认知识库 DEFAULT_KNOWLEDGE_BASE（默认 samples）、默认向量库类型 DEFAULT_VS_TYPE（可选 faiss/milvus/zilliz/pg/es/relyt/chromadb，默认 faiss）、文本分割器等
model_settings.yaml	ApiModelSettings	MODEL_PLATFORMS 模型平台列表、默认 LLM DEFAULT_LLM_MODEL（默认 glm4-chat）、默认 Embedding DEFAULT_EMBEDDING_MODEL、LLM_MODEL_CONFIG 分角色温度/历史轮数配置等
tool_settings.yaml	ToolSettings	Agent 工具开关与 API Key 等
prompt_settings.yaml	PromptSettings	各场景系统提示词模板

这些配置类支持热加载（set_auto_reload），但 BasicSettings 的注释 明确说明：除 log_verbose/HTTPX_DEFAULT_TIMEOUT 外，其余配置修改后需重启服务才生效。

chatchat init 的可选参数

chatchat init 还接受若干选项，可在初始化时直接落定模型配置（见 cli.py）：

参数	说明
-x, --xinference-endpoint	指定 Xinference API 服务地址，默认 http://127.0.0.1:9997/v1
-l, --llm-model	指定默认 LLM 模型，默认 glm4-chat
-e, --embed-model	指定默认 Embedding 模型（CLI 帮助默认 bge-large-zh-v1.5；而 settings.py 中 DEFAULT_EMBEDDING_MODEL 的当前默认值为 bge-m3，以实际生成模板为准）
-r, --recreate-kb	初始化同时重建知识库（必须确保指定的 embed model 可用）
-k, --kb-names	要重建的知识库名称，多个名称以英文逗号分隔，默认 samples

初始化完成后，程序会提示「请先检查确认 model_settings.yaml 里模型平台、LLM 模型和 Embed 模型信息已经正确」——这是后续所有 RAG 功能正常工作的前提。

构建知识库并启动服务

chatchat kb -r：重建向量库

确认配置无误后（尤其是 LLM 与 Embedding 模型），先重建知识库向量库：

chatchat kb -r

该命令对应 init_database.py 中注册的 kb 子命令。从源码可以看到它除 -r, --recreate-vs（重建向量库，适用于向 content 目录新增文档后、或 DEFAULT_VS_TYPE/DEFAULT_EMBEDDING_MODEL 变更后重新向量化）外，还提供了一整套知识库运维选项：

参数	作用
-r, --recreate-vs	重建向量库
--create-tables	不存在时创建空表
--clear-tables	重建向量库前清空/删除数据库表
-u, --update-in-db	仅重建数据库中已存在文件的向量（跳过本地新增文件）
-i, --increment	仅对本地新增且不在库中的文件做增量向量化
--prune-db	删除库中在本地目录已不存在的文档记录
--prune-folder	删除本地目录中在库中不存在的文档文件（释放磁盘）
-n, --kb-name	指定要操作的知识库名称，默认为 KB_ROOT_PATH 下全部知识库
-e, --embed-model	指定 Embedding 模型，默认取配置中的 DEFAULT_EMBEDDING_MODEL
--import-db	从指定 sqlite 数据库导入表

实际重建时，会调用 migrate.py 中的 folder2db(kb_names, mode="recreate_vs", vs_type=..., embed_model=...)，按 kb_settings.yaml 中的 DEFAULT_VS_TYPE 将 content 目录下的文档切分并向量化入库。

chatchat start -a：双进程启动

chatchat start -a

start 子命令注册于 startup.py，三个开关为：

• -a, --all：同时启动 API Server 与 WEBUI Server（即 chatchat start -a 的效果）；
• --api：仅启动 API 服务；
• -w, --webui：仅启动 WebUI 服务。

从 start_main_server 的源码结构看，服务启动采用 multiprocessing 的 spawn 方式派生两个独立进程：

• API Server：由 run_api_server 以 uvicorn 运行 FastAPI 应用（create_app），默认监听 basic_settings.yaml 中 API_SERVER 的 0.0.0.0:7861；
• WEBUI Server：由 run_webui 通过 Streamlit bootstrap 机制运行 webui.py，默认端口 8501。

启动时 dump_server_info 会打印操作系统、Python 版本、项目版本（当前仓库源码版本为 0.3.1.3，见 chatchat/init.py）、langchain 版本、数据目录、当前分词器与默认 Embedding 名称，便于快速核对部署状态；日志则写入 basic_settings.yaml 的 LOG_PATH（默认 CHATCHAT_ROOT/data/logs）。

如果配置无误，浏览器页面会自动弹出，此时即可在对话页选择知识库提问，或在知识库页管理文档。

更新日志与项目里程碑

0.3.1.1 (2024-07-15) 修复清单

• 修复 WEBUI 中 system message 设置无效的问题；
• 修复模型平台不支持代理的问题；
• 移除无效的 vqasprocessor 与 aqa_processor 工具；
• 修复 Prompt 配置错误导致的 KeyError: template；
• 修复 Searx 搜索引擎不支持中文的问题；
• 修复初始化时默认连接 xinference、默认服务不存在时报错的问题；
• 修复初始化时 shutil.copytree 在 src 与 dst 相同时报错的问题。

项目里程碑

• 2023 年 4 月：Langchain ChatGLM 0.1.0 发布，支持基于 ChatGLM-6B 模型的本地知识库问答；
• 2023 年 8 月：项目更名并采用 fastchat 作为模型加载方案，支持更多模型与数据库；
• 2023 年 10 月：0.2.5 版本发布，引入 Agent 能力；
• 2023 年 12 月：开源项目累计获得超过 20K stars；
• 2024 年 6 月：0.3.0 版本发布，带来全新的项目架构（即本文所述的 chatchat init / kb / start CLI 体系）。

许可与引用

项目代码遵循 Apache 2.0 协议（见 LICENSE）。如果该项目对你的研究有帮助，建议按以下方式引用：

@software{langchain_chatchat,
title        = {{langchain-chatchat}},
author       = {Liu, Qian and Song, Jinke, and Huang, Zhiguo, and Zhang, Yuxuan, and glide-the, and Liu, Qingwei},
year         = 2024,
journal      = {GitHub repository},
publisher    = {GitHub}
}

小结

部署 Langchain-Chatchat 的完整路径可以归纳为四步：

1. 在独立虚拟环境中 pip install langchain-chatchat（避免与 xinference 混装）；
2. export CHATCHAT_ROOT=... 后执行 chatchat init，生成数据目录与 *_settings.yaml 配置模板，并核对 model_settings.yaml 中的模型平台、LLM 与 Embedding 配置；
3. 执行 chatchat kb -r 将 samples（或自建）知识库向量化入库；
4. 执行 chatchat start -a 同时拉起 7861 端口的 FastAPI 服务与 8501 端口的 Streamlit WebUI。

这套「环境变量定根目录、YAML 定行为、CLI 管生命周期」的设计，使得离线私有化 RAG 部署只需数条命令即可完成；如需深入定制，建议结合 贡献指南、设置说明 与 仓库结构文档 进一步阅读源码。