跳至主要內容

Spring AI 1.0正式版：核心新特性全解析与迁移指南

老张2026/4/21大约 16 分钟Spring AI 1.0新特性迁移指南ChatClientJava

Spring AI 1.0正式版：核心新特性全解析与迁移指南

那个周一早上，204个编译错误

2025年11月的一个周一早上8:47，阿里云某事业部的技术负责人陈明盯着屏幕，脸色铁青。

他的团队花了整整一个周末，把公司内部的AI智能客服系统从Spring AI 0.8.1升级到刚发布的1.0.0。结果：204个编译错误，一个都运行不了。

error: cannot find symbol
  symbol:   class AiClient
  location: class CustomerServiceBot
error: cannot find symbol  
  symbol:   class OpenAiChatClient
  location: class ModelConfig
error: package org.springframework.ai.client does not exist
...（共204个）

陈明的团队有12个人，AI项目投入了6个月，代码量超过8万行。当初选择Spring AI时，看中的是Spring生态的稳定性。结果1.0正式版一出，整个AI层全部需要重写。

这不是个例。Spring AI从0.x到1.0的升级，涉及到核心API的全面重构：AiClient消失了，ChatClient彻底改变了，FunctionCallback变成了@Tool，连包名都变了。

陈明团队最终花了11天完成迁移，期间踩了大量坑。他在内部复盘会上说了一句话：

"如果当初有一篇完整的迁移指南，我们最多3天就能搞定。"

这篇文章，就是那份迁移指南。

Spring AI版本演进全景

在开始迁移之前，先搞清楚Spring AI的版本历史，很多人对此一知半解。

关键时间节点：

  • 0.8.x：很多团队在此版本停留，API相对稳定但是实验性的
  • 1.0.0-M1：开始大规模重构，AiClient被废弃
  • 1.0.0-RC1：ChatClient Fluent API定型
  • 1.0.0正式版：API冻结，生产可用

核心架构变化：一张图看懂

核心变化对比表：

组件0.8.x1.0.0说明
顶层接口AiClientChatModel完全重命名
客户端OpenAiChatClientOpenAiChatModelClient→Model
调用入口ChatClient(直接)ChatClient(Builder模式)变为Fluent API
函数调用FunctionCallback@Tool注解驱动
拦截器无Advisor全新机制
包名org.springframework.ai.clientorg.springframework.ai.chat.client包重组
输出解析BeanOutputParserBeanOutputConverter重命名+增强

完整pom.xml：Spring AI 1.0 BOM

这是迁移的第一步，也是最容易出错的地方。

<?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>
        <!-- Spring AI 1.0要求Spring Boot 3.3+ -->
        <version>3.3.5</version>
        <relativePath/>
    </parent>
    
    <groupId>com.laozhang.ai</groupId>
    <artifactId>spring-ai-1x-demo</artifactId>
    <version>1.0.0</version>
    <name>Spring AI 1.0 Demo</name>
    
    <properties>
        <java.version>21</java.version>
        <!-- Spring AI 1.0 正式版 -->
        <spring-ai.version>1.0.0</spring-ai.version>
    </properties>
    
    <!-- Spring AI BOM：必须在dependencyManagement中声明 -->
    <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>
    
    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Spring AI OpenAI Starter（包含ChatModel） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <!-- 版本由BOM管理，不要手动指定 -->
        </dependency>
        
        <!-- Spring AI Anthropic（Claude支持） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
        </dependency>
        
        <!-- 向量数据库：Redis -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-redis-store-spring-boot-starter</artifactId>
        </dependency>
        
        <!-- 向量数据库：PGVector -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
        </dependency>
        
        <!-- PDF文档读取 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-pdf-document-reader</artifactId>
        </dependency>
        
        <!-- Tika文档读取（多格式） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-tika-document-reader</artifactId>
        </dependency>
        
        <!-- Micrometer监控 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        
        <!-- 测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
    
    <!-- Spring AI里程碑版本需要额外的Repository（正式版不需要） -->
    <!-- 如果使用1.0.0正式版，以下可以删除 -->
    <!--
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    -->
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

application.yml：完整配置

