企业官网建设流程全解析

前一阵把 SQLBot 从开源仓库拉下来，接上自己的 MySQL，用 5 万条订单数据从头到尾做了一轮智能问数实测。这三个关键词拆开看都不新鲜：开源项目满大街都是，SQLBot 这类“自然语言转 SQL”的智能问数工具也不是第一家，但真把它放到一个相对真实、带点脏数据、带点业务口径歧义的数据库里，一句一句问下去，就会发现很多评测 Demo 里根本看不到的问题。

这篇记录整个实测过程：我如何准备数据、如何设计评测问题集、SQLBot 在简单查询、多表关联、复杂语义三个维度上到底表现如何，以及调试时踩过哪些坑。适合正在给数据库找自然语言入口的开发者、数据产品经理，以及那些在 GitHub 上翻开源方案但还没想清楚怎么评估的人。看完你应该能得出一个自己的判断：开源智能问数到底能不能上生产、能上到哪一步。

1. SQLBot 是什么：先看清智能问数工具的定位

1.1 它解决的是取数环节的效率问题

先说背景。很多团队表面上缺的是“写 SQL 的人”，实际上缺的是“把业务问题翻译成 SQL 的中间层”。业务侧要一个数，可能只是问“上周哪些品类卖得好”，但这句话要被翻译成一张多表 join、带时间窗口、还要排除掉退款订单的查询。过去这件事只能靠数据分析师肉眼理解业务、再手工写 SQL，瓶颈不在 SQL 语法本身，而在于“对口径”和“等排期”。

SQLBot 这类工具想做的，就是把这个翻译过程自动化。用户用自然语言提问，它负责生成 SQL、执行查询、再返回可读的结果。它和自己调大模型 API 的区别在于：它把数据库表结构、字段注释、采样内容、甚至指标口径都组织成一套提示词，同时提供了执行层和结果展示层，让用户不需要自己写胶水代码。

我之所以拿开源版本做主力测试，原因有三。第一，数据不出内网，所有请求经过我自己的数据库账号，不会把业务数据传到第三方平台；第二，提示词和代码逻辑都可以改，能看清楚它在哪一步翻车；第三，它可以被接进内部系统做定制，而不是一个用完就走的在线玩具。对于想认真评估智能问数能力的团队，这种“看得见内部逻辑”的特性比任何演示都重要。

1.2 从自然语言到 SQL 的核心链路

拆开 SQLBot 的请求链路，大致是五步。第一步，系统读取数据库的元数据，把表名、字段名、字段注释、枚举值说明组装成一份数据库字典。第二步，根据用户的自然语言问题，从字典里召回可能相关的表和字段，避免把所有表结构一次性塞给大模型。第三步，把“用户问题 + 相关表结构 + 少量示例”拼成提示词，请求大模型生成候选 SQL。第四步，做一层基础校验，比如是否包含危险操作、字段是否存在于元数据中，通过后才交给数据库执行。第五步，拿到查询结果，再由大模型生成一段自然语言总结。

这个链路里最容易被忽视的是第二步。很多人以为表结构越多越全，模型越聪明，其实不对。上下文窗口有限，塞进去几百张表反而会让模型在无关表上“强行联想”，生成一些看似合理、实则对不上的 SQL。SQLBot 的表结构召回策略是否有效，直接决定了它能不能在真实企业级 Schema 里活下去。这次测试库只有四张表，召回压力不大，但我在第 3 部分会讲到，字段注释缺失时它照样会出现幻觉列名。

1.3 为什么强调“5 万条”而不是“5 亿条”

先破个误区：5 万条数据对数据库来说太轻松了，一张普通 MySQL 表跑聚合查询基本是毫秒级，根本不可能成为瓶颈。所以如果你拿“数据量大不大”来测试 SQLBot，方向就错了。真正要测的是：在这 5 万条带着真实业务特征的数据里，它的语义理解准确率、SQL 生成正确率、以及面对脏数据和歧义表达时的兜底能力。

