Spring AI 源码解析（一）：自动配置与核心启动流程

Spring AI 源码解析（一）：自动配置与核心启动流程

经过前面四篇文章的学习，我们已经能够熟练使用 Spring AI 进行开发。但从今天开始，我们将深入源码层面，探究 Spring AI 背后的实现原理。本文作为源码解析系列的第一篇，将重点分析 Spring AI 的自动配置机制和核心启动流程。

概述：从 Starter 到 Bean 的完整链路

当我们在项目中引入 spring-ai-openai-spring-boot-starter 时，Spring Boot 会在启动时自动完成以下工作：

源码入口：自动配置类

OpenAiAutoConfiguration

所有的自动配置都始于 OpenAiAutoConfiguration 类，位于 spring-ai-openai 模块：

@AutoConfiguration
@ConditionalOnClass(OpenAiApi.class)
@EnableConfigurationProperties(OpenAiConnectionProperties.class)
public class OpenAiAutoConfiguration {

@Bean
@ConditionalOnMissingBean
public OpenAiApi openAiApi(
OpenAiConnectionProperties connectionProperties,
OpenAiChatOptions chatOptions) {
return new OpenAiApi(
connectionProperties.getBaseUrl(),
connectionProperties.getApiKey(),
connectionProperties.getApiVersion(),
chatOptions);
}
}

关键点解析：

• @AutoConfiguration：标记为自动配置类
• @ConditionalOnClass(OpenAiApi.class)：仅当 OpenAiApi 类在 Classpath 中存在时才生效
• @EnableConfigurationProperties：绑定以 spring.ai.openai 为前缀的配置属性

ChatModel 的自动装配

@Configuration
@ConditionalOnBean(OpenAiApi.class)
@ConditionalOnProperty(
prefix = "spring.ai.openai.chat", name = "enabled",
havingValue = "true", matchIfMissing = true)
public class OpenAiChatAutoConfiguration {

@Bean
@ConditionalOnMissingBean
public OpenAiChatModel openAiChatModel(
OpenAiApi openAiApi,
OpenAiChatOptions chatOptions,
List<FunctionCallback> toolFunctions) {
return new OpenAiChatModel(openAiApi, chatOptions)
.withToolFunctions(toolFunctions);
}

@Bean
@ConditionalOnMissingBean
public ChatClient.Builder chatClientBuilder(
List<ChatModel> chatModels) {
return ChatClient.builder(chatModels.get(0));
}
}

配置属性绑定

属性类层次

@ConfigurationProperties(prefix = "spring.ai.openai")
public class OpenAiConnectionProperties {

private String baseUrl = "https://api.openai.com";
private String apiKey;
private String apiVersion;
private OpenAiChatOptions chat = new OpenAiChatOptions();
private OpenAiEmbeddingOptions embedding = new OpenAiEmbeddingOptions();
}

public class OpenAiChatOptions implements ChatOptions {

private String model = "gpt-4o";
private Double temperature;
private Integer maxTokens;
private Double topP;
private List<String> stop;
}

核心客户端：OpenAiApi

OpenAiApi 是 OpenAI HTTP 客户端的核心封装，它使用了 Spring 的 RestClient：

public class OpenAiApi {

private final RestClient restClient;
private final OpenAiChatOptions chatOptions;

public OpenAiApi(String baseUrl, String apiKey, OpenAiChatOptions chatOptions) {
this.restClient = RestClient.builder()
.baseUrl(baseUrl)
.defaultHeader("Authorization", "Bearer " + apiKey)
.defaultHeader("Content-Type", "application/json")
.build();
this.chatOptions = chatOptions;
}

public ChatCompletionResult chatCompletion(ChatCompletionRequest request) {
return restClient.post()
.uri("/v1/chat/completions")
.body(request)
.retrieve()
.body(ChatCompletionResult.class);
}
}

启动流程

Spring Boot 启动
|
v
加载 AutoConfiguration.imports
|
+— OpenAiAutoConfiguration
| |
| v
| 创建 OpenAiApi Bean
|
+— OpenAiChatAutoConfiguration
| |
| +— 创建 OpenAiChatModel Bean
| +— 创建 ChatClient.Builder Bean
|
+— OpenAiEmbeddingAutoConfiguration
| |
| v
| 创建 OpenAiEmbeddingModel Bean
|
v
应用启动完成，所有 AI Bean 就绪

条件装配的巧妙之处

Spring AI 大量使用了 Spring Boot 的条件注解来实现灵活的装配策略：

关键设计原则：Spring AI 始终优先使用用户自定义的 Bean，只有当用户未提供时才使用默认实现，这符合 Spring 生态的一贯理念。

总结：本文要点

• Spring AI 的自动配置入口是 OpenAiAutoConfiguration
• 条件装配 通过 @ConditionalOnClass、@ConditionalOnMissingBean 等注解实现灵活控制
• OpenAiApi 是对 OpenAI REST API 的 HTTP 客户端封装，使用 Spring 6 的 RestClient
• 配置属性绑定通过 @ConfigurationProperties 实现，前缀为 spring.ai.openai
• 自动配置的最终产物是 ChatModel、EmbeddingModel 等核心 Bean 以及 ChatClient.Builder