Langchain-Chatchat 0.3.x 部署全指南：基于 chatchat-server 的安装、初始化与启动实操

本篇指南以 chatchat-server（即 PyPI 包 langchain-chatchat 的源码载体，仓库 libs/chatchat-server）的官方 README 为骨架，系统讲解 Langchain-Chatchat 0.3.x 从零起步的完整落地路径：四种安装方式（PyPI / 源码 / Docker / AutoDL）、CHATCHAT_ROOT 数据目录与 YAML 配置体系的初始化原理、知识库重建与前后端服务启动的标准命令。结合对 cli.py、startup.py、init_database.py、settings.py 等源码的逐行分析，读者可同时掌握"命令怎么用"与"命令背后发生了什么"两层能力，顺利在本机或服务器上跑起一套基于本地大模型的 RAG 与 Agent 应用。

项目定位：本地知识库 RAG 与 Agent 应用的组件化落地

Langchain-Chatchat（原 Langchain-ChatGLM）是一个基于 ChatGLM、Qwen、Llama 等开源大语言模型与 Langchain 应用框架实现的、开源且可离线部署的 RAG（检索增强生成）与 Agent 应用项目。其核心形态是：把本地文档切分、向量化后存入知识库，让大模型在回答时先检索相关知识片段再作答，同时通过工具调用机制让模型具备联网搜索、代码执行、数据库查询等 Agent 能力。

0.3.0 起项目改为 monorepo 结构，本指南所对应的 chatchat-server 子库承担全部核心逻辑，仓库根目录的 pyproject.toml 已无实际依赖管理职责。chatchat-server 内部分层清晰，主要模块包括：

• chatchat/cli.py：chatchat 命令入口，聚合 init、kb、start 三个子命令；
• chatchat/startup.py：API Server（FastAPI）与 WEBUI（Streamlit）的多进程编排；
• chatchat/init_database.py：知识库/向量库相关操作命令；
• chatchat/settings.py：全部配置模型（Basic/KB/Model/Tool/Prompt 五类 Settings）及默认值定义；
• chatchat/server/：API 路由、知识库服务、Agent 工具、RAG 检索器等实现；
• langchain_chatchat/：面向 Langchain 生态的集成层（Agents、工具库、Embeddings、MCP 客户端封装等）。

安装前的准备：Python 版本、虚拟环境与"隔离"红线

依据 chatchat-server/pyproject.toml，包的运行环境要求为 python = ">=3.10,<3.12"，因此请确认使用 Python 3.10 或 3.11。

官方 README 特别强调两点：

1. 必须使用独立虚拟环境（conda / venv / virtualenv 均可）安装 chatchat，不要直接装进系统 Python；
2. 不要把 chatchat 与 xinference 安装到同一环境。已知问题表明两者共处一环境会导致部分插件异常，例如文件无法上传。正确做法是 chatchat 走独立环境，xinference 由外部服务（或 Docker）提供模型 API。在 pyproject.toml 中 xinference = ["xinference_client"] 属于 [tool.poetry.extras] 的受支持 extra，若确实需要使用 xinference 客户端可显式安装该 extra（详见下文 PyPI 安装），但须理解这与"共享运行环境"是两回事。

方式一：PyPI 安装（推荐给一般使用者）

在准备好的虚拟环境中执行：

pip install langchain-chatchat

# 若希望由 xinference 提供模型 API，可安装带 extra 的版本：
# pip install langchain-chatchat[xinference]

升级注意事项：若从旧版本升级，建议重新执行一次初始化以更新 YAML 配置模板（0.3.x 各版本的配置项存在差异）：

pip install -U langchain-chatchat
chatchat init

若希望以源码方式安装（便于调试、跟踪 bug 或改进基础设施），可参考仓库内的 docs/contributing/README_dev.md。该文档同时说明：0.3.0 起源码/开发部署不再使用 requirements.txt，而是统一用 Poetry 管理依赖（对应命令为 poetry install --with lint,test -E xinference，或用 pip install -e . 进行可编辑安装）。官方建议不熟悉开发流程的新手直接使用 PyPI 安装。

方式二：源码安装与开发模式

需要从源码启动时，官方指引见 docs/contributing/README_dev.md，核心步骤为：克隆仓库 → 安装 Poetry（建议配合 conda/pyenv，并执行 poetry config virtualenvs.prefer-active-python true）→ 在 libs/chatchat-server/ 下执行 poetry install → 以 chatchat/ 目录为源码根目录进行开发 → 通过 python chatchat/cli.py init|kb|start 完成初始化与启动。开发模式下 poetry install 会在虚拟环境 site-packages 中生成带 direct_url.json 的 chatchat-<version>.dist-info，用于指向本地开发目录。

