Text2SQL落地避坑：SQLBot配置方法与实践复盘

前段时给公司数据平台加自然语言查数功能，本来以为 Text2SQL 现在这轮大模型热潮下应该已经很成熟了，接个 API 就能直接干活，结果配置 SQLBot 的第一周就被连续打脸。同一个问题换个问法，SQL 质量能差到离谱；再加几个业务条件，模型甚至能一本正经地编出不存在的字段。后来我把 Text2SQL 服务涉及的配置项一个一个揪出来，按使用场景重新组织，SQL 准确率才慢慢拉回来。

这篇内容是份项目复盘笔记。虽然标题写的是“SQLBot 配置方法”，但我不打算只丢出几份配置文件让你抄。配置背后为什么这么设计、哪些参数会在什么场景下变成坑、五个场景分别对应什么能力，我都会摊开聊。适合正在做 Text2SQL 落地，或者准备把自然语言查询接进内部数据平台的同学参考。

如果你刚接触这个概念，先别急着把它想成“聊天机器人连一下数据库”。Text2SQL 的真正难点，不在于让模型理解“帮我查一下上个月订单金额”这句大白话，而在于让模型知道你的表结构长什么样、字段语义是什么、表与表之间的关系是什么、业务口径又是什么。SQLBot 这类工具本质上就是把这些“上下文”通过配置方式组织起来，再交给大模型去生成 SQL。配置得好不好，直接决定上线之后是助手还是事故现场。

1. 配置 SQLBot 前，先弄明白 Text2SQL 到底在调什么

很多团队第一次配 Text2SQL，习惯性先调模型参数——temperature 调到 0.7，prompt 里写满“你是一个资深 SQL 专家”，然后就希望模型能输出完美 SQL。我一开始也这么干过，结果发现模型确实很会“表演”，生成的 SQL 看起来结构完整，一执行就是字段不存在或者 JOIN 关系完全错误。

后来我才把思路捋顺：Text2SQL 不是一个纯生成问题，而是一个“可控生成”问题。大模型只是其中负责语言转译的引擎，真正决定 SQL 质量的是喂给引擎的上下文，以及生成后的校验环节。SQLBot 的配置方法，本质上是在管理下面这条链路里的每一个节点。

第一个节点是数据源元数据。模型并不知道你数据库里 orders 表代表什么含义，它只能根据表名和字段名去猜。如果你的字段叫 a01、b22，或者注释是空的，那再强的模型也只能瞎猜。SQLBot 在配置阶段最核心的动作，就是清理元数据，把表注释、字段注释、字段类型、枚举值含义都补全。元数据做得越干净，后面所有场景的准确率都会跟着提升。

第二个节点是提示词策略。这里不能只写“你是一名 SQL 专家”就完事，真正有效的提示词要回答三个问题：用户需求对应了哪些表、生成 SQL 时要遵守什么规则、用户如果问得模糊应该怎么办。SQLBot 配置里一般都会有 schema、relations、rules、examples 这些区块，它们其实就是在替模型回答这三个问题。

第三个节点是查询执行和结果校验。模型生成的 SQL 不能直接扔到生产库上去跑，至少要经过一道 SQL 解析器和安全规则检查。比如是否只包含 SELECT、是否命中允许查询的表、是否触发了 DELETE/UPDATE 等危险词。执行结果超时了怎么办、返回行数过多怎么办、SQL 报错后要不要自动重试，这些都属于 SQLBot 的容器化配置，和生产稳定性强相关。

我当时整理过一份三类配置方式的对比，直观感受非常明显：

我个人的经验是，先把这条链路想明白再动手配 SQLBot，比急着堆参数重要得多。配置不是一锤子买卖，而是随着场景复杂度不断补充的过程。

2. 不想在环境上浪费半天时间，先装好这些工具