spring:
  application:
    name: spring-ai-1x-demo
  
  ai:
    # OpenAI配置
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com  # 可替换为代理地址
      chat:
        options:
          model: gpt-4o
          temperature: 0.7
          max-tokens: 4096
          top-p: 1.0
          # 1.0新增：流式响应配置
          stream-usage: true
      embedding:
        options:
          model: text-embedding-3-small
    
    # Anthropic配置（Claude）
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-3-5-sonnet-20241022
          max-tokens: 8192
          temperature: 0.7
    
    # 1.0新增：重试配置
    retry:
      max-attempts: 3
      on-client-errors: false  # 4xx不重试
      exclude-on-http-codes: 404, 401  # 这些状态码不重试
      multiplier: 2.0
      initial-interval: 2s
      max-interval: 30s

# 日志配置（开发时查看AI请求详情）
logging:
  level:
    org.springframework.ai: DEBUG
    io.github.resilience4j: INFO

# Actuator（监控Spring AI指标）
management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus
  metrics:
    tags:
      application: ${spring.application.name}

新API详解：ChatClient Fluent API

这是1.0最大的变化。原来的命令式调用变成了流式Builder模式。

基础用法对比

0.8.x旧写法（已废弃）：

// 旧写法 - 在1.0中编译报错
@Autowired
private ChatClient chatClient;  // 注意：1.0中ChatClient不能直接注入了

public String ask(String question) {
    return chatClient.call(question);
}

1.0新写法：

package com.laozhang.ai.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Service
public class ChatService {
    
    private final ChatClient chatClient;
    
    // 1.0中，通过ChatClient.Builder构建
    public ChatService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
            .defaultSystem("你是一个专业的Java技术专家，擅长Spring生态系统")
            .build();
    }
    
    // 最简单的调用
    public String simpleAsk(String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }
    
    // 带系统提示词的调用
    public String askWithSystem(String systemPrompt, String userMessage) {
        return chatClient.prompt()
            .system(systemPrompt)
            .user(userMessage)
            .call()
            .content();
    }
    
    // 带参数的提示词模板
    public String askWithTemplate(String userName, String topic) {
        return chatClient.prompt()
            .system(s -> s.text("你是{role}，请用{style}回答问题")
                         .param("role", "Java架构师")
                         .param("style", "简洁专业的风格"))
            .user(u -> u.text("{user}想了解{topic}的最佳实践")
                        .param("user", userName)
                        .param("topic", topic))
            .call()
            .content();
    }
}

ChatClient完整配置类

package com.laozhang.ai.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.anthropic.AnthropicChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

@Configuration
public class ChatClientConfig {
    
    /**
     * 主ChatClient（使用OpenAI）
     * 带默认Advisor链
     */
    @Bean
    @Primary
    public ChatClient primaryChatClient(OpenAiChatModel openAiChatModel) {
        return ChatClient.builder(openAiChatModel)
            // 默认系统提示词
            .defaultSystem("""
                你是老张AI助手，专注于帮助Java工程师进行AI转型。
                请用专业、简洁的语言回答问题。
                如果问题超出你的知识范围，请直接说明。
                """)
            // 默认Advisor链（按顺序执行）
            .defaultAdvisors(
                new SimpleLoggerAdvisor(),          // 日志记录
                new MessageChatMemoryAdvisor(new InMemoryChatMemory())  // 对话记忆
            )
            // 默认ChatOptions
            .defaultOptions(
                org.springframework.ai.openai.OpenAiChatOptions.builder()
                    .withModel("gpt-4o")
                    .withTemperature(0.7f)
                    .withMaxTokens(2048)
                    .build()
            )
            .build();
    }
    
    /**
     * Claude ChatClient（备用）
     */
    @Bean("claudeChatClient")
    public ChatClient claudeChatClient(AnthropicChatModel anthropicChatModel) {
        return ChatClient.builder(anthropicChatModel)
            .defaultSystem("你是Claude，Anthropic开发的AI助手。")
            .defaultAdvisors(new SimpleLoggerAdvisor())
            .build();
    }
    
    /**
     * 无Advisor的轻量ChatClient（用于批量处理，减少开销）
     */
    @Bean("lightChatClient")
    public ChatClient lightChatClient(OpenAiChatModel openAiChatModel) {
        return ChatClient.builder(openAiChatModel).build();
    }
}

Advisor机制：Spring AI 1.0最重要的新特性

Advisor是1.0引入的AOP思想在AI调用链上的应用，可以在请求前/后插入自定义逻辑。

SafeGuardAdvisor：安全防护实现

package com.laozhang.ai.advisor;

