让业务人员直接“问“数据库：Spring AI Alibaba NL2SQL 实战指南

不用学 SQL不用找开发排期用大白话就能查数据——这不是未来而是现在就能落地的方案。一个真实的痛点你是公司的运营负责人想知道上个月华东地区复购率最高的三个品类。在传统模式下这个需求的链路是这样的你提需求 → 开发排期3天后→ 写 SQL → 测试 → 上线 → 你拿到数据如果第二天你又想知道按周维度的趋势变化再来一轮。NL2SQLNatural Language to SQL要解决的正是这个问题——让不懂 SQL 的人也能用自然语言直接查询数据库。但 NL2SQL 不是新概念。早在 ChatGPT 出现之前学术界就在研究这个问题。为什么以前的方案没有普及核心障碍有三个Schema 理解不准模型不知道你的业务表结构容易张冠李戴复杂查询搞不定多表关联、窗口函数一上生成质量断崖式下降执行不可控生成的 SQL 可能有语法错误甚至误删数据Spring AI Alibaba 的 NL2SQL 模块正是针对这三个痛点将阿里云析言 GBI 产品中的核心能力模块化、开源化。一、整体架构三步走Spring AI Alibaba NL2SQL 的核心链路可以概括为三步┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 用户自然语言 │───►│ Schema 召回 │───►│ SQL 生成 │ │ 上月华东区 │ │ 找到相关表 │ │ 大模型翻译 │ │ 复购率Top3 │ │ 和字段 │ │ 为 SQL │ └──────────────┘ └──────────────┘ └──────┬───────┘ │ ▼ ┌──────────────┐ │ SQL 执行 │ │ 返回结果 │ │ 错误处理 │ └──────────────┘每一步解决什么问题步骤核心问题解决方案Schema 召回数据库可能有上百张表模型怎么知道该用哪张将表结构向量化根据用户问题语义匹配最相关的表和字段SQL 生成自然语言怎么变成准确的 SQL大模型 数据库方言适配 复杂查询优化SQL 执行生成的 SQL 能直接跑吗安全吗连接池管理、只读保护、错误反馈二、环境准备2.1 前置条件JDK 17Spring Boot 3.x 的最低要求MySQL 8.0或其他 JDBC 兼容的数据库DashScope API Key用于调用通义千问等大模型设置 API KeyexportAI_DASHSCOPE_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxx2.2 准备测试数据为了演示效果我们先准备一个简单的电商数据库CREATEDATABASEecommerce_demo;USEecommerce_demo;-- 商品表CREATETABLEproducts(product_idINTPRIMARYKEYAUTO_INCREMENT,product_nameVARCHAR(100),categoryVARCHAR(50),priceDECIMAL(10,2));-- 订单表CREATETABLEorders(order_idINTPRIMARYKEYAUTO_INCREMENT,user_idINT,product_idINT,quantityINT,order_dateDATE,regionVARCHAR(50),FOREIGNKEY(product_id)REFERENCESproducts(product_id));-- 插入测试数据INSERTINTOproductsVALUES(1,iPhone 15,手机,5999),(2,MacBook Pro,电脑,12999),(3,AirPods Pro,耳机,1899);INSERTINTOordersVALUES(1,101,1,2,2024-01-15,华东),(2,102,2,1,2024-02-20,华北),(3,101,3,3,2024-03-10,华东),(4,103,1,1,2024-04-05,华南);三、项目搭建3.1 引入依赖创建 Spring Boot 项目后在pom.xml中添加 NL2SQL 相关依赖dependencies!-- Spring AI Alibaba 基础依赖 --dependencygroupIdcom.alibaba.cloud.ai/groupIdartifactIdspring-ai-alibaba-starter/artifactIdversion1.0.0.2/version/dependency!-- NL2SQL 模块 --dependencygroupIdcom.alibaba.cloud.ai/groupIdartifactIdspring-ai-alibaba-starter-nl2sql/artifactIdversion1.0.0.2/version/dependency!-- MySQL 驱动 --dependencygroupIdcom.mysql/groupIdartifactIdmysql-connector-j/artifactIdversion8.3.0/version/dependency!-- Web 支持 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency/dependencies同时需要配置 Maven 仓库Spring Milestone 仓库repositoriesrepositoryidspring-milestones/idnameSpring Milestones/nameurlhttps://repo.spring.io/milestone/urlsnapshotsenabledfalse/enabled/snapshots/repository/repositories3.2 配置文件在application.yml中配置数据库和大模型连接spring:datasource:url:jdbc:mysql://localhost:3306/ecommerce_demo?useSSLfalseserverTimezoneAsia/Shanghaiusername:rootpassword:your_passworddriver-class-name:com.mysql.cj.jdbc.Driverai:dashscope:api-key:${AI_DASHSCOPE_API_KEY}chat:model:qwen-plusnl2sql:# 数据库方言database-type:mysql# 是否自动执行生成的 SQL生产环境建议设为 falseauto-execute:true# Schema 召回策略schema-recall:# 召回的表数量上限max-tables:10# 相似度阈值similarity-threshold:0.6四、核心实现4.1 Schema 注册NL2SQL 的第一步是让模型认识你的数据库。Spring AI Alibaba NL2SQL 提供了 Schema 管理模块可以自动扫描数据库结构并建立向量索引importcom.alibaba.cloud.ai.nl2sql.schema.SchemaManager;importorg.springframework.boot.ApplicationArguments;importorg.springframework.boot.ApplicationRunner;importorg.springframework.stereotype.Component;ComponentpublicclassSchemaInitializerimplementsApplicationRunner{privatefinalSchemaManagerschemaManager;publicSchemaInitializer(SchemaManagerschemaManager){this.schemaManagerschemaManager;}Overridepublicvoidrun(ApplicationArgumentsargs)throwsException{// 自动扫描数据库 Schema 并建立向量索引schemaManager.initialize();System.out.println(Schema 初始化完成已注册表和字段信息);}}这个过程会做以下几件事通过 JDBC 读取数据库的元数据表名、字段名、字段类型、注释将元数据信息转为向量表示存入向量数据库供后续语义检索使用关于字段注释的重要性如果你的表有完善的注释COMMENTSchema 召回的准确率会大幅提升。建议在数据库设计时就写好注释例如ALTERTABLEordersMODIFYCOLUMNregionVARCHAR(50)COMMENT订单所属地区;4.2 NL2SQL 服务接下来实现核心的自然语言转 SQL 功能importcom.alibaba.cloud.ai.nl2sql.service.Nl2SqlService;importcom.alibaba.cloud.ai.nl2sql.model.Nl2SqlResult;importorg.springframework.stereotype.Service;ServicepublicclassDataQueryService{privatefinalNl2SqlServicenl2SqlService;publicDataQueryService(Nl2SqlServicenl2SqlService){this.nl2SqlServicenl2SqlService;}/** * 自然语言查询数据库 * param naturalQuery 用户的自然语言问题 * return 查询结果 */publicNl2SqlResultquery(StringnaturalQuery){returnnl2SqlService.nl2sql(naturalQuery);}}Nl2SqlResult通常包含以下信息生成的 SQL 语句执行结果如果开启了自动执行召回的 Schema 信息用于调试和审计错误信息如果生成或执行失败4.3 REST 接口对外暴露一个简洁的 HTTP 接口importorg.springframework.web.bind.annotation.*;RestControllerRequestMapping(/api/data)publicclassDataQueryController{privatefinalDataQueryServicedataQueryService;publicDataQueryController(DataQueryServicedataQueryService){this.dataQueryServicedataQueryService;}/** * 自然语言查询接口 * GET /api/data/query?question列出所有商品的价格 */GetMapping(/query)publicDataQueryResponsequery(RequestParamStringquestion){try{varresultdataQueryService.query(question);returnDataQueryResponse.success(result.getSql(),result.getExecutionResult());}catch(Exceptione){returnDataQueryResponse.error(e.getMessage());}}// 响应 DTOpublicrecordDataQueryResponse(booleansuccess,Stringsql,Objectdata,StringerrorMessage){publicstaticDataQueryResponsesuccess(Stringsql,Objectdata){returnnewDataQueryResponse(true,sql,data,null);}publicstaticDataQueryResponseerror(Stringmessage){returnnewDataQueryResponse(false,null,null,message);}}}五、测试验证启动应用后用几个典型场景来测试效果场景一简单查询curlhttp://localhost:8080/api/data/query?question列出所有商品预期生成的 SQLSELECTproduct_id,product_name,category,priceFROMproducts;场景二条件过滤 排序curlhttp://localhost:8080/api/data/query?question华东地区有多少个订单预期生成的 SQLSELECTCOUNT(*)FROMordersWHEREregion华东;场景三多表关联curlhttp://localhost:8080/api/data/query?question每个品类的商品平均价格是多少预期生成的 SQLSELECTcategory,AVG(price)asavg_priceFROMproductsGROUPBYcategory;场景四复杂聚合curlhttp://localhost:8080/api/data/query?question复购次数最多的用户是谁预期生成的 SQLSELECTuser_id,COUNT(*)asorder_countFROMordersGROUPBYuser_idORDERBYorder_countDESCLIMIT1;六、生产环境关键考量上面的代码跑通了基本流程。但在真实业务中还需要解决以下问题6.1 安全防护只读保护绝对不要让 NL2SQL 直接拥有写权限。建议spring:datasource:# 使用只读账号url:jdbc:mysql://localhost:3306/ecommerce_demo?useSSLfalseusername:readonly_userpassword:readonly_password同时在代码层面增加 SQL 校验publicbooleanisSafeSql(Stringsql){Stringuppersql.trim().toUpperCase();// 只允许 SELECT 语句returnupper.startsWith(SELECT);}6.2 SQL 审核与人工确认对于关键业务场景建议增加生成 → 审核 → 执行的流程publicNl2SqlResultqueryWithReview(StringnaturalQuery){// 第一步生成 SQL不执行Nl2SqlResultresultnl2SqlService.generateOnly(naturalQuery);// 第二步返回 SQL 给人工审核// ... 审核流程 ...// 第三步审核通过后执行if(approved){resultnl2SqlService.executeSql(result.getSql());}returnresult;}6.3 查询超时与资源限制防止慢查询拖垮数据库importjava.sql.Statement;importjava.util.concurrent.*;publicObjectexecuteWithTimeout(Stringsql,inttimeoutSeconds){ExecutorServiceexecutorExecutors.newSingleThreadExecutor();FutureObjectfutureexecutor.submit(()-{// 执行 SQLreturnjdbcTemplate.queryForList(sql);});try{returnfuture.get(timeoutSeconds,TimeUnit.SECONDS);}catch(TimeoutExceptione){future.cancel(true);thrownewRuntimeException(查询超时timeoutSeconds秒);}}6.4 结果缓存对于高频查询可以加一层缓存importorg.springframework.cache.annotation.Cacheable;Cacheable(valuenl2sql,key#naturalQuery)publicNl2SqlResultquery(StringnaturalQuery){returnnl2SqlService.nl2sql(naturalQuery);}6.5 多数据源支持企业通常有多个数据库订单库、用户库、商品库。Spring AI Alibaba NL2SQL 支持多数据源配置ConfigurationpublicclassMultiDataSourceConfig{BeanConfigurationProperties(spring.datasource.order)publicDataSourceorderDataSource(){returnDataSourceBuilder.create().build();}BeanConfigurationProperties(spring.datasource.user)publicDataSourceuserDataSource(){returnDataSourceBuilder.create().build();}}七、提升 NL2SQL 准确率的实战技巧7.1 完善数据库注释这是最有效的优化手段。模型对字段的理解完全依赖元数据中的注释信息。-- 好的注释ALTERTABLEordersADDCOLUMNorder_statusTINYINTCOMMENT订单状态1-待支付2-已支付3-已发货4-已完成5-已取消;-- 不好的注释或没有注释ALTERTABLEordersADDCOLUMNorder_statusTINYINT;7.2 提供业务术语映射用户的自然语言表述和数据库字段名往往不一致。可以建立术语映射表publicclassBusinessTermMapping{privatestaticfinalMapString,StringTERM_MAPMap.of(销售额,price * quantity,复购,user_id 出现次数 1,华东区,region IN (上海, 江苏, 浙江, 安徽));publicstaticStringenrichQuery(StringnaturalQuery){for(varentry:TERM_MAP.entrySet()){naturalQuerynaturalQuery.replace(entry.getKey(),entry.getValue());}returnnaturalQuery;}}7.3 Few-Shot 示例增强在 Prompt 中提供几个正确的问题 → SQL示例可以显著提升生成质量示例1 问题找出价格超过100元的商品 SQLSELECT * FROM products WHERE price 100 示例2 问题统计每个地区的订单数量 SQLSELECT region, COUNT(*) FROM orders GROUP BY region 现在请回答 问题{user_question} SQL7.4 选择合适的模型不同模型在 NL2SQL 任务上的表现差异很大模型适用场景成本qwen-plus日常使用性价比高低qwen-max复杂查询多表关联中XiYan-SQL开源专注 NL2SQL 的专用模型免费对于简单的单表查询qwen-plus 已经够用涉及多表 JOIN、子查询、窗口函数的场景建议使用 qwen-max 或专用的 SQL 生成模型。八、常见问题排查Q生成的 SQL 语法错误怎么办A排查顺序确认数据库方言配置正确database-type: mysql检查 Schema 是否正确注册查看初始化日志尝试换用更强的模型qwen-max在 Prompt 中增加 Few-Shot 示例Q召回的表不对导致生成的 SQL 完全错误A检查字段注释是否完善降低similarity-threshold阈值增加max-tables数量手动指定相关表通过 API 参数Q回答速度太慢ANL2SQL 涉及多次 LLM 调用Schema 召回 SQL 生成整体耗时通常在 3-8 秒。优化方向使用流式输出先返回 SQL 再执行缓存常见查询的结果选择响应更快的模型Q依赖拉取失败A确认已配置 Spring Milestones 仓库见上文 3.1 节。如果仍然失败可以尝试使用快照版本或检查网络连接。九、总结NL2SQL 不是要取代 SQL而是要降低数据查询的门槛。它的最佳应用场景是业务人员的自助分析不用等开发排期自己问数据数据产品的底层引擎为 BI 工具、智能客服提供数据查询能力开发者的效率工具快速生成复杂 SQL减少手写错误Spring AI Alibaba NL2SQL 的价值在于开箱即用引入依赖即可启动服务不需要从零搭建模块化设计Schema 召回、SQL 生成、SQL 执行三个环节解耦可按需组合企业级能力多数据源、安全防护、错误处理一应俱全持续迭代背靠阿里云析言 GBI 产品能力持续增强对于 Java 团队来说这意味着你可以在几天内搭建一个对话式数据查询系统而不需要投入大量人力去造轮子。 福利时间如果你正在备战面试或者想要学习其他知识给大家推荐一个宝藏知识库作者整理了一些列 Java 程序员需要掌握的核心知识有需要的自取不谢。知识库地址https://farerboy.com/