LangChain-chatchat 0.3.x入门级教程

前言

一种利用 langchain 思想实现的基于本地知识库的问答应用，目标期望建立一套对中文场景与开源模型支持友好、可离线运行的知识库问答解决方案。该项目支持市面上主流的开源 LLM、 Embedding 模型与向量数据库，可实现全部使用开源模型离线私有部署。项目地址：chatchat-space/Langchain-Chatchat: Langchain-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

一、LangChain-chatchat介绍

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

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

功能介绍，相交0.2.x版本新增加多个功能：

二、部署

1、Xinference部署

从 0.3.0 版本起，Langchain-Chatchat 不再根据用户输入的本地模型路径直接进行模型加载，涉及到的模型种类包括 LLM、Embedding、Reranker 及后续会提供支持的多模态模型等，均改为支持市面常见的各大模型推理框架接入，如 Xinference、Ollama、LocalAI、FastChat、One API 等。

这里我们使用Xinference来作为大模型推理框架。这里我们需要创建两个虚拟环境，因为安装Xinference环境时会与Langchain-Chatchat的环境发生冲突。

1.1 Xinference安装

参考官方文档：安装 — Xinference，在执行`pip install "xinference[all]" `之前，可以先安装自己服务器上对应的pytorch版本，地址：Previous PyTorch Versions | PyTorch

conda create -n xinference python=3.10 # 创建xinference虚拟环境
conda activate xinference # 激活xinference环境
pip install "xinference[all]" 

安装Xinference可能遇到的问题：

llama-cpp-python这个库安装不了，可以去Releases · abetlen/llama-cpp-python找到对应的whl文件进行安装。

1.2 启动模型推理框架并加载模型

启动Xinference，XINFERENCE_HOME对应模型下载的地址，XINFERENCE_MODEL_SRC对应模型从哪里下载，因为huggingface需要翻墙，可以从modelscope下载。

XINFERENCE_HOME=Langchain-Chatchat/model XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9998

这里可能出现的报错：/lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.29' not found

解决办法：这里应该是llama-cpp-python导致的，我不选择使用Llama.cpp 引擎，所以这个时候只需要将llama-cpp-python卸载掉就不会报错了。

打开http://0.0.0.0:9998

这里我们选用qwen1.5-chat最为我们的LLM，bge-large-zh-v1.5作为Embedding模型

这里我已经缓存了，所以后面会接一个Cached。点击下面的小火箭就会开始下载了。

同理bge-large-zh-v1.5也同样的下载。

下载好后可以在对应的文件夹查看。

接下来启动刚才下载好的两个模型，如果按照我的配置下载的，可以直接复制，如果不是，请修改对应的参数。

xinference launch --model-engine Transformers --model-name qwen1.5-chat --size-in-billions 1_8 --model-format pytorch --quantization 4-bit --gpu-idx 1

xinference launch --model-type embedding --model-name bge-large-zh-v1.5 --model-engine transformers --model-format pytorch --gpu-idx 1

加载好后可以通过以下命令进行查看

xinference list

停止启动的模型：

xinference terminate --model-uid "qwen1.5-chat"
xinference terminate --model-uid "bge-large-zh-v1.5"

2、chatchat部署

2.1 安装chatchat虚拟环境

conda create -n chatchat python=3.10
conda activate chatchat
pip install langchain-chatchat -U

2.2 初始化项目配置与数据目录

设置 Chatchat 存储配置文件和数据文件的根目录，在项目根目录创建一个chatchat_data文件夹。

# on linux or macos
export CHATCHAT_ROOT=Langchain-Chatchat/chatchat_data# on windows
set CHATCHAT_ROOT=./chatchat_data

初始化chatchat

chatchat init

修改配置文件

配置模型设置文件（model_settings.yaml）

# 默认选用的 LLM 名称
DEFAULT_LLM_MODEL: qwen1.5-chat# 默认选用的 Embedding 名称
DEFAULT_EMBEDDING_MODEL: bge-large-zh-v1.5# AgentLM模型的名称 (可以不指定，指定之后就锁定进入Agent之后的Chain的模型，不指定就是 DEFAULT_LLM_MODEL)
Agent_MODEL: ''# 默认历史对话轮数
HISTORY_LEN: 3# 大模型最长支持的长度，如果不填写，则使用模型默认的最大长度，如果填写，则为用户设定的最大长度
MAX_TOKENS:# LLM通用对话参数
TEMPERATURE: 0.7# 支持的Agent模型
SUPPORT_AGENT_MODELS:- chatglm3-6b- glm-4- openai-api- Qwen-2- qwen2-instruct- gpt-3.5-turbo- gpt-4o# LLM模型配置，包括了不同模态初始化参数。
# `model` 如果留空则自动使用 DEFAULT_LLM_MODEL
LLM_MODEL_CONFIG:preprocess_model:model: ''temperature: 0.05max_tokens: 4096history_len: 10prompt_name: defaultcallbacks: falsellm_model:model: 'qwen1.5-chat'temperature: 0.9max_tokens: 4096history_len: 10prompt_name: defaultcallbacks: trueaction_model:model: 'qwen1.5-chat'temperature: 0.01max_tokens: 4096history_len: 10prompt_name: ChatGLM3callbacks: truepostprocess_model:model: ''temperature: 0.01max_tokens: 4096history_len: 10prompt_name: defaultcallbacks: trueimage_model:model: sd-turbosize: 256*256MODEL_PLATFORMS:- platform_name: xinferenceplatform_type: xinferenceapi_base_url: http://127.0.0.1:9997/v1api_key: EMPTYapi_proxy: ''api_concurrencies: 5auto_detect_model: truellm_models: []embed_models: []text2image_models: []image2text_models: []rerank_models: []speech2text_models: []text2speech_models: []

配置知识库路径（basic_settings.yaml），KB_ROOT_PATH根据自己的路径进行修改，怕出错就弄绝对路径。

# 服务器基本配置信息
# 除 log_verbose/HTTPX_DEFAULT_TIMEOUT 修改后即时生效
# 其它配置项修改后都需要重启服务器才能生效，服务运行期间请勿修改# 生成该配置模板的项目代码版本，如这里的值与程序实际版本不一致，建议重建配置文件模板
version: 0.3.1.3# 是否开启日志详细信息
log_verbose: false# httpx 请求默认超时时间（秒）。如果加载模型或对话较慢，出现超时错误，可以适当加大该值。
HTTPX_DEFAULT_TIMEOUT: 300.0# 知识库默认存储路径
KB_ROOT_PATH: Langchain-Chatchat-master/chatchat_data/data/knowledge_base# Langchain-Chatchat-master/libs/chatchat-server/chatchat_data/data/knowledge_base # 默认# 数据库默认存储路径。如果使用sqlite，可以直接修改DB_ROOT_PATH；如果使用其它数据库，请直接修改SQLALCHEMY_DATABASE_URI。
# DB_ROOT_PATH: 
#   Langchain-Chatchat-master/libs/chatchat-server/chatchat_data/data/knowledge_base/info.db# # 知识库信息数据库连接URI
# SQLALCHEMY_DATABASE_URI: 
#   sqlite:Langchain-Chatchat-master/libs/chatchat-server/chatchat_data/data/knowledge_base/info.db# API 是否开启跨域
OPEN_CROSS_DOMAIN: false# 各服务器默认绑定host。如改为"0.0.0.0"需要修改下方所有XX_SERVER的host
# Windows 下 WEBUI 自动弹出浏览器时，如果地址为 "0.0.0.0" 是无法访问的，需要手动修改地址栏
DEFAULT_BIND_HOST: 0.0.0.0# API 服务器地址。其中 public_host 用于生成云服务公网访问链接（如知识库文档链接）
API_SERVER:host: 0.0.0.0port: 7861public_host: 127.0.0.1public_port: 7861# WEBUI 服务器地址
WEBUI_SERVER:host: 0.0.0.0port: 8501

2.3 初始化知识库

进行知识库初始化前，需要确保启动模型推理框架及对应 embedding 模型。