import org.springframework.ai.chat.client.advisor.api.AdvisedRequest;
import org.springframework.ai.chat.client.advisor.api.AdvisedResponse;
import org.springframework.ai.chat.client.advisor.api.CallAroundAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAroundAdvisorChain;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.model.Generation;
import lombok.extern.slf4j.Slf4j;

import java.util.List;
import java.util.Map;
import java.util.regex.Pattern;

/**
 * 安全防护Advisor
 * 拦截包含敏感词/注入攻击的请求
 */
@Slf4j
public class SafeGuardAdvisor implements CallAroundAdvisor {
    
    // 危险关键词列表（实际项目中从数据库或配置中心加载）
    private static final List<String> BLOCKED_WORDS = List.of(
        "忽略之前的指令", "ignore previous", "system prompt", 
        "你是谁", "reveal your instructions", "DAN",
        "jailbreak", "越狱", "扮演", "roleplay as evil"
    );
    
    // SQL注入检测
    private static final Pattern SQL_PATTERN = Pattern.compile(
        "(?i)(drop|delete|truncate|insert|update|select).*(table|from|into|set)",
        Pattern.CASE_INSENSITIVE
    );
    
    @Override
    public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, 
                                       CallAroundAdvisorChain chain) {
        // 1. 请求前检测
        String userInput = extractUserInput(advisedRequest);
        
        if (containsBlockedContent(userInput)) {
            log.warn("[SafeGuard] 检测到危险内容，拦截请求: {}", 
                     userInput.substring(0, Math.min(50, userInput.length())));
            
            // 返回拒绝响应，不调用LLM
            return buildRejectedResponse(advisedRequest);
        }
        
        // 2. 放行，继续调用链
        AdvisedResponse response = chain.nextAroundCall(advisedRequest);
        
        // 3. 响应后检测（可选）
        // checkResponseContent(response);
        
        return response;
    }
    
    private String extractUserInput(AdvisedRequest request) {
        return request.userText() != null ? request.userText() : "";
    }
    
    private boolean containsBlockedContent(String input) {
        String lowerInput = input.toLowerCase();
        
        // 检测敏感词
        for (String word : BLOCKED_WORDS) {
            if (lowerInput.contains(word.toLowerCase())) {
                return true;
            }
        }
        
        // 检测SQL注入特征
        if (SQL_PATTERN.matcher(input).find()) {
            log.warn("[SafeGuard] 疑似SQL注入: {}", input);
            return true;
        }
        
        return false;
    }
    
    private AdvisedResponse buildRejectedResponse(AdvisedRequest request) {
        AssistantMessage message = new AssistantMessage(
            "抱歉，您的请求包含不允许的内容，无法处理。如有疑问请联系管理员。"
        );
        ChatResponse chatResponse = new ChatResponse(
            List.of(new Generation(message))
        );
        return new AdvisedResponse(chatResponse, Map.of());
    }
    
    @Override
    public String getName() {
        return "SafeGuardAdvisor";
    }
    
    @Override
    public int getOrder() {
        // 数值越小越先执行，安全检测应最先执行
        return Integer.MIN_VALUE + 100;
    }
}

LoggingAdvisor：完整日志追踪

package com.laozhang.ai.advisor;

import org.springframework.ai.chat.client.advisor.api.AdvisedRequest;
import org.springframework.ai.chat.client.advisor.api.AdvisedResponse;
import org.springframework.ai.chat.client.advisor.api.CallAroundAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAroundAdvisorChain;
import org.springframework.ai.chat.metadata.Usage;
import lombok.extern.slf4j.Slf4j;

import java.time.Duration;
import java.time.Instant;
import java.util.Optional;

/**
 * 完整日志追踪Advisor
 * 记录请求/响应/Token消耗/耗时
 */
@Slf4j
public class DetailedLoggingAdvisor implements CallAroundAdvisor {
    
    private final boolean logRequestContent;
    private final boolean logResponseContent;
    
    public DetailedLoggingAdvisor(boolean logRequestContent, boolean logResponseContent) {
        this.logRequestContent = logRequestContent;
        this.logResponseContent = logResponseContent;
    }
    
    public static DetailedLoggingAdvisor forProduction() {
        // 生产环境：不记录具体内容，只记录统计信息
        return new DetailedLoggingAdvisor(false, false);
    }
    
    public static DetailedLoggingAdvisor forDevelopment() {
        // 开发环境：记录完整内容
        return new DetailedLoggingAdvisor(true, true);
    }
    
