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/langchainchatglm.png展示了知识库离线建库 在线问答的经典双阶段结构左侧是把本地文档离线切分、向量化并存入向量库的过程右侧是用户提问后把问句向量化、检索相似片段、与问题拼接成 Prompt 提交给 LLM 的过程。从文档处理角度进一步展开可以拆解为如下文件处理管线对应 docs/img/langchainchatglm2.png 所示流程文件加载支持 PDF、Word、PPT、CSV、图片OCR、文本等多种格式。仓库中的实际加载器位于 libs/chatchat-server/chatchat/server/file_rag/document_loaders例如 mypdfloader.py、mypptloader.py、ocr.py 等并对非结构化文档解析做了兼容处理。文本分割将长文档切分为语义完整的 Chunk。项目内置多种分割器位于 libs/chatchat-server/chatchat/server/file_rag/text_splitter其中 chinese_recursive_text_splitter.py 是针对中文场景的递归分割器默认配置TEXT_SPLITTER_NAME: ChineseRecursiveTextSplitter见 settings.py。文本向量化Embedding调用 Embedding 模型默认如 bge-large-zh-v1.5 / bge-m3将文本块转为向量并写入向量库。在线检索将用户问句向量化后在向量库中检索最相似的 top k 个文本块。组装 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.2.x0.3.x模型接入本地fastchat在线XXXModelWorker本地model_provider支持大部分主流模型加载框架在线oneapi所有模型接入均兼容 openai sdkAgent不稳定针对 ChatGLM3 和 Qwen 进行优化Agent 能力显著提升LLM 对话支持支持知识库对话支持支持搜索引擎对话支持支持文件对话仅向量检索统一为 File RAG 功能支持 BM25 KNN 等多种检索方式数据库对话不支持支持多模态图片对话不支持支持推荐 qwen-vl-chatARXIV 文献对话不支持支持Wolfram 对话不支持支持文生图不支持支持本地知识库管理支持支持WEBUI支持更好的多会话支持、自定义系统提示词等0.3.x 的核心能力围绕Agent构建但项目同时保留了多档手动工具调用的降级方案以适应不同 Agent 能力的模型具体操作矩阵如下操作方式实现的功能适用场景选中启用 Agent选择多个工具由 LLM 自动进行工具调用使用 ChatGLM3/Qwen 或在线 API 等具备 Agent 能力的模型选中启用 Agent选择单个工具LLM 仅解析工具参数所用模型 Agent 能力一般不能很好选择工具或想手动选择功能不选中启用 Agent选择单个工具不使用 Agent 功能时手动填入参数进行工具调用所用模型不具备 Agent 能力不选中任何工具上传一个图片图片对话使用 qwen-vl-chat 等多模态模型对应源码中Agent 编排能力位于 libs/chatchat-server/langchain_chatchat/agents其中 structured_chat 下提供了针对 ChatGLM3glm3_agent.py与 Qwenqwen_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及后续多模态模型一律通过市面常见的模型推理框架接入。这带来两个重要变化模型加载职责外置模型由 Xinference、Ollama、LocalAI、FastChat 等框架负责启动与加载Chatchat 只负责通过 OpenAI 兼容的 HTTP 接口调用天然支持 GPU / CPU / NPU / MPS 等异构硬件。接入即 OpenAI 兼容所有框架与模型的接入均对齐 OpenAI API 协议因此在线 API经 One API 网关与本地框架可以统一配置、统一调用。项目官方对本地模型部署框架支持情况的汇总如下模型部署框架XinferenceLocalAIOllamaFastChatOpenAI API 接口对齐支持支持支持支持加速推理引擎GPTQ, GGML, vLLM, TensorRT, mlxGPTQ, GGML, vLLM, TensorRTGGUF, GGMLvLLM接入模型类型LLM, Embedding, Rerank, Text-to-Image, Vision, AudioLLM, Embedding, Rerank, Text-to-Image, Vision, AudioLLM, Text-to-Image, VisionLLM, VisionFunction Call支持支持支持不支持更多平台支持CPU, Metal支持支持支持支持异构支持支持不支持不支持集群支持支持不支持不支持此外项目对 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_urlOpenAI 兼容接口地址、api_key、api_proxy代理、api_concurrencies单模型最大并发数默认 5、auto_detect_model是否自动拉取平台可用模型列表。按模型能力维度声明平台可提供的模型llm_models大语言模型、embed_modelsEmbedding、rerank_models重排、text2image_models文生图、image2text_models多模态、speech2text_models语音转写、text2speech_models语音合成。auto_detect_model置为 True 时这些列表可用auto自动检测。仓库默认预置了 xinference默认监听http://127.0.0.1:9997/v1、ollamahttp://127.0.0.1:11434/v1、oneapihttp://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中的可选依赖extralibs/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 中BasicSettingsKB_ROOT_PATH默认指向CHATCHAT_ROOT/data/knowledge_baseDB_ROOT_PATH默认指向其下的info.dbSQLALCHEMY_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.0Windows 下为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}/docsSwagger 文档中查看参数并直接测试。常用接口包括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克隆 master 分支代码使用源码启动请拉取 master 分支。安装 Poetry并建议先用conda create -n chatchat python3.9创建独立环境。进入服务端主目录安装依赖libs/chatchat-servercd 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% 兼容与成功迁移前务必备份重要数据。参考步骤如下按上述安装部署中的步骤完成运行环境配置、修改配置文件将 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.mdCLI 入口libs/chatchat-server/chatchat/cli.pyinit/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.pyRAG 实现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/testsAPI 级测试含 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/langchainchatglm.png展示了知识库离线建库 在线问答的经典双阶段结构左侧是把本地文档离线切分、向量化并存入向量库的过程右侧是用户提问后把问句向量化、检索相似片段、与问题拼接成 Prompt 提交给 LLM 的过程。从文档处理角度进一步展开可以拆解为如下文件处理管线对应 docs/img/langchainchatglm2.png 所示流程文件加载支持 PDF、Word、PPT、CSV、图片OCR、文本等多种格式。仓库中的实际加载器位于 libs/chatchat-server/chatchat/server/file_rag/document_loaders例如 mypdfloader.py、mypptloader.py、ocr.py 等并对非结构化文档解析做了兼容处理。文本分割将长文档切分为语义完整的 Chunk。项目内置多种分割器位于 libs/chatchat-server/chatchat/server/file_rag/text_splitter其中 chinese_recursive_text_splitter.py 是针对中文场景的递归分割器默认配置TEXT_SPLITTER_NAME: ChineseRecursiveTextSplitter见 settings.py。文本向量化Embedding调用 Embedding 模型默认如 bge-large-zh-v1.5 / bge-m3将文本块转为向量并写入向量库。在线检索将用户问句向量化后在向量库中检索最相似的 top k 个文本块。组装 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.2.x0.3.x模型接入本地fastchat在线XXXModelWorker本地model_provider支持大部分主流模型加载框架在线oneapi所有模型接入均兼容 openai sdkAgent不稳定针对 ChatGLM3 和 Qwen 进行优化Agent 能力显著提升LLM 对话支持支持知识库对话支持支持搜索引擎对话支持支持文件对话仅向量检索统一为 File RAG 功能支持 BM25 KNN 等多种检索方式数据库对话不支持支持多模态图片对话不支持支持推荐 qwen-vl-chatARXIV 文献对话不支持支持Wolfram 对话不支持支持文生图不支持支持本地知识库管理支持支持WEBUI支持更好的多会话支持、自定义系统提示词等0.3.x 的核心能力围绕Agent构建但项目同时保留了多档手动工具调用的降级方案以适应不同 Agent 能力的模型具体操作矩阵如下操作方式实现的功能适用场景选中启用 Agent选择多个工具由 LLM 自动进行工具调用使用 ChatGLM3/Qwen 或在线 API 等具备 Agent 能力的模型选中启用 Agent选择单个工具LLM 仅解析工具参数所用模型 Agent 能力一般不能很好选择工具或想手动选择功能不选中启用 Agent选择单个工具不使用 Agent 功能时手动填入参数进行工具调用所用模型不具备 Agent 能力不选中任何工具上传一个图片图片对话使用 qwen-vl-chat 等多模态模型对应源码中Agent 编排能力位于 libs/chatchat-server/langchain_chatchat/agents其中 structured_chat 下提供了针对 ChatGLM3glm3_agent.py与 Qwenqwen_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及后续多模态模型一律通过市面常见的模型推理框架接入。这带来两个重要变化模型加载职责外置模型由 Xinference、Ollama、LocalAI、FastChat 等框架负责启动与加载Chatchat 只负责通过 OpenAI 兼容的 HTTP 接口调用天然支持 GPU / CPU / NPU / MPS 等异构硬件。接入即 OpenAI 兼容所有框架与模型的接入均对齐 OpenAI API 协议因此在线 API经 One API 网关与本地框架可以统一配置、统一调用。项目官方对本地模型部署框架支持情况的汇总如下模型部署框架XinferenceLocalAIOllamaFastChatOpenAI API 接口对齐支持支持支持支持加速推理引擎GPTQ, GGML, vLLM, TensorRT, mlxGPTQ, GGML, vLLM, TensorRTGGUF, GGMLvLLM接入模型类型LLM, Embedding, Rerank, Text-to-Image, Vision, AudioLLM, Embedding, Rerank, Text-to-Image, Vision, AudioLLM, Text-to-Image, VisionLLM, VisionFunction Call支持支持支持不支持更多平台支持CPU, Metal支持支持支持支持异构支持支持不支持不支持集群支持支持不支持不支持此外项目对 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_urlOpenAI 兼容接口地址、api_key、api_proxy代理、api_concurrencies单模型最大并发数默认 5、auto_detect_model是否自动拉取平台可用模型列表。按模型能力维度声明平台可提供的模型llm_models大语言模型、embed_modelsEmbedding、rerank_models重排、text2image_models文生图、image2text_models多模态、speech2text_models语音转写、text2speech_models语音合成。auto_detect_model置为 True 时这些列表可用auto自动检测。仓库默认预置了 xinference默认监听http://127.0.0.1:9997/v1、ollamahttp://127.0.0.1:11434/v1、oneapihttp://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中的可选依赖extralibs/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 中BasicSettingsKB_ROOT_PATH默认指向CHATCHAT_ROOT/data/knowledge_baseDB_ROOT_PATH默认指向其下的info.dbSQLALCHEMY_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.0Windows 下为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}/docsSwagger 文档中查看参数并直接测试。常用接口包括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克隆 master 分支代码使用源码启动请拉取 master 分支。安装 Poetry并建议先用conda create -n chatchat python3.9创建独立环境。进入服务端主目录安装依赖libs/chatchat-servercd 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% 兼容与成功迁移前务必备份重要数据。参考步骤如下按上述安装部署中的步骤完成运行环境配置、修改配置文件将 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.mdCLI 入口libs/chatchat-server/chatchat/cli.pyinit/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.pyRAG 实现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/testsAPI 级测试含 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考