聊配置之前，必须先说一下运行环境。做这个项目时，团队里有人一台电脑连 JDK 都没有，有人 PyCharm 的 Python 解释器选错导致依赖装了一晚上还是红的，光环境问题就折腾了接近一天。不是说 SQLBot 一定要依赖 Java 和 Python，但排错和扩展的时候两套环境几乎躲不开。

第一套环境是 Java。SQLBot 依赖的服务端骨架、连接池管理、数据源路由，很多实现是基于 JVM 生态的，尤其市面上不少数据中间件都打包成 Jar 或者 Spring Boot 服务。所以 JDK 版本要装对。我自己建议直接装 JDK 11 或 17 的 LTS 版本，别用太老的 JDK 8，也别追最新的 JDK 23，容易出现各种兼容性小毛病。Java 安装教程及环境配置其实就是三板斧：下载安装包、设置 JAVA_HOME 环境变量、把 JAVA_HOME\bin 加入 PATH。装完在终端里执行 java -version 能出版本号就说明没问题。这里容易踩的一个坑是，机器上以前装过老 JDK，PATH 里残留了旧路径，导致新版本怎么都生效不了。我的处理办法是把系统环境变量里的 Java 相关路径全部清理掉，再重新配一遍。

第二套环境是 Python。为什么需要 Python？因为做 Text2SQL 实验时，你需要写脚本快速调模型接口、解析结果、生成测试用例，Python 在这块的效率比 Java 高太多。PyCharm 配置 Python 环境的重点，是给每个项目单独建虚拟环境。用 PyCharm 新建项目时，在 Interpreter 类型里选择 Virtualenv，Base interpreter 指向你安装的 Python 3.10 或 3.11，这样项目之间不会互相污染。很多同学图省事直接用了系统全局 Python，后面装包时权限报错、版本冲突会让人崩溃。还有一个很低级但常见的坑：PyCharm 里明明配置好了环境，Terminal 终端执行命令却提示找不到模块，因为终端没有激活虚拟环境。Windows 下执行 venv\Scripts\activate，macOS/Linux 下执行 source venv/bin/activate，确认终端命令前出现 (venv) 字样再装依赖。

数据库连接依赖也得提醒一句。不要用系统里已有的 MySQL 客户端驱动版本去猜，SQLBot 通过 JDBC 连接数据库时，驱动版本要和数据库版本匹配。比如 MySQL 8.0 建议使用 mysql-connector-j 8.0.x 版本，连接串里最好带 serverTimezone=Asia/Shanghai，否则会因为时区问题报错。用 Python 低代码方式联调时，pymysql 和 SQLAlchemy 是一套常规组合。除此之外，准备一个最小配置文件的思路很实用：

yaml复制datasource:
  url: jdbc:mysql://localhost:3306/retail_db
  username: sqlbot_reader
  password: 你的密码
  driver-class-name: com.mysql.cj.jdbc.Driver

model:
  provider: openai-compatible
  base_url: http://localhost:8000/v1
  api_key: sk-xxx
  model_name: qwen-max
  temperature: 0.1

看到 username 我特别想强调：哪怕是搭建测试环境，也不要直接拿 root 账号给 SQLBot 用。你越早养成这个习惯，之后到安全边界场景时越省心。

3. 场景一：单表单条件查询，先让 SQLBot 跑通最小闭环

配置 Text2SQL，我强烈建议从一个最简场景入手。你不需要一开始就让它处理几十张表的复杂业务，先拿出一张表，比如订单表，把查询跑通。这一步意义不是功能演示，而是验证链路：提问进来之后，模型能不能准确理解字段含义，SQL 能不能通过解析器并成功执行，结果能不能返回给用户。

我当时整理了一张简化版订单表作为测试对象：

text复制orders
- id             订单ID，主键
- user_id        下单用户ID
- ordered_at     下单时间
- total_amount   订单实付金额，单位元
- status         订单状态：paid/completed/refunded/cancelled