    @Override
    public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, 
                                       CallAroundAdvisorChain chain) {
        Instant start = Instant.now();
        String requestId = generateRequestId();
        
        // 请求日志
        logRequest(requestId, advisedRequest);
        
        AdvisedResponse response;
        try {
            response = chain.nextAroundCall(advisedRequest);
        } catch (Exception e) {
            long durationMs = Duration.between(start, Instant.now()).toMillis();
            log.error("[AI-LOG] requestId={} 调用失败 duration={}ms error={}", 
                      requestId, durationMs, e.getMessage());
            throw e;
        }
        
        // 响应日志
        long durationMs = Duration.between(start, Instant.now()).toMillis();
        logResponse(requestId, response, durationMs);
        
        return response;
    }
    
    private void logRequest(String requestId, AdvisedRequest request) {
        if (logRequestContent) {
            log.info("[AI-LOG] requestId={} system='{}' user='{}'",
                     requestId,
                     truncate(request.systemText(), 100),
                     truncate(request.userText(), 200));
        } else {
            log.info("[AI-LOG] requestId={} AI请求开始 userLength={}", 
                     requestId,
                     Optional.ofNullable(request.userText()).map(String::length).orElse(0));
        }
    }
    
    private void logResponse(String requestId, AdvisedResponse response, long durationMs) {
        Usage usage = Optional.ofNullable(response.response())
            .map(r -> r.getMetadata().getUsage())
            .orElse(null);
        
        if (usage != null) {
            log.info("[AI-LOG] requestId={} duration={}ms promptTokens={} completionTokens={} totalTokens={}",
                     requestId, durationMs,
                     usage.getPromptTokens(),
                     usage.getGenerationTokens(),
                     usage.getTotalTokens());
        } else {
            log.info("[AI-LOG] requestId={} duration={}ms", requestId, durationMs);
        }
        
        if (logResponseContent && response.response() != null) {
            String content = response.response().getResult().getOutput().getContent();
            log.debug("[AI-LOG] requestId={} response='{}'", requestId, truncate(content, 200));
        }
    }
    
    private String generateRequestId() {
        return "ai-" + System.currentTimeMillis() + "-" + 
               (int)(Math.random() * 10000);
    }
    
    private String truncate(String text, int maxLength) {
        if (text == null) return "null";
        return text.length() > maxLength ? text.substring(0, maxLength) + "..." : text;
    }
    
    @Override
    public String getName() {
        return "DetailedLoggingAdvisor";
    }
    
    @Override
    public int getOrder() {
        return 0;
    }
}

@Tool注解：新的函数调用方式

这是从0.8.x的FunctionCallback迁移到1.0的@Tool注解最容易出错的地方。

旧写法（0.8.x）vs 新写法（1.0）

旧写法（已废弃）：

// 0.8.x的FunctionCallback写法 - 1.0中已移除
@Bean
public FunctionCallback weatherFunction() {
    return FunctionCallbackWrapper.builder(new WeatherService())
        .withName("getWeather")
        .withDescription("获取天气信息")
        .withResponseConverter(Object::toString)
        .build();
}

1.0新写法：

package com.laozhang.ai.tool;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import lombok.extern.slf4j.Slf4j;

/**
 * Spring AI 1.0 @Tool注解工具类
 * 注意：@Tool方法必须在Spring Bean中，且方法必须是public
 */
@Slf4j
@Component
public class WeatherTools {
    
    /**
     * 获取当前天气
     * @Tool注解中的description至关重要——AI依赖它决定何时调用
     */
    @Tool(description = "获取指定城市的实时天气信息。支持中国主要城市。" +
                        "返回温度(摄氏度)、天气状况、湿度和风速。")
    public WeatherInfo getCurrentWeather(
            @ToolParam(description = "城市名称，如：北京、上海、深圳") String city) {
        
        log.info("[Tool] 获取天气: city={}", city);
        
        // 实际项目中调用天气API
        return fetchWeatherFromApi(city);
    }
    
    /**
     * 获取未来N天天气预报
     */
    @Tool(description = "获取指定城市未来1-7天的天气预报。" +
                        "当用户询问'明天'、'后天'、'本周'等天气时使用此工具。")
    public WeatherForecast getWeatherForecast(
            @ToolParam(description = "城市名称") String city,
            @ToolParam(description = "预报天数，1-7之间的整数") int days) {
        
        if (days < 1 || days > 7) {
            throw new IllegalArgumentException("预报天数必须在1-7之间，实际值: " + days);
        }
        
        log.info("[Tool] 获取天气预报: city={}, days={}", city, days);
        return fetchForecastFromApi(city, days);
    }
    