方式三：Docker 容器化部署

仓库提供了现成的容器镜像与编排文件。按 README 可直接拉取镜像：

docker pull chatimage/chatchat:0.3.1.2-2024-0720

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

[!important] 官方强烈建议使用 docker-compose 部署，具体步骤见 docs/install/README_docker.md：通过 docker-compose 同时拉起 chatchat（API + WEBUI）与 xinference（模型推理）两个容器，并验证 8501（WEBUI）、7861（API）、9997（xinference）三个端口监听正常。

仓库 docker/docker-compose.yaml 印证了这一架构：xinference 服务以 xprobe/xinference:v0.12.3 镜像、xinference-local -H 0.0.0.0 命令启动（支持 NVIDIA GPU 预留与 ModelScope 模型源切换），chatchat 服务使用 chatimage/chatchat:0.3.1.3-93e2c87-20240829（较 README 示例更新的 0.3.1.3 标签）或国内腾讯云镜像；两者均采用 network_mode: "host" 共享宿主机网络，并通过 volume 将 ~/xinference、~/chatchat 等本地路径持久化。Docker 部署过程中若需迁移历史数据，可使用 docker/data.tar.gz（内含初始化后的 samples 知识库及完整目录结构），配合 docker/Dockerfile 理解镜像构建上下文。

方式四：AutoDL 云端镜像

AutoDL 镜像 0.3.1 版本所使用代码已同步更新至项目 v0.3.1 版本，适合在云端 GPU 租用环境中快速体验；该环境通常与 xinference、模型下载脚本结合使用（可参考 tools/autodl_start_script 中的启动脚本族）。

初始化与配置：CHATCHAT_ROOT + YAML 模板的生成机制

安装完成后即可执行初始化。核心在于先用环境变量指定"数据根目录"，再生成全部配置模板：

# set the root path where storing data.
# will use current directory if not set
export CHATCHAT_ROOT=/path/to/chatchat_data

# initialize data and yaml configuration templates
chatchat init

CHATCHAT_ROOT 是整套部署的数据锚点。在 settings.py 中可见其定义逻辑：

CHATCHAT_ROOT = Path(os.environ.get("CHATCHAT_ROOT", ".")).resolve()

未设置时默认取当前工作目录。其下的数据目录由 BasicSettings.make_dirs()（settings.py）统一创建，包括：data（用户数据根）、data/logs（运行日志）、data/media（模型生成内容，含 image/audio/video 子目录）、data/temp（文件对话临时目录，含 openai_files 子目录）以及 data/knowledge_base（知识库根目录）。关键默认路径如下：

路径项	默认值	说明
KB_ROOT_PATH	<CHATCHAT_ROOT>/data/knowledge_base	各知识库的文档内容目录
DB_ROOT_PATH	<CHATCHAT_ROOT>/data/knowledge_base/info.db	SQLite 数据库文件（知识库/文件元数据）
SQLALCHEMY_DATABASE_URI	sqlite:///<CHATCHAT_ROOT>/data/knowledge_base/info.db	若换用其他数据库，直接改此项即可
NLTK_DATA_PATH	<包目录>/data/nltk_data	nltk 分词模型存储路径

chatchat init 到底做了什么

追踪 cli.py 中 init 命令的实现，其内部依次完成：

1. 关闭配置热重载（避免初始化过程触发文件监听），打印数据目录；
2. 调用 Settings.basic_settings.make_dirs() 创建全部数据目录；
3. 将包内置示例知识库 data/knowledge_base/samples（与 chatchat/data/knowledge_base/samples/content 对应的样例文件）复制到 KB_ROOT_PATH/samples；
4. 通过 create_tables() 建表（初始化 info.db 中的知识库/文档/元数据等表，见 server/knowledge_base/migrate.py）；
5. 按传入参数覆盖模型平台配置；
6. 调用 Settings.createl_all_templates() 写出全部 YAML 配置模板。

init 支持以下选项（完整定义见 cli.py）：

chatchat init [OPTIONS]
  -x, --xinference-endpoint TEXT  指定 Xinference API 服务地址，默认为 http://127.0.0.1:9997/v1
  -l, --llm-model TEXT            指定默认 LLM 模型
  -e, --embed-model TEXT          指定默认 Embedding 模型
  -r, --recreate-kb               是否同时重建知识库（必须确保指定 embed model 可用）
  -k, --kb-names TEXT             要重建的知识库名称，多个用逗号分隔，默认 samples