这张表在元数据配置里不要只写字段名，字段注释和枚举值说明必须跟上。比如 status 字段，如果不告诉模型 refunded 和 cancelled 都代表订单没有实际成交，用户问“有效订单有多少”，模型可能把 refunded 状态的订单也算进去。SQLBot 的 schema 区块可以这样准备：

yaml复制schema:
  tables:
    - name: orders
      comment: 订单表，一条记录代表一个订单
      fields:
        - name: id
          type: bigint
          comment: 订单ID，主键
        - name: user_id
          type: bigint
          comment: 下单用户ID
        - name: ordered_at
          type: datetime
          comment: 下单时间
        - name: total_amount
          type: decimal(10, 2)
          comment: 订单实付金额，单位为元
        - name: status
          type: string
          comment: 订单状态，paid=已支付、completed=已完成、refunded=已退款、cancelled=已取消

然后定义一个最小提示词规则：

text复制你是一名数据分析师。用户的提问需要用 SQL 在给定表结构中查询。
请只输出可执行的 SQL，不要输出解释。
默认只允许 SELECT 查询。

接下来测试一句话：“5月1日到今天，一共有多少笔支付成功的订单，总金额是多少？”在元数据清晰的条件下，SQLBot 生成的 SQL 基本能符合预期：

sql复制SELECT COUNT(*) AS order_count,
       SUM(total_amount) AS total_amount
FROM orders
WHERE status IN ('paid', 'completed')
  AND ordered_at >= '2025-05-01'
  AND ordered_at < '2025-06-01';

单表场景的几个配置要点，你可以记一下。

第一，temperature 不要设置太高。Text2SQL 是确定性任务，不是创意写作。temperature 高了，模型会在 SQL 写法上增加不必要的变化，很容易把稳定输出变成抽盲盒。我建议设置在 0 到 0.2 之间。

第二，注释里面的业务细节要具体。不要写“订单状态”四个字就结束，要写清楚每个枚举值代表什么含义。很多团队的字段注释停留在“状态”“类型”这种粒度，模型遇到这种字段就只能靠猜。

第三，先不要急着把几十张表全部塞给模型。表一多，模型反而被无关字段干扰，准确率不升反降。SQLBot 通常支持配置允许访问的表清单，先按业务范围圈定几张核心表，等基础效果稳定了再逐步放开。

单表跑通之后的成就感其实不强，但这一步非常有价值。因为它让你确认：模型 API 调用是否正常、数据库连接是否稳定、SQL 解析链路是否通、结果返回格式是否满足前端展示。如果连最小闭环都跑不通，后面所有复杂场景都无从谈起。

4. 场景二：多表 JOIN，关系配置才是高手和新手的分水岭

单表查询稳定之后，很快会碰到真正的硬骨头：多表 JOIN。运营同事不会总问订单表里有什么，他们会问“各区域的销售额排名”“每个品类的复购率”“不同支付方式的订单占比”这类需要跨多张表统计的问题。

多表场景里，模型最容易翻车的点有两个：一是不知道该通过哪个字段关联两张表，容易自己猜出一个根本不存在的关联条件；二是不理解表之间的“粒度”，比如订单表和订单明细表是一对多关系，如果直接用 SUM(orders.total_amount) 和明细表 JOIN 后再汇总，金额会被放大数倍。这个错误非常隐蔽，尤其是数据量大的时候，结果看似合理、实际完全错误。

想要解决这两个问题，不能在提示词里写“请正确 JOIN”，而是要把表关系显式配置给模型。你可以在 SQLBot 的 relations 区域里维护一份关系清单：

yaml复制relations:
  - left_table: orders
    left_field: id
    right_table: order_items
    right_field: order_id
    relation_type: one_to_many
    comment: 一个订单包含多个商品明细行，订单金额不要和明细表JOIN后直接SUM

  - left_table: order_items
    left_field: product_id
    right_table: products
    right_field: id
    relation_type: many_to_one
    comment: 商品明细关联商品主表

  - left_table: orders
    left_field: user_id
    right_table: users
    right_field: id
    relation_type: many_to_one
    comment: 订单表关联用户表

