开发环境部署

软件要求

要顺利运行本代码，请按照以下系统要求进行配置

已经测试过的系统

• Linux Ubuntu 22.04.5 kernel version 6.7

其他系统可能出现系统兼容性问题。

最低要求

该要求仅针对标准模式，轻量模式使用在线模型，不需要安装torch等库，也不需要显卡即可运行。

• Python 版本: >= 3.8(很不稳定), < 3.12
• CUDA 版本: >= 12.1

推荐要求

开发者在以下环境下进行代码调试，在该环境下能够避免最多环境问题。

• Python 版本 == 3.11.7
• CUDA 版本: == 12.1

硬件要求

本框架使用 fschat驱动，统一使用 huggingface进行推理，其他推理方式(如 llama-cpp，TensorRT加速引擎 建议通过推理引擎以 API 形式接入我们的框架)。

同时, 我们没有对 Int4 模型进行适配，不保证Int4模型能够正常运行。因此，量化版本暂时需要由开发者自行适配, 我们可能在未来放。

如果想要顺利在GPU运行本地模型的 FP16 版本，你至少需要以下的硬件配置，来保证在我们框架下能够实现 稳定连续对话

• ChatGLM3-6B & LLaMA-7B-Chat 等 7B模型
  • 最低显存要求: 14GB
  • 推荐显卡: RTX 4080
• Qwen-14B-Chat 等 14B模型
  • 最低显存要求: 30GB
  • 推荐显卡: V100
• Yi-34B-Chat 等 34B模型
  • 最低显存要求: 69GB
  • 推荐显卡: A100
• Qwen-72B-Chat 等 72B模型
  • 最低显存要求: 145GB
  • 推荐显卡：多卡 A100 以上

一种简单的估算方式为：

FP16: 显存占用(GB) = 模型量级 x 2
Int4: 显存占用(GB) = 模型量级 x 0.75

以上数据仅为估算，实际情况以 nvidia-smi 占用为准。 请注意，如果使用最低配置，仅能保证代码能够运行，但运行速度较慢，体验不佳。

同时，Embedding 模型将会占用 1-2G 的显存，历史记录最多会占用 数GB 的显存，因此，需要多冗余一些显存。

内存最低要求: 内存要求至少应该比模型运行的显存大。

例如，运行ChatGLM3-6B FP16 模型，显存占用13G，推荐使用16G以上内存。

部分测试用机配置参考，在以下机器下开发组成员已经进行原生模拟测试（创建新环境并根据要求下载后运行），确保能流畅运行全部功能的代码框架。

• 服务器

处理器: Intel® Xeon® Platinum 8558P Processor (260M Cache, 2.7 GHz)
内存: 4 TB
显卡组:  NVIDIA H800 SXM5 80GB x 8
硬盘: 6 PB 
操作系统: Ubuntu 22.04 LTS,Linux kernel 5.15.0-60-generic
显卡驱动版本: 535.129.03
Cuda版本: 12.1 
Python版本: 3.11.7
网络IP地址：美国，洛杉矶

• 个人PC

处理器: Intel® Core™ i9 processor 14900K 
内存: 256 GB DDR5
显卡组:  NVIDIA RTX4090 X 1 / NVIDIA RTXA6000 X 1
硬盘: 1 TB
操作系统: Ubuntu 22.04 LTS / Arch Linux, Linux Kernel 6.6.7
显卡驱动版本: 545.29.06
Cuda版本: 12.3 Update 1
Python版本: 3.11.7
网络IP地址：中国，上海 

VPN

如果您位于中国(含港，澳，台) 需要调用 OpenAI 或者 其他境外模型的 API，需要使用 VPN 工具或访问镜像站。

从 Huggingface 下载模型或者从本仓库拉取最新的代码时，需要开发者自行设置代理。本项目不涉及任何代理工具设置和使用，也不解决任何关于代理的问题。

Docker 部署

开发组为开发者们提供了一键部署的 docker 镜像文件懒人包。开发者们可以在 AutoDL 平台和 Docker 平台一键部署。

🌐 AutoDL 镜像 ，已经更新到V13版本,对应0.2.9

🐳 Docker 镜像

💻 本次更新后同时支持 DockerHub、阿里云、腾讯云镜像源 🌲：

