Text2SQL 实战:Java 让大模型安全查库
摘要: Text2SQL 不是一句 prompt 就完事。本文用 Spring AI 搭一条完整链路:把表结构喂给模型、生成 SQL、做安全校验、执行,再把数据库报错回灌给模型重试。附只读账号、超时、行数限制和选型建议。
运营在群里问:「上个月华东区退款金额最高的三个品类是什么?」数据团队排期排到下周。你想着接个大模型,让它直接查库,半小时就能做完。demo 跑通了,上线第一天就出问题:模型编了个不存在的字段,还把一张 800 万行的订单表全表扫了一遍,数据库 CPU 直接拉满。这篇文章解决的就是这件事:怎么让大模型查库,既查得对,又不会把库搞挂。
一、这个问题到底是什么
结论:Text2SQL 的难点不在生成 SQL,而在让这条 SQL 安全、正确地跑在你的库上。
先把角色分清楚。大模型不连数据库,它只做一件事:看着你给的表结构,把「上个月退款最多的品类」翻译成一串 SQL 文本。真正执行这条 SQL 的,是你 Java 代码里的 JdbcTemplate。
这意味着模型可以胡说,而你的代码会当真。中间没有编译器,没有类型检查,没有权限提示。它写 pay_amount,你库里叫 amount,SQL 直接报错;它忘了写 LIMIT,你的从库就开始冒烟。
demo 很惊艳,上线就翻车
网上的 Text2SQL 示例,通常长这样:一张 users 表,三个字段,问「有多少用户」,模型写 SELECT COUNT(*) FROM users。当然准。
真实环境是另一回事:
- 库里有 60 张表,表名还带业务前缀,
t_order_main、biz_refund_record。 - 字段注释是十年前写的,
flag后面跟着「是否有效(1 是 0 否,但历史数据有 2)」。 - 同一个「金额」,订单表叫
total_amount,退款表叫refund_fee,还一个存分、一个存元。 - 数据库账号是读写账号,模型哪天真写出
UPDATE,你连后悔的时间都没有。
三个必须解决的问题
字段幻觉。 模型会按训练语料里的常见表结构补全字段名。你的表越不标准,它编得越起劲。
查询失控。 没有 LIMIT 的 SELECT *,加上一个 LIKE '%关键词%',足够让小库卡住。大表还能把连接池占满。
权限越界。 多租户系统里,A 公司的运营问一句「所有订单」,模型可能真的生成不带 tenant_id 的 SQL。
一个可执行的验收标准
别用「感觉挺准」来评估。准备 20 个真实业务问题,每个问题人工写好标准答案,然后记录三件事:
- SQL 一次执行成功率;
- 查询结果和标准答案是否一致;
- 从提问到返回的 P95 耗时。
三个数字都达标,再谈上线。第一版能做到 70% 可用,已经算不错,剩下的靠 schema 注释和错误回灌慢慢补。
二、底层原理到底怎么回事
结论:把 Text2SQL 当成「翻译 + 编译检查 + 运行反馈」三段流水线,而不是一次问答。
模型看到的只有你给的 schema
大模型对这个库的全部认知,来自你塞进 prompt 的那段表结构。你给什么,它知道什么;你没给的,它靠猜。
所以 schema 不是随便 SHOW CREATE TABLE 一下就完事。有用的信息包括:
- 表名、列名、数据类型;
- 列的 COMMENT,最好写成业务语言;
- 枚举字段的全部取值,比如
status: paid/refunded/cancelled; - 今天日期,以及「上个月」「最近 7 天」按哪个时区算;
- 哪些字段是金额、单位是元还是分。
列注释的价值被严重低估。status VARCHAR(20) 模型只能猜,status VARCHAR(20) -- 订单状态:paid 已支付 / refunded 已退款 / cancelled 已取消 模型基本不会用错。
代价是 token。一张 20 列的表,描述完大概 300 到 500 token;十张表就是三五千 token。每次提问都带一遍,成本不低。后面会讲怎么按业务域裁剪。
模型为什么会编字段
它本质是在做概率补全。训练数据里大量出现 id、user_id、created_at、amount,于是它默认你的表也长这样。你的字段叫 payable_amount,它照样写 amount,因为这样「最顺」。
三种补救手段,建议全上:
- 只给真实 schema,别给示例,别让它自由发挥;
- 生成后校验列名,拿
information_schema.columns对一遍,不存在的列直接打回; - 执行报错回灌,把数据库的
Unknown column 'amount' in 'field list'原样丢回给模型,让它改。
第三条最有效。模型看到真实报错,比你说十遍「不要编字段」都管用。
一次性生成和工具循环的区别
一次性生成像闭卷考试:模型看完题,写完交卷,对不对听天由命。
工具循环像开卷考试,还允许重做:模型可以先调 describeSchema 看字段,再调 runQuery 执行,报错了拿着错误信息改一版再跑。Spring AI 的 @Tool 就是干这个的。
代价很直接。一次生成只调一次模型,工具循环通常要 2 到 5 次,延迟翻倍,token 也翻倍。内部工具可以接受,面向 C 端的高并发接口就要掂量。
安全要三道门,缺一不可
第一道,数据库账号。 给 Text2SQL 单独开一个只读账号,只授权 SELECT,只给业务库,不给系统库。这是最后一道门,也是唯一一道模型绕不过去的门。
第二道,应用层 SQL 校验。 只允许 SELECT 和 WITH 开头,禁止多语句、注释、DDL、INTO OUTFILE、SLEEP 这类东西。它防的是模型手滑和 prompt 注入,不是专业黑客。真要被攻破,靠的还是第一道门。
第三道,执行层限制。 强制 LIMIT,设置 queryTimeout 和 maxRows,最好再走只读从库。这三样是保命的,别省。
结果总结也会幻觉
SQL 查出来 37 行,模型总结时写成「共 42 条」。这种事很常见,因为它在「复述数字」时又做了一次概率生成。
办法很简单:数字在 Java 里算好,模型只负责解释。或者明确告诉它「只能引用结果里出现的数字,不要做任何加减乘除」。结果行数也要截断,几百行 JSON 塞进去,既贵又容易让它看花眼。
三、实战:手把手写代码
结论:先跑通「生成 → 校验 → 执行 → 总结」的最小链路,再加工具循环,最后补权限和审计。
3.1 依赖和配置
pom.xml 如下。模型走 OpenAI 兼容协议,这里以 DeepSeek 为例,换成通义、豆包、OpenAI 只改 base-url 和 model。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.1</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>text2sql-demo</artifactId>
<version>1.0.0</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>4.1.1</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
<version>4.1.1</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
<version>2.0.1</version>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<version>26.7.0</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<version>4.1.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.1</version>
</plugin>
</plugins>
</build>
</project>
配置文件里,base-url 指向 OpenAI 兼容网关,temperature 设 0,尽量让每次生成稳定。数据库账号必须是只读账号,不要图省事用 root。
server:
port: 8080
spring:
datasource:
url: jdbc:mysql://localhost:3306/shop?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
username: readonly
password: readonly_pwd
hikari:
maximum-pool-size: 10
ai:
openai:
api-key: ${DEEPSEEK_API_KEY}
base-url: https://api.deepseek.com
chat:
options:
model: deepseek-chat
temperature: 0
建库脚本也贴上,三张表,带中文注释。注释就是模型理解业务的地图,别省。
CREATE DATABASE IF NOT EXISTS shop DEFAULT CHARACTER SET utf8mb4;
USE shop;
CREATE TABLE products (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '商品ID',
name VARCHAR(100) NOT NULL COMMENT '商品名称',
category VARCHAR(50) NOT NULL COMMENT '品类:手机/电脑/配件',
price DECIMAL(10,2) NOT NULL COMMENT '售价,单位元'
) COMMENT '商品表';
CREATE TABLE orders (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '订单ID',
user_id BIGINT NOT NULL COMMENT '用户ID',
tenant_id BIGINT NOT NULL COMMENT '租户ID,华东=1,华南=2',
status VARCHAR(20) NOT NULL COMMENT '订单状态:paid 已支付 / refunded 已退款 / cancelled 已取消',
total_amount DECIMAL(12,2) NOT NULL COMMENT '订单金额,单位元',
created_at DATETIME NOT NULL COMMENT '下单时间'
) COMMENT '订单主表';
CREATE TABLE order_items (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '明细ID',
order_id BIGINT NOT NULL COMMENT '订单ID',
product_id BIGINT NOT NULL COMMENT '商品ID',
quantity INT NOT NULL COMMENT '购买数量',
item_amount DECIMAL(12,2) NOT NULL COMMENT '明细金额,单位元'
) COMMENT '订单明细表';
INSERT INTO products (name, category, price) VALUES
('iPhone 17', '手机', 5999.00),
('MacBook Air', '电脑', 8999.00),
('USB-C 充电线', '配件', 79.00);
INSERT INTO orders (user_id, tenant_id, status, total_amount, created_at) VALUES
(1001, 1, 'paid', 5999.00, '2026-09-03 10:12:00'),
(1002, 1, 'refunded', 8999.00, '2026-09-08 14:30:00'),
(1003, 2, 'paid', 158.00, '2026-09-15 09:05:00'),
(1004, 1, 'refunded', 5999.00, '2026-09-21 20:41:00'),
(1005, 2, 'paid', 8999.00, '2026-10-02 11:20:00');
INSERT INTO order_items (order_id, product_id, quantity, item_amount) VALUES
(1, 1, 1, 5999.00),
(2, 2, 1, 8999.00),
(3, 3, 2, 158.00),
(4, 1, 1, 5999.00),
(5, 2, 1, 8999.00);
3.2 最小链路:生成、校验、执行、总结
先解决两个基础设施。JdbcTemplate 统一加上超时和最大行数,这样即使模型漏了 LIMIT,JDBC 层也只取 200 行。
package com.example.text2sql;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;
import javax.sql.DataSource;
@Configuration
public class JdbcConfig {
@Bean
public JdbcTemplate jdbcTemplate(DataSource dataSource) {
JdbcTemplate template = new JdbcTemplate(dataSource);
template.setQueryTimeout(5);
template.setMaxRows(200);
template.setFetchSize(50);
return template;
}
}
SchemaProvider 负责把 information_schema 里的真实结构拼成一段给模型看的文字。注意它读的是数据库元数据,不是手写的 JSON,这样表结构变了不用改代码。
package com.example.text2sql;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
@Component
public class SchemaProvider {
private final JdbcTemplate jdbcTemplate;
public SchemaProvider(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public String describe(List<String> tables) {
if (tables == null || tables.isEmpty()) {
throw new IllegalArgumentException("至少指定一张表");
}
String placeholders = tables.stream().map(t -> "?").collect(Collectors.joining(","));
String sql = """
SELECT table_name AS tableName,
column_name AS columnName,
data_type AS dataType,
column_comment AS columnComment
FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name IN (%s)
ORDER BY table_name, ordinal_position
""".formatted(placeholders);
List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql, tables.toArray());
Map<String, StringBuilder> byTable = new LinkedHashMap<>();
for (Map<String, Object> row : rows) {
String table = String.valueOf(row.get("tableName"));
String column = String.valueOf(row.get("columnName"));
String type = String.valueOf(row.get("dataType"));
Object commentValue = row.get("columnComment");
String comment = commentValue == null ? "" : String.valueOf(commentValue);
StringBuilder builder = byTable.computeIfAbsent(
table, key -> new StringBuilder("表 ").append(key).append(":\n"));
builder.append(" - ").append(column).append(" ").append(type);
if (!comment.isBlank()) {
builder.append(" -- ").append(comment);
}
builder.append("\n");
}
return byTable.values().stream()
.map(StringBuilder::toString)
.collect(Collectors.joining("\n"));
}
}
SqlGuard 是应用层的门。它干四件事:去掉 markdown 代码块、去掉注释、拒绝多语句和非查询语句、补上或压低 LIMIT。
package com.example.text2sql;
import org.springframework.stereotype.Component;
import java.util.Locale;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@Component
public class SqlGuard {
private static final int MAX_ROWS = 200;
private static final Set<String> BLOCKED_WORDS = Set.of(
"insert", "update", "delete", "drop", "alter", "truncate",
"create", "grant", "revoke", "replace", "merge", "call",
"execute", "load_file", "outfile", "dumpfile", "sleep",
"benchmark", "information_schema", "performance_schema",
"mysql", "sys"
);
private static final Pattern CODE_FENCE =
Pattern.compile("^\\x60{3}[a-zA-Z]*\\s*|\\s*\\x60{3}$");
private static final Pattern COMMENTS =
Pattern.compile("(--[^\\n]*|/\\*.*?\\*/)", Pattern.DOTALL);
private static final Pattern LIMIT =
Pattern.compile("(?i)\\blimit\\s+(\\d+)");
private static final Pattern BLOCKED = Pattern.compile(
"\\b(" + String.join("|", BLOCKED_WORDS) + ")\\b", Pattern.CASE_INSENSITIVE);
public String check(String rawSql) {
if (rawSql == null || rawSql.isBlank()) {
throw new IllegalArgumentException("模型没有返回 SQL");
}
String sql = CODE_FENCE.matcher(rawSql.trim()).replaceAll("");
sql = COMMENTS.matcher(sql).replaceAll(" ").trim();
while (sql.endsWith(";")) {
sql = sql.substring(0, sql.length() - 1).trim();
}
if (sql.contains(";")) {
throw new IllegalArgumentException("只允许单条语句");
}
String lower = sql.toLowerCase(Locale.ROOT);
if (!lower.startsWith("select") && !lower.startsWith("with")) {
throw new IllegalArgumentException("只允许 SELECT 或 WITH 开头的查询");
}
Matcher blocked = BLOCKED.matcher(sql);
if (blocked.find()) {
throw new IllegalArgumentException("SQL 含禁用关键字:" + blocked.group(1));
}
if (lower.contains("for update") || lower.contains("lock in share mode")) {
throw new IllegalArgumentException("不允许加锁读");
}
Matcher limit = LIMIT.matcher(sql);
if (limit.find()) {
int current = Integer.parseInt(limit.group(1));
if (current > MAX_ROWS) {
sql = sql.substring(0, limit.start())
+ "limit " + MAX_ROWS
+ sql.substring(limit.end());
}
} else {
sql = sql + " limit " + MAX_ROWS;
}
return sql;
}
}
QueryPlan 是模型输出的结构。用 record 加 JsonPropertyDescription,Spring AI 会把它转成 JSON Schema 塞进提示词,模型返回的 JSON 再反序列化成对象。
package com.example.text2sql;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
public record QueryPlan(
@JsonPropertyDescription("一条 MySQL 方言的只读 SELECT 语句,不要带 markdown 代码块,不要带分号")
String sql,
@JsonPropertyDescription("把用户问题拆成查询条件的一句话说明")
String reasoning
) {
}
核心服务把四步串起来。注意系统提示词里写了「今天是哪天」,这比让模型自己算日期靠谱得多。
package com.example.text2sql;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
@Service
public class Text2SqlService {
private static final String SYSTEM_PROMPT = """
你是 MySQL 数据分析师。根据给定的表结构,把用户问题翻译成一条 SELECT 语句。
规则:
1. 只能使用表结构里真实存在的表和列,禁止猜测字段名。
2. 只生成一条语句,只能是 SELECT 或 WITH 开头。
3. 时间范围用 MySQL 函数表达,今天是 %s。
4. 金额字段单位是元,不要做汇率换算。
5. 不确定用户指哪个字段时,选注释最贴近的那个,并在 reasoning 里说明。
6. 不要输出 markdown 代码块,sql 字段只放裸 SQL。
""";
private final ChatClient chatClient;
private final SchemaProvider schemaProvider;
private final SqlGuard sqlGuard;
private final JdbcTemplate jdbcTemplate;
public Text2SqlService(ChatClient.Builder builder,
SchemaProvider schemaProvider,
SqlGuard sqlGuard,
JdbcTemplate jdbcTemplate) {
this.chatClient = builder.build();
this.schemaProvider = schemaProvider;
this.sqlGuard = sqlGuard;
this.jdbcTemplate = jdbcTemplate;
}
public Answer ask(String question, List<String> tables) {
String schema = schemaProvider.describe(tables);
QueryPlan plan = chatClient.prompt()
.system(SYSTEM_PROMPT.formatted(LocalDate.now()))
.user(u -> u.text("""
表结构:
{schema}
用户问题:{question}
""")
.param("schema", schema)
.param("question", question))
.call()
.entity(QueryPlan.class);
String sql = sqlGuard.check(plan.sql());
List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql);
String answer = explain(question, sql, rows);
return new Answer(sql, rows, answer);
}
private String explain(String question, String sql, List<Map<String, Object>> rows) {
String data = rows.isEmpty() ? "查询结果为空" : rows.toString();
if (data.length() > 4000) {
data = data.substring(0, 4000) + "...(已截断)";
}
return chatClient.prompt()
.system("""
你是数据分析师。根据 SQL 和查询结果回答用户问题。
只解释结果,不要重新计算数字,不要编造结果里没有的数据。
结果为空就直接说没查到,并给出一个可能的原因。
回答控制在 120 字以内。
""")
.user(u -> u.text("问题:{question}\nSQL:{sql}\n结果:{data}")
.param("question", question)
.param("sql", sql)
.param("data", data))
.call()
.content();
}
public record Answer(String sql, List<Map<String, Object>> rows, String answer) {
}
}
一个 REST 接口把它暴露出去。默认只允许三张表,别让前端随便传表名。
package com.example.text2sql;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
@RequestMapping("/api/text2sql")
public class Text2SqlController {
private final Text2SqlService text2SqlService;
public Text2SqlController(Text2SqlService text2SqlService) {
this.text2SqlService = text2SqlService;
}
public record AskRequest(String question, List<String> tables) {
}
@PostMapping("/ask")
public Text2SqlService.Answer ask(@RequestBody AskRequest request) {
if (request.question() == null || request.question().isBlank()) {
throw new IllegalArgumentException("question 不能为空");
}
List<String> tables = request.tables() == null || request.tables().isEmpty()
? List.of("orders", "order_items", "products")
: request.tables();
return text2SqlService.ask(request.question(), tables);
}
}
跑起来之后,这样调:
curl -s http://localhost:8080/api/text2sql/ask \
-H 'Content-Type: application/json' \
-d '{"question":"上个月退款订单的总金额是多少"}'
返回里会带 sql、rows 和一段人话 answer。先把 sql 打出来看一眼,这是排查问题最有效的手段。
3.3 工具循环:让模型自己看报错、改 SQL
最小链路的问题是一锤子买卖。字段错了,接口直接 500,用户只看到「系统繁忙」。
把查库能力包成工具,模型就能自己重试。describeSchema 让它先确认字段,runQuery 返回结果或错误信息。
package com.example.text2sql;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;
import java.util.StringJoiner;
@Component
public class DbQueryTools {
private final JdbcTemplate jdbcTemplate;
private final SqlGuard sqlGuard;
private final SchemaProvider schemaProvider;
public DbQueryTools(JdbcTemplate jdbcTemplate,
SqlGuard sqlGuard,
SchemaProvider schemaProvider) {
this.jdbcTemplate = jdbcTemplate;
this.sqlGuard = sqlGuard;
this.schemaProvider = schemaProvider;
}
@Tool(description = "查看指定表的字段结构。参数是逗号分隔的表名,例如 orders,order_items")
public String describeSchema(String tables) {
List<String> tableList = List.of(tables.split("\\s*,\\s*"));
return schemaProvider.describe(tableList);
}
@Tool(description = "执行一条只读 SELECT 查询,返回 CSV 文本,最多 50 行。SQL 使用 MySQL 方言,不要加 markdown 代码块")
public String runQuery(String sql) {
try {
String safeSql = sqlGuard.check(sql);
List<Map<String, Object>> rows = jdbcTemplate.queryForList(safeSql);
if (rows.isEmpty()) {
return "查询成功,但没有数据";
}
Map<String, Object> first = rows.get(0);
StringBuilder result = new StringBuilder(String.join(",", first.keySet())).append("\n");
int count = 0;
for (Map<String, Object> row : rows) {
if (count++ >= 50) {
break;
}
StringJoiner line = new StringJoiner(",");
for (String key : first.keySet()) {
Object value = row.get(key);
line.add(value == null ? "" : String.valueOf(value));
}
result.append(line).append("\n");
}
return result.toString();
} catch (Exception e) {
return "SQL 执行失败:" + e.getMessage() + "。请检查字段名、函数和语法,修正后重试。";
}
}
}
Agent 服务只负责给规则,重试逻辑交给模型和 Spring AI 的工具调用循环。
package com.example.text2sql;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
@Service
public class Text2SqlAgent {
private final ChatClient chatClient;
private final DbQueryTools dbQueryTools;
public Text2SqlAgent(ChatClient.Builder builder, DbQueryTools dbQueryTools) {
this.chatClient = builder.build();
this.dbQueryTools = dbQueryTools;
}
public String ask(String question) {
return chatClient.prompt()
.system("""
你是电商数据分析师,可以调用工具查库。
工作方式:
1. 先用 describeSchema 确认字段,再写 SQL。
2. 用 runQuery 执行。SQL 报错就把错误信息当成线索改 SQL,最多重试 3 次。
3. 只查 orders、order_items、products 三张表。
4. 回答给业务同学看:先给结论,再给关键数字,不要贴 SQL。
5. 数据为空就说没查到,不要编。
""")
.user(question)
.tools(dbQueryTools)
.call()
.content();
}
}
把它接到接口上,就是一个会自我纠错的查询入口:
package com.example.text2sql;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequestMapping("/api/text2sql")
public class Text2SqlAgentController {
private final Text2SqlAgent text2SqlAgent;
public Text2SqlAgentController(Text2SqlAgent text2SqlAgent) {
this.text2SqlAgent = text2SqlAgent;
}
public record AgentRequest(String question) {
}
@PostMapping("/agent")
public Map<String, String> ask(@RequestBody AgentRequest request) {
if (request.question() == null || request.question().isBlank()) {
throw new IllegalArgumentException("question 不能为空");
}
return Map.of("answer", text2SqlAgent.ask(request.question()));
}
}
两个接口的差别要心里有数:/ask 一次模型调用,快、便宜、错就错;/agent 两到五次调用,慢、贵、但能自己修正。内部工具用后者,对外接口用前者加人工兜底。
四、踩坑经验和最佳实践
结论:Text2SQL 的效果,八成取决于 schema 和边界,两成取决于模型。
schema 不是越全越好。 我见过把整个库几十张表全塞进去的做法,token 烧得快,模型还容易被相似表名带偏。按业务域分组,一次只给 3 到 8 张表。用户问订单,就别给商品库存表。
列注释要写人话,还要写枚举。 type TINYINT 等于没说。写成 type TINYINT -- 订单类型:1 普通 / 2 预售 / 3 虚拟,准确率立刻不一样。历史脏数据也要写进去,比如「有 2 表示已删除,统计时要过滤」。
别让模型算日期。 「上个月」对模型是个模糊概念,它可能按训练数据的时间算。把 LocalDate.now() 写进系统提示词,再明确时区。跨月、闰年这些事,交给数据库函数。
LIMIT 一定要双保险。 应用层补 LIMIT,JDBC 层设 maxRows,数据库账号再配 MAX_EXECUTION_TIME。三层里任何一层失效,另外两层还能兜住。
SQL 校验别做成正则地狱。 简单场景用关键字黑名单够用,复杂 SQL 建议上 JSqlParser 做 AST 校验,至少能准确判断是不是单条 SELECT。自己写正则判断嵌套查询,迟早漏。
行级权限不要交给模型。 多租户场景,正确做法是给每个租户建视图,或者在 SQL 外面套一层 WHERE tenant_id = ?,参数从登录态取。让模型「记得加 tenant_id」,等于把安全交给运气。
结果总结只让它解释,不让它计算。 总数、平均值、环比,在 Java 里算完再给它。模型负责把数字翻译成人话,这个它擅长。
留审计日志。 每次记录:谁问的、问题原文、生成的 SQL、是否被 guard 拦截、执行耗时、返回行数。出问题时,这份日志比任何监控都管用。
给高频问题留后门。 Top 20 的问题,直接配 SQL 模板,不走模型。又快又准,还省钱。模型只处理长尾。
别把整段对话历史塞进 prompt。 上一轮生成的错误 SQL 和报错信息,会让模型反复复读旧字段。只保留最近一轮的 SQL 和错误摘要,够用就行。
五、性能对比和技术选型
结论:没有一种方案通吃,高频走模板,长尾走模型,复杂查询走 Agent。
| 方案 | 模型调用次数 | 延迟 | 单次成本 | 准确率 | 适合场景 |
|---|---|---|---|---|---|
| 预置 SQL 模板 | 0 | 10-50ms | 0 | 接近 100% | 高频固定报表 |
| 一次性生成 | 1 | 1-3s | 低 | 中等 | 内部简单查询 |
| 工具循环 Agent | 2-5 | 3-10s | 中高 | 较高 | 长尾、多表、需要纠错 |
| 混合方案 | 0-5 | 按需 | 可控 | 高 | 生产环境推荐 |
延迟的大头在模型生成,不在数据库执行。一条走索引的查询通常几十毫秒,模型写 SQL 要一两秒,Agent 多轮更久。所以优化重点是把常见问题从「生成」降到「模板」,而不是去调 JVM 参数。
并发上,Text2SQL 不适合直接扛 C 端流量。一个请求占一次模型调用,还占一个数据库连接。真要做,前面加队列和限流,数据库走只读从库,连接池单独隔离,别和主业务抢。
这些场景建议别用 Text2SQL:
- 强一致、要求分毫不差的财务报表;
- 涉及 5 张以上表复杂 join 的查询;
- 权限模型复杂到需要行级、列级混合控制;
- 对外公开、会被恶意构造问题的入口。
六、总结
Text2SQL 不是「接个大模型就能查库」,它是一套工程:schema 怎么描述、SQL 怎么校验、错误怎么回灌、权限怎么兜底。
落地顺序我建议这样走:
- 先开只读账号,只给三张表,把最小链路跑通;
- 准备 20 个真实问题,记录可执行率和正确率;
- 补 schema 注释,加
LIMIT、超时、maxRows; - 再上工具循环,让模型自己纠错;
- 最后接审计、缓存和高频模板。
别一上来就追求「任意问题都能查」。先把一个业务域做准,比做一个什么都能问、什么都问不准的 demo 有价值得多。
判断一个 Text2SQL 方案值不值得上,就看两件事:它能不能稳定回答业务里最高频的 20 个问题,以及出错时你能不能一眼看出错在哪。前者决定有没有人用,后者决定你敢不敢上线。
模型会升级,schema 会变,唯一不能省的是校验和权限这两道门。别把力气全花在换模型上。
参考资料
文 / 会编程的吕洞宾