例如初始化时直接把模型平台指向已有 xinference 服务、并顺带完成知识库向量化：

chatchat init -x http://127.0.0.1:9997/v1 -l glm4-chat -e bge-large-zh-v1.5 -r

其中 -r 分支会调用 folder2db(kb_names=..., mode="recreate_vs", ...) 用默认向量库类型与默认 Embedding 模型重建向量库；不带 -r 时则提示稍后执行 chatchat kb -r。

生成哪些配置文件、如何修改

初始化完成后，CHATCHAT_ROOT（或当前目录）下会出现五个 *_settings.yaml。它们与 settings.py 中的五个配置类一一对应：

配置文件	对应配置类	管理内容
basic_settings.yaml	BasicSettings	服务器基本配置：API/WEBUI 地址端口、跨域、httpx 超时、日志开关、数据路径等
kb_settings.yaml	KBSettings	知识库：默认向量库类型、文本切分 chunk 参数、检索 top-k 与阈值、各向量库连接串、文本切分器选择等
model_settings.yaml	ApiModelSettings	模型：默认 LLM/Embedding 名称、Agent 模型、对话温度、MODEL_PLATFORMS 模型平台列表等
tool_settings.yaml	ToolSettings	Agent 工具开关与参数：本地知识库检索、联网搜索、arxiv、天气、text2sql、URL 阅读等
prompt_settings.yaml	PromptSettings	Prompt 模板：意图识别、普通 LLM、RAG、Agent（glm3/qwen/openai 等）模板

模板的生成机制值得注意：每个 Settings 类都继承 BaseFileSettings（pydantic_settings_file.py），通过 SettingsConfigDict(yaml_file=CHATCHAT_ROOT / "xxx_settings.yaml") 绑定文件路径，并由 YamlTemplate 把"字段默认值 + 字段 docstring 注释 + 可选值枚举"序列化成带完整注释的 YAML——这意味着生成的配置文件本身就是一本带注释的参数手册。同时 settings_property 对配置做了带 mtime 感知的缓存（_lazy_load_key），当 yaml 文件被修改后再次读取会自动重载，这也是 init 期间需要临时关闭自动重载的原因。

五大配置块关键参数解读（源码级默认值）

修改 model_settings.yaml 前，先看 ApiModelSettings（settings.py）的核心字段：

• DEFAULT_LLM_MODEL：默认 LLM 名称，源码默认 "glm4-chat"；
• DEFAULT_EMBEDDING_MODEL：默认 Embedding 名称，源码默认 "bge-m3"；
• Agent_MODEL：可选，指定后锁定 Agent 进入 Chain 后使用的模型，留空则沿用默认 LLM；
• HISTORY_LEN = 3：默认历史对话轮数；
• TEMPERATURE = 0.7：LLM 通用对话温度；
• MAX_TOKENS：留空使用模型自身最大长度；
• SUPPORT_AGENT_MODELS：内置支持的 Agent 模型列表（如 chatglm3-6b、glm-4、Qwen-2、gpt-3.5-turbo、gpt-4o 等）；
• LLM_MODEL_CONFIG：分角色模型参数（preprocess_model 意图识别、llm_model 常规对话、action_model 工具调用、postprocess_model 后处理、image_model 文生图），各自可配 temperature/max_tokens/history_len/prompt_name。

MODEL_PLATFORMS 是模型接入的核心列表，每项为一个 PlatformConfig 实例（settings.py），关键字段：

字段	说明
platform_name	平台别名
platform_type	平台类型，可选 xinference / ollama / oneapi / fastchat / openai / custom openai
api_base_url	OpenAI 兼容 API 地址（xinference 默认 http://127.0.0.1:9997/v1）
api_key	平台密钥，本地服务通常填 EMPTY
api_proxy	API 代理地址（0.3.1.2 新增能力）
api_concurrencies	该平台单模型最大并发数（默认 5）
auto_detect_model	是否自动探测平台可用模型，置 True 后各类模型列表可填 "auto"
llm_models / embed_models / text2image_models / image2text_models / rerank_models / speech2text_models / text2speech_models	各类模型清单

源码默认预置了四个平台模板：xinference、ollama（含 qwen:7b、quentinz/bge-large-zh-v1.5）、oneapi（智谱/千问/千帆/星火 API）、openai（gpt-4o、text-embedding-3 系列）。日常接入新模型时只需复制一个平台块、修改 platform_type 与 api_base_url 即可，之后把模型名填入 llm_models 并设为默认。