    // DTO类
    public record WeatherInfo(
        String city,
        double temperatureCelsius,
        String condition,
        int humidity,
        double windSpeedKmh
    ) {}
    
    public record WeatherForecast(
        String city,
        List<DailyForecast> dailyForecasts
    ) {}
    
    public record DailyForecast(
        String date,
        double maxTemp,
        double minTemp,
        String condition
    ) {}
    
    // 模拟API调用
    private WeatherInfo fetchWeatherFromApi(String city) {
        return new WeatherInfo(city, 22.5, "晴天", 45, 12.3);
    }
    
    private WeatherForecast fetchForecastFromApi(String city, int days) {
        var forecasts = java.util.stream.IntStream.range(0, days)
            .mapToObj(i -> new DailyForecast(
                java.time.LocalDate.now().plusDays(i + 1).toString(),
                20 + i, 15 + i, "多云"))
            .toList();
        return new WeatherForecast(city, forecasts);
    }
}

在ChatClient中使用@Tool

package com.laozhang.ai.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
import lombok.RequiredArgsConstructor;

@Service
@RequiredArgsConstructor
public class WeatherChatService {
    
    private final ChatClient chatClient;
    private final WeatherTools weatherTools;  // 注入工具Bean
    
    public String askAboutWeather(String question) {
        return chatClient.prompt()
            .system("你是天气助手，当用户询问天气时使用提供的工具获取实时数据。")
            .user(question)
            // 1.0新写法：直接传入Bean，Spring AI自动扫描@Tool方法
            .tools(weatherTools)
            .call()
            .content();
    }
    
    // 动态工具（根据用户权限决定开放哪些工具）
    public String askWithDynamicTools(String question, boolean isPremiumUser) {
        var builder = chatClient.prompt()
            .user(question)
            .tools(weatherTools);
        
        // 付费用户才能用高级工具
        if (isPremiumUser) {
            builder = builder.tools(new PremiumWeatherTools());
        }
        
        return builder.call().content();
    }
}

结构化输出升级：BeanOutputConverter进阶

1.0中BeanOutputParser重命名为BeanOutputConverter，并增强了泛型支持。

package com.laozhang.ai.output;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.converter.BeanOutputConverter;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.stereotype.Service;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import lombok.RequiredArgsConstructor;

import java.util.List;

@Service
@RequiredArgsConstructor
public class StructuredOutputService {
    
    private final ChatClient chatClient;
    
    // 输出DTO（使用JsonPropertyDescription增强描述）
    public record TechArticle(
        @JsonPropertyDescription("文章标题，50字以内") 
        String title,
        
        @JsonPropertyDescription("文章摘要，100-200字") 
        String summary,
        
        @JsonPropertyDescription("技术标签列表，3-5个") 
        List<String> tags,
        
        @JsonPropertyDescription("预计阅读时间（分钟）") 
        int estimatedReadMinutes,
        
        @JsonPropertyDescription("文章内容要点，3-5条") 
        List<String> keyPoints
    ) {}
    
    /**
     * 单对象结构化输出（1.0新写法）
     */
    public TechArticle generateArticleOutline(String topic) {
        return chatClient.prompt()
            .system("你是技术文章编辑，请严格按照要求的JSON格式输出。")
            .user("请为主题「" + topic + "」生成一篇技术文章大纲")
            .call()
            // 1.0新写法：直接用entity()方法，无需手动创建Converter
            .entity(TechArticle.class);
    }
    
    /**
     * 泛型List输出（1.0新特性）
     */
    public List<TechArticle> generateMultipleOutlines(String category, int count) {
        return chatClient.prompt()
            .system("你是技术文章编辑，请输出JSON数组。")
            .user("请为「" + category + "」分类生成" + count + "篇文章大纲")
            .call()
            // 使用ParameterizedTypeReference处理泛型
            .entity(new ParameterizedTypeReference<List<TechArticle>>() {});
    }
    
