Langchain-Chatchat 本地知识库 RAG 与 Agent 应用：0.3.x 架构解析与全流程部署实战指南

Langchain-Chatchat 本地知识库 RAG 与 Agent 应用：0.3.x 架构解析与全流程部署实战指南

【免费下载链接】Langchain-ChatchatLangchain-Chatchat（原Langchain-ChatGLM）基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat

本篇技术指南围绕 Langchain-Chatchat（原 Langchain-ChatGLM）展开，系统讲解这个"基于 ChatGLM、Qwen、Llama 等开源大语言模型与 Langchain 框架、可离线部署的 RAG 与 Agent 应用项目"的设计原理、0.3.x 全新架构、模型部署框架接入机制以及从 pip 安装到启动服务的完整落地流程。读者读完本文后，将掌握其实现原理（加载文件 → 文本分割 → 向量化 → 相似检索 → 组装 Prompt → LLM 生成）、YAML 配置体系（model_settings / basic_settings / kb_settings）的核心参数含义，并能独立完成本地私有化知识库问答与 Agent 对话应用的安装、配置、初始化与启动。

项目概述与设计思想

Langchain-Chatchat 是一种利用 Langchain 思想实现的、基于本地知识库的问答应用，其目标定位非常明确：建立一套对中文场景与开源模型支持友好、可离线运行的知识库问答解决方案。项目支持市面上主流开源 LLM、Embedding 模型与向量数据库，可以全部使用开源模型实现离线私有部署，同时保留了对 OpenAI GPT API 的调用能力。

从项目定位看，Langchain-Chatchat 与普通"LLM 包装壳"有本质区别：核心是通过 RAG 让 LLM 能够基于用户私域文档回答问题。其技术路线受开源社区多个项目启发演化而来，当前版本可借助 Xinference、Ollama 等模型推理框架接入 GLM-4-Chat、Qwen2-Instruct、Llama3 等模型，依托 Langchain 框架通过基于 FastAPI 的 API 对外提供服务，或使用基于 Streamlit 的 WebUI 进行交互。

需要明确的是，本项目不涉及微调与训练过程，属于纯推理期的 RAG + Agent 应用框架；若需要效果优化，可借助外部微调或训练手段对模型进行增强后再接入本项目。

RAG 实现原理：从文件加载到 LLM 生成

Langchain-Chatchat 的 RAG 链路是理解整个项目的钥匙。项目 README 对其实现原理给出了清晰的八步流程：

加载文件 → 读取文本 → 文本分割 → 文本向量化 → 问句向量化 → 在文本向量中匹配出与问句向量最相似的 top k 个 → 匹配出的文本作为上下文和问题一起添加到 prompt 中 → 提交给 LLM 生成回答。

该图（见 docs/img/langchain+chatglm.png）展示了"知识库离线建库 + 在线问答"的经典双阶段结构：左侧是把本地文档离线切分、向量化并存入向量库的过程；右侧是用户提问后，把问句向量化、检索相似片段、与问题拼接成 Prompt 提交给 LLM 的过程。

从文档处理角度进一步展开，可以拆解为如下文件处理管线（对应 docs/img/langchain+chatglm2.png 所示流程）：

1. 文件加载：支持 PDF、Word、PPT、CSV、图片（OCR）、文本等多种格式。仓库中的实际加载器位于 libs/chatchat-server/chatchat/server/file_rag/document_loaders，例如 mypdfloader.py、mypptloader.py、ocr.py 等，并对非结构化文档解析做了兼容处理。
2. 文本分割：将长文档切分为语义完整的 Chunk。项目内置多种分割器，位于 libs/chatchat-server/chatchat/server/file_rag/text_splitter，其中 chinese_recursive_text_splitter.py 是针对中文场景的递归分割器，默认配置TEXT_SPLITTER_NAME: ChineseRecursiveTextSplitter（见 settings.py）。
3. 文本向量化（Embedding）：调用 Embedding 模型（默认如 bge-large-zh-v1.5 / bge-m3）将文本块转为向量并写入向量库。
4. 在线检索：将用户问句向量化后，在向量库中检索最相似的 top k 个文本块。
5. 组装 Prompt 并生成：将检索片段作为上下文与问题一起填入 Prompt 模板，交给 LLM 生成最终回答。