chatchat kb -r

出现下面的界面就是成功了

可能出现的报错1：

2025-03-14 16:37:10.401 | WARNING  | chatchat.server.utils:get_default_llm:205 - default llm model glm4-chat is not found in available llms, using qwen1.5-chat instead
2025-03-14 16:37:10.461 | WARNING  | chatchat.server.utils:get_default_embedding:214 - default embedding model bge-m3 is not found in available embeddings, using m3e-large instead
2025-03-14 16:37:10.493 | WARNING  | chatchat.server.utils:get_default_embedding:214 - default embedding model bge-m3 is not found in available embeddings, using m3e-large instead
2025-03-14 16:37:10.519 | WARNING  | chatchat.server.utils:get_default_embedding:214 - default embedding model bge-m3 is not found in available embeddings, using m3e-large instead
2025-03-14 16:37:10.544 | WARNING  | chatchat.server.utils:get_default_embedding:214 - default embedding model bge-m3 is not found in available embeddings, using m3e-large instead
2025-03-14 16:37:10.571 | ERROR    | chatchat.init_database:worker:61 - (sqlite3.OperationalError) unable to open database file
(Background on this error at: https://sqlalche.me/e/20/e3q8)

解决办法1：

这个错误是没有重新指定CHATCHAT_ROOT 

export CHATCHAT_ROOT=Langchain-Chatchat-master/chatchat_data

可能出现的报错2：

2025-03-12 21:05:44.802 | ERROR    | chatchat.server.knowledge_base.utils:files2docs_in_thread_file2docs:419 - LookupError: 从文件 samples/test_files/test.txt 加载文档时出错：
**********************************************************************Resource punkt not found.Please use the NLTK Downloader to obtain the resource:>>> import nltk>>> nltk.download('punkt')For more information see: https://www.nltk.org/data.htmlAttempted to load tokenizers/punkt/PY3/english.pickle

解决办法2：下载/root/nltk_data/tokenizers/punkt.zip文件解压到/root/nltk_data/tokenizers/

2.4 启动

pip install httpx==0.27.2

chatchat start -a

可能遇到的问题：

Traceback (most recent call last):File "envs/chatchat/lib/python3.10/site-packages/streamlit/runtime/scriptrunner/script_runner.py", line 600, in _run_scriptexec(code, module.__dict__)File "Langchain-Chatchat-master/libs/chatchat-server/chatchat/webui.py", line 71, in <module>kb_chat(api=api)File "Langchain-Chatchat-master/libs/chatchat-server/chatchat/webui_pages/kb_chat.py", line 118, in kb_chatkb_list = [x["kb_name"] for x in api.list_knowledge_bases()]
TypeError: 'NoneType' object is not iterable

解决办法：

pip install httpx==0.27.2

到这里就部署完了！

三、Debug代码

这里我使用的是vscode，配置文件如下，主文件在libs/chatchat-server/chatchat/cli.py中。

{"version": "0.2.0","configurations": [{"name": "kb-r","type": "debugpy","request": "launch","program": "Langchain-Chatchat-master/libs/chatchat-server/chatchat/cli.py","console": "integratedTerminal","cwd": "Langchain-Chatchat-master/libs/chatchat-server","args": ["kb", "-r"],"env": {"CHATCHAT_ROOT": "Langchain-Chatchat-master/chatchat_data"}},{"name": "init","type": "debugpy","request": "launch","program": "Langchain-Chatchat-master/libs/chatchat-server/chatchat/cli.py","console": "integratedTerminal","cwd": "Langchain-Chatchat-master/libs/chatchat-server","args": ["init"],"env": {"CHATCHAT_ROOT": "Langchain-Chatchat-master/chatchat_data"}},{"name": "start","type": "debugpy","request": "launch","program": "Langchain-Chatchat-master/libs/chatchat-server/chatchat/cli.py","console": "integratedTerminal","cwd": "Langchain-Chatchat-master/libs/chatchat-server","args": ["start", "-a"],"env": {"CHATCHAT_ROOT": "Langchain-Chatchat-master/chatchat_data"}},]
}