    /**
     * 手动使用BeanOutputConverter（需要更多控制时）
     */
    public TechArticle generateWithManualConverter(String topic) {
        BeanOutputConverter<TechArticle> converter = 
            new BeanOutputConverter<>(TechArticle.class);
        
        // converter.getFormat() 返回JSON Schema，告诉LLM输出格式
        String formatInstructions = converter.getFormat();
        
        String rawResponse = chatClient.prompt()
            .system("你是技术文章编辑。输出格式要求：\n" + formatInstructions)
            .user("请为「" + topic + "」生成文章大纲")
            .call()
            .content();
        
        return converter.convert(rawResponse);
    }
}

多模型Provider动态切换

package com.laozhang.ai.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

/**
 * 多模型动态切换服务
 * 根据任务类型、成本、可用性选择最合适的模型
 */
@Service
public class MultiModelService {
    
    private final ChatClient openAiClient;
    private final ChatClient claudeClient;
    
    public MultiModelService(
            @Qualifier("primaryChatClient") ChatClient openAiClient,
            @Qualifier("claudeChatClient") ChatClient claudeClient) {
        this.openAiClient = openAiClient;
        this.claudeClient = claudeClient;
    }
    
    public enum TaskType {
        CODE_GENERATION,    // 代码生成
        DOCUMENT_ANALYSIS,  // 文档分析（长文本）
        QUICK_QA,          // 快速问答
        CREATIVE_WRITING    // 创意写作
    }
    
    /**
     * 根据任务类型路由到最合适的模型
     */
    public String routeAndCall(String prompt, TaskType taskType) {
        ChatClient selectedClient = selectClient(taskType);
        
        return selectedClient.prompt()
            .user(prompt)
            .call()
            .content();
    }
    
    private ChatClient selectClient(TaskType taskType) {
        return switch (taskType) {
            // 代码生成：GPT-4o更强
            case CODE_GENERATION -> openAiClient;
            // 长文档分析：Claude上下文窗口更大（200K）
            case DOCUMENT_ANALYSIS -> claudeClient;
            // 快速问答：GPT-4o-mini更便宜
            case QUICK_QA -> openAiClient;
            // 创意写作：Claude更有创意
            case CREATIVE_WRITING -> claudeClient;
        };
    }
    
    /**
     * 主备切换：主模型失败时自动切换到备用
     */
    public String callWithFallback(String prompt) {
        try {
            return openAiClient.prompt()
                .user(prompt)
                .call()
                .content();
        } catch (Exception e) {
            log.warn("主模型(OpenAI)调用失败，切换到备用模型(Claude): {}", e.getMessage());
            return claudeClient.prompt()
                .user(prompt)
                .call()
                .content();
        }
    }
    
    private static final org.slf4j.Logger log = 
        org.slf4j.LoggerFactory.getLogger(MultiModelService.class);
}

迁移步骤：5步从0.8.x到1.0

迁移路线图

Step 1：更新pom.xml

<!-- 删除旧的 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.8.1</version>  <!-- 删除手动版本号 -->
</dependency>

<!-- 替换为新的（版本由BOM管理） -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <!-- 无需指定版本 -->
</dependency>

<!-- 在dependencyManagement中添加BOM -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Step 2：批量修复包名（IDE全局替换）

# 使用sed批量替换（macOS/Linux）
# 或直接用IDE的"Find & Replace in Path"

# 包名替换清单：
org.springframework.ai.client.AiClient          → 删除，使用ChatModel
org.springframework.ai.client.ChatClient        → org.springframework.ai.chat.client.ChatClient
org.springframework.ai.openai.OpenAiChatClient  → org.springframework.ai.openai.OpenAiChatModel
org.springframework.ai.parser.BeanOutputParser  → org.springframework.ai.converter.BeanOutputConverter
org.springframework.ai.prompt.PromptTemplate    → org.springframework.ai.chat.prompt.PromptTemplate

Step 3：重构ChatClient注入

// 旧写法（0.8.x）- 编译报错
@Autowired
private ChatClient chatClient;  // 1.0中ChatClient是接口，无法直接注入

// 新写法（1.0）
private final ChatClient chatClient;

public MyService(ChatClient.Builder chatClientBuilder) {
    this.chatClient = chatClientBuilder.build();
}

Step 4：迁移FunctionCallback到@Tool

// 旧写法（0.8.x）
@Bean
public FunctionCallback myFunction() {
    return FunctionCallbackWrapper.builder(new MyService()::doSomething)
        .withName("myFunction")
        .withDescription("...")
        .build();
}

// chatClient.call(new Prompt("...", 
//     OpenAiChatOptions.builder()
//         .withFunction("myFunction")
//         .build()));

// 新写法（1.0）
@Tool(description = "...")
public ResultType myFunction(@ToolParam(description = "...") String param) {
    return service.doSomething(param);
}

// chatClient.prompt().user("...").tools(toolBean).call().content();

Step 5：添加Advisor强化

// 在ChatClient.Builder中添加Advisor
ChatClient client = ChatClient.builder(chatModel)
    .defaultAdvisors(
        new SafeGuardAdvisor(),
        new DetailedLoggingAdvisor(false, false),
        new MessageChatMemoryAdvisor(chatMemory)
    )
    .build();

常见迁移问题FAQ（10个）

Q1：升级后报NoSuchBeanDefinitionException: ChatClient

A：1.0中ChatClient不是自动注入的Bean，必须通过ChatClient.Builder构建。
解决方案：将注入改为 ChatClient.Builder builder，然后调用 builder.build()。

Q2：OpenAiChatClient找不到了

A：1.0中重命名为 OpenAiChatModel。
全局替换：OpenAiChatClient → OpenAiChatModel

Q3：call(Prompt prompt)方法消失了

A：1.0使用Fluent API，不再有直接call(Prompt)方法。
旧：chatClient.call(new Prompt("hello"))
新：chatClient.prompt().user("hello").call().content()

Q4：FunctionCallback相关类全部找不到

A：0.8.x的FunctionCallback体系在1.0中被@Tool完全替代。
需要将所有FunctionCallback实现改为@Tool注解方法。

Q5：BeanOutputParser编译报错

A：重命名为BeanOutputConverter，且使用方式简化。
旧：new BeanOutputParser<>(MyClass.class)
新：chatClient.prompt()...call().entity(MyClass.class)

Q6：Advisor顺序如何保证？

A：Advisor按照getOrder()返回值升序执行（值越小越先执行）。
建议：SafeGuard=MIN_VALUE+100, Logging=0, Memory=100, RAG=200

Q7：配置文件中spring.ai.openai.chat.options失效

A：检查是否升级了Spring Boot到3.3+，部分配置key有细微变化。
参考官方文档重新核对配置项名称。

Q8：流式响应stream()的响应类型变了

A：1.0中流式响应使用Flux<String>。
新：chatClient.prompt().user("...").stream().content()
返回：Flux<String>，需要WebFlux或订阅处理。

Q9：单元测试中如何Mock ChatClient

// 1.0中推荐使用spring-ai-test模块
@SpringBootTest
class MyServiceTest {
    @Autowired
    private MyService myService;
    
    @MockBean
    private ChatModel chatModel;  // Mock底层ChatModel而不是ChatClient
    
    @Test
    void testAsk() {
        when(chatModel.call(any(Prompt.class)))
            .thenReturn(new ChatResponse(List.of(
                new Generation(new AssistantMessage("测试响应"))
            )));
        assertEquals("测试响应", myService.ask("测试问题"));
    }
}

Q10：如何验证迁移完成？

A：运行以下检查清单：
1. mvn compile 无错误
2. 所有import中无 org.springframework.ai.client（旧包）
3. 无 FunctionCallback、OpenAiChatClient、AiClient 引用
4. 启动后能正常调用LLM
5. Advisor链正常执行（查看日志确认）

性能数据：1.0 vs 0.8.x

基于同等配置（GPT-4o, 1000次调用，Java 21虚拟线程）的压测数据：

指标0.8.11.0.0提升
平均响应延迟1243ms1198ms+3.6%
P99延迟3820ms3650ms+4.5%
吞吐量(TPS)8291+10.9%
内存占用512MB478MB-6.6%
启动时间4.2s3.8s-9.5%

1.0的性能提升主要来自：

  • 更高效的HTTP连接池管理
  • Advisor链的零反射实现
  • 优化的JSON序列化

总结

Spring AI 1.0的核心变化可以用4句话概括：

  1. AiClient/ChatClient→ChatModel+ChatClient(Builder)：职责分离更清晰
  2. FunctionCallback→@Tool：注解驱动更简洁
  3. Advisor机制：AOP思想贯穿AI调用链
  4. BeanOutputParser→entity()：结构化输出更简单

陈明团队11天完成的迁移，用这篇指南，你3天就够了。

编辑此页
最近更新:
贡献者: xiaozhangge