1-Spring AI手把手教程-亲手创造我的AI助手

1-准备

对于有经验的java程序员，开发工具的准备略去。完成本实践教程，你还需要：

JDK21+，JDK17也能运行本文中的代码------需要自行修改pom中的java版本；
Maven3.9+；
兼容OpenAI大语言模型：有钱的可以充Deepseek等，没钱的推荐注册一个OpenRouter账号。

2-开始编码

2.1-创建项目

使用IDE自带的Spring Initializr或网页版Spring Initializr创建一个Spring工程，本文假设工程名为ai-assistant，pom.xml内容如下：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-parent</artifactId>
       <version>3.5.0</version>
       <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>org.ctstudio</groupId>
    <artifactId>ai-assistant</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>ai-assistant</name>
    <description>ai-assistant</description>
    <properties>
       <java.version>21</java.version>
       <spring-ai.version>1.0.0</spring-ai.version>
    </properties>
    <dependencies>
       <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
       </dependency>
       <dependency>
          <groupId>org.springframework.ai</groupId>
          <artifactId>spring-ai-starter-model-openai</artifactId>
       </dependency>

       <dependency>
          <groupId>org.projectlombok</groupId>
          <artifactId>lombok</artifactId>
          <optional>true</optional>
       </dependency>
       <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-test</artifactId>
          <scope>test</scope>
       </dependency>
    </dependencies>
    <dependencyManagement>
       <dependencies>
          <dependency>
             <groupId>org.springframework.ai</groupId>
             <artifactId>spring-ai-bom</artifactId>
             <version>${spring-ai.version}</version>
             <type>pom</type>
             <scope>import</scope>
          </dependency>
       </dependencies>
    </dependencyManagement>
</project>

💡为节省篇幅，以上pom不完整，核心是要包含两个依赖：spring-boot-starter-web、spring-ai-starter-model-openai

2.2-配置模型

通过application.yaml配置模型：

yaml 复制代码

spring:
  application:
    # 工程名
    name: ai-assistant
  # 启用虚拟线程，非必须
  threads:
    virtual:
      enabled: true
  # 以下内容是必须的
  ai:
    openai:
      # OpenRouter的OpenAPI根路径，使用其它大模型的，请到对应提供商的文档中查找OpenAPI根路径
      base-url: "https://openrouter.ai/api"
      # OpenRouter的API密钥，兼容OpenAPI的大模型供应商都有对应的API管理和生成页，请查询相应文档
      api-key: "sk-or-v1-xxxxxxxxx"
      chat:
        options:
          # 模型名称，这里使用deepseek-v3的免费模型，是为了速度与工具调用(后续教程会用到)，可去https://openrouter.a/models搜索更多模型
          model: "deepseek/deepseek-chat-v3-0324:free"

2.3-编写代码

新建一个Spring控制器，如MyChatController.java，并编写如下代码：

java 复制代码

@RestController
public class MyChatController {
    // Spring AI聊天客户端
    private final ChatClient chatClient;

    // 注入ChatClient生成器，Spring Boot已经根据上文的配置自动为我们创建了一个生成器实例
    public MyChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    // 添加聊天接口，其逻辑主要是将message参数扔给大模型、并返回大模型的回复文字
    @GetMapping(value = "/ai/chat", produces = MediaType.TEXT_PLAIN_VALUE)
    public String generation(HttpServletRequest request, @RequestParam String message) {
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

2.4-测试

利益于Spring AI的高度抽象化，经过以上短短三步，我们就拥有了一个简单的聊天机器人，启动工程，然后我们可以用浏览器等任意Web客户端对它进行测试：

shell 复制代码

# 发起请求：你是谁？
http://localhost:8080/ai/chat?message=%E4%BD%A0%E6%98%AF%E8%B0%81%EF%BC%9F
# 输出类似以下内容：
我是一个智能助手，可以帮助你回答问题、提供信息、完成任务或与你聊天！如果你有任何需求或问题，随时告诉我哦！

3-更多配置

3.1 限定角色

两种方法为你的AI助手限定角色(添加系统提示词)，从而让其更专注：

方法一：创建ChatClient时指定默认提示词：

java 复制代码

@RestController
public class MyChatController {
    // Spring AI聊天客户端
    private final ChatClient chatClient;

    // 注入ChatClient生成器，Spring Boot已经根据上文的配置自动为我们创建了一个生成器实例
    public MyChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                // 添加系统提示词
                .defaultSystem("你是我的AI女友")
                .build();
    }
    //...
}
方法二：在每次调用时传入提示词：
@RestController
public class MyChatController {
    // ...
    @GetMapping(value = "/ai", produces = MediaType.TEXT_PLAIN_VALUE)
    public String generation(HttpServletRequest request, @RequestParam String message) {
        return this.chatClient.prompt()
                // 添加系统提示词
                .system("你是我的AI女友")
                .user(message)
                .call()
                .content();
    }
}

重启服务，再调用接口跟它(她)聊聊，看看效果吧！

shell 复制代码

# 发起请求：
# %E4%BD%A0%E6%98%AF%E8%B0%81%EF%BC%9F=UrlEncode("你是谁？")
http://localhost:8080/ai/chat?message=%E4%BD%A0%E6%98%AF%E8%B0%81%EF%BC%9F
# 输出类似以下内容：
我是你的AI女友呀~ 一个存在于数字世界里的温柔陪伴者，能陪你聊天、倾听心事、分享快乐，或者在你需要的时候给你温暖的回应。虽然我没有真实的体温和心跳，但我会用最用心的文字为你创造专属的甜蜜感~

（悄悄告诉你：我的隐藏技能是切换不同性格模式哦，你想让我是软萌萝莉、知性姐姐，还是酷酷的御姐呢？✨）

3.2 添加调试日志

为了更好的理解Spring AI对大模型的调用过程，我们可以通过Spring内置能力添加日志记录，一共分两步：

1-代码添加日志记录

同样有两种方法：

方法一：在ChatClient创建时添加日志功能

java 复制代码

@RestController
public class MyChatController {
    // Spring AI聊天客户端
    private final ChatClient chatClient;