但 5 万条也并不是没意义。它足够容纳多种业务状态：不同城市的用户、不同品类的订单、成功和退款混杂的状态、同一个人多次下单的行为模式。这些才是让自然语言问数“翻车”的土壤。数据量再大，如果只是一堆整齐的随机数，反而测不出问题。这个测试集的思路，是让问题足够像业务人员真实会问出来的话，而不是像教科书里的练习题。

2. 实测准备：数据、环境与评测问题集

2.1 搭建一个贴近真实生产的数据库场景

我没有用现成的公开数据集，而是自己构建了一套迷你电商库，四张表模拟一个很常见的业务：用户、商品、订单、订单明细。这不是为了炫技，而是我想控制“脏数据”的引入方式，知道哪些口径模糊是故意埋的。

表结构大致如下：

CREATE TABLE users ( id INT PRIMARY KEY, user_name VARCHAR(50), city VARCHAR(50), gender TINYINT, register_date DATETIME ); CREATE TABLE products ( id INT PRIMARY KEY, product_name VARCHAR(100), category VARCHAR(50), price DECIMAL(10,2) ); CREATE TABLE orders ( id BIGINT PRIMARY KEY, user_id INT, product_id INT, status VARCHAR(20), amount DECIMAL(10,2), created_at DATETIME );

生成数据时我故意埋了几个坑。orders 表里放了一批 status 为 refund 的订单，amount 为正数，方便测试工具在统计销售额时会不会主动排除退款；还有少量订单的 created_at 是 NULL，模拟上游写入异常；users 表里有几位重复注册的测试用户，city 字段也存在“深圳”和“深圳市”混用的情况。这些细节在第一轮简单查询里可能不暴露，但会严重影响复杂统计的准确性。

字段注释一定要写。我发现 SQLBot 对字段名本身的理解其实依赖大模型，但对“注释”的依赖远远大于我的预期。同样是 status 字段，如果注释写“状态码：1 成功、2 失败”，和写“该字段记录订单当前生命周期状态”，模型生成过滤条件时会有完全不同的表现。甚至可以说，表字段注释质量，决定了整套智能问数系统 50% 以上的上限。

2.2 安装部署与安全配置的注意点

拉取项目后，我按 README 做了基础配置，整个流程不复杂：建虚拟环境、装依赖、改配置文件、填数据库连接和大模型 API Key。不同版本的 SQLBot 启动方式不完全一样，但有几个动作是通用的，几乎适用于所有同类型开源工具。

第一个动作：给 SQLBot 单独建一个只读数据库账号。这属于“就算工具号称有安全检查也必须做”的底线操作。万一它在 SQL 校验环节漏掉一条 update 语句，或者业务人员在对话里故意输入一段注入文本，只读账号可以把损失控制到最小。

llm: model: your-llm-model # 按实际项目配置 api_key: sk-xxxx # 通过环境变量注入，不要写死到仓库 temperature: 0 database: engine: mysql host: 127.0.0.1 port: 3306 user: sqlbot_ro password: only-read-password database: sales_demo

第二个动作：控制结果集返回量。我直接改了配置里的默认 limit，让 SQLBot 生成 SQL 时自动追加 LIMIT 200。5 万条数据全量返回倒是不会崩，但会把结果转自然语言总结的 token 数撑得很大，影响响应用户的速度，而且业务人员看全量明细本来就不是高频需求。限制返回行数不是阉割功能，是保护体验。

第三个动作：别把 API Key 提交进 Git 仓库。自己在本地测试无所谓，一旦放到内网服务器或者 GitHub 上，Key 泄漏就是安全事故。SQLBot 这类开源项目对配置文件的管理通常比较宽松，很多示例配置文件里留有默认 Key 的位置，需要自己替换成环境变量方式。

2.3 把评测问题集分成三个梯度

