跳到主要内容
版本：1.1.4

原生镜像支持

Spring AI 全面支持 Spring Boot 3.x 的 GraalVM AOT（Ahead-of-Time）编译，所有模块均已内置 RuntimeHints 注册，无需额外配置即可编译为原生可执行文件。

1. 启用原生编译​

Spring AI 不引入额外的配置属性，只需在项目中启用 Spring Boot 标准的 GraalVM Native Image 插件：

pom.xml
<!-- Spring Boot 3.x 原生镜像插件 -->
<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
</plugin>
# 使用 Maven 构建原生镜像
mvn -Pnative native:compile

# 使用 Gradle 构建原生镜像
gradle nativeCompile

Spring 的 AOT 引擎在构建时自动发现所有 META-INF/spring/aot.factories 文件，生成必要的反射、资源和代理配置。

2. AOT 注册机制​

Spring AI 通过两种机制注册原生镜像提示：

2.1 RuntimeHintsRegistrar（aot.factories）​

每个模块通过 META-INF/spring/aot.factories 注册 RuntimeHintsRegistrar 实现，构建时由 Spring AOT 引擎调用，生成反射/资源/代理配置。

Spring AI 共包含 16 个 aot.factories 文件，分布在以下模块：

核心模块：

模块注册内容
spring-ai-model所有 Message 类型（UserMessage、AssistantMessage、SystemMessage、ToolResponseMessage 等）、ToolCallback、ToolDefinition、tiktoken BPE 编码文件
spring-ai-vector-storeANTLR 过滤器语法文件 Filters.g4

模型厂商模块：

模块注册内容
spring-ai-openaiorg.springframework.ai.openai 包下所有 Jackson 注解类
spring-ai-ollamaorg.springframework.ai.ollama 包下所有 Jackson 注解类
spring-ai-anthropicorg.springframework.ai.anthropic 包下所有 Jackson 注解类
spring-ai-deepseekorg.springframework.ai.deepseek.api 包下所有 Jackson 注解类
spring-ai-minimaxorg.springframework.ai.minimax 包下所有 Jackson 注解类
spring-ai-mistral-aiorg.springframework.ai.mistralai 包下所有 Jackson 注解类
spring-ai-zhipuaiorg.springframework.ai.zhipuai 包下所有 Jackson 注解类
spring-ai-vertex-ai-geminiorg.springframework.ai.vertexai.gemini 包下所有 Jackson 注解类
spring-ai-azure-openaiAzure SDK 的 OpenAIClient/OpenAIAsyncClient、com.azure.ai.openai.models 全部类、JDK 代理
spring-ai-bedrockorg.springframework.ai.bedrock 包下所有 Jackson 注解类

MCP 模块：

模块注册内容
mcp/commonMcpSchema 的所有嵌套/内部类（用于 JSON 序列化）
mcp/autoconfigureMCP 自动配置相关 Jackson 注解类、**.json 资源模式

其他模块：

模块注册内容
pdf-readerApache PDFBox/FontBox 全部资源文件（字体、CMap、AFM、ICC 等）
pinecone-storeProtobuf 相关类（com.google.protobuf.Value、Struct）
jdbc-chat-memoryjavax.sql.DataSource 反射、SQL Schema 文件资源

2.2 @Tool 注解的 AOT 处理​

spring-ai-model 模块包含 ToolBeanRegistrationAotProcessor，在构建时扫描所有 Bean 中标注 @Tool 的方法，自动生成反射提示注册 Bean 类。这意味着用户在自定义 Bean 中使用的 @Tool 方法在原生素镜像中同样可用，无需手动注册反射。

2.3 @ImportRuntimeHints​

AbstractEmbeddingModel 通过 @ImportRuntimeHints 注册 embedding/embedding-model-dimensions.properties 资源文件，由 Spring AOT 引擎在编译期处理。

3. 使用注意事项​

Jackson 序列化： 各模型厂商的 API 请求/响应类在原生镜像中依赖 Jackson 的反射序列化。所有模型模块已自动扫描并注册带有 @JsonInclude 或 @JsonProperty 注解的类。如果你自定义了请求/响应体，需要通过 RuntimeHintsRegistrar 手动注册。

Azure OpenAI： 由于依赖 Azure SDK 中的大量模型类，该模块单独注册了 com.azure.ai.openai.models 包下的全部类，而非仅 Jackson 注解类。

PDF 读取器： PDFBox 依赖大量字体和 CMap 资源文件，PdfReaderRuntimeHints 已全部注册，确保 PDF 文档读取在原生素镜像中正常工作。

JDBC 聊天记忆： 已注册 DDL 脚本资源模式（schema-*.sql），支持嵌入式数据库的自动建表。

4. 完整示例​

完整示例：原生镜像编译 pom.xml
<project>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.11</version>
    </parent>

    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.1.4</spring-ai.version>
    </properties>

    <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>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-ollama</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.graalvm.buildtools</groupId>
                <artifactId>native-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>