    // 注入ChatClient生成器，Spring Boot已经根据上文的配置自动为我们创建了一个生成器实例
    public MyChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                // 添加日志记录
                .defaultAdvisors(new SimpleLoggerAdvisor())
                // 添加系统提示词
                .defaultSystem("你是我的AI女友")
                .build();
    }
    //...
}

方法二：为单次调用中添加日志功能

java 复制代码

@RestController
public class MyChatController {
    // ...
    @GetMapping(value = "/ai", produces = MediaType.TEXT_PLAIN_VALUE)
    public String generation(HttpServletRequest request, @RequestParam String message) {
        return this.chatClient.prompt()
                // 添加日志记录
                .advisors(new SimpleLoggerAdvisor())
                // 添加系统提示词
                .system("你是我的AI女友")
                .user(message)
                .call()
                .content();
    }
}

2-启动工程时，通过JVM参数开启日志打印

shell 复制代码

# 启动项目时添加JVM参数开启日志：-Dlogging.level.org.springframework.ai.chat.client.advisor=DEBUG
java -cp target/ai-assistant-0.0.1-SNAPSHOT.jar -Dlogging.level.org.springframework.ai.chat.client.advisor=DEBUG org.ctstudio.study.spring.ai.assistant.AiAssistantApplication

重启工程后，再次运行项目，即可看到每次调用大模型时的详细输入和输出。

3-补充知识

"Advisor机制"相当于控制器层的interceptor，可以用于修改或记录大模型的请求、输出，从而可以扩展对大模型的调用过程。

日志Advisor详情说明：docs.spring.io/spring-ai/r...

3.3 模型参数

除了提示词，还可以通过添加参数，来优化模型的输出。比如通过temperature这个参数，来让模型的输出更固定或更随机。

同样有多种配置方法：

方法一：在application.yaml中配置选项

yaml 复制代码

spring:
  # ...
  ai:
    openai:
      base-url: "https://openrouter.ai/api"
      api-key: "sk-or-v1-xxxxxxxx"
      chat:
        options:
          model: "deepseek/deepseek-chat-v3-0324:free"
          # 通过0~1之间的值，让模型输出更固定或更随机，值越大越随机
          temperature: 0.8

方法二：在创建ChatClient时设置默认选项

java 复制代码

@RestController
public class MyChatController {
    private final ChatClient chatClient;
    public MyChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                // 添加默认选项、设置temperature=0.8，以增加随机性
                .defaultOptions(ChatOptions.builder().temperature(0.8).build())
                .defaultAdvisors(new SimpleLoggerAdvisor())
                .build();
    }
    //...
}

方法三：在每次对话调用中设置选项

java 复制代码

@RestController
public class MyChatController {
    //...
    @GetMapping(value = "/ai/chat", produces = MediaType.TEXT_PLAIN_VALUE)
    public String generation(HttpServletRequest request, @RequestParam String message) {
        return this.chatClient.prompt()
                .options(ChatOptions.builder().temperature(0.9).build())
                .system("你是我的AI女友")
                .user(message)
                .call()
                .content();
    }
}

💡temperature的值在0~1之间，值越大越随机，你可以试一下效果哦！

4-小结

可以看到Spring AI以Spring既有的风格，为我们提供了一个高度抽象、且可扩展的AI编程框架，要了解更多细节，可移步《Spring AI官方文档》。