DB-GPT 模型服务集群部署实战：Controller–Worker 架构与 CLI 全命令解析

DB-GPT 模型服务集群部署实战：Controller–Worker 架构与 CLI 全命令解析

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

本文以 DB-GPT 官方集群部署文档（cluster.md）为核心，完整还原"安装 CLI → 启动 Model Controller → 启动 LLM/Embedding/Rerank Worker → 模型巡检 → 接入 Webserver"的集群化模型服务部署全流程，并结合开源仓库源码剖析 Controller/Worker 注册、心跳与模型管理命令的底层实现。读完本篇，你可以掌握dbgpt命令行工具在模型集群场景下的全部用法与参数含义，并理解每个命令背后调用的核心代码路径。

一、集群架构：为什么需要 Controller 与 Worker

DB-GPT 的模型服务采用典型的Controller–Worker 分层架构：

• Model Controller（模型控制器）：集群的统一入口与注册中心，监听默认端口8000，负责接收 Worker 的注册请求、维护模型实例注册表（Registry）并提供健康状态查询；
• Model Worker（模型工作节点）：每台 GPU 机器上运行一个或多个 Worker 进程，加载具体模型（LLM、Embedding、Rerank），向 Controller 注册并按需执行推理；
• Client（客户端/上层应用）：Webserver 等业务进程通过RemoteWorkerManager连接 Controller，按模型名将推理请求路由到对应 Worker。

从源码结构看，该架构的核心组件集中在 dbgpt/model/cluster 包中，其__init__.py导出的公开 API 即对应了部署文档中的每个环节：

• run_model_controller/run_apiserver：分别对应dbgpt start controller/dbgpt start apiserver的启动入口（实现见 controller.py）；
• run_worker_manager：对应dbgpt start worker（实现见 manager.py）；
• ModelRegistryClient、RemoteWorkerManager：dbgpt model list/chat/stop等客户端命令的底层依赖（见 registry.py）；
• DefaultModelWorker、ModelWorker：Worker 侧的模型加载与推理基类。

默认控制器地址在 model/cli.py 中硬编码为http://127.0.0.1:8000，且支持通过环境变量CONTROLLER_ADDRESS覆盖——这与文档中"Model Server默认启动在8000端口"以及--controller_addr http://127.0.0.1:8000参数完全对应。

二、准备：安装 CLI 命令行工具

文档中所有操作均通过dbgpt命令完成。首先需要以可编辑模式安装 DB-GPT 项目（含默认依赖）：

pip install -e ".[default]"

安装后dbgpt命令即可使用。文档还给出了脚本模式调用方式：

python pilot/scripts/cli_scripts.py

需要注意，从当前仓库源码结构看，CLI 入口脚本的实际位置已迁移至 cli_scripts.py，可以直接阅读该文件了解全部命令注册逻辑，也可以以模块方式运行该入口。

dbgpt命令是如何组装的

阅读 cli_scripts.py 可以发现，dbgpt并非单一命令，而是一个 click 命令组，各子命令按可选依赖动态注册：

• start controller/start worker/start apiserver/model命令组来自dbgpt.model.cli（模型服务模块）；
• start webserver/stop webserver/db migration命令来自dbgpt_app._cli（Web 服务端模块）；
• knowledge、trace、repo、app等命令分别来自知识库、追踪、应用管理模块。

每个子命令通过add_command_alias以deepcopy方式挂载到对应父命令组上。这种"可选模块、按需装配"的机制意味着：如果某个可选依赖缺失，对应命令只会产生一条 warning 而不会导致dbgpt整体不可用。

三、启动 Model Controller

dbgpt start controller

Controller 启动后默认监听8000端口，所有 Worker 与客户端均以此地址为注册/连接目标。从源码看（model/cli.py），该命令：

1. 前台模式下直接调用run_model_controller(config)启动 uvicorn 服务；
2. 追加-d/--daemon参数时进入后台守护模式，日志写入LOGDIR下的model_controller_uvicorn.log。

文档中提到的查看日志方式（Docker 部署场景）：

docker logs db-gpt-webserver-1 -f

在非 Docker 场景下，可依据上文 daemon 日志文件名在LOGDIR中查找对应日志文件。