评测不能想起什么问什么，我按难度设计了三组问题，每组 7 个左右，总共 24 个问题。第一组是基础单表查询，比如“昨天产生了多少订单”“统计每个城市的用户数”；第二组是多表关联和聚合统计，比如“最近 30 天每个品类的销售额 Top3”“复购用户的数量”；第三组是语义复杂问题，包含口径歧义、多步骤推理和隐含排除条件，比如“哪个城市的用户平均下单金额最高”“上个月的销售额环比增长了多少”。

这个分梯度的好处是：能快速定位 SQLBot 是在哪一层开始掉链子。如果只是单表查询出错，可能是 schema 理解问题；如果单表全对、一到多表 join 就错，可能是逻辑推理或者表关系描述问题；如果前面都对、一到第三组就错，那大概率是业务口径表达的问题，不是模型能力的问题。

每道题我都记录了三个信息：第一次生成的 SQL 是否直接可用、是否能通过简单纠错后可用、是否完全不可用。用这样的方式评测比凭感觉打分客观得多，也方便在换模型、改提示词之后做前后对比。

3. 5 万条数据实测过程：从基础查询到复杂语义的真实表现

3.1 基础查询：单表过滤和聚合执行得又快又稳

先看表现最好的一层。用户问“8 月成功下单的订单里，分布在哪几个城市的用户最多”，SQLBot 生成的 SQL 基本能直接执行，这是我挑的一个比较典型的结果：

SELECT u.city, COUNT(DISTINCT u.id) AS user_cnt FROM orders o JOIN users u ON o.user_id = u.id WHERE o.status = 'success' AND o.created_at >= '2025-08-01' AND o.created_at < '2025-09-01' GROUP BY u.city ORDER BY user_cnt DESC LIMIT 10;

能看得出来，它在几个细节上处理得不错：日期条件用了半开区间，这样不会漏掉 8 月 31 日最后一秒的订单；对用户计数用了 COUNT(DISTINCT u.id) 而不是 COUNT(*)，防止同一用户下多单造成的重复统计。这些不是模型“聪明”，而是我在表结构注释里写明了主键和常见口径，它把这些信息正确用上了。

第一组里真正让我皱眉的问题，反而是看起来更简单的“昨天有多少订单”。SQLBot 默认会使用“当前日期”作为参照，但这个“当前日期”很容易出错。大模型的知识截止时间未必是今天，它可能把“昨天”理解成训练数据里的某个时间点，而不是用户提问时的真实日期。后来我把前端传参改成了在系统提示词里注入真实当前日期，这个问题就消失了。如果你准备上这类工具，一定要在前端或者服务端把“今天”“本月”“去年”这类相对时间显式换算成具体日期，再拼进提示词，绝对不要指望模型自己算。

3.2 关联查询：多表 join 下正确率开始分化

第二组多表关联问题，SQLBot 的表现在我的预期之内，好的很好，差的很差。像“每个品类最近 30 天的销售金额”这种字段归属清晰、join 路径单一的问题，它处理得很流畅，生成的 SQL 基本不需要改。但一旦涉及“先按 A 条件圈定用户、再统计这批用户的 B 行为”，就开始出现逻辑顺序错误。

我特意测了一道“找出客单价高于整体平均水平的用户”。这道题的严谨做法是先算每个用户的客单价，再和整体平均客单价比较，可以拆成子查询或者窗口函数。SQLBot 第一次生成的 SQL 直接把订单表按照用户分组以后取 AVG(amount)，然后再和全部订单的总金额除以总订单数去比，逻辑上算的其实是“高于整体均值”，但它在子查询里漏掉了只统计成功订单这个条件，导致退款订单也被算进去，数值偏差不小。

