用 Spring AI 构建 Text-to-SQL 聊天机器人：Java 实战指南

在当今数据驱动的世界中，用自然语言查询数据库的能力至关重要。Text-to-SQL 技术应运而生，它能够将人类友好的文本指令转化为机器可理解的 SQL 查询，从而极大地简化了数据访问过程。Spring AI 框架的 Text-to-SQL 功能，为 Spring Boot 应用提供了强大的自然语言查询能力，极大地降低了开发者操作数据库的门槛。本文将带您一步步使用 Spring AI 构建一个 Text-to-SQL 聊天机器人，通过 REST API 提供数据库查询服务，让您轻松实现“一句话查询数据”的梦想。

1. 核心概念：Text-to-SQL 与 Spring AI

Text-to-SQL 的核心目标是将自然语言问题转化为 SQL 查询语句。例如，用户输入“找出所有年龄大于 30 岁的用户”，系统需要将其转化为 SELECT * FROM users WHERE age > 30;。这种技术利用了自然语言处理 (NLP) 和机器学习 (ML) 的强大能力，需要理解用户意图、解析句子结构、并将其映射到数据库的表结构和字段上。

Spring AI 是一个旨在简化 AI 应用开发的 Spring Boot 项目。它集成了各种 AI 模型，包括 Anthropic 的 Claude 模型。通过 Spring AI，开发者可以方便地调用这些模型，并将其集成到自己的应用中。在 Text-to-SQL 场景下，Spring AI 简化了与语言模型的交互，并提供了内置的工具和抽象，使得开发者可以专注于业务逻辑的实现。

2. 项目搭建：Spring Boot 初始化

首先，我们需要一个 Spring Boot 项目作为基础。访问 Spring Initializr (start.spring.io) 生成一个基础项目，建议选择以下依赖：

Spring Web: 用于构建 REST API。
Spring Data JPA: 用于操作数据库。
H2 Database: 一个轻量级的嵌入式数据库，方便本地开发和测试。（当然，您可以替换为 MySQL、PostgreSQL 等更强大的数据库）。
Spring AI: 核心依赖，提供 Text-to-SQL 功能。

下载并解压生成的项目，用您喜欢的 IDE (如 IntelliJ IDEA 或 Eclipse) 打开。

3. 配置 Anthropic API Key

要使用 Anthropic 的 Claude 模型，您需要一个有效的 API Key。前往 Anthropic 官网注册并获取 API Key。

在 Spring Boot 项目的 application.properties 或 application.yml 文件中添加以下配置，将 <your-anthropic-api-key> 替换为您实际的 API Key：

spring.ai.anthropic.api-key=<your-anthropic-api-key>

或者，如果您使用 application.yml:

spring:
  ai:
    anthropic:
      api-key: <your-anthropic-api-key>

务必妥善保管您的 API Key，避免泄露。

4. 数据库设计：H2 嵌入式数据库

为了演示 Text-to-SQL 功能，我们使用 H2 数据库创建一个简单的 users 表，包含以下字段：

id: 用户 ID (INT, 主键)
name: 用户姓名 (VARCHAR)
age: 用户年龄 (INT)
email: 用户邮箱 (VARCHAR)
city: 用户所在城市 (VARCHAR)

您可以通过在 src/main/resources 目录下创建一个 schema.sql 文件来定义表结构：

CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(255),
    age INT,
    email VARCHAR(255),
    city VARCHAR(255)
);

同时，为了方便测试，我们可以插入一些示例数据到 data.sql 文件中：

INSERT INTO users (id, name, age, email, city) VALUES
(1, 'Alice', 25, 'alice@example.com', 'New York'),
(2, 'Bob', 32, 'bob@example.com', 'London'),
(3, 'Charlie', 40, 'charlie@example.com', 'Paris'),
(4, 'David', 28, 'david@example.com', 'Tokyo'),
(5, 'Eve', 35, 'eve@example.com', 'Sydney');

Spring Boot 会自动加载 schema.sql 和 data.sql 文件来初始化数据库。

5. 实现 Text-to-SQL 功能：Spring AI 核心代码

现在，让我们来实现 Text-to-SQL 的核心功能。首先，创建一个名为 TextToSqlService 的 Service 类：

import org.springframework.ai.client.AiClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class TextToSqlService {

    @Autowired
    private AiClient aiClient;

    public String generateSql(String query) {
        String prompt = "Convert the following natural language query to SQL:\n" + query +
                "\nSQL Query:";
        return aiClient.generate(prompt);
    }
}

这个 TextToSqlService 类依赖于 AiClient，AiClient 是 Spring AI 提供的核心组件，用于与 AI 模型进行交互。generateSql 方法接收一个自然语言查询作为输入，并将其拼接成一个 Prompt。Prompt 包含指令 “Convert the following natural language query to SQL:”，并告诉 AI 模型输出 SQL 查询语句。

Prompt 工程的重要性：Prompt 的质量对 Text-to-SQL 的效果至关重要。一个好的 Prompt 应该清晰、简洁地表达指令，并提供必要的上下文信息。例如，可以加入数据库表结构的描述，以帮助 AI 模型更好地理解数据模型。

6. 构建 REST API：接收查询请求并返回结果

为了让用户可以通过网络访问 Text-to-SQL 功能，我们需要创建一个 REST API。创建一个名为 TextToSqlController 的 Controller 类：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TextToSqlController {

    @Autowired
    private TextToSqlService textToSqlService;

    @GetMapping("/query")
    public String query(@RequestParam("q") String query) {
        String sql = textToSqlService.generateSql(query);
        return sql;
    }
}

这个 TextToSqlController 类提供一个 /query 的 GET API，接收一个名为 q 的参数，该参数包含用户输入的自然语言查询。 query 方法调用 TextToSqlService 的 generateSql 方法将查询转化为 SQL 语句，并将 SQL 语句作为结果返回。

安全性考虑：直接将 AI 模型生成的 SQL 语句返回给客户端存在安全风险。攻击者可能会利用 SQL 注入漏洞，通过构造恶意的查询语句来窃取或篡改数据。因此，在实际应用中，强烈建议 对 AI 模型生成的 SQL 语句进行安全审查和过滤，例如，使用白名单机制，只允许执行预定义的 SQL 语句。

7. 添加 Spring Data JPA：执行 SQL 查询并返回数据

以上代码仅仅能够将自然语言转化为 SQL 语句，但无法真正执行 SQL 查询并返回数据。为了实现完整的 Text-to-SQL 功能，我们需要使用 Spring Data JPA。

首先，创建一个 User 实体类，映射到 users 表：

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "users")
public class User {

    @Id
    private Integer id;
    private String name;
    private Integer age;
    private String email;
    private String city;

    // Getters and setters
    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }
}

然后，创建一个 UserRepository 接口，继承自 JpaRepository:

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;

public interface UserRepository extends JpaRepository<User, Integer> {

    @Query(value = ":sql", nativeQuery = true)
    List<User> findByNativeQuery(@Param("sql") String sql);
}

UserRepository 接口提供了基本的 CRUD 操作，以及一个名为 findByNativeQuery 的方法，用于执行原生 SQL 查询。

SQL 注入风险再次强调：findByNativeQuery 方法直接执行原生 SQL 查询，必须对传入的 SQL 语句进行严格的安全审查，以防止 SQL 注入攻击。在生产环境中，请务必采取必要的安全措施。

修改 TextToSqlService 类，使用 UserRepository 执行 SQL 查询：

import org.springframework.ai.client.AiClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
import com.example.demo.entity.User; // 替换为您的 User 实体类所在的包名
import com.example.demo.repository.UserRepository; // 替换为您的 UserRepository 接口所在的包名

@Service
public class TextToSqlService {

    @Autowired
    private AiClient aiClient;

    @Autowired
    private UserRepository userRepository;

    public List<User> executeQuery(String query) {
        String sql = generateSql(query);
        // Security check: Add your SQL injection prevention logic here
        // For example, check if the SQL contains "DELETE", "UPDATE", or other dangerous keywords

        return userRepository.findByNativeQuery(sql);
    }

    private String generateSql(String query) {
        String prompt = "Convert the following natural language query to SQL:\n" + query +
                "\nSQL Query:";
        return aiClient.generate(prompt);
    }
}

修改 TextToSqlController 类，调用 executeQuery 方法并返回数据：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import com.example.demo.entity.User; // 替换为您的 User 实体类所在的包名

@RestController
public class TextToSqlController {

    @Autowired
    private TextToSqlService textToSqlService;

    @GetMapping("/query")
    public List<User> query(@RequestParam("q") String query) {
        List<User> users = textToSqlService.executeQuery(query);
        return users;
    }
}

现在，API 将返回一个 User 对象的列表，表示查询结果。

8. 错误处理：增强应用鲁棒性

Text-to-SQL 应用的错误处理至关重要。由于自然语言的模糊性和 AI 模型的不确定性，可能会出现各种错误情况，例如：

AI 模型无法将自然语言查询转化为有效的 SQL 语句。
生成的 SQL 语句包含语法错误。
执行 SQL 查询时发生异常。

为了增强应用的鲁棒性，我们需要添加适当的错误处理机制。

修改 TextToSqlService 类，添加 try-catch 块来捕获异常：

import org.springframework.ai.client.AiClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Service
public class TextToSqlService {

    private static final Logger logger = LoggerFactory.getLogger(TextToSqlService.class);

    @Autowired
    private AiClient aiClient;

    @Autowired
    private UserRepository userRepository;

    public List<User> executeQuery(String query) {
        try {
            String sql = generateSql(query);

            // Security check
            // ...

            return userRepository.findByNativeQuery(sql);
        } catch (Exception e) {
            logger.error("Error executing query: " + query, e);
            throw new RuntimeException("Failed to execute query: " + query, e); // Re-throw the exception for the controller to handle
        }
    }

    private String generateSql(String query) {
        try {
            String prompt = "Convert the following natural language query to SQL:\n" + query +
                    "\nSQL Query:";
            return aiClient.generate(prompt);
        } catch (Exception e) {
            logger.error("Error generating SQL for query: " + query, e);
            throw new RuntimeException("Failed to generate SQL for query: " + query, e); // Re-throw the exception
        }
    }
}

修改 TextToSqlController 类，添加 @ExceptionHandler 来处理异常：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import com.example.demo.entity.User;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

@RestController
public class TextToSqlController {

    @Autowired
    private TextToSqlService textToSqlService;

    @GetMapping("/query")
    public List<User> query(@RequestParam("q") String query) {
        List<User> users = textToSqlService.executeQuery(query);
        return users;
    }

    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<String> handleException(RuntimeException e) {
        return new ResponseEntity<>("Error: " + e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

通过添加 try-catch 块和 @ExceptionHandler，我们可以捕获并处理异常，避免应用崩溃，并向用户返回有意义的错误信息。

9. 测试与调试

现在，您可以运行 Spring Boot 应用，并通过以下 URL 发送请求来测试 Text-to-SQL 功能：

http://localhost:8080/query?q=Find all users older than 30

如果一切正常，您应该能够看到年龄大于 30 岁的用户的信息。

您还可以尝试其他查询，例如：

What is the total amount spent by each user? (需要修改数据库结构和数据)
Find all users who live in New York
What are the names of users whose age is between 25 and 35?

调试技巧：如果查询没有返回预期的结果，可以使用以下技巧进行调试：

检查 Spring Boot 的日志，查看是否有异常信息。
查看 AI 模型生成的 SQL 语句，确认其是否正确。
直接在 H2 数据库控制台中执行 SQL 语句，验证其结果。

10. 总结与展望

本文介绍了如何使用 Spring AI 构建一个 Text-to-SQL 聊天机器人。通过 Spring AI，我们可以方便地将自然语言查询转化为 SQL 语句，并使用 Spring Data JPA 执行查询并返回数据。 Text-to-SQL 技术为数据访问带来了极大的便利，可以帮助非技术人员更轻松地查询和分析数据。

未来发展方向：

更强大的语言模型：随着 AI 技术的不断发展，更强大的语言模型将能够更好地理解自然语言，并生成更准确的 SQL 语句。
更智能的数据库集成：未来的 Text-to-SQL 系统将能够自动识别数据库表结构和字段，并根据用户意图自动优化 SQL 查询。
更友好的用户界面：未来的 Text-to-SQL 应用将提供更友好的用户界面，例如，支持语音输入、智能提示和可视化查询结果。

希望本文能够帮助您了解 Text-to-SQL 技术，并开始使用 Spring AI 构建自己的 Text-to-SQL 聊天机器人。记住，安全性至关重要，请务必采取必要的安全措施，防止 SQL 注入攻击。通过不断学习和实践，您将能够掌握 Text-to-SQL 技术，并将其应用于各种实际场景中。

用 Spring AI 构建 Text-to-SQL 聊天机器人：Java 实战指南