从源码角度印证，上述文件处理与向量入库逻辑集中在 libs/chatchat-server/chatchat/server/knowledge_base 目录中：kb_service/下提供了 faiss、chromadb、milvus、es、pg、zilliz 等多种向量库服务的统一实现；RAG 在线对话的 API 层见 libs/chatchat-server/chatchat/server/chat/kb_chat.py 与 libs/chatchat-server/chatchat/server/api_server/kb_routes.py。

0.3.x 核心功能与能力矩阵

0.3.0 版本对项目进行了全新架构重构，功能对比（0.2.x vs 0.3.x）如下：

0.3.x 的核心能力围绕Agent构建，但项目同时保留了多档"手动工具调用"的降级方案，以适应不同 Agent 能力的模型，具体操作矩阵如下：

对应源码中，Agent 编排能力位于 libs/chatchat-server/langchain_chatchat/agents，其中 structured_chat 下提供了针对 ChatGLM3（glm3_agent.py）与 Qwen（qwen_agent.py）的专用 Agent 实现；内置工具注册在 libs/chatchat-server/chatchat/server/agent/tools_factory/tools_registry.py 中。而 WebUI 侧的知识库搜索工具依赖样本知识库 samples（详见 libs/chatchat-server/chatchat/server/agent/tools_factory/search_local_knowledgebase.py）。

模型接入架构：模型推理框架统一管理

从 0.3.0 版本起，Langchain-Chatchat不再根据用户输入的本地模型路径直接加载模型，无论是 LLM、Embedding 还是 Reranker（及后续多模态模型），一律通过市面常见的模型推理框架接入。这带来两个重要变化：

1. 模型加载职责外置：模型由 Xinference、Ollama、LocalAI、FastChat 等框架负责启动与加载，Chatchat 只负责通过 OpenAI 兼容的 HTTP 接口调用，天然支持 GPU / CPU / NPU / MPS 等异构硬件。
2. 接入即 OpenAI 兼容：所有框架与模型的接入均对齐 OpenAI API 协议，因此在线 API（经 One API 网关）与本地框架可以统一配置、统一调用。

项目官方对本地模型部署框架支持情况的汇总如下：

此外，项目对 One API 网关的接入提供支持，可统一代理 OpenAI ChatGPT、Azure OpenAI API、Anthropic Claude、智谱清言、百川等常用在线 API。

从源码看，这一设计落实为 settings.py 中的PlatformConfig与ApiModelSettings.MODEL_PLATFORMS：

• 每个平台（platform）对应一份PlatformConfig，关键字段包括：platform_name（平台名称）、platform_type（可选 xinference / ollama / oneapi / fastchat / openai / custom openai）、api_base_url（OpenAI 兼容接口地址）、api_key、api_proxy（代理）、api_concurrencies（单模型最大并发数，默认 5）、auto_detect_model（是否自动拉取平台可用模型列表）。
• 按模型能力维度声明平台可提供的模型：llm_models（大语言模型）、embed_models（Embedding）、rerank_models（重排）、text2image_models（文生图）、image2text_models（多模态）、speech2text_models（语音转写）、text2speech_models（语音合成）。auto_detect_model置为 True 时这些列表可用"auto"自动检测。
• 仓库默认预置了 xinference（默认监听http://127.0.0.1:9997/v1）、ollama（http://127.0.0.1:11434/v1）、oneapi（http://127.0.0.1:3000/v1）、openai（官方 api）等若干平台配置，并在ApiModelSettings中给出DEFAULT_LLM_MODEL（当前仓库源码默认glm4-chat）与DEFAULT_EMBEDDING_MODEL（源码默认bge-m3）作为默认选用模型。

补充：若使用 Xinference 且希望它加载本机已下载的模型（而非自动联网下载内置模型），可以在启动 Xinference 服务后，进入项目 tools/model_loaders 目录执行streamlit run xinference_manager.py，按页面提示为指定模型设置本地路径。

pip 安装部署全流程

0. 软硬件要求

• 软件：支持 Python 3.8–3.11，已在 Windows、macOS、Linux 上测试。
• 硬件：0.3.0 起因改为"框架接入"模型，因此可在 CPU、GPU、NPU、MPS 等不同硬件条件下使用。

1. 安装 Langchain-Chatchat

从 0.3.0 版本起，项目以 Python 库形式发布，直接执行：

pip install langchain-chatchat -U

为确保安装到最新版库，建议使用官方 PyPI 源或清华镜像源。如需搭配 Xinference 使用，由于框架接入需要额外的 Python 依赖，推荐使用带扩展的安装方式：

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

