Spring AI 项目中使用Azure OpenAI O3-mini模型的问题解析

在Spring AI项目中集成Azure OpenAI服务时，开发者可能会遇到调用O3-mini模型失败的问题，错误提示显示该模型仅支持2024-12-01-preview及更高版本的API。本文将深入分析这一问题背后的技术原因，并提供解决方案。

问题现象

当开发者尝试通过Spring AI调用Azure OpenAI的O3-mini模型时，系统会抛出HttpResponseException异常，错误信息明确指出："Model {modelName} is enabled only for api versions 2024-12-01-preview and later"。这表明当前使用的API版本与模型要求不兼容。

根本原因分析

这一问题源于Azure OpenAI服务的API版本管理机制。Azure平台会定期更新其API版本，新推出的模型（如O3-mini）通常需要较新的API版本支持。Spring AI项目底层依赖Azure SDK for Java来实现与Azure OpenAI的交互，而SDK中内置的API版本可能滞后于模型要求。

具体来说，Spring AI 1.0.0-M6版本使用的azure-ai-openai库版本为1.0.0-beta.13，该版本支持的API版本可能不包含2024-12-01-preview或更高版本。

解决方案

要解决这一问题，开发者可以采取以下步骤：

1. 升级依赖版本：将azure-ai-openai库升级至1.0.0-beta.14或更高版本，这些版本已经包含了支持O3-mini模型所需的API版本。

2. 显式指定API版本：在创建OpenAIClient时，显式设置服务版本为最新支持的预览版：

@Bean
public OpenAIClientBuilder openAIClientBuilder() {
    return new OpenAIClientBuilder()
        .credential(new AzureKeyCredential(apiKey))
        .endpoint(endpoint)
        .serviceVersion(OpenAIServiceVersion.V2025_01_01_PREVIEW);
}

3. 检查模型部署：确保在Azure AI Foundry中正确部署了O3-mini模型，并且部署名称与配置文件中指定的名称一致。

最佳实践

为了避免类似问题，建议开发者：

1. 定期关注Azure OpenAI服务的API版本更新公告
2. 在项目中使用最新的稳定版SDK
3. 对于预览版模型，确保使用对应的预览版API
4. 在配置文件中明确记录使用的API版本信息

总结

Spring AI项目与Azure OpenAI的集成需要特别注意API版本与模型版本的兼容性。通过理解Azure平台的版本管理机制，并采取适当的升级和配置措施，开发者可以顺利使用包括O3-mini在内的各种新模型。这一问题的解决也体现了云服务集成中版本管理的重要性，值得所有开发者重视。