对应地，dbgpt stop controller会按进程特征调用_stop_service("controller", "ModelController", port=port)停掉指定（或全部）Controller 进程，见 model/cli.py。

四、启动 LLM 模型 Worker

Worker 是真正承载模型推理的进程。文档给出了两个 LLM Worker 示例：

# 启动 glm-4-9b-chat 模型 Worker 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 模型 Worker 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替换为你本地实际使用的模型名与模型目录。

从源码结构看（model/cli.py），start worker命令前台模式下调用run_worker_manager(config)拉起 Worker 管理器，守护模式下日志按model_worker_{worker_type}_{port}_uvicorn.log的规则写入LOGDIR；dbgpt stop worker [--port 8001]则可按端口精确停止单个 Worker 进程。

多机部署要点：在第二台 GPU 机器上启动 Worker 时，只需将--port换为不冲突的端口，并把--controller_addr指向第一台机器 Controller 的可访问地址（如内网 IP:8000）。Worker 注册时的上报地址默认自动探测，也可用--worker_register_host显式指定（例如多网卡环境下）。

五、启动 Embedding 模型 Worker

向量化能力（知识库、RAG、检索增强）依赖独立的 Embedding Worker：

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

关键参数说明：

• --worker_type text2vec：声明该 Worker 处理的是向量化任务而非 LLM 对话，模型注册表中将以text2vec类型登记（在dbgpt model list输出的Model Type列可见）；
• --model_name/--model_path：同样必须替换为自己的模型名与本地路径。

Embedding Worker 的底层实现参考 embedding_worker.py，上层业务侧的远程向量调用则通过 remote_embedding.py 将请求转发到集群。

六、启动 Reranking 模型 Worker

重排序模型用于对初检结果精排，文档中的启动方式为：

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

--rerank标志位将 Worker 标记为重排模式，--worker_type同样为text2vec系。替换为你自己的 reranker 模型路径与名称即可（如bge-reranker-v2-m3等）。

七、模型巡检：dbgpt model list

Worker 启动并注册成功后，用dbgpt model list查看集群中所有已部署的模型实例：

$ 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 | +-------------------+------------+------------+------+---------+---------+-----------------+----------------------------+

从这份输出可以读出集群拓扑：172.17.0.2上跑了三个 Worker（8001/8002/8003 端口），172.21.0.5上跑了一个（8004 端口）。实现层面，model/cli.py 中list命令先通过ModelRegistryClient向 Controller 拉取get_all_model_instances()，再用PrettyTable渲染上述八列。

各列含义与运维价值：

八、模型管理命令族：start / stop / restart / chat

dbgpt model命令组（model/cli.py）是集群运维的核心工具，除list外还包括：

# 启动模型实例（远程下发到指定 host:port 的 Worker） dbgpt model start --model_name <name> --host <ip> --port <port> # 停止指定实例（需要 host + port 双定位） dbgpt model stop --model_name <name> --host <ip> --port <port> # 重启模型实例 dbgpt model restart --model_name <name> # 命令行直接对话调试 dbgpt model chat -m <name>

结合源码的几点补充：

• 控制器地址解析：model命令组支持--address显式指定 Controller 地址；未指定时调用_detect_controller_address()，优先读取环境变量CONTROLLER_ADDRESS，最终回落到默认的http://127.0.0.1:8000；
• stop 需要 host + port：从 stop 命令实现 看，它构造WorkerStartupRequest(host, port, worker_type, model)后经RemoteWorkerManager.model_shutdown()下发，因此必须同时给出实例所在主机与端口（可从model list输出获取）；
• chat 交互式调试：dbgpt model chat -m glm-4-9b-chat会进入流式对话终端（chat 实现），支持/exit退出、/clear清屏、/reset重置会话，可用--system指定系统提示词，对话历史持久化在~/.dbgpt_cli_chat_history。

九、接入 Webserver 使用集群模型服务

集群部署完成后，Webserver 作为业务入口需要指向 Controller。文档给出的接入方式是修改.env配置（或直接使用环境变量）：

LLM_MODEL=vicuna-13b-v1.5 # The current default MODEL_SERVER address is the address of the Model Controller MODEL_SERVER=http://127.0.0.1:8000

然后以 light 模式启动 Webserver：

dbgpt start webserver --light