源码级佐证：当前仓库正是通过 Poetry 管理libs/chatchat-server/pyproject.toml中的可选依赖（extra），libs/chatchat-server/README.md 对库结构与-E xinference等安装方式有更细说明。

2. 启动模型推理框架并加载模型

这是 0.3.x 部署中容易忽视却至关重要的一步：必须在启动 Langchain-Chatchat 之前，先运行所选模型推理框架并加载好要用的模型。以 Xinference 为例，请参照其官方文档完成框架部署与模型加载（LLM、Embedding 均需就绪）。

重要提示：为避免依赖冲突，请把 Langchain-Chatchat 与模型部署框架（如 Xinference）放在不同的 Python 虚拟环境中（conda、venv、virtualenv 均可）。

3. 初始化项目配置与数据目录

从 0.3.1 版本起，项目改用本地YAML 文件管理全部配置，用户可直接查看、修改，服务器会自动更新配置、无需重启（这是由 settings.py 中基于 pydantic 的配置加载与缓存刷新机制实现的）。

第一步：设置 Chatchat 根目录（可选）

# on linux or macos export CHATCHAT_ROOT=/path/to/chatchat_data # on windows set CHATCHAT_ROOT=/path/to/chatchat_data

若未设置该环境变量，将自动使用当前目录作为根目录。

第二步：执行初始化命令

chatchat init

该命令实际完成三件事（对应 cli.py 中init命令的Settings.basic_settings.make_dirs()、复制 samples、create_tables()、生成配置文件模板等逻辑）：

• 创建所有需要的数据目录；
• 复制 samples 知识库内容；
• 生成默认 YAML 配置文件。

chatchat init还支持几个实用参数：-x/--xinference-endpoint指定 Xinference API 地址（默认http://127.0.0.1:9997/v1）、-l/--llm-model指定默认 LLM（默认glm4-chat）、-e/--embed-model指定默认 Embedding（默认bge-large-zh-v1.5）、-r/--recreate-kb是否在初始化时同步重建知识库（需确保 Embedding 模型可用）、-k/--kb-names指定重建的知识库名称（多个以逗号分隔，默认samples）。

第三步：修改配置文件，主要包括三类：

• 配置模型（model_settings.yaml）：根据第 2 步实际使用的推理框架与模型填写。需要修改的核心内容包括：

# 默认选用的 LLM 名称 DEFAULT_LLM_MODEL: qwen1.5-chat # 默认选用的 Embedding 名称 DEFAULT_EMBEDDING_MODEL: bge-large-zh-v1.5

此外，还需要把LLM_MODEL_CONFIG中llm_model、action_model等子配置的模型键改成对应的 LLM 模型，并在MODEL_PLATFORMS中修改对应模型平台的地址与模型列表（平台字段含义见上文"模型接入架构"一节）。

• 配置数据路径（basic_settings.yaml）（可选）：默认知识库位于CHATCHAT_ROOT/data/knowledge_base。若希望把知识库存放到其他位置，或连接已有的知识库，可修改：

# 知识库默认存储路径 KB_ROOT_PATH: D:\chatchat-test\data\knowledge_base # 数据库默认存储路径。如果使用sqlite，可以直接修改DB_ROOT_PATH；如果使用其它数据库，请直接修改SQLALCHEMY_DATABASE_URI。 DB_ROOT_PATH: D:\chatchat-test\data\knowledge_base\info.db # 知识库信息数据库连接URI SQLALCHEMY_DATABASE_URI: sqlite:///D:\chatchat-test\data\knowledge_base\info.db

对应源码见 settings.py 中BasicSettings：KB_ROOT_PATH默认指向CHATCHAT_ROOT/data/knowledge_base，DB_ROOT_PATH默认指向其下的info.db，SQLALCHEMY_DATABASE_URI默认采用 sqlite URI。

• 配置知识库（kb_settings.yaml）（可选）：默认使用 FAISS 向量库。若想改用其它类型的向量库（Chroma、Milvus、ES、PG 等），可修改DEFAULT_VS_TYPE与kbs_config（例如在kbs_config中为 milvus 配置search_params/index_params的 metric_type 等参数，为 ES 配置 host、port、user、password、verify_certs 等连接信息）。

4. 初始化知识库

警告：初始化知识库前，务必确认已完成两件事——① 模型推理框架已启动且对应Embedding 模型已加载；② 已按第 3 步完成模型接入配置。

chatchat kb -r

更多子命令可执行chatchat kb --help查看（例如重建特定知识库、指定 Embedding 模型等）。出现以下日志即为成功：

