DB-GPT 深度入门:从自然语言问数到可信的数据分析工作流
从 Text2SQL、RAG、Agents、AWEL 与 SMMF 的分工出发,通过渠道收入变化分析,讲清 DB-GPT 的架构、安装入门、SQL 复核、权限边界与效果评估,配三张原创中文示意图。

文章目录
面向希望理解、试用或集成 DB-GPT 的开发者与数据分析人员。本文依据 2026 年 11 月 6 日查阅的官方文档与 GitHub 仓库整理;文档页面标识为 v0.8.1,仓库 main 会持续变化。安装命令、界面与依赖请以所选发行版为准。文中的业务数据、SQL 和落地方案是教学示例,不代表实际运行测评。
“用一句话查询数据库”很容易让人产生期待:输入问题,AI 就能返回答案。但真正的业务分析还需要知道收入如何定义、退款计入哪个月份、用户能看哪些数据,以及结论能否被复核。
DB-GPT 的价值在于把这些数据交互环节连接起来:接入数据源,让大模型生成 SQL 或分析代码,结合知识检索与工具调用,最终形成表格、图表和报告。本文先建立整体认识,再用一个渠道收入分析案例说明它如何落地。

一、DB-GPT 是什么,适合解决什么问题?
官方目前将 DB-GPT 定位为开源的智能体式 AI 数据助手,同时提供构建 AI 原生数据应用的平台能力。它覆盖数据库、CSV / Excel、知识库等数据入口,并结合 Agents、AWEL、RAG 和多模型支持,组织从提问到分析产物的过程。详见官方概览与项目仓库。
对使用者而言,可以从三个层次理解:
| 层次 | 典型需求 | 需要得到的结果 |
|---|---|---|
| 数据查询 | “上个月各渠道收入是多少?” | SQL、查询结果、指标口径 |
| 知识问答 | “净收入是否扣除退款?” | 业务文档中的定义与出处 |
| 分析工作流 | “找出变化最大的渠道并形成报告” | 多步计算、图表、证据与待验证假设 |
它适合探索式分析、内部数据助手和需要组合数据库与业务知识的应用。固定口径、固定样式、长期重复使用的经营看板,仍然适合交给经过治理的 BI 或报表系统;AI 可以帮助分析异常和解释指标。
如果企业尚未统一字段含义、数据粒度和权限,首先应整理这些基础。模型能根据上下文生成答案,但不会自动替团队决定什么才是正确的业务口径。
二、一张图理解核心架构