这份关系配置尽量覆盖所有可能 JOIN 到的路径。很多模型跑错 JOIN，并不是模型不会写 JOIN，而是它不知道这两张表之间的业务关系。你把关系说明写清楚，等于把“数据库外键关系”翻译成了自然语言描述，模型的准确率会立刻上一个台阶。

除了关系描述，我还会为常见统计需求配几组 few-shot 样本。所谓 few-shot，就是给模型几个“用户问法→标准 SQL”的示例，让它在生成时模仿示例风格。比如：

text复制用户问题：“5月各品类的销售金额是多少？”
标准SQL：
SELECT p.category, SUM(oi.quantity * oi.price) AS sales_amount
FROM orders o
JOIN order_items oi ON o.id = oi.order_id
JOIN products p ON oi.product_id = p.id
WHERE o.status IN ('paid', 'completed')
  AND o.ordered_at >= '2025-05-01'
  AND o.ordered_at < '2025-06-01'
GROUP BY p.category;

这里的样本刻意避开了直接 SUM(o.total_amount)，就是为了让模型理解：统计销售额要到明细表里去算 SKU 金额汇总，而不是直接用订单表的总额。通过样本告诉模型“怎么算”，比单纯在注释里写“别算错”有效得多。

实践里我再给两个建议。

第一个建议，如果模型经常漏掉中间表，检查一下关系配置是否覆盖完整。比如订单和品类之间没有直接外键，中间隔了 order_items 和 products，那你可以在关系描述里写明“订单关联商品明细，商品明细关联商品，商品属于某个品类”，模型才能真正理解这条 JOIN 路径。

第二个建议，要在提示词规则里明确“先确认粒度，再写聚合”。一对多 JOIN 会把结果行数放大，涉及 COUNT 的时候要思考是否需要 COUNT(DISTINCT ...)。下面这类约束就很实用：

text复制如果用户想统计订单数，并且查询涉及订单明细表，优先使用 COUNT(DISTINCT orders.id)，避免一对多JOIN导致订单数被放大。

这类约束不是数学公式，而是你用经验总结出来的业务规则。SQLBot 配置到后面，其实就是在不断沉淀这种规则。配置越接近业务，模型的表现越稳定。

5. 场景三：复杂业务口径，用“口径字典”而不是让模型自行发挥

单表和多表都稳定之后，更大的挑战来了：业务口径。这类问题有个典型特征——用户说的每个字你都能听懂，但组合在一起你不知道该怎么算。

举个例子：“统计上个月的有效订单金额。”什么叫“有效”？不同公司定义完全不同，可能是排除退款后的订单，可能是剔除内部测试订单，也可能是只要支付成功的订单都算。模型不知道这些规则，它只会从字面上理解“有效=status正常”。当用户的业务口径和默认理解不一致，结果就错了。

面对这种情况，我采用的配置方法是给 SQLBot 建立“口径字典”，也就是 business_terms 区块。把团队里约定俗成的业务名词和计算定义全部显式写进配置：

yaml复制business_terms:
  有效订单:
    definition: 订单状态为 paid 或 completed，且订单来源不是内部测试渠道，剔除 refunded 和 cancelled
  销售额:
    definition: 基于订单明细行的成交数量和实际成交单价计算，即 SUM(quantity * price)
  新客:
    definition: 该用户首次支付订单发生在统计周期内
  复购用户:
    definition: 统计周期内至少产生两笔有效订单的用户

然后在系统提示词里加一段规则：

text复制如果用户提问中出现了业务术语，请优先从“业务口径字典”中查找对应定义。
如果口径字典中没有定义，不要自行假设业务含义，请向用户澄清后再生成SQL。

这套机制的作用，不是让模型学会某个指标的写法，而是让模型在语义理解阶段就受到约束，避免自由发挥。我见过太多 Text2SQL 项目，前期模型效果不错，一上业务问答就崩，原因就是没有让模型意识到“业务词汇是有标准定义的，不能自己想当然”。