---------------------------------------------------------------------------------------------------- 知识库名称 ：samples 知识库类型 ：faiss 向量模型： ：bge-large-zh-v1.5 知识库路径 ：/root/anaconda3/envs/chatchat/lib/python3.11/site-packages/chatchat/data/knowledge_base/samples 文件总数量 ：47 入库文件数 ：42 知识条目数 ：740 用时 ：0:02:29.701002 ---------------------------------------------------------------------------------------------------- 总计用时 ：0:02:33.414425

日志中的"知识条目数"即向量入库的文本块数量，表明样本知识库已完成切分、向量化与入库。

5. 启动项目

chatchat start -a

-a表示同时启动 API Server 与 WebUI 两个进程。启动成功后会看到 WebUI 界面：

WebUI（见 libs/chatchat-server/chatchat/webui_pages）基于 Streamlit 实现，支持 LLM 对话、知识库对话、Agent 对话、文件对话、数据库对话、多模态对话、WebUI 内嵌的 Agent 工具选择与知识库管理等页面。

注意：默认监听地址DEFAULT_BIND_HOST若为 127.0.0.1，则无法通过其他机器 IP 访问。如需通过本机 IP 远程访问（如 Linux 服务器），需到basic_settings.yaml中将监听地址改为 0.0.0.0。（当前仓库源码 settings.py 在非 Windows 平台默认值即为0.0.0.0，Windows 下为127.0.0.1，请以你本地生成的实际配置文件为准。）

关于 YAML 配置体系（Settings）

