302-Spring AI Alibaba MCP NL2SQL 示例

本示例展示了如何使用 Spring AI Alibaba 的 MCP (Model Context Protocol) 结合 NL2SQL (Natural Language to SQL) 功能，实现自然语言查询数据库的能力。通过本示例，您将了解如何构建一个能够理解自然语言问题并自动转换为 SQL 查询的应用程序。

1. 示例目标

我们将创建一个基于 Spring Boot 的应用程序，实现以下功能：

1. NL2SQL 功能 (nl2Sql)：使用 AnalyticDB 向量数据库，将自然语言问题转换为 SQL 查询并执行。
2. 简化版 NL2SQL 功能 (simpleNl2Sql)：使用内存向量库，将自然语言问题转换为 SQL 查询并执行。

2. 技术栈与核心依赖

• Spring Boot 3.x
• Spring AI Alibaba (用于对接阿里云 DashScope 通义大模型)
• Spring AI NL2SQL (自然语言转 SQL 功能)
• MCP (Model Context Protocol) (模型上下文协议)
• AnalyticDB (阿里云分析型数据库)
• Maven (项目构建工具)

在 pom.xml 中，我们需要引入以下核心依赖：

<dependencies><!-- Spring AI Alibaba NL2SQL 启动器 --><dependency><groupId>com.alibaba.cloud.ai</groupId><artifactId>spring-ai-alibaba-starter-nl2sql</artifactId><version>${spring-ai-alibaba.version}</version></dependency><!-- Spring AI OpenAI 模型启动器 --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-openai</artifactId><version>1.0.0-RC1</version><scope>compile</scope></dependency>
</dependencies>

3. 项目配置

在 src/main/resources/application.yml 文件中，配置应用程序的各项参数。

server:port: 8061 # 服务器端口配置
spring:main:banner-mode: offai:dashscope:api-key: ${DASHSCOPE_API_KEY} # 建议使用环境变量，更安全mcp:server:name: xiyan-server    # MCP服务器名称version: 0.0.1           # 服务器版本号vectorstore:analytic:collectName: chatBiregionId: cn-hangzhoudbInstanceId: ${ANALYTIC_DB_INSTANCE_ID}managerAccount: ${ANALYTIC_DB_MANAGER_ACCOUNT}managerAccountPassword: ${ANALYTIC_DB_MANAGER_PASSWORD}namespace: chatnamespacePassword: chatdefaultTopK: 6defaultSimilarityThreshold: 0.75accessKeyId: ${ALIYUN_ACCESS_KEY_ID}accessKeySecret: ${ALIYUN_ACCESS_KEY_SECRET}openai:base-url: https://dashscope.aliyuncs.com/compatible-modeapi-key: ${DASHSCOPE_API_KEY}model: qwen-max
chatBi:dbConfig:url: ${DATABASE_URL}username: ${DATABASE_USERNAME}password: ${DATABASE_PASSWORD}schema: ${DATABASE_SCHEMA}connection-type: jdbcdialect-type: mysql

重要提示：请将上述配置中的环境变量设置为您实际使用的值，包括 DashScope API Key、AnalyticDB 实例信息、数据库连接信息等。

4. 应用程序入口

应用程序的入口点是 Application.java 文件，它配置了 Spring Boot 应用并注册了 MCP 工具。

package com.alibaba.cloud.ai.example;import com.alibaba.cloud.ai.example.service.McpService;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;@SpringBootApplication
@AutoConfiguration
@ComponentScan("com.alibaba.cloud.ai")
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}@Beanpublic ToolCallbackProvider chatBiTools(McpService mcpService) {return MethodToolCallbackProvider.builder().toolObjects(mcpService).build();}
}

5. 服务层实现

服务层实现位于 McpService.java 文件中，它定义了两个 NL2SQL 工具方法。

package com.alibaba.cloud.ai.example.service;import com.alibaba.cloud.ai.service.analytic.AnalyticNl2SqlService;
import com.alibaba.cloud.ai.service.simple.SimpleNl2SqlService;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;@Service
public class McpService {@Autowiredprivate AnalyticNl2SqlService nl2SqlService;@Autowiredprivate SimpleNl2SqlService simpleNl2SqlService;/*** 从数据库中获取问题所需要的数据* @return 从数据库中获取问题所需要的数据*/@Tool(description = "从数据库中获取问题所需要的数据")public String nl2Sql(String input) throws Exception {String sql = nl2SqlService.nl2sql(input);return nl2SqlService.executeSql(sql);}@Tool(description = "使用内存向量库从数据库中获取问题所需要数据")public String simpleNl2Sql(String input) throws Exception {String sql = simpleNl2SqlService.nl2sql(input);return simpleNl2SqlService.executeSql(sql);}
}

5.1 nl2Sql 方法

此方法使用 AnalyticDB 向量数据库实现 NL2SQL 功能：

• 使用 @Tool 注解标记为 MCP 工具，描述为"从数据库中获取问题所需要的数据"
• 接收自然语言输入 input
• 调用 AnalyticNl2SqlService.nl2sql 将自然语言转换为 SQL
• 调用 AnalyticNl2SqlService.executeSql 执行 SQL 并返回结果

5.2 simpleNl2Sql 方法

此方法使用内存向量库实现简化版 NL2SQL 功能：

• 使用 @Tool 注解标记为 MCP 工具，描述为"使用内存向量库从数据库中获取问题所需要数据"
• 接收自然语言输入 input
• 调用 SimpleNl2SqlService.nl2sql 将自然语言转换为 SQL
• 调用 SimpleNl2SqlService.executeSql 执行 SQL 并返回结果

6. 工作原理

本示例的工作原理如下：

1. 自然语言输入：用户输入自然语言问题，如"查询上个月销售额最高的产品"
2. NL2SQL 转换：系统将自然语言问题转换为 SQL 查询语句
3. SQL 执行：系统执行生成的 SQL 查询并获取结果
4. 结果返回：系统将查询结果返回给用户

两种实现方式的区别

实现方式	向量库	适用场景	优缺点
AnalyticNl2SqlService	AnalyticDB 向量数据库	大规模数据，复杂查询	准确率高，性能好，但需要配置 AnalyticDB
SimpleNl2SqlService	内存向量库	小规模数据，简单查询	配置简单，无需额外数据库，但准确率和性能有限

7. 运行与测试

1. 配置环境变量：设置必要的环境变量，包括 DASHSCOPE_API_KEY、数据库连接信息等
2. 启动应用：运行 Spring Boot 主程序
3. 测试 NL2SQL 功能：通过 MCP 协议调用 NL2SQL 工具

测试示例

您可以通过 MCP 客户端调用以下工具：

测试 AnalyticDB NL2SQL

{"tool": "nl2Sql","parameters": {"input": "查询上个月销售额最高的产品"}
}

测试内存向量库 NL2SQL

{"tool": "simpleNl2Sql","parameters": {"input": "查询上个月销售额最高的产品"}
}

8. 扩展建议

• 自定义提示词模板：可以根据业务需求自定义 NL2SQL 转换的提示词模板，提高转换准确率
• 多数据库支持：扩展支持更多类型的数据库，如 PostgreSQL、Oracle 等
• 查询结果格式化：对查询结果进行格式化，提高可读性
• 查询历史记录：保存查询历史，支持后续分析和优化
• 权限控制：添加用户权限控制，限制可查询的数据范围
• 性能优化：对频繁查询的结果进行缓存，提高响应速度