大模型之 Spring AI实战系列（十五）：Spring AI Tools 初体验——搭建首个可调用工具

系列篇章💥

目录

• 系列篇章💥
• 前言
• 一、什么是 Spring AI Tools？
• 二、开发环境准备
• • （一）Java 版本要求
  • （二）Maven 构建工具
  • （三）OpenAI API 密钥
  • 三、POM依赖引入
  • • （一）Spring AI与OpenAI集成依赖包
    • （二）SpringAI相关依赖包版本管理
    • 四、配置文件详解
    • 五、编写第一个工具类：DateTimeTool
    • 四、通过 ChatClient 调用工具
    • 五、运行测试
    • 六、常见问题与调试技巧
    • • （一）报错：Cannot resolve symbol 'DateTimeTool'
      • （二）工具未被调用
      • （三）参数类型不匹配异常
      • 七、小结

        ---

        前言

        在当前的 AI 应用开发中，一个关键的能力是让大模型具备“调用外部工具”的能力。Spring AI 提供了对工具调用（Tools）的原生支持，允许开发者将业务逻辑封装成工具，并通过自然语言提示词（Prompt）驱动模型自动选择并执行这些工具。

        本文将带你从零开始，一步步构建一个简单的 DateTimeTool 工具类，并通过 ChatClient 接口调用它，实现获取当前时间的功能。

        一、什么是 Spring AI Tools？

        Spring AI 是 Spring 生态中用于集成 AI 能力的新一代框架，其 tools 模块提供了一种机制，使得开发者可以：

        • 将业务逻辑封装为工具；
        • 使用注解定义工具描述和参数；
        • 让模型根据 Prompt 自动决定是否调用这些工具；
        • 支持 OpenAI、Azure OpenAI 等主流模型平台。

          二、开发环境准备

          （一）Java 版本要求

          本项目采用Java 17进行编译和运行，请务必确保你的开发环境已成功安装JDK 17。你可以在命令行中输入以下命令进行检查：

          java -version
          

          输出应类似如下内容：

          openjdk version "17.0.8" 2023-07-18
          OpenJDK Runtime Environment (build 17.0.8+7)
          OpenJDK 64-Bit Server VM (build 17.0.8+7, mixed mode, sharing)
          

          （二）Maven 构建工具

          确保你已安装 Maven 并配置好环境变量：

          mvn -v
          

          输出应类似如下内容：

          Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
          Maven home: D:\Program Files (x86)\apache-maven-3.8.8
          Java version: 17.0.12, vendor: Oracle Corporation, runtime: D:\Program Files\jdk-17.0.12
          Default locale: zh_CN, platform encoding: GBK
          OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
          

          （三）OpenAI API 密钥

          你需要注册 OpenAI 官网 获取 API Key（国内可以直接使用中转地址），并设置为环境变量：

          export OPENAI_API_KEY="your_openai_api_key"
          export OPENAI_API_URL="https://api.openai.com/v1"
          

          注意：出于安全考虑，不建议将密钥硬编码在代码中，推荐使用环境变量或配置中心进行管理。

          三、POM依赖引入

          （一）Spring AI与OpenAI集成依赖包

           
               org.springframework.ai
               spring-ai-starter-model-openai
           
          

          此依赖包用于实现Spring AI与OpenAI的集成，为后续与OpenAI API进行交互提供了必要的支持。

          （二）SpringAI相关依赖包版本管理

          版本管理

           
              
                  
                      org.springframework.ai
                      spring-ai-bom
                      1.0.0-SNAPSHOT
                      pom
                      import
                  
              
          
          

          部分通过引入spring-ai-bom，实现了对SpringAI相关依赖包版本的统一管理。这样，在项目中使用Spring AI相关依赖时，无需在每个依赖声明中单独指定版本号，只需遵循spring-ai-bom中定义的版本即可，极大地简化了依赖管理工作，同时确保了项目中依赖版本的一致性和稳定性。

          四、配置文件详解

          在配置文件 application.yml 中，对 OpenAI 相关参数进行配置：

          server:
            port: 8801
          spring:
            ai:
              openai:
                base-url: ${OPENAI_API_URL}
                api-key: ${OPENAI_API_KEY}
                chat:
                  options:
                    model: gpt-4-turbo
                    temperature: 0.7
          

          五、编写第一个工具类：DateTimeTool

          我们来创建一个工具类，用于返回当前日期和时间。创建 DateTimeTool.java

          package com.example.demo.tools;
          import org.springframework.ai.tool.Tool;
          import org.springframework.stereotype.Component;
          import java.time.LocalDateTime;
          import java.time.format.DateTimeFormatter;
          @Component
          public class DateTimeTool {
              @Tool(description = "获取当前系统的日期和时间")
              public String getCurrentDateTime() {
                  LocalDateTime now = LocalDateTime.now();
                  return now.format(DateTimeFormatter.ISO_DATE_TIME);
              }
          }
          

          关键点说明：

          • @Component：将该类注册为 Spring Bean，便于后续注入。
          • @Tool(description = "...")：标记这是一个可被模型调用的工具方法，description 描述将作为提示词的一部分传给模型。

            四、通过 ChatClient 调用工具

            接下来，我们创建一个控制器，通过 ChatClient 接口调用我们刚刚编写的 DateTimeTool。

            创建 [ChatController.java]

            package com.example.demo.controller;
            import com.example.demo.tools.DateTimeTool;
            import org.springframework.ai.chat.client.ChatClient;
            import org.springframework.ai.chat.model.ChatModel;
            import org.springframework.web.bind.annotation.GetMapping;
            import org.springframework.web.bind.annotation.RequestMapping;
            import org.springframework.web.bind.annotation.RestController;
            @RestController
            @RequestMapping("/chat")
            public class ChatController {
                private final ChatModel chatModel;
                private final DateTimeTool dateTimeTool;
                public ChatController(ChatModel chatModel, DateTimeTool dateTimeTool) {
                    this.chatModel = chatModel;
                    this.dateTimeTool = dateTimeTool;
                }
                @GetMapping("/current-time")
                public String getCurrentTime() {
                    String response = ChatClient.create(chatModel)
                            .prompt("What is the current date and time?")
                            .tools(dateTimeTool)
                            .call()
                            .content();
                    return response;
                }
            }
            

            代码解析：

            • ChatClient.create(chatModel)：构建一个对话客户端；
            • .prompt("...")：设置用户提问内容；
            • .tools(dateTimeTool)：注入可用的工具；
            • .call()：触发模型推理并处理工具调用；
            • .content()：获取最终的文本响应。

              五、运行测试

              启动应用后，访问如下地址：

              http://localhost:8080/chat/current-time
              

              你会看到类似如下的输出：

              The current date and time is 2025-04-05T14:30:45.
              

              这表示模型成功调用了我们定义的 getCurrentDateTime() 工具，并将结果整合到回答中。

              六、常见问题与调试技巧

              （一）报错：Cannot resolve symbol ‘DateTimeTool’

              • 解决办法：确认 DateTimeTool 是否正确注册为 Spring Bean（是否有 @Component 注解）；
              • 检查包扫描路径是否包含该类所在的 package。

                （二）工具未被调用

                • 查看日志是否有类似 Function calling: ... 的输出；
                • 检查 Prompt 是否足够明确，例如尝试 "Please tell me the current date and time."

                  （三）参数类型不匹配异常

                  • 确保工具方法参数类型为基本类型或 JSON 可序列化对象；
                  • 不要使用自定义复杂对象作为参数。

                    ---

                    七、小结

                    通过本文，你已经完成了以下任务：

                    • 了解了 Spring AI Tools 的核心作用；
                    • 搭建了一个基础的 Spring Boot + Spring AI 开发环境；
                    • 实现了一个简单的工具类 DateTimeTool；
                    • 学会了如何通过 ChatClient 调用工具；
                    • 成功运行并验证了工具调用流程。

                      在下一篇文章中，我们将继续深入，教你如何开发更复杂的工具类，比如天气查询、数据库操作等。欢迎关注！

                      ---

                      

                      🎯🔖更多专栏系列文章：AI大模型提示工程完全指南、AI大模型探索之路（零基础入门）、AI大模型预训练微调进阶、AI大模型开源精选实践、AI大模型RAG应用探索实践🔥🔥🔥 其他专栏可以查看博客主页📑

                      😎 作者介绍：资深程序老猿，从业10年+、互联网系统架构师，目前专注于AIGC的探索（CSDN博客之星|AIGC领域优质创作者）

                      📖专属社群：欢迎关注【小兵的AI视界】公众号或扫描下方👇二维码，回复‘入群’ 即刻上车，获取邀请链接。

                      💘领取三大专属福利：1️⃣免费赠送AI+编程📚500本，2️⃣AI技术教程副业资料1套，3️⃣DeepSeek资料教程1套🔥（限前500人）

                      如果文章内容对您有所触动，别忘了点赞、⭐关注，收藏！加入我们，一起携手同行AI的探索之旅，开启智能时代的大门！