部署中的全部配置由chatchat.settings.Settings统一管理，替代旧版chatchat/configs/*.py。该设计（详见 docs/contributing/settings.md）带来的工程收益包括：

• 配置项与 Python 代码分离，升级代码不再覆盖用户配置，改配置更方便；
• 切换不同 YAML 文件即可切换不同配置，方便多环境管理与测试；
• 配置项通过 pydantic 模型定义，加强数据验证、简化环境变量读取，并支持 yaml / json / toml 多种文件后端；
• 可自动生成 YAML 模板并附带配置说明；
• 配置读取带缓存，当.yaml/.env文件被修改时可自动刷新缓存（通过Settings.xx_settings.XX方式访问会跟踪文件变更自动刷新；若先把Settings.xx_settings赋给变量再用s.XX方式访问则不会自动刷新）。

分组访问示例：

from chatchat.settings import Settings print(Settings.basic_settings) # 基本配置：数据目录、服务器配置等 print(Settings.kb_settings) # 知识库相关配置 print(Settings.model_settings) # 模型相关配置 print(Settings.tool_settings) # 工具相关配置 print(Settings.prompt_settings) # prompt 模板

chatchat init生成配置模板的具体实现是Settings.createl_all_templates()；若自行在源码中新增了配置字段，可执行CHATCHAT_ROOT=/path/to/data chatchat init --gen-config重新生成含新字段的配置模板。

与 API 服务的衔接

启动后，所有 HTTP 接口都可以在{api_address}/docs（Swagger 文档）中查看参数并直接测试。常用接口包括：

• GET /tools：列出所有工具及其参数、配置信息（如知识库检索工具search_local_knowledgebase的 database 可选列表、top_k、score_threshold 等）。
• POST /chat/chat/completions：通用对话接口，兼容 OpenAI SDK 格式，支持纯 LLM 对话、Agent 对话（传tools）、半 Agent 对话（传tool_choice）三种模式。
• POST /knowledge_base/chat/completions：面向 RAG 的专用接口，支持local_kb（本地知识库）、temp_kb（临时文件知识库）、search_engine（搜索引擎）三种检索模式，以及top_k、score_threshold、return_direct（仅返回检索结果不经 LLM）等增强参数。

更完整的调用示例（含 SSE 流式输出、Agent 步骤status字段语义等）请参阅 docs/contributing/api.md。

常见问题：Windows 下重建知识库卡住

Windows 下重建知识库或添加知识文件时卡住不动，常出现于新建的虚拟环境。可先执行下面语句确认问题根因：

from unstructured.partition.auto import partition

若该语句执行卡住，说明python-magic-bin版本不兼容，可执行以下命令卸载后重装匹配的版本：

pip uninstall python-magic-bin # 查看被卸载的版本号 pip install 'python-magic-bin=={version}'

然后重新执行知识库初始化即可。

源码安装部署（开发部署）

从 0.3.0 版本起，源码部署不再使用 requirements.txt，而是改用Poetry管理依赖，以规避依赖包版本冲突并支持 pip 方式的库打包发布。简要步骤如下（完整说明见 docs/contributing/README_dev.md）：

1. 克隆 master 分支代码（使用源码启动请拉取 master 分支）。
2. 安装 Poetry，并建议先用conda create -n chatchat python=3.9创建独立环境。
3. 进入服务端主目录安装依赖（libs/chatchat-server）：

cd libs/chatchat-server/ poetry install --with lint,test -E xinference # 或者以可编辑模式用 pip 安装 pip install -e .

开发环境下若需把当前代码打包成 Python 库进行测试，可在该目录执行poetry build，构建产物生成于dist/目录。 4.设置数据根目录并初始化：

export CHATCHAT_ROOT=/path/to/chatchat_data python chatchat/cli.py init

（也可在仓库根目录直接调用libs/chatchat-server/chatchat/cli.py下的同一套命令。） 5.初始化知识库：python chatchat/cli.py kb --recreate-vs。注意该命令会清空数据库、删除已有配置文件，执行前请备份重要数据。如需使用其它 Embedding 模型或只重建特定知识库，用python chatchat/cli.py kb --help查看参数。 6.启动服务：python chatchat/cli.py start -a。

依赖变动时，更新主目录pyproject.toml后执行poetry update；需要 API 对接时参阅 docs/contributing/api.md。

Docker 部署

如需以容器方式快速体验，可拉取已构建镜像：

docker pull chatimage/chatchat:0.3.1.3-93e2c87-20240829 docker pull ccr.ccs.tencentyun.com/langchain-chatchat/chatchat:0.3.1.3-93e2c87-20240829 # 国内镜像

强烈建议使用 docker-compose 进行部署，具体步骤参考 docs/install/README_docker.md。仓库根目录同时提供了 Dockerfile（见 docker/Dockerfile）可供镜像构建参考。

旧版本（0.2.x）迁移说明

0.3.x 相比 0.2.x 结构改变很大，官方强烈建议按照文档全新部署，迁移指南不保证 100% 兼容与成功，迁移前务必备份重要数据。参考步骤如下：

1. 按上述"安装部署"中的步骤完成运行环境配置、修改配置文件；
2. 将 0.2.x 项目的knowledge_base目录拷贝到新版本配置的DATA目录下。

版本里程碑

了解项目演进有助于判断各版本能力边界（此处仅陈述仓库记录的公开信息，不包含任何未经验证的性能或规模断言）：

• 2023年4月：发布Langchain-ChatGLM 0.1.0，支持基于 ChatGLM-6B 的本地知识库问答。
• 2023年8月：Langchain-ChatGLM更名为Langchain-Chatchat，发布0.2.0，使用 fastchat 作为模型加载方案，支持更多模型与数据库。
• 2023年10月：发布0.2.5，推出 Agent 内容。
• 2023年12月：开源项目获得超过 20K stars。
• 2024年6月：发布0.3.0，带来全新项目架构。

源码阅读地图

若希望深入本项目做二次开发或贡献，建议按以下路径阅读仓库关键源码（主代码位于 libs/chatchat-server/chatchat）：

• 配置体系：libs/chatchat-server/chatchat/settings.py（含各 XXSettings 类的完整字段注释与默认值）、docs/contributing/settings.md
• CLI 入口：libs/chatchat-server/chatchat/cli.py（init/kb/start三个子命令）、libs/chatchat-server/chatchat/init_database.py
• 服务启动：libs/chatchat-server/chatchat/startup.py、API 组装见 libs/chatchat-server/chatchat/server/api_server/server_app.py
• RAG 实现：libs/chatchat-server/chatchat/server/knowledge_base（向量库服务、文档入库）、libs/chatchat-server/chatchat/server/file_rag（文档加载与分割）
• Agent 与工具：libs/chatchat-server/langchain_chatchat/agents、libs/chatchat-server/chatchat/server/agent/tools_factory/tools_registry.py
• 测试用例（可用作行为参考）：libs/chatchat-server/tests（API 级测试含 test_stream_chat_api.py、test_tools.py 等，向量库级测试见 kb_vector_db）
• 开发协作相关：docs/contributing/README.md、docs/contributing/repo_structure.md

协议

本项目代码遵循 Apache-2.0 协议，协议全文见 LICENSE。

【免费下载链接】Langchain-ChatchatLangchain-Chatchat（原Langchain-ChatGLM）基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat