本文介绍了如何利用 Spring AI Alibaba 的 NL2SQL（自然语言转 SQL）模块，简化 BI 场景中的复杂查询。核心目标是让用户用“人话”提问（如“最近一周销售额最高的商品？”），自动生成 SQL 并执行。以下是关键要点，结构清晰，便于快速上手。

1. 什么是 NL2SQL？

spring-ai-alibaba-nl2sql 是一个服务层模块，可将自然语言问题转换为 SQL，支持 SQL 执行、结果格式化，并可生成 Python 代码辅助分析。它基于阿里云析言 GBI 能力，提供组件化封装：

• Schema 召回（向量检索）：检索相关表结构。
• SQL 生成（大模型推理）：生成候选 SQL。
• SQL 校验与执行：确保语法和语义正确。
• Python 代码生成（可选）：支持容器运行进行深度分析。
  模块需与 spring-ai-alibaba-nl2sql-management 管控模块结合使用，适合开发/运维。

2. 适用场景

• 自助问数：业务团队快速查询数据，如“本月用户增长趋势”。
• 嵌入式能力：融入企业内部系统或客服中台。
• 半结构化探索：结合“证据文本”（如业务定义）提升准确率。

3. 架构与流程

整体流程：自然语言 → 关键词与时间理解 → Schema 召回与表关系推理 → SQL 生成 → 校验 → 执行 → Python 分析（可选）。
典型步骤：

1. 解析与重写：抽取关键词（时间、指标等）。
2. Schema 召回：向量化存储表结构，检索相关表和字段。
3. 表关系推理：基于外键建议连接路径。
4. SQL 生成：模型生成 SQL，必要时迭代补充 Schema。
5. 校验：先语法检查，再语义一致性验证。
6. 执行与呈现：输出 Markdown 表格；可选生成 Python 代码。
   详细工作流和日志可参考 spring-ai-alibaba-nl2sql-chat 的 README。

4. 模块划分

项目结构精简：

spring-ai-alibaba-nl2sql/
├── spring-ai-alibaba-nl2sql-management  # 管理端（Web 界面、Schema 初始化）
├── spring-ai-alibaba-nl2sql-chat         # 核心服务组件（供集成）
└── spring-ai-alibaba-nl2sql-common       # 公共模型与工具

• 管理端：适合演示和运维，独立运行。
• Chat 模块：接入 Spring Boot 工程，作为内部服务复用。

5. 快速上手

管理端体验：

1. 准备业务库（MySQL/PG），导入示例数据（参考 README 脚本）。
2. 配置 application.yml（填入数据库和模型 Key）。
3. 启动管理端和前端（spring-ai-alibaba-nl2sql-web-ui）。
4. 访问 http://localhost:3000，完成数据源配置、Schema 初始化等。
   页面支持：数据源测试、预设问题、实时调试。

组件接入（Maven 示例）：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-nl2sql</artifactId>
    <version>${spring-ai-alibaba.version}</version>
</dependency>

接入要点：

• 配置向量存储（开发用 SimpleVector；生产用 AnalyticDB）。
• 配置大模型（支持 DashScope、OpenAI、Ollama 等）。
• 初始化 Schema 到向量库（首次或变更时执行）。

6. 关键配置示例

模型与向量（YAML 配置）：

spring:
  ai:
    openai:
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      api-key: ${AI_DASHSCOPE_API_KEY}
      model: qwen-max
      embedding:
        model: text-embedding-v4
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      embedding:
        model: text-embedding-v2
  vectorstore:
    analytic:
      collectName: ${VECTOR_COLLECTION_NAME}
      regionId: ${REGION_ID}
      # ... 其他参数（详见文档）

注意：切换 Embedding 模型需重新初始化 Schema。

业务库连接：

chatbi:
  dbconfig:
    url: ${JDBC_URL}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    dialecttype: mysql  # 或 postgresql

Python 代码执行（可选）：

spring:
  ai:
    alibaba:
      nl2sql:
        code-executor:
          code-pool-executor: docker
          image-name: continuumio/anaconda3:latest
          # ... 其他参数（如容器配置）

开发时可开启 AI 模拟模式验证流程。

7. 调用方式

最小化调用步骤：

1. 初始化 Schema 到向量库（变更时执行）。
2. 注入 NL2SQL Graph，传入用户查询 query。
   控制器伪代码（Java 示例）：

@GetMapping("/nl2sql/search")
public String search(@RequestParam String query) throws Exception {
    // 初始化 Schema
    SchemaInitRequest req = new SchemaInitRequest().setDbConfig(dbConfig)
        .setTables(List.of("orders", "products")); // 示例表
    simpleVectorStoreService.schema(req);
    // 调用图执行
    OverAllState state = compiledGraph.invoke(Map.of(INPUT_KEY, query)).orElseThrow();
    return state.value(RESULT).get().toString();
}

完整示例见模块 README。

8. 最佳实践与常见坑

• 提升准确率：提供精确 Schema 和字段注释；用“证据文本”补充业务定义（如“销量=购买数量求和”）。
• 开发迭代：先在 SimpleVector 本地测试，再切换 AnalyticDB 上线；注意向量重建。
• 校验机制：复杂查询开启“语义一致性校验”，允许多轮召回补全。
• Python 执行：生产环境务必使用真实容器，避免“幻觉”问题。

9. 局限性：何时不该用 NL2SQL？

• 依赖超复杂存储过程或自定义函数的报表。
• 需毫秒级响应的高频 OLTP 场景（延迟较高）。
• 数据模型频繁变更时（需重建 Schema）。

10. 总结

Spring AI Alibaba NL2SQL 模块显著降低 BI 查询门槛，适用于自助分析和嵌入式系统。通过合理配置 Schema 召回和校验机制，可提升准确率。建议从管理端开始体验，逐步集成到后端系统，避开常见坑点（如向量兼容问题）。详细文档和示例代码见项目 README。