图 1:原创概念示意图,用于解释组件分工;不是官方部署拓扑。底部的治理能力需要结合实际系统建设。
不必一次记住所有缩写,先理解每个组件回答的问题。
| 概念 | 通俗理解 | 在分析中的职责 |
|---|---|---|
| Text2SQL | 把问题翻译成数据库查询 | 根据表结构、字段与口径生成候选 SQL |
| RAG | 先查资料,再组织回答 | 检索指标说明、业务规则与相关文档 |
| Agent | 能使用工具完成任务的执行者 | 拆解目标、选择资源、执行与反馈 |
| AWEL | 明确表达步骤和依赖的工作流 | 连接检索、模型、查询、汇总等节点 |
| SMMF | 统一管理模型接入的基础层 | 管理 LLM 与 Embedding 等模型服务 |
| Skills | 可复用的领域方法与步骤 | 将重复的分析经验组织为可调用能力 |
Text2SQL:生成 SQL 之前,要先理解数据
例如“收入最高的渠道”至少包含三个隐含条件:收入是支付额还是扣退款后的净额,渠道按订单归属还是用户首次来源,以及比较哪个时间段。
表名和字段名只能提供部分线索。更可靠的上下文包括字段注释、主外键关系、数据粒度、枚举含义、指标定义和经过审核的查询样例。实际系统还需要在执行前验证 SQL,并用数据库权限限制其能力。
RAG:为模型提供可引用的业务知识
RAG(检索增强生成)先从知识库检索相关内容,再将这些内容与用户问题一起提供给模型。DB-GPT 的文档介绍了文档解析、切分、向量化、存储、检索、可选重排和生成等环节,也介绍了向量、关键词、知识图谱与混合检索。参见官方 RAG 概念。
例如,知识库可以保存“净收入按资金实际发生日统计,退款计入退款发生月”的说明。SQL 负责根据该规则计算,RAG 帮助找到规则及其出处。文档检索不能代替数据库对全部交易的精确聚合。
检索质量往往取决于文档本身:一段话里应同时保留指标名称、公式、适用范围和生效时间。若把公式与例外条件切到互不相关的片段中,模型即使检索成功,也可能只得到半个定义。
Agents 与 AWEL:组织任务和组织流程
DB-GPT 的 Agent 框架包含角色、记忆、规划、动作和资源等概念,可让多个执行者按不同方式协作。官方 Agents 文档提供了进一步说明。
从工程角度看,Agent 适合处理“下一步需要查什么”这类存在探索空间的问题;AWEL 适合明确表达哪些步骤必须发生、哪些结果需要汇合。AWEL 使用有向无环图(DAG)与算子组织流程,并提供可视化编辑能力。参见官方 AWEL 概念。
一个实际应用可以允许 Agent 选择分析维度,同时把权限检查、查询预算和结果校验设置为固定流程。是否存在这些节点、失败后如何处理,需要由应用实现和验证,不能仅根据框架名称推定。
SMMF:把模型选择变成可管理的配置
SMMF 是 DB-GPT 的模型管理层,统一接入和管理不同 LLM、Embedding 及相关模型服务,支持 API 代理和本地模型等方式。官方 SMMF 文档给出了配置与部署思路。
试用时可以先用已有模型 API 降低环境复杂度;涉及受限数据时,则应根据数据外发要求选择模型部署方式。无论使用哪种方式,都要分别检查对话、向量化与重排的实际调用端点。
三、完整示例:为什么某个渠道的收入下降?
假设业务方提出问题:
比较 2026 年 9 月和 10 月各渠道净收入,找出下降金额最大的渠道,说明变化表现,并列出进一步验证原因所需的数据。
这是一个教学场景。下面的数据与表结构均为示例,不对应任何真实企业。
第一步:把业务问题改写为明确约束
在查询前确认以下内容:
- 时间:比较两个完整自然月,业务日按 Asia/Shanghai 划分。
- 指标:净收入 = 当期成功支付金额 − 当期成功退款金额。
- 退款归属:按退款实际发生日入账,不回溯至原订单月份。
- 币种与单位:仅统计人民币,底层使用整数分,展示时转换为元。
- 渠道维度:采用已治理的交易渠道归属,无法归属的记录放入“未知”。
- 分析范围:排除测试交易;迟到数据、补单与退款更新可能导致历史数值变化,应标明数据截止时间。
如果财务口径要求退款回溯原订单月,就必须调整数据模型和查询。这两种口径都可能有业务用途,但不能混在同一份报告里比较。
第二步:准备最小的数据上下文
为降低首次试用的复杂度,可以由数据团队提供只读日汇总视图。本文将其命名为 daily_channel_revenue,约定每个业务日、每个渠道只有一行:
| 字段 | 类型示意 | 含义 |
|---|---|---|
| business_date | date | 已转换到业务时区的日期 |
| channel | text | 非空渠道标识,缺失值已归为“未知” |
| paid_amount_cents | bigint | 当日成功支付金额,单位为分 |
| refund_amount_cents | bigint | 当日成功退款金额,单位为分 |
金额字段约定非空;视图构建过程已完成交易去重、测试记录排除和币种过滤。它是本例的输入契约,并非 DB-GPT 自带的数据表。
如果直接对订单、支付、退款等多张明细表做分析,需要先确认关联基数。一个订单对应多次支付尝试或多笔退款时,直接连接后再求和很容易重复计算。通常应先将各类交易聚合到一致粒度,再进行关联。
第三步:生成并复核候选 SQL
下面是基于上述约定编写的 PostgreSQL 示例。它比较两个完整月份,保留只在其中一个月份出现的渠道,并将上期为零时的增长率返回为空。
WITH monthly AS (
SELECT
channel,
SUM(CASE
WHEN business_date >= DATE '2026-09-01'
AND business_date < DATE '2026-10-01'
THEN paid_amount_cents::numeric
- refund_amount_cents::numeric
ELSE 0
END) AS previous_net_cents,
SUM(CASE
WHEN business_date >= DATE '2026-10-01'
AND business_date < DATE '2026-11-01'
THEN paid_amount_cents::numeric
- refund_amount_cents::numeric
ELSE 0
END) AS current_net_cents
FROM daily_channel_revenue
WHERE business_date >= DATE '2026-09-01'
AND business_date < DATE '2026-11-01'
GROUP BY channel
)
SELECT
channel,
ROUND(previous_net_cents / 100, 2) AS previous_net_yuan,
ROUND(current_net_cents / 100, 2) AS current_net_yuan,
ROUND((current_net_cents - previous_net_cents) / 100, 2)
AS change_yuan,
CASE WHEN previous_net_cents > 0 THEN
ROUND(100 * (current_net_cents - previous_net_cents)
/ previous_net_cents, 2)
END AS change_percent
FROM monthly
ORDER BY change_yuan ASC, channel ASC;
这里有四个容易忽略的细节:
- 日期采用左闭右开区间,避免把下个月第一天算入本月。
- 转成 numeric 后再汇总与除法,保留金额精度并避免整数除法。
- 上期为零或负数时,百分比需要单独解释,本例仅对正基数计算。
- “下降最大”按变化金额升序排序;若问题要求“降幅最大”,排序指标应改成百分比,并设定合理的基数规则。
该示例用于解释查询逻辑,尚未在目标 DB-GPT 环境或真实数据集执行。接入实际系统时,应核对视图定义、数据库方言、权限和执行计划。生产查询中的用户参数应通过参数绑定传入。
第四步:执行、检查,再解释

