[DataAgent] DB-GPT 使用指南

0 序

DB-GPT 就像一个「会说话、会动手的数据助手/数据分析师」：你只需用日常语言提问，它就能自动将问题转化为 SQL 语句查询数据库，甚至生成数据报表、解读分析结果。无论是企业的数据分析师、软件开发者，还是需要处理本地数据的普通用户，都能通过 DBGPT 大幅提升数据分析与数据处理的效率。

  • DB-GPT 是一个开源的、AI原生的【数据应用开发框架】(AI Native Data App Development framework with AWEL(Agentic Workflow Expression Language) and Agents)。

目的是构建大模型领域的基础设施，通过开发多模型管理(SMMF)、Text2SQL效果优化、RAG框架以及优化、Multi-Agents框架协作、AWEL(智能体工作流编排)等多种技术能力，让围绕数据库/数据文件构建大模型应用更简单，更方便。

1 安装部署篇

1.1 源码部署方式

直接通过源码部署 DB-GPT。这是最灵活的方式，适合开发、调试以及自定义集成场景。

  • 硬件要求
模式 CPU × 内存 GPU 说明
API proxy 4C × 8 GB 无 代理模式不使用本地 GPU
Local model 8C × 32 GB ≥ 24 GB VRAM 需要支持 CUDA 的 NVIDIA GPU

step1 克隆/下载项目源码

git clone https://github.com/eosphoros-ai/DB-GPT.git
cd DB-GPT

step2 安装 python 的依赖包与环境管理工具: uv

  • 方式1: PyPI (pipx) 方式（官方推荐）
python -m pip install --upgrade pip
python -m pip install --upgrade pipx
python -m pipx ensurepath
pipx install uv --global
  • 方式2: 全局安装 uv
//笔者是 Windows Powershell 环境下做的全局安装:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • 验证方法
uv --version
where.exe uv

step3 安装Python依赖

  • OpenAI (proxy) 方式 （笔者的选择）
uv sync --all-packages \
  --extra "base" \
  --extra "proxy_openai" \
  --extra "rag" \
  --extra "storage_chromadb" \
  --extra "dbgpts"
  • DeepSeek (proxy) 方式

DeepSeek 使用 OpenAI 兼容代理，因此所需 extras 与 OpenAI 相同。

uv sync --all-packages \
  --extra "base" \
  --extra "proxy_openai" \
  --extra "rag" \
  --extra "storage_chromadb" \
  --extra "dbgpts"
  • Ollama (local) 方式
uv sync --all-packages \
  --extra "base" \
  --extra "proxy_ollama" \
  --extra "rag" \
  --extra "storage_chromadb" \
  --extra "dbgpts"
  • Local GPU (HuggingFace) 方式
uv sync --all-packages \
  --extra "base" \
  --extra "cuda121" \
  --extra "hf" \
  --extra "rag" \
  --extra "storage_chromadb" \
  --extra "quant_bnb" \
  --extra "dbgpts"

step4 配置模型 (如:硅基流动)

编辑与你所选 provider 对应的 TOML 配置文件。详情请参考 Model Providers。
笔者选择的 Model Provider： 硅基流动的模型配置 - dbgpt.cn 【推荐阅读】

科普博客: 硅基流动(SiliconFlow) : AI大模型时代的基础设施(Model API as Service) - 博客园/千千寰宇
配置 DB-GPT 使用 SiliconFlow 托管模型 API。SiliconFlow 提供统一 API，可接入多种开源模型，并且服务位于国内环境中。

  • 前置条件
  • 已安装带 proxy_openai 扩展的 DB-GPT
  • 一个可用的 SiliconFlow API key

注册/访问入口: https://account.siliconflow.cn - 硅基流动/SiliconFlow
科普博客: 硅基流动(SiliconFlow) : AI大模型时代的基础设施(Model API as Service) - 博客园/千千寰宇

  • 安装依赖

如果 step3 已经做过了，则忽略即可

uv sync --all-packages \
  --extra "base" \
  --extra "proxy_openai" \
  --extra "rag" \
  --extra "storage_chromadb" \
  --extra "dbgpts"
  • 配置方式

编辑源码目录下 configs/dbgpt-proxy-siliconflow.toml 文件：