• --light表示不启动内嵌的单机模型服务，仅连接远端集群；
• MODEL_SERVER默认即指向 Model Controller 地址，所有模型请求经 Controller 路由到注册了对应模型的 Worker；
• 也可以完全通过命令行内联指定模型：

LLM_MODEL=glm-4-9b-chat dbgpt start webserver --light --remote_embedding

其中--remote_embedding表示 Embedding 能力同样走集群中注册的远程 text2vec Worker，而不是本地计算。

版本提示：从当前仓库源码结构看（_cli.py），新版dbgpt start webserver已演进为以 TOML 配置文件为核心的启动方式，暴露-c/--config、-p/--profile、-y/--yes、--api-key、-d/--daemon等选项，并通过~/.dbgpt/下的 profile 管理 LLM 服务商配置；上文文档中的--light/--remote_embedding为早期接口用法，实际部署时请以dbgpt start webserver --help输出为准。

十、dbgpt start worker完整参数速查

文档附带了dbgpt start worker --help的完整输出，这里整理为参数表供对照（默认值与帮助文本以文档 help 快照为准）：

几个实战向的关键参数解读：

• --standalone：小规模单机场景可以不单独起 Controller，Worker 内嵌运行 Controller，一条命令完成"注册中心 + 推理节点"合一部署；
• --register+--worker_register_host：跨网段/多网卡部署时最容易被忽略的一组——若不指定注册主机，Worker 上报的可能是容器内部地址，导致 Controller 反向调用失败；
• --limit_model_concurrency：控制单 Worker 的推理并发，GPU 显存有限时应下调以换取稳定性；
• 量化参数组合：显存紧张的小模型可用--load_4bit+--use_double_quant（默认开启双重量化）+ 必要时叠加--cpu_offloading进一步压低显存占用。

从源码结构看，这些选项并非在 CLI 中静态写死，而是由 parameter.py 中的ModelWorkerParameters参数类经build_lazy_click_command动态生成 click 选项，因此新增模型类型（如 vLLM 后端）时无需改动 CLI 注册代码。

十一、命令全景与帮助体系

dbgpt --help展示的一级命令结构（文档快照）：

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.

dbgpt start子命令（集群部署直接相关的四个）：

Usage: dbgpt start [OPTIONS] COMMAND [ARGS]... Start specific server. Commands: apiserver Start apiserver controller Start model controller webserver Start webserver(dbgpt_server.py) worker Start model worker

dbgpt model子命令族：

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 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 stop controller/dbgpt stop worker [--port <p>]/dbgpt stop apiserver；此外 cli_scripts.py 中注册的dbgpt stop all会遍历stop_all_func_list，依次调用_stop_all_model_server与_stop_all_dbgpt_server，一键清理 Worker、Controller、APIServer 与 Webserver 全部进程（见 _stop_all_model_server）。

十二、部署检查清单（TL;DR）

按顺序执行并逐项验证，即可完成一次标准的 DB-GPT 模型集群部署：

1. pip install -e ".[default]"安装并确认dbgpt --version可用；
2. dbgpt start controller启动 Controller，确认监听8000端口；
3. 逐台机器执行dbgpt start worker ...，依次拉起 LLM（如 8001/8002）、Embedding（8003）、Rerank（8004）Worker，跨机时注意--controller_addr与--worker_register_host；
4. dbgpt model list核对每个实例的Host/Port/Healthy，心跳时间应持续刷新；
5. 设置LLM_MODEL与MODEL_SERVER=http://<controller_ip>:8000后启动 Webserver（--light模式，embedding 走集群时加--remote_embedding）；
6. 需要快速验证模型连通性时，用dbgpt model chat -m <name>直接命令行对话；
7. 维护期用dbgpt model stop/restart管理实例，dbgpt stop worker --port <p>或dbgpt stop all做进程回收。

配套源码阅读路径，方便深入：

• CLI 命令注册与组装：packages/dbgpt-core/src/dbgpt/cli/cli_scripts.py
• 模型集群客户端命令实现：packages/dbgpt-core/src/dbgpt/model/cli.py
• Controller / Registry / Worker 核心包：packages/dbgpt-core/src/dbgpt/model/cluster
• Webserver 启动命令：packages/dbgpt-app/src/dbgpt_app/_cli.py

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT