Feature Request: Migrate from Azure OpenAI Java SDK to OpenAI Java Library

Summary

Request to add support for the official OpenAI Java library (openai-java) in Spring AI, as the Azure OpenAI Java SDK has been deprecated and is no longer receiving updates.

Background

The Azure OpenAI Java SDK (previously used by Spring AI) has been officially deprecated and Microsoft is directing users to migrate to the community-maintained OpenAI Java library. This change affects Spring AI users who rely on OpenAI integration through Azure endpoints.

Current Status: - Azure OpenAI Java SDK: ⚠️ Deprecated - No longer receiving updates - Recommended Alternative: [OpenAI Java Library]- Actively maintained community project

Motivation

Sustainability: The current Azure OpenAI SDK will not receive security updates or new features
Future Compatibility: New OpenAI API features will only be available through the actively maintained library
Community Support: The OpenAI Java library has active community support and regular updates
API Parity: Ensures continued compatibility with latest OpenAI API capabilities

Proposed Solution

Implement support for the OpenAI Java library while maintaining backward compatibility where possible.

Suggested Implementation Approach:

Add new dependency: Include openai-java library as an optional dependency
Create new configuration classes: Implement Spring Boot auto-configuration for the new library
Maintain existing interfaces: Keep current Spring AI interfaces to minimize breaking changes
Provide migration guide: Document the transition path for existing users
Deprecation timeline: Establish a timeline for phasing out the old Azure SDK integration

Benefits

Long-term maintainability: Ensures Spring AI remains up-to-date with OpenAI developments
Enhanced features: Access to latest OpenAI API capabilities
Better performance: Potential improvements from actively maintained library
Community alignment: Aligns with OpenAI ecosystem recommendations

Compatibility Considerations

Maintain existing Spring AI API surface to minimize migration effort
Provide clear migration documentation
Consider supporting both libraries during a transition period
Ensure Azure OpenAI endpoints continue to work with the new library

Implementation Tasks

[ ] Research OpenAI Java library integration requirements
[ ] Design new auto-configuration classes
[ ] Implement new client adapters
[ ] Create comprehensive tests
[ ] Write migration documentation
[ ] Update Spring AI documentation

Alternative Solutions Considered

Continue with deprecated Azure SDK: Not viable due to lack of updates
Custom HTTP client implementation: More maintenance overhead
Multiple library support: Increases complexity but may be necessary during transition

Impact Assessment

Breaking Changes: Minimal if existing interfaces are preserved
Migration Effort: Medium - requires configuration updates
Timeline: Suggest implementation in next major/minor release

References

Community Input

This feature request addresses a critical dependency issue that affects all Spring AI users leveraging OpenAI integration. Community feedback and contributions would be valuable for ensuring a smooth transition.

Priority: High - Due to deprecated dependency security and maintenance concerns Type: Enhancement/Migration Area: Core Integration

Comment From: apappascs

migration guide: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/openai/azure-ai-openai-stainless/MIGRATION.md

Comment From: making

Spring AI's OpenAI client doesn't use the OpenAI Java SDK. Instead, it uses RestClient and WebClient. I prefer this approach because Spring's existing ecosystem can be leveraged.

Just like the OpenAI Java SDK does, Spring's OpenAI client can also access Azure OpenAI Service. In fact, Azure OpenAI Service can be accessed by adding spring-ai-starter-model-openai (not spring-ai-starter-model-azure-openai) to dependencies and setting up properties like this.

spring.ai.openai.base-url=https://xxxxxxxxxxx.openai.azure.com
spring.ai.openai.chat.options.model=gpt-4.1-mini
spring.ai.openai.chat.completions-path=/openai/deployments/${spring.ai.openai.chat.options.model}/chat/completions?api-version=2024-02-01
spring.ai.openai.api-key=${AZURE_OPEN_AI_API_KEY}

Since the Azure OpenAI Java SDK has been deprecated, wouldn't it be good for Spring AI to deprecate spring-ai-starter-model-azure-openai and recommend spring-ai-starter-model-openai instead? If Entra ID authentication is desired like the migration guide linked in the comment above, only com.azure:azure-identity would need to be added.

Comment From: jdubois

Hey, I work at Microsoft and implemented the Azure OpenAI SDK and the new OpenAI Java SDK (the official one, from Stainless, that you mention) on LangChain4j. The Azure OpenAI SDK isn't deprecated or unmaintained: we have numerous customers happily using it, and there's no issue at all in doing so. There's obviously some historical reason (it was the first one available), but also it integrates better with the Azure stack (if you're an Azure user, you probably use other Azure libraries, and you want unified dependencies). That being said, I'm personally a big fan of the OpenAI Java SDK, and I believe it should be available for Spring AI users. As most LLMs providers will support it as the de facto standard, you'll also have more LLMs supporting it than the Azure OpenAI SDK (it works with DeepSeek, for example). As I did this for LangChain4j (have a look at https://github.com/langchain4j/langchain4j/pull/2508 ), I can volunteer to do it also for Spring AI -> I'm not sure who to ask for validation, @markpollack maybe?).