Langchain-Chatchat/README.md

🌍 READ THIS IN ENGLISH

📃 LangChain-Chatchat (原 Langchain-ChatGLM): 基于 Langchain 与 ChatGLM 等大语言模型的本地知识库问答应用实现。

目录

• 介绍
• 变更日志
• 模型支持
• Docker 部署
• 开发部署
  • 软件需求
  • 1. 开发环境准备
  • 2. 下载模型至本地
  • 3. 设置配置项
  • 4. 知识库初始化与迁移
  • 5. 一键启动 API 服务或 Web UI
• 常见问题
• 路线图
• 项目交流群

---

介绍

🤖️ 一种利用 langchain 思想实现的基于本地知识库的问答应用，目标期望建立一套对中文场景与开源模型支持友好、可离线运行的知识库问答解决方案。

💡 受 GanymedeNil 的项目 document.ai 和 AlexZhangji 创建的 ChatGLM-6B Pull Request 启发，建立了全流程可使用开源模型实现的本地知识库问答应用。本项目的最新版本中通过使用 FastChat 接入 Vicuna, Alpaca, LLaMA, Koala, RWKV 等模型，依托于 langchain 框架支持通过基于 FastAPI 提供的 API 调用服务，或使用基于 Streamlit 的 WebUI 进行操作。

✅ 依托于本项目支持的开源 LLM 与 Embedding 模型，本项目可实现全部使用开源模型离线私有部署。与此同时，本项目也支持 OpenAI GPT API 的调用，并将在后续持续扩充对各类模型及模型 API 的接入。

⛓️ 本项目实现原理如下图所示，过程包括加载文件 -> 读取文本 -> 文本分割 -> 文本向量化 -> 问句向量化 -> 在文本向量中匹配出与问句向量最相似的 top k个 -> 匹配出的文本作为上下文和问题一起添加到 prompt中 -> 提交给 LLM生成回答。

📺 原理介绍视频

从文档处理角度来看，实现流程如下：

🚩 本项目未涉及微调、训练过程，但可利用微调或训练对本项目效果进行优化。

🌐 AutoDL 镜像 中 v8 版本所使用代码已更新至本项目 v0.2.4 版本。

🐳 Docker 镜像

💻 一行命令运行 Docker 🌲：

docker run -d --gpus all -p 80:8501 registry.cn-beijing.aliyuncs.com/chatchat/chatchat:0.2.3

---

环境最低要求

想顺利运行本代码，请按照以下的最低要求进行配置：

• Python版本: >= 3.8.5, < 3.11
• Cuda版本: >= 11.7, 且能顺利安装Python

如果想要顺利在GPU运行本地模型(int4版本)，你至少需要以下的硬件配置:

• chatglm2-6b & LLaMA-7B 最低显存要求: 7GB 推荐显卡: RTX 3060, RTX 2060
• LLaMA-13B 最低显存要求: 11GB 推荐显卡: RTX 2060 12GB, RTX3060 12GB, RTX3080, RTXA2000
• Qwen-14B-Chat 最低显存要求: 13GB 推荐显卡: RTX 3090
• LLaMA-30B 最低显存要求: 22GB 推荐显卡：RTX A5000,RTX 3090,RTX 4090,RTX 6000,Tesla V100,RTX Tesla P40
• LLaMA-65B 最低显存要求: 40GB 推荐显卡：A100,A40,A6000

如果是int8 则显存x1.5 fp16 x2.5的要求 如：使用fp16 推理Qwen-7B-Chat 模型 则需要使用16GB显存。

以上仅为估算，实际情况以nvidia-smi占用为准。

变更日志

参见 版本更新日志。

从 0.1.x 升级过来的用户请注意，需要按照开发部署过程操作，将现有知识库迁移到新格式，具体见知识库初始化与迁移。

0.2.0 版本与 0.1.x 版本区别