除了口径字典，我还会配置“预检查规则”。在读取用户问题之后、生成 SQL 之前，先让模型对问题做一层简单分类。比如问题涉及“时间对比”，生成 SQL 时要包含两个时间范围；问题涉及“排名”，要思考是用 ORDER BY 还是窗口函数；问题涉及“首次”，要确认是否需要子查询定义首次时间。示例写法如下：

text复制要求：
1. 用户问题中出现“首次”“最近”“最新”等词汇时，先判断是否存在隐含的子查询。
2. 涉及“占比”“环比”“同比”时，注意分子和分母的时间范围一致性。
3. SQL 必须能被数据库执行，不允许输出模型凭空想象的技术字段。

业务口径还有一个实践，是让 SQLBot 生成的 SQL 自带注释。比如在 SELECT 字段后面直接写上指标口径来源：

sql复制SELECT COUNT(DISTINCT u.id) AS new_customer_count  -- 口径：首次支付订单时间在统计周期内
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.status IN ('paid', 'completed')
  AND o.first_paid_at >= '2025-05-01'
  AND o.first_paid_at < '2025-06-01';

这样做的好处是，业务方拿到结果后能直接确认是不是自己理解的口径，不会出现“数看起来对、其实算法不是我们想要”的情况。

6. 场景四：敏感数据与查询边界，安全配置不是上线前才做的事

配置 Text2SQL 时，安全往往是被放到最后才考虑的问题，但实际上，它是需要一开始就刻进架构里的。原因很简单：模型生成的 SQL 天然具有不可控性，即使前面几层配置做得很好，也不能保证每一次输出都符合预期。如果 SQLBot 连接的是一个高权限账号，一次异常 SQL 就可能对整个数据库产生不可挽回的影响。

我在项目里把安全划分为三层。

第一层是数据库账号权限隔离。SQLBot 运行服务应该使用只读账号，并且账号只允许访问业务需要的库表。这个账号不应该有 DELETE、UPDATE、INSERT、DROP 等写权限。数据库层面的限制，比任何应用层过滤都可靠。你可以单独建一个账号：

sql复制CREATE USER 'sqlbot_ro'@'%' IDENTIFIED BY 'xxxx';
GRANT SELECT ON retail_db.* TO 'sqlbot_ro'@'%';

只给 SELECT 权限，是从根上防范风险。就算模型被精心构造的提示词诱导生成 DELETE 语句，数据库也会因为权限不足拒绝执行。

第二层是应用层 SQL 预检查。在 SQLBot 执行模型生成的 SQL 之前，用解析器先对 SQL 做一次静态检查。重点检查内容可以列成一张清单：SQL 是否只包含 SELECT；是否出现被禁止的关键词；FROM 中的表是否在允许查询的名单内；SELECT 字段是否包含敏感字段；是否带有自动追加的 LIMIT。配置样例可以这样写：

yaml复制security:
  read_only: true
  banned_statements:
    - delete
    - update
    - insert
    - drop
    - alter
    - truncate
  allowed_tables:
    - orders
    - order_items
    - users
    - products
  blocked_columns:
    - name: users.phone
      action: deny
    - name: orders.payment_info
      action: redact
  max_return_rows: 500
  timeout_seconds: 15

第三层是查询行为限制。即使所有 SQL 都是 SELECT，也要防止它把整个数据库拖垮。比如用户问“统计所有用户的消费金额”，SQLBot 可能生成没有过滤条件的全表扫描，数据量几个亿时很容易把数据库连接池打满。所以我在配置里给查询执行加了几条兜底：默认超时 15 秒；每次查询最大返回行数 500；超过一定扫描行数就终止执行。部分 SQLBot 还支持把大查询自动路由到只读从库，避免影响在线业务。