# Model Configurations
[models]
[[models.llms]]
#name = "Qwen/Qwen2.5-Coder-32B-Instruct"
name = "${env:LLM_MODEL_NAME:-deepseek-ai/DeepSeek-V4-Flash}"
provider = "proxy/siliconflow"
#api_key = "${env:SILICONFLOW_API_KEY}"
api_key = "${env:SILICONFLOW_API_KEY:-sk-xxxxxxxxx}"
api_base = "https://api.siliconflow.cn/v1"

[[models.embeddings]]
#name = "BAAI/bge-large-zh-v1.5"
name="Qwen/Qwen3-Embedding-4B"
#provider = "proxy/openai"
provider = "proxy/siliconflow"
api_url = "https://api.siliconflow.cn/v1/embeddings"
#api_key = "${env:SILICONFLOW_API_KEY}"
api_key = "${env:SILICONFLOW_API_KEY:-sk-xxxxxxxxx}"

[[models.rerankers]]
#name = "BAAI/bge-reranker-v2-m3"
name = "Qwen/Qwen3-Reranker-4B"
provider = "proxy/siliconflow"
#api_key = "${env:SILICONFLOW_API_KEY}"
api_key = "${env:SILICONFLOW_API_KEY:-sk-xxxxxxxxx}"

建议使用环境变量，例如：export SILICONFLOW_API_KEY="your-siliconflow-api-key"

image

  • 配置解释：可用的LLM模型 （仅供参考，笔者未完全按照这个表格的来）

SiliconFlow 托管了很多开源模型，常见可选模型包括：

模型 配置名 说明
Qwen2.5-Coder-32B Qwen/Qwen2.5-Coder-32B-Instruct 偏代码场景
Qwen2.5-72B Qwen/Qwen2.5-72B-Instruct 通用用途
DeepSeek-V3 deepseek-ai/DeepSeek-V3 推理能力强
GLM-4-9B THUDM/glm-4-9b-chat 中英文兼顾

最新模型列表和价格请参考 SiliconFlow 官方页面。

  • 特殊特性

SiliconFlow 配置还支持 reranker，用于增强 RAG 检索效果：

[[models.rerankers]]
name = "BAAI/bge-reranker-v2-m3"
provider = "proxy/siliconflow"
api_key = "${env:SILICONFLOW_API_KEY}"

step5 启动服务

uv run dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml
或: uv run --no-sync dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml

若操作系统有网络代理时，需让 db-gpt 工程忽略此代理问题：（网络代理问题是一个坑）

  • 方法1 一次性跳过代理（当前终端，最直接、亲测）
$env:NO_PROXY="127.0.0.1,localhost"; uv run dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml
$env:NO_PROXY="127.0.0.1,localhost,192.168.31.xx"; uv run --no-sync dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml
$env:NO_PROXY="127.0.0.1,localhost,192.168.31.xx"; uv run dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml
$env:NO_PROXY="127.0.0.1,localhost,192.168.31.xx"; uv run --no-sync dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml

python 的 httpx 认 NO_PROXY：命中豁免列表的目标直连、不走代理；外部网络的请求（SiliconFlow API）仍走 7890(操作系统配置的代理端口) 代理，互不影响。

  • 方法2 持久化（新终端都生效，推荐）
setx NO_PROXY "127.0.0.1,localhost,192.168.31.xx"

写入用户级环境变量，新开终端生效（当前终端需手动设一次）。同时查一下 HTTP_PROXY 是谁写入的：

[Environment]::GetEnvironmentVariable("HTTP_PROXY","User")   # 用户级
Get-Content $PROFILE | Select-String -Pattern "proxy"        # PowerShell 启动脚本

如果是代理软件（如 *** 系）注入的用户级变量，去软件设置里关掉 "设置系统代理 / 写入环境变量" 更干净；如果写在 $PROFILE 里，删掉那一行即根治。

  • 方法3 启动脚本（一劳永逸，适合频繁启动）

保存为 F:\Codes-Minor\Github\DB-GPT\start-dbgpt.ps1：

# 屏蔽代理环境变量，豁免本地回环
Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY, Env:http_proxy, Env:https_proxy -ErrorAction SilentlyContinue
$env:NO_PROXY = "127.0.0.1,localhost,192.168.31.xx"
Set-Location $PSScriptRoot
uv run --no-sync dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml

以后直接 .\start-dbgpt.ps1 即可。

方法4 修改源代码 （不建议）
改 DB-GPT 源码（packages/dbgpt-core/src/dbgpt/util/api_utils.py 里 httpx.AsyncClient() 改成 trust_env=False 也能根治）。