docker run -d --gpus all -p 80:8501 isafetech/chatchat:0.2.10
docker run -d --gpus all -p 80:8501 ccr.ccs.tencentyun.com/chatchat/chatchat:0.2.10
docker run -d --gpus all -p 80:8501 registry.cn-beijing.aliyuncs.com/chatchat/chatchat:0.2.10

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

常规模式本地部署方案

# 首先，确信你的机器安装了 Python 3.8 - 3.10 版本
$ python --version
Python 3.8.13

# 如果低于这个版本，可使用conda安装环境
$ conda create -p /your_path/env_name python=3.8

# 激活环境
$ source activate /your_path/env_name

# 或，conda安装，不指定路径, 注意以下，都将/your_path/env_name替换为env_name
$ conda create -n env_name python=3.8
$ conda activate env_name # Activate the environment

# 更新py库
$ pip3 install --upgrade pip

# 关闭环境
$ source deactivate /your_path/env_name

# 删除环境
$ conda env remove -p  /your_path/env_name

接着，开始安装项目的依赖

# 拉取仓库
$ git clone --recursive https://github.com/chatchat-space/Langchain-Chatchat.git

# 进入目录
$ cd Langchain-Chatchat

# 安装全部依赖
$ pip install -r requirements.txt

# 默认依赖包括基本运行环境（FAISS向量库）。以下是可选依赖：
- 如果要使用 milvus/pg_vector 等向量库，请将 requirements.txt 中相应依赖取消注释再安装。
- 如果要开启 OCR GPU 加速，请安装 rapidocr_paddle[gpu]
- 如果要使用在线 API 模型，请安装对用的 SDK

此外，为方便用户 API 与 webui 分离运行，可单独根据运行需求安装依赖包。

• 如果只需运行 API，可执行：

  $ pip install -r requirements_api.txt
  
  # 默认依赖包括基本运行环境（FAISS向量库）。如果要使用 milvus/pg_vector 等向量库，请将 requirements.txt 中相应依赖取消注释再安装。

• 如果只需运行 WebUI，可执行：

  $ pip install -r requirements_webui.txt

注：使用 langchain.document_loaders.UnstructuredFileLoader进行 .docx 等格式非结构化文件接入时，可能需要依据文档进行其他依赖包的安装，请参考 langchain 文档。

需要注意的是，对于以下依赖，我们建议源码安装依赖或者定期检查是否为最新版本，我们的框架可能会大量使用这些依赖的最新特性。

• transformers
• fastchat
• fastapi
• streamlit 以及其组件
• langchain 以及其组件
• xformers

模型下载

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

以本项目中默认使用的 LLM 模型 THUDM/chatglm3-6b 与 Embedding 模型 BAAI/bge-large-zh-v1.5 为例：

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

$ git lfs install
$ git clone https://huggingface.co/THUDM/chatglm2-6b
$ git clone https://huggingface.co/moka-ai/m3e-base

初始化知识库

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

• 如果您已经有创建过知识库，可以先执行以下命令创建或更新数据库表：

  $ python init_database.py --create-tables

  如果可以正常运行，则无需再重建知识库。

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

  $ python init_database.py --recreate-vs

一键启动

启动前，确保已经按照参数配置正确配置各config模块。

一键启动脚本 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 服务；
• 其他为单独服务启动选项。

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

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

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

多卡加载

项目支持多卡加载，需在 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字典中对应参数实现多卡加载，且需注意server_config.py的配置会覆盖create_model_worker_app 函数的配置。

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

CUDA_VISIBLE_DEVICES=0,1 python startup.py -a

最轻模式本地部署方案

该模式的配置方式与常规模式相同，但无需安装 torch 等重依赖，通过在线API实现 LLM 和 Ebeddings 相关功能，适合没有显卡的电脑使用。

$ pip install -r requirements_lite.txt
$ python startup.py -a --lite

该模式支持的在线 Embeddings 包括：

• 智谱AI
• MiniMax
• 百度千帆
• 阿里云通义千问

在 model_config.py 中 将 LLM_MODELS 和 EMBEDDING_MODEL 设置为可用的在线 API 名称即可。

注意：在对话过程中并不要求 LLM 模型与 Embeddings 模型一致，你可以在知识库管理页面中使用 zhipu-api 作为嵌入模型，在知识库对话页面使用其它模型。