Spring AI 代码分析（十）--Spring Boot集成

Spring Boot 集成分析

请关注微信公众号：阿呆-bot

1. 工程结构概览

Spring AI 通过 Spring Boot Starter 和 Auto Configuration 机制，实现了零配置的 AI 应用开发。开发者只需要添加依赖和配置属性，就能使用各种 AI 能力。

复制代码

spring-ai-spring-boot-starters/  # Starter 模块
├── spring-ai-starter-model-openai/      # OpenAI Starter
├── spring-ai-starter-model-ollama/        # Ollama Starter
├── spring-ai-starter-vector-store-pgvector/  # PGVector Starter
└── ... (50+ 个 Starter)

auto-configurations/              # 自动配置模块
├── models/                      # 模型自动配置
│   ├── spring-ai-autoconfigure-model-openai/
│   ├── spring-ai-autoconfigure-model-ollama/
│   └── ...
├── vector-stores/               # 向量存储自动配置
│   ├── spring-ai-autoconfigure-vector-store-pgvector/
│   └── ...
├── common/                      # 通用自动配置
│   ├── spring-ai-autoconfigure-retry/
│   └── spring-ai-autoconfigure-model-tool/
└── mcp/                         # MCP 自动配置

2. 技术体系与模块关系

Spring Boot 集成采用 Starter + Auto Configuration 模式：

3. 关键场景示例代码

3.1 最简单的使用

只需要添加依赖和配置：

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

yaml 复制代码

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4

java 复制代码

@RestController
public class ChatController {
    @Autowired
    private ChatModel chatModel;  // 自动注入
    
    @GetMapping("/chat")
    public String chat(String message) {
        return chatModel.call(message);
    }
}

3.2 配置属性

所有配置都通过 application.yml 或 application.properties：

yaml 复制代码

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4
          temperature: 0.7
          max-tokens: 1000
      embedding:
        options:
          model: text-embedding-3-small

3.3 条件装配

自动配置会根据条件决定是否启用：

java 复制代码

@AutoConfiguration
@ConditionalOnClass(OpenAiChatModel.class)
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true
)
public class OpenAiChatAutoConfiguration {
    // ...
}

3.4 自定义 Bean

可以覆盖自动配置的 Bean：

java 复制代码

@Configuration
public class CustomConfig {
    @Bean
    @Primary
    public ChatModel customChatModel() {
        // 自定义实现
        return new CustomChatModel();
    }
}

4. 核心实现图

4.1 自动配置流程

5. 入口类与关键类关系

6. 关键实现逻辑分析

6.1 Starter 设计

Starter 是一个空的 Maven 模块，只包含依赖：

xml 复制代码

<dependencies>
    <!-- 核心实现 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai</artifactId>
    </dependency>
    
    <!-- 自动配置 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-model-openai</artifactId>
    </dependency>
    
    <!-- 通用自动配置 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-retry</artifactId>
    </dependency>
</dependencies>

Starter 的优势：

简化依赖管理：用户只需要添加一个依赖
版本统一：所有相关依赖版本统一管理
功能完整：包含所有必需的依赖

6.2 自动配置类实现

自动配置类使用条件注解：

java 复制代码

@AutoConfiguration
@ConditionalOnClass(OpenAiChatModel.class)
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true
)
@EnableConfigurationProperties(OpenAiChatProperties.class)
public class OpenAiChatAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public OpenAiChatModel chatModel(
        OpenAiChatProperties properties,
        RetryTemplate retryTemplate,
        RestClient.Builder restClientBuilder
    ) {
        // 1. 构建 API 客户端
        OpenAiApi openAiApi = new OpenAiApi(
            properties.getBaseUrl(),
            properties.getApiKey(),
            restClientBuilder,
            retryTemplate
        );
        
        // 2. 创建 ChatModel
        return new OpenAiChatModel(
            openAiApi,
            properties.getChat().getOptions()
        );
    }
    
    @Bean
    @ConditionalOnMissingBean
    public OpenAiChatOptions chatOptions(OpenAiChatProperties properties) {
        return properties.getChat().getOptions();
    }
}

关键注解说明：

@AutoConfiguration：标记为自动配置类
@ConditionalOnClass：只有当类路径存在指定类时才启用
@ConditionalOnProperty：只有当配置属性满足条件时才启用
@ConditionalOnMissingBean：只有当容器中不存在指定 Bean 时才创建
@EnableConfigurationProperties：启用配置属性绑定

6.3 配置属性绑定

配置属性类使用 @ConfigurationProperties：

java 复制代码

@ConfigurationProperties(prefix = "spring.ai.openai")
public class OpenAiChatProperties {
    private String apiKey;
    private String baseUrl = "https://api.openai.com";
    
    private Chat chat = new Chat();
    
    public static class Chat {
        private boolean enabled = true;
        private OpenAiChatOptions options = new OpenAiChatOptions();
        
        // getters and setters
    }
    
    // getters and setters
}

配置属性支持：

类型安全：强类型绑定
IDE 提示 ：通过 spring-boot-configuration-processor 生成元数据
验证：支持 JSR-303 验证注解

6.4 自动配置注册

自动配置类通过 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 注册：

复制代码

org.springframework.ai.model.openai.autoconfigure.OpenAiChatAutoConfiguration
org.springframework.ai.model.openai.autoconfigure.OpenAiEmbeddingAutoConfiguration
org.springframework.ai.model.openai.autoconfigure.OpenAiImageAutoConfiguration

Spring Boot 3.x 使用 AutoConfiguration.imports 文件（替代了之前的 spring.factories）。

6.5 条件装配机制

Spring AI 使用多种条件注解：

java 复制代码

// 1. 类路径条件
@ConditionalOnClass(OpenAiChatModel.class)

// 2. 配置属性条件
@ConditionalOnProperty(
    prefix = "spring.ai.openai.chat",
    name = "enabled",
    havingValue = "true"
)

// 3. Bean 存在条件
@ConditionalOnMissingBean(ChatModel.class)

// 4. 资源条件
@ConditionalOnResource(resources = "classpath:openai-config.properties")

这些条件让自动配置变得智能：

按需加载：只加载需要的配置
避免冲突：不会覆盖用户自定义的 Bean
灵活配置：可以通过配置属性控制行为

6.6 重试机制自动配置

重试是 AI 应用的重要能力：

java 复制代码

@AutoConfiguration
@ConditionalOnClass(RetryUtils.class)
@EnableConfigurationProperties(SpringAiRetryProperties.class)
public class SpringAiRetryAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public RetryTemplate retryTemplate(SpringAiRetryProperties properties) {
        return RetryTemplate.builder()
            .maxAttempts(properties.getMaxAttempts())
            .retryOn(TransientAiException.class)
            .retryOn(ResourceAccessException.class)
            .exponentialBackoff(
                properties.getBackoff().getInitialInterval(),
                properties.getBackoff().getMultiplier(),
                properties.getBackoff().getMaxInterval()
            )
            .build();
    }
}

配置示例：

yaml 复制代码

spring:
  ai:
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 1s
        multiplier: 2.0
        max-interval: 10s

6.7 工具调用自动配置

工具调用自动配置：

java 复制代码

@AutoConfiguration
@ConditionalOnClass({ToolCallingManager.class, ChatModel.class})
public class ToolCallingAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    public ToolCallingManager toolCallingManager(
        ObservationRegistry observationRegistry,
        ToolCallbackResolver toolCallbackResolver
    ) {
        return new DefaultToolCallingManager(
            observationRegistry,
            toolCallbackResolver,
            new DefaultToolExecutionExceptionProcessor()
        );
    }
    
    @Bean
    @ConditionalOnMissingBean
    public ToolCallbackResolver toolCallbackResolver(ApplicationContext context) {
        return new DelegatingToolCallbackResolver(
            new SpringBeanToolCallbackResolver(context),
            new StaticToolCallbackResolver()
        );
    }
}

7. 配置属性管理

7.1 配置属性层次

Spring AI 的配置属性采用层次结构：

yaml 复制代码

spring:
  ai:
    openai:                    # 提供商级别
      api-key: xxx
      chat:                     # 功能级别
        enabled: true
        options:                # 选项级别
          model: gpt-4
          temperature: 0.7

7.2 配置属性验证

支持 JSR-303 验证：

java 复制代码

@ConfigurationProperties(prefix = "spring.ai.openai")
@Validated
public class OpenAiChatProperties {
    @NotBlank
    private String apiKey;
    
    @Min(0)
    @Max(2)
    private Double temperature;
}

7.3 配置属性提示

通过 additional-spring-configuration-metadata.json 提供 IDE 提示：

json 复制代码

{
  "properties": [{
    "name": "spring.ai.openai.chat.options.model",
    "type": "java.lang.String",
    "description": "The model to use for chat completions.",
    "defaultValue": "gpt-3.5-turbo"
  }]
}

8. Bean 创建流程

8.1 Bean 创建顺序

自动配置的 Bean 创建顺序：

配置属性 Bean：首先创建配置属性 Bean
依赖 Bean：创建依赖的 Bean（如 RetryTemplate）
核心 Bean：创建核心功能 Bean（如 ChatModel）
增强 Bean：创建增强功能 Bean（如 Advisor）

8.2 Bean 覆盖机制

用户可以通过 @Primary 或 @ConditionalOnMissingBean 覆盖自动配置的 Bean：

java 复制代码

@Configuration
public class CustomConfig {
    @Bean
    @Primary  // 优先使用
    public ChatModel customChatModel() {
        return new CustomChatModel();
    }
}

9. 外部依赖

9.1 Spring Boot

spring-boot-starter：核心 Starter
spring-boot-autoconfigure：自动配置支持
spring-boot-configuration-processor：配置属性处理

9.2 Spring Framework

spring-context：IoC 容器
spring-beans：Bean 管理
spring-core：核心功能

10. 工程总结

Spring AI 的 Spring Boot 集成设计有几个亮点：

零配置理念。通过 Starter 和 Auto Configuration，用户只需要添加依赖和配置属性，就能使用 AI 能力，无需编写任何配置代码。想用 OpenAI？加个依赖，配个 API Key，就能用了。

条件装配 。使用 @ConditionalOn* 注解，让自动配置变得智能，只加载需要的配置，避免不必要的 Bean 创建

配置属性驱动 。所有配置都通过 application.yml 或 application.properties，支持类型安全和 IDE 提示。写配置时有自动补全，写错了编译期就能发现。

可扩展性 。用户可以轻松覆盖自动配置的 Bean，实现自定义行为。想自定义 ChatModel？加个 @Primary 注解就行。

模块化设计 。每个功能都有独立的 Starter 和 Auto Configuration，用户可以选择性地添加需要的功能。想用向量存储？加个 spring-ai-starter-vector-store-pgvector 就行。

总的来说，Spring AI 的 Spring Boot 集成既简单又强大。简单的使用方式降低了学习成本，强大的自动配置机制让系统可以适应各种场景。这种设计让开发者可以快速构建 AI 应用，同时也能根据需求进行深度定制。