这暴露出一个关键问题：SQLBot 对“从主表出发还是从子查询出发”这种查询规划能力理解得不够稳。它毕竟不是一个原生的 SQL 优化器，它只是把自然语言翻译成 SQL，然后交给 MySQL 去跑。如果翻译出来的结构本身就错了，后面执行再快也没有意义。所以多表复杂统计这一层，现实建议是：让懂 SQL 的分析师先把它生成的语句审查一遍，而不是直接开放给业务人员。

3.3 复杂问题：语义歧义暴露了系统的知识盲区

第三组问题才是拉开差距的地方。我问了一个看起来很自然的问题：“上个月的销售额环比增长了多少”。这里隐藏着两个坑：一是“上个月”要正确换算成日期范围，二是“环比”要和上上个周期比较，而且必须保证两段周期天数一致、过滤口径一致。SQLBot 生成的 SQL 在时间过滤上做对了，但对比基期的查询里居然没有排除退款订单，口径和当期不一致，导致算出来的增长率失真。

另一个更典型的问题是“深圳市的用户里有多少人在 30 天内重复购买”。业务上“深圳市”和表里的“深圳”是同一个含义，但 SQLBot 如果只拿到字段注释“用户所在城市”，它会老老实实地写WHERE city = '深圳市'，查出来是 0。这不是 SQL 语法问题，是数据质量问题传导到了模型层。如果是人工分析师看到城市分布数据，大概率会意识到这种差异，但 SQLBot 不会主动去猜测，除非注释里写明“city 字段可能存缩写，查询时建议用 LIKE”。

这类问题让我意识到，智能问数工具本质上更像一个“非常熟悉 SQL 语法、但对你的业务一无所知的实习生”。它能把一句人话翻译得很工整，但译得对不对，取决于你对它交代了多少业务背景。这也解释了为什么那些让人工智能直接问生产库的在线 Demo 看起来很惊艳，实际放进企业内部却容易翻车：Demo 库的表结构干净、字段注释完整、不存在多层口径，而现实世界不是这样。

3.4 生成耗时和资源占用的真实观察

这轮测试我没有刻意压测并发，只记录了单请求的耗时分布。基础问题的完整链路大概 2 到 4 秒，多表复杂问题能到 6 到 10 秒。其中数据库本身执行 SQL 基本都在几十毫秒，绝大部分时间花在大模型生成 SQL 以及最终结果总结上。5 万条订单在这种规模下对执行端毫无压力，压力全在模型推理延迟上。

如果你的用户是业务人员，他们对“问一句话要等 5 秒”普遍还能忍受，但如果连续追问多个问题，累积等待就会变得很烦。我自己的处理办法是把“结果总结”这步的模型换来更快的小模型，SQL 生成部分继续用推理能力更强的大模型。很多开源工具支持这种配置拆分，SQLBot 这类项目一般也允许在链路不同环节指定不同模型，值得一试。

生成结果后我还遇到了一个隐藏问题：当查询结果有几十行时，模型会把每一行数据都读一遍再总结，Token 消耗会成倍上涨。把返回行数压到 200 以内之后，总结速度快了不少，回答也更精炼。大模型产品做久了都会发现，限制输入有时候比优化输出更有效。

4. 常见问题与调试实录

4.1 高频执行报错的排查顺序

先说一个现象：SQLBot 抛出来的报错，大多数时候不是“数据库连不上”，而是“SQL 执行错误”。问它为什么，它会给你一个大模型生成的解释，但这个解释不一定对。我碰到的高频问题基本有三类，排查顺序也相对固定。

第一类，报 Unknown column。这种基本可以断定是模型幻觉出了不存在的字段名，原因通常是表结构或字段注释里没有说清楚有哪些列。我一开始表注释写得比较粗，它就在订单表里凭空生成一个 coupon_id。解决办法不是去调模型，而是先把字段注释补齐，并且在提示词里显式声明“只能在给出的字段列表中选择”。如果项目支持字段白名单，一定要开。