kb_settings.yaml 对应的 KBSettings（settings.py）值得留意的参数：DEFAULT_KNOWLEDGE_BASE="samples"、DEFAULT_VS_TYPE（可选项 faiss/milvus/zilliz/pg/es/relyt/chromadb，默认 faiss）、CHUNK_SIZE=750/OVERLAP_SIZE=150（切分长度与重叠）、VECTOR_SEARCH_TOP_K=3、SCORE_THRESHOLD=2.0（相似度阈值，取值 0–2，越小越严格，建议 0.5 左右）、TEXT_SPLITTER_NAME="ChineseRecursiveTextSplitter"，以及 kbs_config 中 milvus/zilliz/pg/es 等外部向量库的连接串（默认 FAISS 无需外部服务）。这些参数与 RAG 检索质量直接相关，建议结合样例库实际效果调优后再上线。

启动服务：从知识库初始化到一键前后端拉起

配置确认无误（尤其是 LLM 与 Embedding 模型已可访问）后，依次执行：

chatchat kb -r
chatchat start -a

如无错误，会自动弹出浏览器页面进入 WEBUI。更多命令通过 chatchat --help 查看。

第一步：chatchat kb -r 重建向量库

kb 子命令对应 init_database.py 中的独立命令（通过 cli.py main.add_command(kb_main, "kb") 注册）。它把工作委托给独立 worker 进程执行，完整选项如下：

chatchat kb [OPTIONS]
  -r, --recreate-vs     重建向量库（把文档内容重新切分并向量化，写回向量库）
  --create-tables       若表不存在则创建空表
  --clear-tables        先清空/重建数据库表，再重建向量库
  -u, --update-in-db    仅对数据库中已存在的文件重建向量
  -i, --increment       仅对本地存在但数据库中没有的文件增量建向量
  --prune-db            删除数据库中存在但本地文件已不存在的文档记录
  --prune-folder        删除本地存在但数据库中不存在的冗余文档文件（释放磁盘）
  -n, --kb-name TEXT    指定要操作的知识库名称（可多次指定），默认处理 KB_ROOT_PATH 下所有目录
  -e, --embed-model TEXT  指定 Embedding 模型，默认取 settings 中的默认值
  --import-db TEXT      从指定 sqlite 数据库导入数据

底层在 server/knowledge_base/migrate.py 的 folder2db 中依据 mode（recreate_vs/update_in_db/increment）把 content 目录里的文档切块并用默认 Embedding 向量化入库。典型的运维场景是：更换了默认向量库类型或 Embedding 模型、或往 content 目录手动拷贝了新文档后，执行 chatchat kb -r 让库与磁盘内容对齐。若内容较多，建议限定到单个知识库（如 -n samples）逐个操作。

第二步：chatchat start -a 一键启动

start 命令对应 startup.py 中的 main，支持三个开关：

chatchat start [OPTIONS]
  -a, --all       同时启动 API Server 与 WEBUI（官方推荐路径）
  --api           仅启动 API Server
  -w, --webui     仅启动 WEBUI Server

其执行流程（startup.py）可概括为：

1. 启动前先调用 create_tables() 确保数据库表存在；
2. 打印环境信息（OS、Python、项目版本、langchain 版本、数据目录、分词器、Embedding、运行地址等，见 dump_server_info）；
3. 用 multiprocessing 以 spawn 方式分别拉起两个子进程，并通过 manager.Event() 同步"端口已就绪"状态——只有 API 起来后才启动 WEBUI，保证联动可用：
   • run_api_server：读取 basic_settings.API_SERVER 的 host/port（默认 0.0.0.0:7861），通过 create_app() 构建 FastAPI 应用后交给 uvicorn 运行，日志写入 <DATA>/logs/run_api_server_<timestamp>；
   • run_webui：读取 WEBUI_SERVER（默认 0.0.0.0:8501），以 chatchat/webui.py 为入口，以"light 主题 + 主色 #165dff"等 flag 调用 Streamlit bootstrap 启动；
4. 主进程守护子进程生命周期，收到中断信号后统一清理。

端口方面需要注意 Windows 与 Linux 的差异（DEFAULT_BIND_HOST 在非 Windows 下为 0.0.0.0，Windows 下为 127.0.0.1，见 settings.py）；若在云服务器或反向代理后面部署，需在 basic_settings.yaml 的 API_SERVER 中配置 public_host/public_port（默认 127.0.0.1:7861），以便生成正确的公网 API 地址（如知识库文档下载链接）。