安全配置最容易忽略的是“字段级敏感信息”。有一次业务同事在测试环境问“把用户手机号导出给我”，模型立刻生成 SELECT phone FROM users。这个 SQL 本身没有语法问题，还很快执行成功了。但手机号并不应该让每个使用 SQLBot 的人都能查到。我在 blocked_columns 里把手机号列设为 deny，并为这类请求配置了友好返回话术：“当前账号没有权限查看手机号字段，如需使用请联系数据管理员。”如果你需要展示脱敏后的手机号，也可以配置成 redact 模式，让模型生成 CONCAT(LEFT(phone,3), '****', RIGHT(phone,4)) 这种脱敏表达式。

SQLBot 里的安全配置其实可以写成一张“规则-现象-兜底”的对应表来检查自己是否覆盖完全。我个人的验收标准是：哪怕某一天提示词被人恶意篡改，数据库也不会出现写操作，敏感字段也无法被批量拉取，大查询也会被资源限制挡住。只有做到这一层，我才敢把 SQLBot 开放给内部业务同学用。

7. 场景五：从“查得对”到“答得稳”，后处理与调优配置

前四个场景如果都跑顺了，说明模型已经能把大部分查询转换成可用 SQL。但你会发现，真正到了生产环境，零零碎碎的问题仍然层出不穷。模型偶尔会把 SQL 包在一个 Markdown 代码块里，解析器直接取不到；查询可能因为一次网络抖动执行超时，用户看到的是一个难看的报错；同一句提问，第一次跑成功了，第二次模型换了一种写法，SQL 直接语法错误。让 SQLBot 从“能查”变成“稳定可查”，还需要配置后处理和错误恢复逻辑。

先说说输出解析。很多模型在生成 SQL 时会习惯性加上 Markdown 标记，如果你直接拿原文去执行，必然报错。我的做法是配置一个强制性的 SQL 提取器，只提取代码块里的 SQL 内容；如果模型没有用代码块，就取第一个 SELECT 关键字到结尾的文本。然后再交给解析器做语法解析。这个步骤不起眼，却能挡掉非常多低级的执行错误。

再来看失败重试机制。SQLBot 生成的 SQL 第一次执行失败时，不应直接把异常反馈给用户，而是把报错信息返回给模型，让它自己修正一次。这种“自我修正”机制在实测中对 SQL 语法错误尤其有效。例如模型把保留字当成了字段名：

text复制第一次SQL：SELECT name FROM order WHERE ...
数据库报错：Unknown column 'name' in 'field list'
修正提示：用户想查询订单表中的客户名称，但该表没有 name 列，请根据表结构选择合适的字段。
第二次SQL：SELECT customer_name FROM orders WHERE ...

这个机制挺香，但不能无限重试，否则遇到模型反复生成错误 SQL 时，响应速度会变得不可接受。我一般设置为最多重试 2 次，超过次数就返回“暂时无法解答，请换个说法或联系管理员”。

结果为空和结果过大的处理也要提前想好。用户问“上个月这个城市的订单量”可能一个月前该城市还没有业务，SQL 执行成功但是结果集为空。这时候如果只返回一个空表格，用户会怀疑工具坏了。我在 SQLBot 后处理里增加了一个空结果解释开关，如果查询结果为空，则基于查询条件和生成 SQL 的上下文生成一句话解释，比如“没有查询到 2025 年 4 月深圳地区的订单数据，可能是该期间内无有效订单或订单状态已变更。”这样一来，用户至少知道系统是正常工作的。

关于缓存，也值得配置一下。业务同事经常会在短时间内反复查同一个问题，比如“昨天的支付金额是多少”，实际上数据可能一天才更新一次。对这种高频且数据变化不敏感的查询，加一个 5 到 15 分钟的缓存可以明显降低数据库压力。注意缓存 key 不能直接用用户原文，最好用“规范化后的语义表达式”或者 MD5 后的模型提示词，否则相近但不同的问法每次都会穿透缓存。

下面这个配置文件片段展示了我常用的后处理参数：

