企业官网建设流程全解析

简介：DB-GPT数据库大语言模型资源包聚焦于自然语言与数据库查询的结合，面向希望降低SQL使用门槛的开发者、数据分析师及AI应用研究者。资源完整收录了模型源码、预训练与微调相关脚本、部署配置和说明文档，包含Python实现、SQL示例、Dockerfile、Shell脚本以及Markdown分析笔记，能够支撑从环境搭建、数据预处理、模型训练到自然语言转SQL测试的完整流程。压缩包共441个文件，约14.97MB，其中252个Python文件为核心代码，另有40个JavaScript文件、36个Markdown文档、8个SQL脚本及多种格式的配置与辅助材料，目录结构清晰便于按模块学习。目前已有1576人学习，内容覆盖多表连接、子查询、聚合函数等复杂查询场景，可直接用于理解DB-GPT的模型架构与调优思路，也可作为二次开发或课程设计的参考资料。

1. 为什么 DB-GPT 值得你花一个下午重新认识

DB-GPT 这个名字看起来像"数据库+大模型的又一个套壳项目"，但真正把关系型数据库、向量数据库和大语言模型串成一条可用链路之后，你会发现它解决的是最实际的问题：业务方不懂 SQL，懂 SQL 的人又没时间天天陪业务方改报表口径。DB-GPT 要做的事情，是让你用自然语言直接问数据库，比如"上个月华东区退货率最高的三个品类是什么"，它负责把这句话翻译成 SQL、执行、再把结果用自然语言答回来。适合谁？手里有真实业务数据、想给团队交付一个"内网版 ChatBI"但又不想从零写 Agent 编排的人。它不是一个对话 Demo，而是一套可以接私有数据、可以调模型、可以走 API 被业务系统复用的半成品框架——这意味着你能改，也能扩展。

我最早接触它是因为某次接了一个"用大模型做经营分析"的模拟项目，当时团队里没有一个能稳定生成多表 JOIN 的 Text-to-SQL 方案。后来把 DB-GPT 部署到内网，接上测试库和开源模型，从装环境到出第一个可用问答页面，大概用了一个下午。这篇文章就按这条落地的路径来写：先讲清楚它的架构思路，再讲最小部署、建库、调优和避坑，最后聊一聊怎么把它嵌进你自己的业务系统里。

2. DB-GPT 的核心思路：数据库能力是怎么被大模型"接管"的

2.1 不是让模型直接连数据库，而是让模型学会"使用工具"

很多人第一次听到"用自然语言查数据库"，第一反应是直接把数据库连接串和 Schema 丢给大模型，让它自己生成 SQL 并执行。这在实验环境能跑通，到真实环境就翻车：生产库的权限控制、敏感字段脱敏、超长 SQL 的稳定性、以及模型把"上月"理解成"上一自然月"还是"最近30天"，没有一个环节是白送的。DB-GPT 的架构思路不是"模型直连数据库"，而是把数据库操作封装成一组工具，模型只负责"理解问题 + 规划步骤 + 调用工具"，真正的查询由数据源层去执行。

这个设计带来的直接好处是：你可以在模型和数据库之间插入鉴权、脱敏、审计、超时控制，甚至把多数据源统一到一个入口后面。Text-to-SQL 在大模型应用里其实只是中间一环，前面有意图识别和参数抽取，后面有结果解释和追问澄清。DB-GPT 把这一整条链路串成了默认流程，这也是它相比"自己写几句 Prompt 调 OpenAI 接口"最核心的差异点——它给的是一个可落地的框架，不是一个一次性脚本。

2.2 双模型架构：为什么生成模型和推理模型要分开

它的默认架构里值得注意的一点，是区分了"生成模型"和"推理模型"。生成模型负责做 Embedding、做 SQL 结果的自然语言总结这类任务，推理模型负责做 Text-to-SQL、做问题理解这类复杂推理。为什么要分开？因为这两类任务对模型能力的要求不一样：Embedding 任务只要稳定、快、便宜，推理任务则需要参数更大、指令跟随能力更强的模型。如果你只用一个小模型同时扛这两类任务，会发现"问简单问题还行，问带子查询和窗口函数的问题就胡编 SQL"；如果全用大模型又太慢太贵。

