DB-GPT 集群部署指南：使用 dbgpt CLI 搭建分布式模型服务
DB-GPT 集群部署指南：使用 dbgpt CLI 搭建分布式模型服务
项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT 本指南基于 docs/docs/installation/model_service/cluster.md 展开，完整讲解如何通过 dbgpt 命令行工具在 DB-GPT 中搭建「Model Controller + Model Worker」的模型服务集群，覆盖 LLM、Embedding、Reranker 三类模型的部署与验证，并深入 CLI 的源码实现，帮助读者掌握从单机模型部署到多模型水平扩展的完整实战路径。
部署架构：Controller 与 Worker 的分工
在动手执行命令之前，先理解 DB-GPT 模型集群的拓扑。从 packages/dbgpt-core/src/dbgpt/model/cluster/init.py 的导出可以看到，集群由三大核心组件构成：
- Model Controller：模型的注册中心与调度中枢，默认监听
8000端口，负责收集各 Worker 的心跳、维护模型实例的注册表（Registry），并向调用方暴露统一的服务发现能力； - Model Worker：真正加载并执行模型推理的进程，每个 Worker 以独立端口提供服务（文档示例中 LLM 用
8001/8002，Embedding 用8003，Reranker 用8004）； - Model API Server（apiserver）：可选的外部 API 网关层，默认监听
8100端口，可附加 API Key 鉴权与 CORS 控制（见 ModelAPIServerParameters）。
启动时的默认端口、心跳参数可以在 ModelControllerParameters 与 ModelWorkerParameters 中直接确认：Controller 默认端口 8000，心跳检查间隔 20s、超时 60s；Worker 默认端口 8001、默认自动注册（register=True）、默认发送心跳（send_heartbeat=True）。
这种「Controller 集中管理 + Worker 分布式推理」的架构，让模型可以跨主机、跨 GPU 横向扩展，是实现 AI 原生数据应用多模型服务的基础。
第一步：安装命令行工具
所有后续操作都通过 dbgpt 命令完成，因此首先需要安装 DB-GPT 项目：
$ pip install -e ".[default]"
-e 表示以可编辑模式安装，便于开发调试；[default] 会附带默认运行所需依赖。
如果不希望安装到环境中，也可以直接以脚本方式运行 CLI 入口：
$ python pilot/scripts/cli_scripts.py
需要说明的是：在当前仓库中，CLI 的真实实现位于 packages/dbgpt-core/src/dbgpt/cli/cli_scripts.py，文件末尾通过 main() 调用 cli() 进入 Click 命令行框架。脚本模式下通过 python .../cli_scripts.py 执行，效果等价于 dbgpt 命令。
安装完成后可以验证命令是否可用：
$ dbgpt --help
Already connect 'dbgpt'
Usage: dbgpt [OPTIONS] COMMAND [ARGS]...
Options:
--log-level TEXT Log level
--version Show the version and exit.
--help Show this message and exit.
Commands:
install Install dependencies, plugins, etc.
knowledge Knowledge command line tool
model Clients that manage model serving
start Start specific server.
stop Start specific server.
trace Analyze and visualize trace spans.
第二步：启动 Model Controller
集群的起点是 Model Controller，它是所有模型实例的注册中枢：
$ dbgpt start controller
默认情况下 Model Controller 监听 8000 端口。从源码看，该命令最终会调用 run_model_controller（由 cli.py 中的 start_model_controller 转发），其端口与心跳策略由 ModelControllerParameters 定义。
提示：如果 DB-GPT 运行在 Docker 容器中，可以通过如下命令跟踪 Controller 的日志：
$ docker logs db-gpt-webserver-1 -f
第三步：启动 LLM Model Worker
Controller 就绪后，即可逐个拉起模型 Worker。每个 Worker 通过 --controller_addr 指向 Controller，并以独立端口对外提供服务。
启动 glm-4-9b-chat 模型：
dbgpt start worker --model_name glm-4-9b-chat \
--model_path /app/models/glm-4-9b-chat \
--port 8001 \
--controller_addr http://127.0.0.1:8000
启动 vicuna-13b-v1.5 模型：
dbgpt start worker --model_name vicuna-13b-v1.5 \
--model_path /app/models/vicuna-13b-v1.5 \
--port 8002 \
--controller_addr http://127.0.0.1:8000
⚠️ 请务必替换为你自己的模型名称与模型路径，
--model_name与--model_path均为必填参数。
从 start_model_worker 的实现可以看到，该命令最终调用 run_worker_manager 启动 Worker 管理器；多个 LLM Worker 可以并行启动、共享同一个 Controller，从而实现多模型共存。
第四步：启动 Embedding 模型 Worker
向量化是 RAG 知识库问答的基础能力。启动 Embedding 模型需要显式指定 --worker_type text2vec：
dbgpt start worker --model_name text2vec \
--model_path /app/models/text2vec-large-chinese \
--worker_type text2vec \
--port 8003 \
--controller_addr http://127.0.0.1:8000
⚠️ 请务必替换为你自己的模型名称与模型路径。
text2vec 属于 Embedding 专用 Worker 类型，它与 LLM Worker 在 WorkerType 枚举中区分（内部以 model_name@worker_type 的形式注册，如 text2vec@text2vec）。
第五步：启动 Reranker 模型 Worker
Reranker（重排序）模型用于对召回结果进行精细排序，提升 RAG 检索质量。通过 --rerank 标志开启重排序模式：
dbgpt start worker --worker_type text2vec \
--rerank \
--model_path /app/models/bge-reranker-base \
--model_name bge-reranker-base \
--port 8004 \
--controller_addr http://127.0.0.1:8000
⚠️ 请务必替换为你自己的模型名称与模型路径。
注意：文档示例中 Reranker 的
--worker_type同样标注为text2vec（与 Embedding 共用 Worker 类型），但通过--rerank标志区分用途。
第六步：查看已部署的模型
部署完成后，可以通过 dbgpt model list 检查所有模型实例的注册状态。该命令在 cli.py 中实现，内部通过 ModelRegistryClient 向 Controller 查询实例列表，并以表格输出每个实例的名称、类型、Host、Port、健康状态与最近心跳时间：
$ dbgpt model list
+-------------------+------------+------------+------+---------+---------+-----------------+----------------------------+
| Model Name | Model Type | Host | Port | Healthy | Enabled | Prompt Template | Last Heartbeat |
+-------------------+------------+------------+------+---------+---------+-----------------+----------------------------+
| glm-4-9b-chat | llm | 172.17.0.2 | 8001 | True | True | | 2023-09-12T23:04:31.287654 |
| WorkerManager | service | 172.17.0.2 | 8001 | True | True | | 2023-09-12T23:04:31.286668 |
| WorkerManager | service | 172.17.0.2 | 8003 | True | True | | 2023-09-12T23:04:29.845617 |
| WorkerManager | service | 172.17.0.2 | 8002 | True | True | | 2023-09-12T23:04:24.598439 |
| WorkerManager | service | 172.21.0.5 | 8004 | True | True | | 2023-09-12T23:04:24.598439 |
| text2vec | text2vec | 172.17.0.2 | 8003 | True | True | | 2023-09-12T23:04:29.844796 |
| vicuna-13b-v1.5 | llm | 172.17.0.2 | 8002 | True | True | | 2023-09-12T23:04:24.597775 |
| bge-reranker-base | text2vec | 172.21.0.5 | 8004 | True | True | | 2024-05-15T11:36:12.935012 |
+-------------------+------------+------------+------+---------+---------+-----------------+----------------------------+
解读这张表的关键信息：
- Healthy = True 表示该实例在心跳超时窗口（默认
60s）内正常上报，若超过则会被 Controller 标记为不健康； - WorkerManager 行是每个 Worker 进程中自带的服务实例记录，属正常现象；
- 同一 Controller 下可同时管理多个主机（如示例中的
172.17.0.2与172.21.0.5）上的模型，这正是集群部署的核心价值。
第七步：通过 WebServer 使用模型服务
上述部署好的模型服务可以通过 WebServer（dbgpt_server）对外使用。
修改环境变量
首先修改 .env 配置文件，指定默认模型与 Model Controller 地址：
LLM_MODEL=vicuna-13b-v1.5
# 当前默认的 MODEL_SERVER 地址就是 Model Controller 的地址
MODEL_SERVER=http://127.0.0.1:8000
启动 WebServer
dbgpt start webserver --light
--light 表示不启动内置的模型服务，此时 WebServer 只作为前端与业务服务，通过 MODEL_SERVER 连接外部的 Model Controller，复用我们前面手动部署的模型实例。
从 dbgpt_app/_cli.py 的
start_webserver实现可以看到，WebServer 启动时会打印 Profile、Config、Workspace 信息，支持--daemon后台运行，并将日志写入LOGDIR/webserver_uvicorn.log。
指定模型直接启动
也可以直接在命令行指定模型启动（此时 Embedding 也使用远程服务）：
LLM_MODEL=glm-4-9b-chat dbgpt start webserver --light --remote_embedding
--remote_embedding 表示 Embedding 模型同样使用集群中已部署的远程服务，而非本地加载。
深入 CLI：关键命令帮助与参数全解
DB-GPT 的 CLI 基于 Click 实现（入口见 packages/dbgpt-core/src/dbgpt/cli/cli_scripts.py），所有命令都支持 --help 查看详细用法。
dbgpt start --help
dbgpt start --help
Already connect 'dbgpt'
Usage: dbgpt start [OPTIONS] COMMAND [ARGS]...
Start specific server.
Options:
--help Show this message and exit.
Commands:
apiserver Start apiserver
controller Start model controller
webserver Start webserver(dbgpt_server.py)
worker Start model worker
(dbgpt_env) magic@B-4TMH9N3X-2120 ~ %
dbgpt start worker --help
Worker 参数是最丰富的，逐一说明如下：
dbgpt start worker --help
Already connect 'dbgpt'
Usage: dbgpt start worker [OPTIONS]
Start model worker
Options:
--model_name TEXT Model name [required]
--model_path TEXT Model path [required]
--worker_type TEXT Worker type
--worker_class TEXT Model worker class,
pilot.model.cluster.DefaultModelWorker
--model_type TEXT Model type: huggingface, llama.cpp, proxy
and vllm [default: huggingface]
--host TEXT Model worker deploy host [default: 0.0.0.0]
--port INTEGER Model worker deploy port [default: 8001]
--daemon Run Model Worker in background
--limit_model_concurrency INTEGER
Model concurrency limit [default: 5]
--standalone Standalone mode. If True, embedded Run
ModelController
--register Register current worker to model controller
[default: True]
--worker_register_host TEXT The ip address of current worker to register
to ModelController. If None, the address is
automatically determined
--controller_addr TEXT The Model controller address to register
--send_heartbeat Send heartbeat to model controller
[default: True]
--heartbeat_interval INTEGER The interval for sending heartbeats
(seconds) [default: 20]
--log_level TEXT Logging level
--log_file TEXT The filename to store log [default:
dbgpt_model_worker_manager.log]
--tracer_file TEXT The filename to store tracer span records
[default:
dbgpt_model_worker_manager_tracer.jsonl]
--tracer_storage_cls TEXT The storage class to storage tracer span
records
--device TEXT Device to run model. If None, the device is
automatically determined
--prompt_template TEXT Prompt template. If None, the prompt
template is automatically determined from
model path, supported template: zero_shot,vi
cuna_v1.1,llama-2,codellama,alpaca,baichuan-
chat,internlm-chat
--max_context_size INTEGER Maximum context size [default: 4096]
--num_gpus INTEGER The number of gpus you expect to use, if it
is empty, use all of them as much as
possible
--max_gpu_memory TEXT The maximum memory limit of each GPU, only
valid in multi-GPU configuration
--cpu_offloading CPU offloading
--load_8bit 8-bit quantization
--load_4bit 4-bit quantization
--quant_type TEXT Quantization datatypes, `fp4` (four bit
float) and `nf4` (normal four bit float),
only valid when load_4bit=True [default:
nf4]
--use_double_quant Nested quantization, only valid when
load_4bit=True [default: True]
--compute_dtype TEXT Model compute type
--trust_remote_code Trust remote code [default: True]
--verbose Show verbose output.
--help Show this message and exit.
关键参数解读（与 ModelWorkerParameters 定义一一对应）：
| 参数 | 默认值 | 作用 |
|---|---|---|
--model_type | huggingface | 模型加载引擎，可选 huggingface、llama.cpp、proxy、vllm |
--port | 8001 | Worker 对外服务端口，多模型部署时需各不相同 |
--limit_model_concurrency | 5 | 单模型并发上限，超过后请求排队 |
--standalone | False | 独立模式，开启后 Worker 内嵌运行 Model Controller，适合单机单进程场景 |
--register | True | 是否自动向 Controller 注册 |
--send_heartbeat / --heartbeat_interval | True / 20 | 心跳上报开关与间隔（秒） |
--max_context_size | 4096 | 最大上下文长度 |
--num_gpus / --max_gpu_memory | 空 | 多 GPU 场景下指定使用 GPU 数量与单卡显存上限 |
--load_8bit / --load_4bit / --quant_type | — / — / nf4 | 量化加载，4bit 时可选 fp4 与 nf4，--use_double_quant 默认开启嵌套量化 |
--prompt_template | 自动推断 | 可从模型路径自动识别，也可手动指定（zero_shot、vicuna_v1.1、llama-2、codellama、alpaca、baichuan-chat、internlm-chat 等） |
--trust_remote_code | True | 允许加载依赖远程代码的模型（如 ChatGLM 系） |
dbgpt model --help
dbgpt model 是模型服务的管理客户端，连接地址可通过 --address 参数或环境变量 CONTROLLER_ADDRESS 指定：
dbgpt model --help
Already connect 'dbgpt'
Usage: dbgpt model [OPTIONS] COMMAND [ARGS]...
Clients that manage model serving
Options:
--address TEXT Address of the Model Controller to connect to. Just support
light deploy model, If the environment variable
CONTROLLER_ADDRESS is configured, read from the environment
variable
--help Show this message and exit.
Commands:
chat Interact with your bot from the command line
list List model instances
restart Restart model instances
start Start model instances
stop Stop model instances
其中 dbgpt model chat 支持直接在终端与已部署模型进行流式对话（内部通过 RemoteWorkerManager.generate_stream 实现，见 cli.py），支持 /exit、/clear、/reset 等会话命令，可用于快速验证模型服务是否正常；dbgpt model start/stop/restart 则用于远程管理已注册的模型实例。
综合实战：一次完整的集群部署流程
将以上步骤串联，一个可用的最小集群部署流程如下：
- 安装 CLI：
pip install -e ".[default]"（或脚本模式运行）； - 启动 Controller：
dbgpt start controller（默认:8000）； - 启动 LLM Worker：分别以不同端口启动多个 LLM（如
glm-4-9b-chat在8001、vicuna-13b-v1.5在8002），均指向--controller_addr http://127.0.0.1:8000； - 启动 Embedding Worker：
text2vec类型在8003； - 启动 Reranker Worker：加
--rerank标志在8004； - 验证注册：
dbgpt model list检查所有实例 Healthy/Enabled 状态； - 接入业务：设置
.env中LLM_MODEL与MODEL_SERVER，执行dbgpt start webserver --light（或--light --remote_embedding）使 Web 服务使用集群模型； - 运维管理：使用
dbgpt model chat/list/restart/start/stop完成日常管理与快速验证；如需后台运行可使用--daemon参数，并通过dbgpt stop controller/worker/webserver停止相应服务（停止逻辑见 cli.py 与_stop_service工具）。
总结
通过 dbgpt CLI 的 controller、worker、model、webserver 系列命令，DB-GPT 将模型服务的部署、注册、调度与消费链路完整打通：Controller 负责集中注册与心跳健康检查，Worker 负责分布式模型推理，dbgpt model 提供统一的管理与交互入口。本文覆盖的命令与参数均可在当前仓库的 cli.py、parameter.py 与 cluster 目录中找到对应实现，读者可结合实际模型路径直接上手，从单模型部署平滑演进到多模型、多主机的集群化模型服务。
更多推荐
5
0- 0
已为社区贡献8条内容
所有评论(0)