第二类，报 SQL syntax error。排查时先别急着怪模型，把生成的 SQL 复制出来在数据库客户端里跑一遍，看报错位置。很多时候是 ORDER BY 和 GROUP BY 的顺序问题，或者中英文标点混用。遇到这种，我会在评测集里加一条类似语法的标准示例，让后续生成有 few-shot 可以参考，效果立竿见影。

第三类，查询能跑但结果明显不对。这种最坑，因为没有报错，业务人员如果不够细心可能直接用错误数据做决策。我的经验是，对高频统计口径提前写“口径模板”，比如“销售额 = status 为 success 的订单金额合计”，把它固化在系统配置里，让每一次生成都带上这条约束。下表是我整理的通用排查清单，可以贴在工位上参考：

4.2 提示词该怎么写：一次案例的前后对比

我试过两种做法。第一种是在系统提示词里堆了一大段关于“你是资深数据分析师、请谨慎考虑”的废话，加了各种规则，结果并没有变好，反而让模型在简单查询上过度发挥，生成很多不必要的子查询。第二种是把提示词控制在合理长度，重点突出“当前日期”“业务口径”“示例问题”三件事，效果明显更好。

关于智能问数 agent 的提示词字数，网上讨论很多，我的体感是：不建议盲目追求大而全。大模型上下文窗口再大也有限，关键是让它在最关键的信息上做精准推理。与其写 5000 字业务手册，不如把核心口径写成结构化条目，让系统在和数据库交互时动态检索相关片段再注入提示词。

下面是我调整后的一个简化示例片段，直接放在系统提示词里：

当前真实日期：2025-08-16 统计销售额时，只统计订单状态为 success 的记录。 需要排除退款订单。 city 字段存在“深圳”与“深圳市”混用的情况，统计城市时做等价处理。

这短短几句话，把我在第二、三组测试里遇到的大量问题直接解决掉了。你会在调了几次之后发现，智能问数系统优化的真正抓手，不是调模型温度，而是把业务知识结构化成模型能看懂的语言。这个投入比换更强的大模型还要划算。

4.3 实测结论：开源智能问数适合什么场景

回到标题那个问题：开源智能问数能走多远？我的判断是，它能走到的距离，取决于你愿意为它铺设多长的路，而不是它自己能跑多远。

它能稳定覆盖的场景有：字段命名规范、注释完整、业务口径相对简单的中小型数据库；数据分析团队内部用来加速取数；或者面向内部员工做了严格表范围隔离和只读控制的自助查询平台。在这些场景里，它能把“写 SQL”的门槛打下来一半以上，把简单重复的提数需求从分析师手里接走。

它目前还搞不定的场景也很清晰：Schema 混乱且缺注释的老系统、口径藏在几十个存储过程里没人讲得清的指标、涉及复杂权限控制的多租户数据、以及要求百分百准确的财务审计场景。在这些地方，用 SQLBot 生成的 SQL 当草稿可以，但直接放给业务用，风险大于收益。

这轮测试给我最大的收获不是“哪个模型更强、哪个参数更优”，而是明白了开源智能问数项目的真正价值：它提供了一个可以持续打磨的底座，至于最终智能不智能，完全取决于使用者愿意投入多少精力去治理数据、整理口径。开源项目本身不会变魔术，但它给了你一个能自己动手变魔术的机会。

我个人的经验是，如果你的团队准备引入这类工具，别急着扩展功能，先找一张业务最核心的表，把表注释、字段注释、枚举值含义、常用统计口径全部梳理一遍，然后用二三十个真实业务问题做验收。等这张表上的准确率达到你能接受的水平，再往其他表复制。这样一步步来，比一开始就想让工具理解全公司所有数据要稳妥得多。最后再分享一个很实用的小技巧：在面向业务人员开放前，先让流程上接触 SQL 最多的数据分析师用两周，他们会天然地把踩过的坑转化为一批可复用的示例问答，这批东西才是智能问数系统最值钱的资产。