实际部署的时候，这种设计让你能按预算混搭：Embedding 用本地的小模型，推理用 API 模型或者稍大的本地模型。在模拟项目X里我还试过另一种组合——推理模型用中等规模的开源模型，Embedding 用更小的模型，整体效果和全上大模型差距不大，但显存占用低了一个量级。这个"双模型分工"不只是一种配置技巧，它决定了你后续做模型选型时的取舍逻辑。

2.3 从"问答"到"Agent"：为什么它不只是一个 SQL 翻译器

DB-GPT 的野心不止于 Text-to-SQL。它把数据库操作、知识库检索、模型调用都做成了 Agent 可调用的能力，这意味着你可以让模型"先查一下有哪些表，再根据表结构决定 SQL 怎么写，最后把结果画成趋势说明"。这一个能力链条很重要，因为真实业务问题往往是模糊的："帮我看看这个月业绩怎么回事"——你得先拆出指标、拆出维度、定位到表和字段，才能写 SQL。

它做的另外一件事是"插件化"。官方内置的插件包括知识库问答、数据库查询、报表生成等，你可以按需打开或关闭。这种插件化设计带来的实际价值是：你可以先只开放"数据库查询"这一个能力做试点，防止模型在业务方乱跑其他工具。

3. 从零到可用：DB-GPT 的最小部署与本地跑通

3.1 环境准备：显卡、系统和依赖项怎么选

先给结论：如果想在本地跑通完整链路，一张 24G 显存的卡是最舒服的起步配置（能同时跑 7B~8B 量级的推理模型和一个 Embedding 模型）；如果只有 16G，就得接受速度慢一截，或者让推理部分走 API。我见过有人用纯 CPU 跑 7B 模型做 Text-to-SQL，一条查询等三分钟，属于"能跑但没人愿意用"的状态。如果你之前部署过其他大模型应用，DB-GPT 的环境要求并不算特殊——Python 3.10 以上、PyTorch、CUDA 这几个大头准备好，基本就畅通了。

操作系统方面，Ubuntu 系和 CentOS 系我都跑过，Ubuntu 体验更顺，主要是依赖编译工具链齐全，少踩很多"缺这个头文件、缺那个库"的坑。Windows 也能跑，但建议用 WSL2 而不是原生环境，否则光编译一些 Python 扩展就够折腾半天的。下面是启动 DB-GPT 服务的最小命令集。

# 创建虚拟环境，避免和系统 Python 环境互相污染 python3 -m venv .venv source .venv/bin/activate # 安装核心依赖（以 0.6.x 版本为例，具体以官方 tag 为准） pip install -e . # 运行一键安装脚本，初始化默认配置和依赖项 bash ./scripts/install_all_dependencies.sh # 启动服务，默认端口 5670 python -m dbgpt.server

第一条命令创建虚拟环境，这一步不是为了走形式，而是 DB-GPT 依赖的包很多且版本要求偏新，直接装到系统环境里很容易和已有项目打架。pip install -e . 是开发模式安装，能让你改完代码不用重新安装就能生效。install_all_dependencies.sh 这个脚本会把服务端、前端构建和核心 Python 依赖一次性装好。最后一条启动命令起来之后，访问 http://localhost:5670 就能看到管理界面。如果你有特定的推理模型要走 API，等服务起来后去界面里的模型管理页配置即可。

3.2 配置模型：本地模型和 API 模型该填什么

服务能起来只是第一步，真正决定能不能用的是模型配置。DB-GPT 的模型配置有两种常见路径：一是通过管理界面的模型管理页面添加，二是直接改配置文件。我建议新手用界面操作，因为配置项的校验和提示都更友好。配置本地模型时你需要填模型名称、模型路径、推理后端类型，还要指定它跑在 GPU 还是 CPU 上；配置 API 模型时则需要填 API 地址、API Key 和模型名。

这里面最容易搞混的两个概念是"模型名称"和"模型路径"。模型名称是你在系统里给它起的逻辑名字，比如chat_model，模型路径是实际权重文件的路径，比如/data/models/Qwen2.5-7B-Instruct。后面建应用、连数据库时引用的都是逻辑名称，不是路径。如果你后续要换一个同类型的模型，只需重新配置这个逻辑名称对应的路径，不用改业务配置。