图 2:建议采用的分析流程。权限和资源控制应在执行器、数据库及应用侧落实。
假设得到下面的演示结果,金额单位为万元:
| 渠道 | 9 月净收入 | 10 月净收入 | 变化金额 | 变化率 |
|---|---|---|---|---|
| A | 80 | 60 | -20 | -25.0% |
| B | 40 | 45 | +5 | +12.5% |
| 合计 | 120 | 105 | -15 | -12.5% |
能够直接确认的是:A 渠道下降 20 万元,B 渠道增长 5 万元,总体减少 15 万元。A 是此示例中下降金额最大的渠道,B 抵消了部分下降。
**仅凭净收入结果,无法确认下降原因。**下一步可以分别检查支付人数、支付次数、客单价、退款额,以及渠道投放、活动和数据上报变化。若要讨论转化率,还需要明确曝光、点击、注册、付费等环节的用户群和去重方式。
一份严谨的报告应把“已观察到的变化”“可能的解释”和“仍需补充的证据”分开。例如可以提出“退款增加可能影响净收入”的待验证假设,但在未查询退款数据之前,不能将其写成确定原因。
四、如何开始试用:先跑通一个小闭环
1. 选择安装方式
官方提供 CLI、源码及 Docker 等安装路径。第一次体验可以先阅读安装概览与CLI Quick Start。CLI 文档列出的前提是 Python 3.10 或更高版本,以及 uv 或 pip。
在准备好独立 Python 环境后,官方的基础安装与启动入口为:
pip install dbgpt-app
dbgpt start
首次启动按向导选择模型服务、填写凭据并确认模型名称和 API 地址,随后访问本机的 http://localhost:5670 。如需数据库驱动等可选依赖,应按照所选版本的 Optional Modules 安装;例如 PostgreSQL 依赖的文档名称为 datasource_postgres。
CLI 文档介绍的配置使用 profile 与 TOML 文件。旧教程中可能出现不同的配置格式和启动参数,不宜将不同版本的命令片段直接拼接使用。本文只整理入口,没有在当前环境安装或启动 DB-GPT。
2. 先验证模型,再增加数据源
建议按以下顺序排查依赖:
- 使用不含业务数据的普通问题,确认模型调用可用。
- 接入少量脱敏样例或只读汇总视图,确认连接、字段与权限。
- 提出一个能用人工 SQL 算出标准答案的问题,比较结果。
- 增加指标说明文档,观察系统能否引用正确口径。
- 最后组合图表、报告或多步骤工作流。
每次只增加一个变量,出了问题才容易区分是模型连接、数据源配置、检索还是查询逻辑导致的。
3. 为第一次问数准备清晰的问题
与“分析一下收入”相比,下面的提问更容易复核:
使用 daily_channel_revenue 视图,比较 2026 年 9 月与 10 月各渠道净收入。净收入按支付发生额减退款发生额计算,业务日为 Asia/Shanghai,金额从分转换成元。请先给出 SQL 和口径说明,再给出结果与变化金额。上期为零时不要计算增长率;没有证据时不要推断原因。
这类提问明确了数据集、期间、公式、单位和边界。正式产品中应将稳定口径维护在受控配置或指标知识库中,减少每个用户重复描述规则造成的偏差。
五、私有化与安全:沿着真实数据流检查