参数解释（可跳过）

  • uv run 参数
  • uv 是 Rust 写的现代 Python 包/项目管理工具（同类：poetry、pipenv）。uv run <命令> 的核心作用：
  • 自动定位项目（向上找 pyproject.toml / uv.lock）；
  • 找到（必要时创建）项目的虚拟环境 .venv；
  • 把命令放进项目虚拟环境里执行——保证用的是项目依赖的那套 python 和包，而不是系统 Python。
    对笔者这条命令：uv run dbgpt ... 实际运行的是 F:\Codes-Minor\Github\DB-GPT\.venv 里的 dbgpt 命令和依赖，与 conda 的 (python-3.13) 虚拟环境无关。
  • --no-sync 参数
  • 作用：跳过"运行前同步依赖"这一步。
  • uv run 默认在执行命令前会先做一次 project sync：对照 pyproject.toml文件 + uv.lock文件，检查
    Python虚拟环境的依赖是否齐全、版本是否一致，缺了就现场安装/更新。
项 不加（默认） 加 --no-sync
启动前 检查并同步依赖（可能联网安装） 直接用现有 .venv
启动速度 慢；依赖变更或网络慢时可能卡数分钟无输出（你之前就踩过，约 3 分钟） 快，秒起
依赖缺失时 自动补装 直接报 ImportError/命令找不到
适用 首次克隆、改过依赖、要保证环境一致 开发调试、依赖已就绪的日常启动

日常启动加 --no-sync 省时间；改了 pyproject.toml 或换了新环境时去掉它做一次同步。

  • dbgpt start webserver 命令参数
  • dbgpt：DB-GPT 项目的 CLI 入口命令，由 packages/dbgpt-core/pyproject.toml 的 [project.scripts] 注册（指向 packages/dbgpt-app/src/dbgpt_app/_cli.py），所以装好依赖后任何位置都有 dbgpt 命令。

image

DB-GPT\packages\dbgpt-app\src\dbgpt_app_cli.py

image

DB-GPT\packages\dbgpt-app\src\dbgpt_app\dbgpt_server.py

  • start webserver：子命令组，启动 DB-GPT 的 Web 服务端，一条命令拉起整条链：
    • 模型集群 worker：LLM（DeepSeek-V4-Flash）、embedding（Qwen3-Embedding-4B）、reranker（Qwen3-Reranker-4B），经代理调用 SiliconFlow API；
    • controller：worker 注册中心（127.0.0.1:5670 的 /api/controller/models，就是之前 502 的那条注册链路）；
    • Web 服务：FastAPI/uvicorn 监听 0.0.0.0:5670（Web UI + /api/health + 推理接口）；
    • 周边：SQLite（observability / 知识库）、配置加载。
  • 命令依据（源码路径，已查证）：
    • CLI 入口：packages/dbgpt-app/src/dbgpt_app/_cli.py（start/stop 命令组，stop webserver --port 5670 也在其中）；
    • 实际启动：packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py 的 run_webserver → run_uvicorn；
    • 配置来源：--config configs/dbgpt-proxy-siliconflow.toml（[service.web] 端口、[service.model.worker]、LLM 代理与 api_base 等）。

对照关系：dbgpt start webserver 启动整条服务链，dbgpt stop webserver --port 5670 优雅停止；如需确认当前残留进程，可 netstat -ano | findstr :5670 查看。

  • 项目根目录的 pyproject.toml（name = dbgpt-mono）：
[tool.uv.workspace]                    # L31-40：声明成员目录
members = ["packages/dbgpt-app", ..., "packages/dbgpt-core", ...]

[tool.uv.sources]                      # L15-23：依赖源映射
dbgpt = { workspace = true }           # 依赖中的 dbgpt 用本地成员包，不从 PyPI 装
  • packages/dbgpt-core/pyproject.toml（name = dbgpt）：
[project.scripts]                      # L206-207
dbgpt = "dbgpt.cli.cli_scripts:main"

image