一个实操经验：初始配置时，先把 Embedding 模型固定用本地小模型，推理模型用 API 或中等规模本地模型，跑通后再逐步调整。这样做的好处是降低首跑的不确定因素——如果一上来就两个模型都是本地的，任何一个环节失败，你很难判断是哪一段出了问题。

3.3 第一次连接数据库：建数据源时的关键选项

在界面的"数据源管理"里添加数据库连接时，除了常规的主机地址、端口、用户名、密码之外，有两处需要多留意。一个是"数据库类型"要选对，比如 MySQL 就选 MySQL，不要选成"其他"，因为不同类型走的是不同的方言适配器，直接影响后面 Text-to-SQL 的生成效果。另一个是"Schema 信息是否自动同步"，建议勾上。这个选项会自动把库里的表结构、字段注释、索引信息同步到 DB-GPT 的元数据里，模型生成 SQL 时才能"看到"有哪些表和字段可用。

# 用命令行方式创建数据源的等价做法（通过 API） curl -X POST http://localhost:5670/api/v1/datasource/add \ -H "Content-Type: application/json" \ -d '{ "db_type": "mysql", "db_host": "127.0.0.1", "db_port": 3306, "db_user": "readonly_user", "db_pwd": "your_password", "db_name": "business_analytics", "sync_schema": true }'

上面这个 API 调用演示了用脚本批量建数据源的方式，适合你有多个测试库要一次性接进来的场景。db_type 指定数据库类型，readonly_user 那个账号是专门为这套系统创建的只读账号，这个习惯值得保持——不要用生产库的高权限账号去接大模型应用，因为它生成的 SQL 你无法完全预判，至少也要保证账号只有 SELECT 权限。sync_schema 参数就是前面说的自动同步表结构，建议第一次就打开，省得后面一个个手填字段。同步完成后，你可以在界面的"数据源详情"里看到每个表的字段列表和字段注释，这些就是模型生成 SQL 时的"上下文"。

3.4 验证链路：让模型回答一个真实问题

链路是否通了，不要问"你好"这种寒暄，直接问一个带业务语义的问题。比如"查询每个产品线最近三个月的销售额，按月份展示"。如果配置正确，你会看到执行计划里出现了"识别需求 → 生成 SQL → 执行 → 总结结果"这样一串步骤。第一次跑的时候建议在界面里打开"执行详情"，看它生成的 SQL 到底是什么，不要只看最终文字结果——文字结果看起来对，SQL 可能 JOIN 错了表，这个习惯从第一天就要养。

-- 这是 DB-GPT 针对上述问题生成的一条典型 SQL -- 注意看 GROUP BY 和日期筛选条件是否符合业务口径 SELECT p.product_line, DATE_FORMAT(o.order_date, '%Y-%m') AS month, SUM(o.amount) AS total_sales FROM orders o JOIN products p ON o.product_id = p.id WHERE o.order_date >= DATE_SUB(CURDATE(), INTERVAL 3 MONTH) GROUP BY p.product_line, DATE_FORMAT(o.order_date, '%Y-%m') ORDER BY month DESC;

这条 SQL 看着中规中矩，但注意两处容易出问题的细节。一个是对"最近三个月"的解读，这里用了 CURDATE() 往前推三个月，但业务上"最近三个月"有时指"这三个月完整月份"，比如现在是 6 月 15 号，业务要的是 3、4、5 月整月数据，这种场景下这条 SQL 会把 6 月 1 号到 15 号的数据也算进去。另一个是"销售额"的口径，是订单金额还是实付金额，是含税还是不含税，模型的判断依据完全来自字段名和注释。所以你会发现，DB-GPT 的准确率上限其实不取决于模型，取决于你的元数据质量。字段没注释、表名混乱、同一含义字段在不同表里叫不同名字，这些才是真正拖垮效果的因素。

4. 把领域知识喂进去：知识库与提示词的双重调优

4.1 为什么要建知识库：让模型理解"你们公司的说法"