yaml复制post_processing:
  extract_sql_from_markdown: true
  on_error:
    retry_enabled: true
    max_retries: 2
    retry_prompt: "上一次生成的SQL执行失败，请根据数据库报错修正SQL，只输出修正后的SQL。"
  on_empty_result:
    explain_enabled: true
  cache:
    enabled: true
    ttl_seconds: 600
  result_formatter: markdown_table

还有一个务实习惯：把每次失败的提问和模型生成结果记录到日志或数据表里，每周或者每两周集中复盘一次。你会发现很多问题不是偶发的，而是某一类字段注释缺失、某一个业务术语没有进口径字典、某一种问法常被模型误解。把这些 badcase 结构化出来，反哺到元数据和样本配置里，是让 Text2SQL 效果持续变好的最重要路径。

8. 问题排查复盘：那几个高频报错和对应的定位思路

最后一部分，我干脆把这段时间遇到过的高频问题按现象归类，写成一个快速排查的思路，希望你能少走弯路。

第一个高频现象是“模型生成了不存在的字段”。比如用户问某个商品分类，模型却给出一个并不存在的 category_name。这种问题八成不是模型智商问题，而是元数据不完整。如果 products 表里的字段实际叫 product_category，但注释没有写清楚，模型只能根据“分类”这个语义自行构造字段名。排查思路很简单：把模型输出的 SQL 里涉及的字段名，逐一到元数据表里去比对，凡是查不到的，去补注释。不要先去怪模型。

第二个高频现象是“JOIN 查询结果翻倍”。销售问的是“订单数量”，模型 JOIN 了订单明细表之后用 COUNT(*)，结果订单数膨胀了几十倍。这种问题的根因就是粒度理解不够，没有把关系类型和 COUNT DISTINCT 规则告诉模型。排查时去看 SQL 中关联的表是否包含一对多关系，然后补上 COUNT(DISTINCT 主表.id) 的规则说明。

第三个高频现象是“同一个问题，模型时对时错”。这种间歇性不稳定通常和 temperature 设置有关，或者模型本身的采样随机性太大。先检查 temperature，把它调到 0.1 或者 0；再检查是否存在缓存命中导致旧模式时好时坏的问题。如果还是不稳，那就可能提示词里缺少足够明确的约束，需要从“生成规则”里补充要求。

第四个高频现象是“查询跑很久然后超时”。模型生成的 SQL 本身没错，但没有加 LIMIT，也没有针对索引字段加过滤条件，执行计划走了全表扫描。SQLBot 层面可以先配置强制 LIMIT，但更本质的解法是优化 SQL 或提示模型使用分区字段作为过滤条件。

我整理成表，方便对照：

虽然这里给了一个对照表，但真正的排查过程并不是按图索骥那么轻松。我记得有一次某个指标在周五突然大面积报错，我先是怀疑模型配置被调乱了，后来反复看了快一个小时才发现是表结构发生变化，某个字段改了名，但 SQLBot 缓存里的元数据没有刷新，导致所有涉及这个字段的查询全部失败。这个坑也提醒我，数据表结构变更后，第一时间要做的不是刷新页面，而是清除元数据缓存、召回 SQLBot 的表结构信息。所以我把“元数据刷新机制”也纳入了日常运维清单，数据模型变更的公告里一定要同步给 SQLBot 维护方。

多说一句，Text2SQL 是典型的“配置工程”大于“模型工程”的方向。遇到问题先想是不是元数据没喂够、关系没描述清楚、规则没约束住，而不是急着换更大更强的模型。我踩过一次很深的坑：为了提升准确率，把一个中等规模模型换成了当时最强的大参数模型，结果效果提升有，但成本明显增加，而且原本的 JOIN 问题并没有实质改善。后来把关系配置补齐，弱模型也能跑出不错的效果。这也让我更坚信一个判断：SQLBot 配置的核心价值，就是让大模型少一点“自由发挥”，多一点“照章办事”，在确定性的任务里追求确定性的结果。