1. 使用 FastChat 提供开源 LLM 模型的 API，以 OpenAI API 接口形式接入，提升 LLM 模型加载效果；
2. 使用 langchain 中已有 Chain 的实现，便于后续接入不同类型 Chain，并将对 Agent 接入开展测试；
3. 使用 FastAPI 提供 API 服务，全部接口可在 FastAPI 自动生成的 docs 中开展测试，且所有对话接口支持通过参数设置流式或非流式输出；
4. 使用 Streamlit 提供 WebUI 服务，可选是否基于 API 服务启动 WebUI，增加会话管理，可以自定义会话主题并切换，且后续可支持不同形式输出内容的显示；
5. 项目中默认 LLM 模型改为 THUDM/chatglm2-6b，默认 Embedding 模型改为 moka-ai/m3e-base，文件加载方式与文段划分方式也有调整，后续将重新实现上下文扩充，并增加可选设置；
6. 项目中扩充了对不同类型向量库的支持，除支持 FAISS 向量库外，还提供 Milvus, PGVector 向量库的接入；
7. 项目中搜索引擎对话，除 Bing 搜索外，增加 DuckDuckGo 搜索选项，DuckDuckGo 搜索无需配置 API Key，在可访问国外服务环境下可直接使用。

---

模型支持

本项目中默认使用的 LLM 模型为 THUDM/chatglm2-6b，默认使用的 Embedding 模型为 moka-ai/m3e-base 为例。

LLM 模型支持

本项目最新版本中支持接入本地模型与在线 LLM API。

本地 LLM 模型接入基于 FastChat 实现，支持模型如下：

• meta-llama/Llama-2-7b-chat-hf
• Vicuna, Alpaca, LLaMA, Koala
• BlinkDL/RWKV-4-Raven
• camel-ai/CAMEL-13B-Combined-Data
• databricks/dolly-v2-12b
• FreedomIntelligence/phoenix-inst-chat-7b
• h2oai/h2ogpt-gm-oasst1-en-2048-open-llama-7b
• lcw99/polyglot-ko-12.8b-chang-instruct-chat
• lmsys/fastchat-t5-3b-v1.0
• mosaicml/mpt-7b-chat
• Neutralzz/BiLLa-7B-SFT
• nomic-ai/gpt4all-13b-snoozy
• NousResearch/Nous-Hermes-13b
• openaccess-ai-collective/manticore-13b-chat-pyg
• OpenAssistant/oasst-sft-4-pythia-12b-epoch-3.5
• project-baize/baize-v2-7b
• Salesforce/codet5p-6b
• StabilityAI/stablelm-tuned-alpha-7b
• THUDM/chatglm-6b
• THUDM/chatglm2-6b
• tiiuae/falcon-40b
• timdettmers/guanaco-33b-merged
• togethercomputer/RedPajama-INCITE-7B-Chat
• WizardLM/WizardLM-13B-V1.0
• WizardLM/WizardCoder-15B-V1.0
• baichuan-inc/baichuan-7B
• internlm/internlm-chat-7b
• Qwen/Qwen-7B-Chat/Qwen-14B-Chat
• HuggingFaceH4/starchat-beta
• FlagAlpha/Llama2-Chinese-13b-Chat and others
• BAAI/AquilaChat-7B
• all models of OpenOrca
• Spicyboros + airoboros 2.2
• VMware's OpenLLaMa OpenInstruct
• baichuan2-7b/baichuan2-13b
• 任何 EleutherAI 的 pythia 模型，如 pythia-6.9b
• 在以上模型基础上训练的任何 Peft 适配器。为了激活，模型路径中必须有 peft 。注意：如果加载多个peft模型，你可以通过在任何模型工作器中设置环境变量 PEFT_SHARE_BASE_WEIGHTS=true 来使它们共享基础模型的权重。

以上模型支持列表可能随 FastChat 更新而持续更新，可参考 FastChat 已支持模型列表。

除本地模型外，本项目也支持直接接入 OpenAI API、智谱AI等在线模型，具体设置可参考 configs/model_configs.py.example 中的 llm_model_dict 的配置信息。

在线 LLM 模型目前已支持：

• ChatGPT
• 智谱AI
• MiniMax
• 讯飞星火
• 百度千帆
• 阿里云通义千问