Text-to-SQL 的上限由元数据决定，但元数据只能告诉模型"有哪些表和字段"，告诉不了它"你们公司的退货率是按签收时间算而不是下单时间算"，也告诉不了它"VIP 客户的定义是近 90 天消费超过 5000 元"。这些业务口径如果不告诉模型，它就只能按字面意思猜，猜错就是一堆看起来正常但口径不对的 SQL。DB-GPT 解决这个问题的方式是引入知识库——你可以把业务指标文档、历史口径说明、甚至 DBA 平时写的 SQL 规范文档都传进去，模型在生成 SQL 前会先去知识库里检索相关片段作为参照。

这一步我建议别跳过。我第一次部署时偷懒没建知识库，结果"退货率"被模型生成了"退货订单数/总订单数"，而业务方实际定义是"退货金额/销售额"，完全两个数字。建了知识库并写入口径说明之后，这类问题明显减少。知识库的本质是给模型一本"你们公司专属的 SQL 手册"，它回答问题时先去翻手册再动手。

4.2 知识库入库与召回测试：你会遇到的三个细节

建知识库的过程在界面上不复杂：新建知识库、上传文档、选择切分方式、触发向量化。但有几个细节会影响最终效果。第一个是文档格式，Markdown 和纯文本的解析效果好于 PDF，扫描版 PDF 是纯图片，向量化之后基本搜不出来，建议先转成文本再上传。第二个是切分长度，默认的切分参数对大部分场景都适用，但如果你文档里有大量表格，切分点正好落在表格中间会导致语义不完整，需要调小切分长度并开启"按段落切分"。

第三个细节最容易忽略——召回测试。入库之后不要直接去问复杂问题，先在知识库管理页面里搜索一个关键词，看看召回的片段到底是不是你想要的。比如你上传了"退货率口径说明"，搜索"退货率"应该召回这段，如果召回的是其他不相干片段，说明切分或向量化有问题。DB-GPT 支持在知识库页面直接测试召回效果，这一步 30 秒就能做完，但能帮你省下后面一小时的排错时间。

# 通过 SDK 方式向知识库追加文档（适合批量处理） from dbgpt.rag import KnowledgeLoader loader = KnowledgeLoader( knowledge_space_name="business_terms", file_path="/data/docs/return_rate_rule.md", chunk_size=512, # 切分长度，表格多时调小 chunk_overlap=64, # 相邻片段重叠，保持上下文连续 separators=["\n\n", "\n", "。", "；"], # 优先按段落切分 ) loader.load_and_vectorize()

这段代码演示的是批量追加文档的姿势。chunk_size 设置的是每个切分片段的最大长度，512 个字符对中文场景是个还算稳妥的起点；如果文档里表格密集，我会调到 256 并配合分隔符"。"来切，避免表格被截断成无意义碎片。chunk_overlap 是相邻片段的重叠长度，太小会让被切断的语义接不上，太大会让重复内容占满向量空间，一般设在 chunk_size 的 10%~20% 之间。separators 的优先级很重要，传了 ["\n\n", "\n", "。", "；"] 意思是先按空行切，空行不够再按换行切，再不够按句号切，这个顺序可以让段落完整度最大化。跑完这段代码后，回到界面搜"退货率"，能召回到对应段落就说明入库成功。

4.3 提示词模板：把模型"装进"你们的业务语境里

DB-GPT 允许你自定义 Text-to-SQL 的提示词模板，默认模板是通用场景的，但对特定业务需要做定制。最值得改的两个地方：一是"角色设定"，告诉模型"你是一名精通 MySQL 的数据分析师，熟悉电商零售业务口径"；二是"输出约束"，明确要求"只能使用只读查询、禁止 DELETE/UPDATE、如果问题不明确需要先问清楚再生成 SQL"。

这里有个小技巧：不要把提示词写得像法律条文一样长，模型对过长提示词的遵循度反而会下降。把"你最核心的口径约束"压缩成三五条，放在提示词靠前的位置，效果远好于写在长篇背景说明后面。我在模拟项目X里实践下来，提示词调优的收益常常比换更大的模型还明显——毕竟 Text-to-SQL 的任务难点不在"智力"，在"对齐"。

5. 避坑手册：部署与使用中的 7 个典型问题

5.1 问题一：模型目录填对了，但服务一直报找不到模型

现象：模型配置页显示模型存在，但发起对话时报"model not found"或"模型加载失败"。

原因：这个坑我踩过三次，基本都是同一个原因——模型配置里的"模型名称"和前端调用时引用的名称不一致。比如你在模型管理里把名字写成sql_model，但数据库问答应用里默认引用的是chat_model，自然找不到。如果你配置过多个模型，"默认模型"和"应用实际调用的模型"是两个不同的概念，很多人只配了默认模型，忘了改应用那里的引用。

解决：到模型管理页面核对两处——当前默认模型是谁，数据库问答应用的模型引用是谁。让这两者保持一致，或者在应用配置里显式指定你新建的模型名称。一个习惯建义：给模型起名时直接叫default_llm，避免每次建新应用都要重新指定。

5.2 问题二：生成的 SQL 语法正确但查不到数据，或者报字段不存在

现象：模型生成的 SQL 看起来结构完整，执行时却报 "Unknown column"。

原因：数据库表结构在你建完数据源之后发生过变更，新加的字段没有同步到 DB-GPT 的元数据里。模型只"看"得到建数据源时同步的 Schema，之后你加字段它也不知道，自然生成出不存在的字段名。

解决：在数据源管理里对对应数据源触发一次"重新同步 Schema"，之后模型就能"看到"新字段。如果你经常改表结构，建议做一个定时任务，每天凌晨同步一次全量数据源的元数据。

5.3 问题三：部署后界面能开，但问答一直转圈没有响应

现象：前端页面正常加载，发消息后一直 loading，后端日志无报错。

原因：推理模型没有真正启动成功，或者模型加载进了显存但在推理时崩溃。常见诱因是显存不足，模型加载时显示成功，真正推理时 OOM 被系统杀掉，进程还在但服务不可用。

解决：先看nvidia-smi确认显存占用；如果显存满了，换更小的模型或开启量化；再看后端日志里有没有 "CUDA out of memory" 字样。如果模型是首次加载，第一次问答会慢到像卡死，这其实是正常的——模型权重在加载到显存，等一分钟后就好了。

5.4 问题四：知识库上传了文档但问答时好像完全没用到

现象：知识库里文档已经入库且召回测试正常，但问答时模型的回答里没有任何知识库内容。

原因：知识库和数据库问答不是一个自动绑定的关系。你需要在"数据库问答"应用或 Agent 配置里明确挂载知识库，模型才会在生成 SQL 前去检索它。很多人以为传了文档就会自动生效，其实还要在应用侧开"知识库增强"的开关。

解决：在对应的应用/Agent 配置里，找到知识库关联的选项，把建好的知识库挂上去。再测试才能看到效果。如果你的场景里知识库和数据库都要用，确认两个能力都挂在了同一个 Agent 上。

5.5 问题五：SQL 执行很慢，甚至把数据库拖卡

现象：某条问答触发了全表扫描或嵌套子查询，数据库 CPU 飙高。

原因：模型生成的 SQL 不一定会主动加索引条件，尤其当字段名没有明确语义时，它倾向于写范围查询或扫描。这在测试库无所谓，在生产库就是事故。

解决：一是给数据库账号设置最大执行时间（max_execution_time），超时自动 kill；二是通过提示词约束"必须使用索引字段作为筛选条件"；三是在数据源侧把生产库设置为只读账号并启用语句超时。

5.6 问题六：多轮对话后上下文被"带偏"

现象：前面几轮答得好好的，追问几个问题后，模型开始把上一轮的表名或字段用到当前的问题里。

原因：多轮对话时历史信息会被拼接进上下文，如果历史里有错误 SQL 或无关表名，模型会被带跑偏，这在长对话里很常见。

解决：DB-GPT 支持配置多轮对话的记忆策略，可以限制只保留最近一轮或两轮。对数据库问答场景，建议把历史轮次设小一点——你只需要它能承接"上一题的筛选条件再排除某个品类"这种轻量依赖，不需要它记住十轮前的所有细节。

5.7 问题七：Embedding 模型用中英文混用导致检索效果差

现象：知识库召回结果不稳定，有时候相关文档排在很后面。

原因：Embedding 模型按训练语料分了语系，有些模型英文效果好中文差，或者反过来。知识库文档如果是中文为主，默认配置的模型可能不是最优。

解决：把 Embedding 模型换成中文优化过的模型。判断方法很简单——建一个只有一两个文档的小知识库，搜索中文关键词，看召回排序是否合理。这一步 5 分钟就能验证，值得在正式投入前做一次。

6. 进阶用法：把 DB-GPT 接入现有业务系统做"内网 ChatBI"

6.1 从界面到 API：一个可被业务系统调用的问答接口

界面问答只是第一步，真正让 DB-GPT 产生业务价值的是把它封装成 API 给现有系统调用。它提供的接口里，最核心的是"对话补全"接口，你可以用任意语言发起 HTTP 请求，传入问题、会话 ID 和可选的上下文参数，拿到模型生成的结果。这意味着你可以把自然语言查数能力嵌入到已有的报表系统、企业微信机器人或者内部工作台里，让业务方在原本的办公流里直接问数，不必再打开一个单独的界面。

# 调用 DB-GPT 的问答接口（HTTP 方式） curl -X POST http://localhost:5670/api/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "default_llm", "messages": [ {"role": "user", "content": "华东区上季度各品类退货率，按退货金额口径"} ], "chat_mode": "chat_with_db_execute", "datasource": "business_analytics", "user_input": "华东区上季度各品类退货率" }'

参数说明：model 字段明确指定走哪个模型，chat_mode 用chat_with_db_execute表示走"数据库查询并执行"链路，datasource 指定数据源别名。值得提醒的是，这里的 datasource 名称要和建数据源时的命名一致。返回结果里会有 SQL、执行结果和最终的自然语言总结三个部分，业务系统可以只展示总结，也可以把 SQL 存下来做审计。

6.2 把"模型生成的结果"和"业务已有的可信结果"做比对

AI 生成的 SQL 准确率再高，也不能直接替代正式报表。真正稳妥的推进方式是"AI 生成 SQL + 人工确认后执行"或者"AI 生成 SQL 与已有报表数据做自动比对"。后者是我比较推荐的第一步——把 DB-GPT 生成的结果导出，和现有报表数据按月对拍，差异率低于阈值再逐步放开权限。这本质上是在给模型建立一份"可信度账本"，没有这份账本，你很难说服业务方真正信任它。

另一个值得做的动作是保存历史问答和对应 SQL。DB-GPT 支持将对话记录持久化，你可以定期翻一翻"模型生成过哪些低质量 SQL"，把它沉淀成知识库里的负面案例。这比调十次提示词都有效——因为模型会从正确示例里学，也会从被纠正的历史里学。

6.3 敏捷落地的节奏：从只读库到全量数据源需要几步走

如果你想把这件事真正做成一个"内网 ChatBI"，我的建议是分三步。第一步，只接入一个只读库，开放给 3~5 个核心用户试用，目标是验证"模型生成的 SQL 有没有低级错误"。第二步，接入知识库，把业务口径文档喂进去，用一周的真实问题做回归测试，目标是让准确率稳定在可用线以上。第三步，再接入第二个数据源，测试跨库查询和多轮对话的稳定性。

这里有一个经常被忽略的细节：你的第一步和第二步之间，至少要留出"口径收集"的时间。业务方真正在意的是"你算的数字和我平时看的不一样"，而这个"不一样"绝大部分来自口径差异，不是 SQL 语法错误。把收集口径当成和调模型一样重要的事来做，DB-GPT 项目才真正算是完成了从技术验证到业务交付的转身。我自己的教训是：第一次做这类项目时花了大量时间调提示词，后来发现只要把口径文档喂进知识库，效果立刻上一个台阶——模型本身不缺智力，缺的是你给它划定的业务边界。希望这套从部署到嵌入的路径能帮到你，至少能让你少踩几个我已经替你趟过的坑。

本文还有配套的精品资源，点击获取