Langchain-Chatchat RAG 问答完整实战-育师

Langchain-Chatchat RAG 问答完整实战

【免费下载链接】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 与 GLM、Qwen、Llama 等开源大模型打造的开源 RAG + Agent 应用，能用你自己的文档搭一套完全离线、数据不出内网的本地知识库问答系统。跟着本文，你可以三步把它装进本机机器，配好知识库与模型，直接对内部文档提问。

从一个痛点切入：50 页文档的第一次提问

设想一个场景：同事把一份 50 页的 PDF 丢给你，问"第三条的付款周期是多少"。翻全文要半天，搜索引擎又答不了内部问题。你想要的是在自己机器上跑一个"看得懂这份文档"的系统，断网也能用。

Langchain-Chatchat（原 Langchain-ChatGLM）解决的就是这件事：文档先进知识库（RAG，即先检索相关片段再让大模型作答），还能以 Agent 模式调用工具。它的前端不是传统 React 工程，而是基于 Streamlit（用 Python 写 WebUI 的框架）的页面，后端是 FastAPI（高性能 Python Web 框架）服务，两条路径都由一个命令行入口驱动。

这个设计的好处是：你不用碰 npm、构建配置和前端状态管理，装一个 Python 包就能开工。

🔧 跑起来：3 步完成 Langchain-Chatchat 本地部署（安装、初始化、启动）

先准备 Python 3.8~3.11 环境，并建一个干净的虚拟环境。项目本体与模型推理框架（如 Xinference，一站式模型部署框架）要放进不同虚拟环境，否则依赖冲突几乎必然发生。

依次执行：

pip install langchain-chatchat -U export CHATCHAT_ROOT=/path/to/chatchat_data chatchat init chatchat kb -r chatchat start -a

每一步的作用：

pip install：装好 CLI 与全部代码；
CHATCHAT_ROOT：指定配置文件和数据目录，不设置就用当前目录；
chatchat init：建数据目录、拷贝内置 samples 知识库、生成默认 yaml 配置；
chatchat kb -r：把知识库文件向量化入库，前提是 embedding 模型已经启动；
chatchat start -a：启动服务，按终端输出的地址用浏览器打开即可。

看到左侧导航加对话区，说明服务起来了。到这里，部署环节才算真正跑通，剩下的是把它调对。

🔍 看懂它：一张图加一个模块，搞懂 RAG 检索链路

知识库问答的完整链路是一条流水线：

加载文件、读取文本、文本分割、文本向量化、问句向量化、匹配出 top-k 最相似片段、把片段连同问题拼进 prompt，最后交给 LLM（大语言模型）生成回答。其中决定答案质量的不是模型，而是检索环节——向量匹配不准，回答就会开始编。

前端对话页只是这条链路的薄壳。看对话模块源码会发现它只做三件事：维护会话框、从配置读取模型与工具列表、把问题发给后端kb_chat链路。真正的重活——向量库选择、BM25 + KNN 混合检索（前者是关键词匹配，后者是向量相似度匹配）——全在服务端完成，页面端不感知。

所以改造时记住一条边界：界面改动只碰 webui_pages，检索质量改动碰检索器与向量库配置，两者别混在一起。

⚙️ 调好它：3 个 yaml 配好模型、知识库与 Agent

0.3.1 起，配置全部落在本地三个 yaml 文件里，改完自动生效、无需重启服务。字段定义可对照 settings 配置类。

模型接入：model_settings.yaml

这个文件决定"用哪个大脑回答"：

# model_settings.yaml DEFAULT_LLM_MODEL: qwen1.5-chat DEFAULT_EMBEDDING_MODEL: bge-large-zh-v1.5

DEFAULT_LLM_MODEL：问答模型，必须与你在推理框架里启动的模型名一致；
DEFAULT_EMBEDDING_MODEL：embedding 模型（把文本转成向量的模型），它决定知识库向量的"方言"，换掉它必须重建知识库；
MODEL_PLATFORMS：推理平台地址与类型，Ollama、One API 在线接口都从这里接。

知识库、网络与超时：另外两个文件

kb_settings.yaml里的DEFAULT_VS_TYPE默认是 FAISS（纯本地向量库），知识库规模上去后改成 milvus 或 pg 是绕不开的一步；
basic_settings.yaml里DEFAULT_BIND_HOST默认 127.0.0.1，想让别的机器访问就改成 0.0.0.0；HTTPX_DEFAULT_TIMEOUT默认 300 秒，大模型响应慢、频繁超时就在这一项上加大。

对话页勾选"启用 Agent"后，LLM 会自动从内置工具集里挑工具调用（arxiv 检索、天气、计算器等）。模型能力强就让它自选；能力一般就手动选单个工具，它只负责解析参数。

调好的标准就一句话：随便问一个内部问题，答案和引用都能对得上。

⚠️ 避坑：离线跑出的 4 个高频错误与性能调优

Windows 下知识库入库卡死：unstructured在新虚拟环境中 import 就挂起，多数是python-magic-bin版本问题，卸载后重装正确版本再重建知识库；
没起 embedding 就执行 kb -r：向量化直接失败，先确认推理框架里 embedding 模型已经加载；
换了 embedding 模型不重建知识库：新旧向量不匹配，检索质量断崖式下跌，必须重跑chatchat kb -r；
只有本机能访问：这是DEFAULT_BIND_HOST配置问题，不是防火墙问题。

性能上再提醒一点：FAISS 向量库随服务加载，几千条分片启动多花几秒属正常现象；分片到百万级再考虑迁 Milvus 或 Postgres。这些坑没有一个是代码缺陷，全是环境与配置的账。