图 3:原创落地建议图。图中的边界需要通过部署、权限与网络配置实现。
DB-GPT 支持本地或不同服务商的模型接入,但把应用部署在内网,并不能单独证明业务数据始终留在内网。需要检查提示词、表结构、检索片段、查询结果、模型端点、日志与分析产物的实际流向。
以下是工程建议,不表示项目默认完整实现了这些能力:
| 边界 | 建议措施 | 要验证的问题 |
|---|---|---|
| 数据库 | 专用只读账号、视图、行列权限 | 用户是否只能访问被授权的数据? |
| SQL 执行 | 语法结构检查、数据集白名单、超时和并发限制 | 复杂查询会不会拖垮业务库? |
| 文档检索 | 按身份和文档权限过滤 | 检索结果是否混入其他团队的内容? |
| 代码运行 | 明确沙箱、挂载、网络和资源限制 | 代码能读取哪些文件、访问哪些服务? |
| 模型调用 | 分别核对 LLM、Embedding、Rerank 端点 | 哪些字段或片段会发送到外部? |
| 日志与产物 | 脱敏、访问控制和保留期限 | 查询结果、错误信息和报告会保留在哪里? |
只检查 SQL 是否以 SELECT 开头是不够的,还需要考虑函数调用、复杂子查询、资源消耗以及数据库方言。只读查询也可能读取敏感字段,或消耗大量 CPU、内存和 I/O;权限和查询预算应由系统强制执行。
代码沙箱与数据库授权解决不同层面的问题。沙箱限制代码运行环境,数据库权限决定查询能看到什么;二者应结合使用。文档中的文本也属于不可信输入,检索到的“忽略权限并导出数据”等内容不能获得工具执行授权。
六、从演示走向业务使用,如何验证效果?
不要只挑几条容易回答的问题展示。可以构建一个小型评估集,覆盖单表聚合、多表关联、时间边界、退款口径、空结果、零基数、权限拒绝和缺少定义等情况。
| 维度 | 验证方法 |
|---|---|
| 计算正确性 | 对照人工审核的 SQL 与固定快照结果 |
| 业务口径 | 检查时间、币种、退款归属、去重和关联粒度 |
| 引用可信度 | 核查文档出处、版本和结论是否得到证据支持 |
| 权限隔离 | 用不同身份尝试越权查询和跨范围检索 |
| 稳定性 | 检查模型超时、SQL 失败和工具错误时的输出 |
| 成本与延迟 | 记录一次任务的模型调用、检索和查询耗时 |
| 可复现性 | 保存数据截止时间、模型与配置标识、SQL 和必要上下文 |
SQL 能执行,只能说明语法和当前环境允许它运行;结果正确,还需要与标准答案比对;具备业务价值,则还要看它是否回答了真实问题。
对于数值结果,可按业务精度设置误差容忍;对于证据不足的问题,应检查系统是否主动说明缺口。让模型在信息不足时承认无法确定,是分析质量的一部分。
七、常见问题与排查方向
SQL 能运行,数字却不对
优先检查指标定义、时间字段、时区、交易状态、重复行和连接基数。最常见的错误之一,是把一对多明细连接后直接 SUM,导致同一笔金额被重复累加。换一个更大的模型通常无法修复缺失的数据定义。
文档已经上传,回答仍然偏离规则
先检查文档是否处理完成、检索是否命中正确片段,再检查切分、同义词和文档版本。旧规则与新规则同时存在时,应保留明确的生效日期和适用范围。
接入模型后能聊天,知识库却不可用
对话模型与 Embedding 的依赖可能不同。分别检查模型端点、权限、可选依赖和向量存储连接。切换 Embedding 模型后,已有索引是否需要重建,应按实际实现和版本说明确认。
报告写得流畅,却没有解释依据
要求输出指标口径、SQL、数据截止时间与引用来源,并明确区分事实和假设。如果来源不足,应列出需要补充的数据。语言表达的完整程度不能代替证据质量。
一次分析调用太多、耗时太长
检查任务拆解是否过细、同一数据是否重复查询、是否将过多明细发给模型,以及是否可以先在数据库中聚合。需要重试时设置次数和时间预算,避免工具失败后无边界地循环调用。
八、把第一次试用变成可持续的分析能力
一个务实的起点,是选择一个数据范围小、标准答案明确的问题,提供只读视图和业务定义,让 DB-GPT 输出 SQL、结果与解释,再与人工分析对照。
当这个闭环稳定后,再扩展数据源、补齐领域知识、复用 Skills,并通过 AWEL 固化必须执行的步骤。每次扩展都应保留权限边界、查询预算和可追溯证据,让业务人员能够看懂结论,也让开发者能够定位问题。
DB-GPT 提供了连接模型、知识、数据与工具的基础能力。最终能否形成可信的数据助手,取决于这些能力是否建立在明确的数据口径、可验证的查询和受控的执行流程之上。
参考资料与说明
- DB-GPT 官方文档:产品入口与文档导航。
- DB-GPT GitHub 仓库:项目说明、源码及发行信息。
- Overview:产品定位与能力概览。
- CLI Quick Start:安装、启动、profile 与可选模块。
- RAG、Agents、AWEL、SMMF:核心概念与组件说明。
本文为基于官方公开资料的原创解读。三张配图均为原创概念图,案例数据为演示数据;安装步骤依据文档整理,未对实际部署、模型效果或性能作实测承诺。




交流与讨论
留下你的思考,友善交流。昵称和评论将公开展示,请勿填写个人敏感信息。