服务起来后，API 文档、Agent/知识库对话等能力入口均挂在 API Server 下（路由实现位于 server/api_server）；如果对 API 形态感兴趣，可参考 docs/contributing/api.md 及 markdown_docs/server/api.md。

官方更新日志解读（0.3.1.3 / 0.3.1.2 / 0.3.1.1）

README 记录了 0.3.1 系列三个补丁版本的重点变更，帮助判断当前环境需要关注哪些能力与已知问题：

0.3.1.3（2024-07-23）：修复 nltk_data 未能在项目初始化时复制的问题；在依赖中加入 python-docx，满足知识库初始化时处理 docx 文件的需求（当前 pyproject.toml 中 python-docx = "1.1.2" 已确认存在）。

0.3.1.2（2024-07-20）——新功能：

• Model Platform 支持配置代理（api_proxy）；
• 提供默认可用的 searx 服务器（国内联网搜索更友好）；
• 更新 docker 镜像；
• 新增 URL 内容阅读器：借助 jina-ai/reader 项目把 URL 内容转换为 LLM 易读文本（对应 server/agent/tools_factory/url_reader.py）；
• 优化 qwen 模型下 tools 输出的 JSON 修复成功率（相关修复库 json_repair 已加入依赖）；
• 支持在 basic_settings.API_SERVER 配置 public_host/public_port，便于云服务器/反代下生成正确的公网 API 地址；
• 新增模型与服务自动化脚本及单元测试。

修复：WEBUI 中 System message 设置无效；移除失效的 vqa_processor/aqa_processor 工具；KeyError: 'template' 错误；chatchat init 时 nltk_data 目录设置错误；chatchat init 出现 xinference-client 连接错误；xinference 自动检测模型改用缓存提升 UI 响应；chatchat.log 重复记录；优化错误信息传递与前端显示；修正 openai.chat.completions.create 参数构造；Milvus retriever NotImplementedError；ChromaDB Collection 作为 retriever 的 bug；langchain 升级后 DocumentWithVsId id 重复问题；重建知识库只处理一个库的问题；openapi 默认把 max_tokens 设为 0 导致的 chat api 报错。

0.3.1.1（2024-07-15）：修复 WEBUI system message 无效；模型平台不支持代理；移除失效工具；prompt settings 导致的 KeyError: 'template'；searx 不支持中文；init 默认去连 xinference 在服务不存在时报错；init 时 shutil.copytree 在 src 与 dst 相同时报错等问题。

项目里程碑与协议

官方 README 的里程碑记录勾勒了项目演进脉络：

• 2023 年 4 月：Langchain-ChatGLM 0.1.0 发布，支持基于 ChatGLM-6B 的本地知识库问答；
• 2023 年 8 月：更名为 Langchain-Chatchat 并发布 0.2.0，改用 fastchat 加载模型，支持更多模型与数据库；
• 2023 年 10 月：0.2.5 推出 Agent 能力，并在 Founder Park & Zhipu AI & Zilliz 黑客马拉松获三等奖；
• 2023 年 12 月：开源项目累计获得超过 20K stars（里程碑当时记录）；
• 2024 年 6 月：0.3.0 发布，带来全新项目架构（即 monorepo + chatchat-server 子库形态）。

本项目代码遵循 Apache-2.0 协议，协议全文见仓库根目录 LICENSE。英文版 README 位于 libs/chatchat-server/README_en.md，仓库总览与更高层的快速上手说明见根目录 README.md。若需通过 Git 拉取源码进行开发部署，参考 docs/contributing/README_dev.md 中的 git clone 与 Poetry 初始化步骤即可。

小结

Langchain-Chatchat 0.3.x 的落地路径可以凝练为四步：隔离环境装包 → 设定 CHATCHAT_ROOT 并 chatchat init 生成带注释的 YAML 配置 → 按需修改 model_settings.yaml（模型平台/默认模型）与 kb_settings.yaml → chatchat kb -r 重建向量库后 chatchat start -a 一键启动。从源码角度看，chatchat 命令的三个子命令把"数据目录创建与模板生成"（init）、"文档切分与向量化"（kb）、"FastAPI API + Streamlit WEBUI 多进程编排"（start）三个生命周期阶段解耦得十分清晰，任何一个环节出问题都可以从 cli.py、startup.py、init_database.py 与 settings.py 中定位根因——这套"命令 + YAML + 源码"三位一体的排查思路，比直接修改代码更能在日常运维与二次开发中发挥作用。