uv 的 workspace 机制把所有子包合并成同一个项目来解析和安装，scripts 是每个子包自己声明、由安装阶段消费的。完整流程如下：

  1. 识别 workspace：你执行 uv run 时，uv 从当前目录向上找到根 pyproject.toml，读取 [tool.uv.workspace].members，把列出的 8 个子包目录认作同一工作区的成员；
  2. 解析依赖图：uv 读取根包 + 全部成员包各自的 [project] 依赖声明，合并成一个统一的依赖解析单元；[tool.uv.sources] 中 { workspace = true } 保证解析时 "dbgpt、dbgpt-app…" 指向本地源码而非 PyPI；
  3. 生成 / 校验锁文件：解析结果写入 uv.lock（整个 workspace 一份），uv run 默认按它做 sync（这正是 --no-sync 跳过的步骤）；
  4. 安装、并生成命令：所有成员包被装进同一个 .venv（本地路径方式）。安装 dbgpt-core 时，pip/uv 消费它的 [project.scripts]，在 .venv\Scripts\ 生成 dbgpt.exe—— 内容等价于 import dbgpt.cli.cli_scripts; sys.exit(main())；
  5. 命令命中：uv run dbgpt ... 把 .venv\Scripts 放进 PATH，dbgpt 解析为 .venv\Scripts\dbgpt.exe，执行 dbgpt.cli.cli_scripts:main()；
  6. 子命令分发：main() 解析 start webserver → 调用 dbgpt-app 包的启动逻辑（dbgpt_app/_cli.py、dbgpt_server.py 的 run_webserver → run_uvicorn）—— 而 dbgpt-app 也是同 workspace 成员、同 venv，所以 import 得到。

项目根目录的 pyproject.toml 的作用是声明 "这是一个 workspace，成员有哪些、依赖源怎么映射"；[project.scripts] 则始终属于声明它的子包，由 uv 在安装该子包到 .venv 时自动生成可执行入口。根目录文件本身不 "读取"scripts—— 两者通过 "workspace 成员 → 统一安装 → 生成 console script" 这条链连接。

step6 访问 DB-GPT

image

2 主流程体验篇

Step1 配置模型

  • 设置-模型管理-添加模型

LLM 模型、嵌入模式、重排序模型（具体的配置样例值，可参照 安装部署的模型配置章节。）

image

step2 添加数据源

添加 MYSQL 数据源为例:

image

  • 这里我提供了3张表: 学生 --(选择)--> 课程
  • 学生表

image

  • 课程表
    image
  • 选课关系表

image

step3 创建数据分析任务，享用数据分析助手

  • CASE 简单任务: 涉及到查询单张表

image

  • CASE 进阶任务: 涉及到关联2张表、并多个过滤条件

image

  • CASE 复杂任务: 涉及Plan多个子任务、并对子任务的结果聚合

image
image

3 功能模块篇

任务管理 & 探索广场

  • 探索广场

image

  • 新建任务 / 任务列表

image

技能/Skill

image

image

数据源

  • 支持的数据库类型的数据源

Spark / Hive / HBase / Clickhouse / Apache Doris / StarRocks / MaxCompute / ...
DuckDB / SQLLite / Access / MSSQL / MySQL / PostgreSQL / Oracle / MongoDB / Redis / Cassandra
TuGraph / Neo4j
Vertica / OpenGuass / GaussDB / OceanBase
Space / Omc / Couchbase

image

  • SQLLite 数据源（安装时内置的样例数据源）

image

知识库

  • 创建知识库
    image

  • 配置参数
    image

召回分数 = 设置相似向量检索的阈值分数
模型 = 用于创建文本或其他数据的矢量表示的模型
分片大小 = 处理中使用的数据块的大小
  • 上传文件
    image

image

设置

模型管理

image

应用程序

  • 应用程序列表

image

创建应用

image

  • 工作模式: 多智能体自动规划模式 / 任务流编排模式 / 单一智能体模式 / 原生应用模式

样例应用: Chat Data

  • Chat Data
  • tag: native_app / chat_with_db_execute
  • description: Have a conversation with your private data through natural language

image

image

样例: Chat Dashboard

  • URL
  • 配置应用
    image

image

样例应用: Chat DB

  • 编辑应用

image

  • 对话/使用
    image

AWEL工作流

使用 AWEL Flow 编辑器以可视化方式构建 AI 工作流。它提供拖拽式界面，无需编写代码即可组合 LLM 流水线。

  • URL

image

  • 支持：模板、导入、保存 3种编辑操作

image

连接器管理(MCP + 外部系统)

  • 支持提供MCP机制连接的外部系统: 自定义的 MCP Server / 飞书 / 语雀 / Github / 钉钉 / Notion / DeepWiki / Tavily / Linear / ...

image

定时任务

image

模型评测

image

可观测

image

Z FAQ for DB-GPT

Y 推荐文献

  • DB-GPT
  • SiliconFlow/硅基流动

X 参考文献

posted @ 2026-09-09 14:12  数据知音  阅读(32)  评论(0)    收藏  举报