项目中默认使用的 LLM 类型为 THUDM/chatglm2-6b，如需使用其他 LLM 类型，请在 [configs/model_config.py] 中对 llm_model_dict 和 LLM_MODEL 进行修改。

Embedding 模型支持

本项目支持调用 HuggingFace 中的 Embedding 模型，已支持的 Embedding 模型如下：

• moka-ai/m3e-small
• moka-ai/m3e-base
• moka-ai/m3e-large
• BAAI/bge-small-zh
• BAAI/bge-base-zh
• BAAI/bge-large-zh
• BAAI/bge-large-zh-noinstruct
• sensenova/piccolo-base-zh
• sensenova/piccolo-large-zh
• shibing624/text2vec-base-chinese-sentence
• shibing624/text2vec-base-chinese-paraphrase
• shibing624/text2vec-base-multilingual
• shibing624/text2vec-base-chinese
• shibing624/text2vec-bge-large-chinese
• GanymedeNil/text2vec-large-chinese
• nghuyong/ernie-3.0-nano-zh
• nghuyong/ernie-3.0-base-zh
• sensenova/piccolo-base-zh
• sensenova/piccolo-base-zh
• OpenAI/text-embedding-ada-002

项目中默认使用的 Embedding 类型为 sensenova/piccolo-base-zh，如需使用其他 Embedding 类型，请在 [configs/model_config.py] 中对 embedding_model_dict 和 EMBEDDING_MODEL 进行修改。

---

Text Splitter 个性化支持

本项目支持调用 Langchain 的 Text Splitter 分词器以及基于此改进的自定义分词器，已支持的 Text Splitter 类型如下：

• CharacterTextSplitter
• LatexTextSplitter
• MarkdownHeaderTextSplitter
• MarkdownTextSplitter
• NLTKTextSplitter
• PythonCodeTextSplitter
• RecursiveCharacterTextSplitter
• SentenceTransformersTokenTextSplitter
• SpacyTextSplitter

已经支持的定制分词器如下：

• AliTextSplitter
• ChineseRecursiveTextSplitter
• ChineseTextSplitter

项目中默认使用的 Text Splitter 类型为 ChineseRecursiveTextSplitter，如需使用其他 Text Splitter 类型，请在 [configs/model_config.py] 中对 text_splitter_dict 和 TEXT_SPLITTER 进行修改。

关于如何使用自定义分词器和贡献自己的分词器，可以参考Text Splitter 贡献说明。

Agent生态

基础的Agent

在本版本中，我们实现了一个简单的基于OpenAI的React的Agent模型，目前，经过我们测试，仅有以下两个模型支持：

• OpenAI GPT4
• ChatGLM2-130B

目前版本的Agent仍然需要对提示词进行大量调试，调试位置

构建自己的Agent工具

详见 自定义Agent说明

Docker 部署

🐳 Docker 镜像地址: registry.cn-beijing.aliyuncs.com/chatchat/chatchat:0.2.5)

docker run -d --gpus all -p 80:8501 registry.cn-beijing.aliyuncs.com/chatchat/chatchat:0.2.5

• 该版本镜像大小 35.3GB，使用 v0.2.5，以 nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04 为基础镜像
• 该版本内置两个 embedding 模型：m3e-large，text2vec-bge-large-chinese，默认启用后者，内置 chatglm2-6b-32k
• 该版本目标为方便一键部署使用，请确保您已经在Linux发行版上安装了NVIDIA驱动程序
• 请注意，您不需要在主机系统上安装CUDA工具包，但需要安装 NVIDIA Driver 以及 NVIDIA Container Toolkit，请参考安装指南
• 首次拉取和启动均需要一定时间，首次启动时请参照下图使用 docker logs -f <container id> 查看日志
• 如遇到启动过程卡在 Waiting.. 步骤，建议使用 docker exec -it <container id> bash 进入 /logs/ 目录查看对应阶段日志

---

开发部署

软件需求

本项目已在 Python 3.8.1 - 3.10，CUDA 11.7 环境下完成测试。已在 Windows、ARM 架构的 macOS、Linux 系统中完成测试。

1. 开发环境准备

参见 开发环境准备。

请注意： 0.2.3 及更新版本的依赖包与 0.1.x 版本依赖包可能发生冲突，强烈建议新建环境后重新安装依赖包。

2. 下载模型至本地

如需在本地或离线环境下运行本项目，需要首先将项目所需的模型下载至本地，通常开源 LLM 与 Embedding 模型可以从 HuggingFace 下载。

以本项目中默认使用的 LLM 模型 THUDM/chatglm2-6b 与 Embedding 模型 moka-ai/m3e-base 为例：

下载模型需要先安装Git LFS，然后运行

$ git clone https://huggingface.co/THUDM/chatglm2-6b

$ git clone https://huggingface.co/moka-ai/m3e-base

3. 设置配置项

复制模型相关参数配置模板文件 configs/model_config.py.example 存储至项目路径下 ./configs 路径下，并重命名为 model_config.py。

复制服务相关参数配置模板文件 configs/server_config.py.example 存储至项目路径下 ./configs 路径下，并重命名为 server_config.py。

在开始执行 Web UI 或命令行交互前，请先检查 configs/model_config.py 和 configs/server_config.py 中的各项模型参数设计是否符合需求：

• 请确认已下载至本地的 LLM 模型本地存储路径写在 llm_model_dict 对应模型的 local_model_path 属性中，如:

llm_model_dict={
                "chatglm2-6b": {
                        "local_model_path": "/Users/xxx/Downloads/chatglm2-6b",
                        "api_base_url": "http://localhost:8888/v1",  # "name"修改为 FastChat 服务中的"api_base_url"
                        "api_key": "EMPTY"
                    },
                }

• 请确认已下载至本地的 Embedding 模型本地存储路径写在 embedding_model_dict 对应模型位置，如：

embedding_model_dict = {
                        "m3e-base": "/Users/xxx/Downloads/m3e-base",
                       }

• 请确认本地分词器路径是否已经填写，如：

text_splitter_dict = {
    "ChineseRecursiveTextSplitter": {
        "source": "huggingface",  ## 选择tiktoken则使用openai的方法,不填写则默认为字符长度切割方法。
        "tokenizer_name_or_path": "", ## 空格不填则默认使用大模型的分词器。 
    }
}

如果你选择使用OpenAI的Embedding模型，请将模型的 key写入 embedding_model_dict中。使用该模型，你需要能够访问OpenAI官的API，或设置代理。

4. 知识库初始化与迁移

当前项目的知识库信息存储在数据库中，在正式运行项目之前请先初始化数据库（我们强烈建议您在执行操作前备份您的知识文件）。

• 如果您是从 0.1.x 版本升级过来的用户，针对已建立的知识库，请确认知识库的向量库类型、Embedding 模型与 configs/model_config.py 中默认设置一致，如无变化只需以下命令将现有知识库信息添加到数据库即可：

  $ python init_database.py
  

• 如果您是第一次运行本项目，知识库尚未建立，或者配置文件中的知识库类型、嵌入模型发生变化，或者之前的向量库没有开启 normalize_L2，需要以下命令初始化或重建知识库：

  $ python init_database.py --recreate-vs
  

5. 一键启动 API 服务或 Web UI

5.1 启动命令

一键启动脚本 startup.py,一键启动所有 Fastchat 服务、API 服务、WebUI 服务，示例代码：

$ python startup.py -a

并可使用 Ctrl + C 直接关闭所有运行服务。如果一次结束不了，可以多按几次。

可选参数包括 -a (或--all-webui), --all-api, --llm-api, -c (或--controller), --openai-api, -m (或--model-worker), --api, --webui，其中：

• --all-webui 为一键启动 WebUI 所有依赖服务；
• --all-api 为一键启动 API 所有依赖服务；
• --llm-api 为一键启动 Fastchat 所有依赖的 LLM 服务；
• --openai-api 为仅启动 FastChat 的 controller 和 openai-api-server 服务；
• 其他为单独服务启动选项。

5.2 启动非默认模型

若想指定非默认模型，需要用 --model-name 选项，示例：

$ python startup.py --all-webui --model-name Qwen-7B-Chat

更多信息可通过 python startup.py -h查看。

5.3 多卡加载

项目支持多卡加载，需在 startup.py 中的 create_model_worker_app 函数中，修改如下三个参数:

gpus=None, 
num_gpus=1, 
max_gpu_memory="20GiB"

其中，gpus 控制使用的显卡的ID，例如 "0,1";

num_gpus 控制使用的卡数;

max_gpu_memory 控制每个卡使用的显存容量。

注1：server_config.py的FSCHAT_MODEL_WORKERS字典中也增加了相关配置，如有需要也可通过修改FSCHAT_MODEL_WORKERS字典中对应参数实现多卡加载。

注2：少数情况下，gpus参数会不生效，此时需要通过设置环境变量CUDA_VISIBLE_DEVICES来指定torch可见的gpu,示例代码：

CUDA_VISIBLE_DEVICES=0,1 python startup.py -a

5.4 PEFT 加载(包括lora,p-tuning,prefix tuning, prompt tuning,ia3等)

本项目基于 FastChat 加载 LLM 服务，故需以 FastChat 加载 PEFT 路径，即保证路径名称里必须有 peft 这个词，配置文件的名字为 adapter_config.json，peft 路径下包含.bin 格式的 PEFT 权重，peft路径在startup.py中create_model_worker_app函数的args.model_names中指定，并开启环境变量PEFT_SHARE_BASE_WEIGHTS=true参数。

注：如果上述方式启动失败，则需要以标准的fastchat服务启动方式分步启动，分步启动步骤参考第六节，PEFT加载详细步骤参考加载lora微调后模型失效，

5.5 注意事项：

1. startup 脚本用多进程方式启动各模块的服务，可能会导致打印顺序问题，请等待全部服务发起后再调用，并根据默认或指定端口调用服务（默认 LLM API 服务端口：127.0.0.1:8888,默认 API 服务端口：127.0.0.1:7861,默认 WebUI 服务端口：本机IP：8501)

2.服务启动时间示设备不同而不同，约 3-10 分钟，如长时间没有启动请前往 ./logs目录下监控日志，定位问题。

3. 在Linux上使用ctrl+C退出可能会由于linux的多进程机制导致multiprocessing遗留孤儿进程，可通过shutdown_all.sh进行退出

5.6 启动界面示例：

1. FastAPI docs 界面

2. webui启动界面示例：

• Web UI 对话界面：

• Web UI 知识库管理页面：

---

常见问题

参见 常见问题。

---

路线图

• Langchain 应用
  • 本地数据接入
    • 接入非结构化文档
      • .md
      • .txt
      • .docx
    • 结构化数据接入
      • .csv
      • .xlsx
    • 分词及召回
      • 接入不同类型 TextSplitter
      • 优化依据中文标点符号设计的 ChineseTextSplitter
      • 重新实现上下文拼接召回
    • 本地网页接入
    • SQL 接入
    • 知识图谱/图数据库接入
  • 搜索引擎接入
    • Bing 搜索
    • DuckDuckGo 搜索
  • Agent 实现
    • 基础React形式的Agent实现，包括调用计算器等
    • Langchain 自带的Agent实现和调用
    • 更多模型的Agent支持
    • 更多工具
• LLM 模型接入
  • 支持通过调用 FastChat api 调用 llm
  • 支持 ChatGLM API 等 LLM API 的接入
• Embedding 模型接入
  • 支持调用 HuggingFace 中各开源 Emebdding 模型
  • 支持 OpenAI Embedding API 等 Embedding API 的接入
• 基于 FastAPI 的 API 方式调用
• Web UI
  • 基于 Streamlit 的 Web UI

---

项目交流群

🎉 langchain-Chatchat 项目微信交流群，如果你也对本项目感兴趣，欢迎加入群聊参与讨论交流。

关注我们

🎉 langchain-Chatchat 项目官方公众号，欢迎扫码关注。