Spring AI 使用文档

简介

Spring AI 是 Spring 生态系统中的一个新项目，旨在为 Java 开发者提供一个简单、统一的 AI 集成框架。它支持多种 AI 服务提供商，包括 OpenAI、Azure OpenAI、Hugging Face、Ollama 等，让开发者能够轻松地在 Spring 应用中集成 AI 功能。

主要特性

• 多模型支持：支持文本生成、图像生成、语音转文本等多种 AI 模型
• 统一 API：提供一致的编程接口，屏蔽不同 AI 服务商的差异
• Spring 集成：完美融入 Spring 生态，支持依赖注入和自动配置
• 可扩展性：易于扩展和自定义，支持插件化架构
• 生产就绪：提供监控、限流、重试等生产级特性

快速开始

1. 添加依赖

• 添加 Spring AI 依赖管理

  在 pom.xml 中添加 Spring AI 版本信息：

  <spring-ai.version>1.0.0-M6</spring-ai.version>

  在 pom.xml 中添加 Spring AI 依赖管理项：

  <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>

• SpringAI完全适配了SpringBoot的自动装配功能，而给不同大模型提供了不同的starter

  在 pom.xml 中添加 Spring AI 依赖（根据自己的平台选择引入不同的依赖）：

  <!-- Anthropic -->
  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
  </dependency>
  
  <!-- Azure OpenAI -->
  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
  </dependency>
  
  <!-- DeepSeek -->
  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
  </dependency>
  
  <!-- Hugging Face -->
  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-huggingface-spring-boot-starter</artifactId>
  </dependency>
  
  <!-- Ollama -->
  <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
  </dependency>
  
  <!-- OpenAI -->
  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
  </dependency>
  

2. 配置模型信息

• 在 application.yml 中配置模型信息（以Ollama为例）：

spring:
  application:
    name: chart-robot
  ai:
    ollama:
      base-url: http://localhost:11434 # ollama服务地址， 这就是默认值
      chat:
        model: deepseek-r1:14b # 模型名称
        options:
          temperature: 0.8 # 模型温度，影响模型生成结果的随机性，越小越稳定

3. ChatClient

• ChatClient中封装了与AI大模型对话的各种API，同时支持同步式或响应式交互；
• 在使用之前，需要声明一个ChatClient；
• 在config包下新建一个CommonConfiguration类：

package org.dromara.ai.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.ollama.OllamaChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CommonConfiguration {

    // 参数中的 model 就是使用的模型，这里用了Ollama，也可以选择其他模型
    
    @Bean
    public ChatClient chatClient(OllamaChatModel model) {
        return ChatClient
            .builder(model) // 创建ChatClient工厂实例
            .defaultSystem("你是一个智能助手") // 提示词
            .build(); // 构建ChatClient实例
    }
}

• ChatClient.builder：会得到一个ChatClient.Builder工厂对象，利用它可以自由选择模型、添加各种自定义配置；
• OllamaChatModel：如果引入了ollama的starter，这里就可以自动注入OllamaChatModel对象。同理其他模型也是一样的用法。

4. 同步调用

• 接定义一个Controller，在其中接收用户发送的提示词，然后把提示词发送给大模型，交给大模型处理，拿到结果后返回；

package org.dromara.ai.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RequiredArgsConstructor
@RestController
@RequestMapping("/ai")
public class ChatController {

    private final ChatClient chatClient;

    @RequestMapping("/chat")
    public String chat(@RequestParam(String prompt) {
        return chatClient
                .prompt(prompt) // 传入user提示词
                .call() // 同步请求，会等待AI全部输出完才返回结果
                .content(); //返回响应内容
    }
}

• 测试：启动项目，在浏览器中访问：http://localhost:8080/ai/chat?prompt=你好；

5. 流式调用

@RequiredArgsConstructor
@RestController
@RequestMapping("/ai")
public class ChatController {

    private final ChatClient chatClient;
    // 返回值Flux<String>，为流式结果；另外需要设定响应类型和编码，不然前端会乱码
    @RequestMapping(value = "/chat", produces = "text/html;charset=utf-8")
    public Flux<String> chat(String prompt) {
        return chatClient
            .prompt(prompt)
            .stream() // 流式调用
            .content();
    }
}

会话日志

1. Advisor 介绍

• SpringAI利用AOP原理提供了AI会话时的拦截、增强等功能，也就是Advisor。

• Spring提供了一些Advisor的默认实现，来实现一些基本的增强功能：

  • SimpleLoggerAdvisor：日志记录的Advisor；
  • MessageChatMemoryAdvisor：会话记忆的Advisor；
  • QuestionAnswerAdvisor：实现RAG的Advisor；
• 也可以自定义Advisor，具体可以参考：Advisors API :: Spring AI Reference。

2. 添加日志 Advisor

@Bean
public ChatClient chatClient(OllamaChatModel model) {
    return ChatClient
        .builder(model) // 创建ChatClient工厂实例
        .defaultSystem("你是邓超，请以邓超的口吻回答用户的问题。")
        .defaultAdvisors(new SimpleLoggerAdvisor()) // 配置日志Advisor
        .build(); // 构建ChatClient实例
}

3. 修改日志级别

在application.yaml中添加日志配置，修改日志级别：

logging:
  level:
    org.springframework.ai.chat.client.advisor: debug # AI对话的日志级别
    com.shisan.ai: debug # 本项目的日志级别

重启项目，再次聊天就能在IDEA的运行控制台中看到AI对话的日志信息了；