Migrate from Azure OpenAI Java SDK to OpenAI Java Library

[Reasch]

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

1. Sustainability: The current Azure OpenAI SDK will not receive security updates or new features
2. Future Compatibility: New OpenAI API features will only be available through the actively maintained library
3. Community Support: The OpenAI Java library has active community support and regular updates
4. 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:

1. Add new dependency: Include openai-java library as an optional dependency
2. Create new configuration classes: Implement Spring Boot auto-configuration for the new library
3. Maintain existing interfaces: Keep current Spring AI interfaces to minimize breaking changes
4. Provide migration guide: Document the transition path for existing users
5. 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

1. Continue with deprecated Azure SDK: Not viable due to lack of updates
2. Custom HTTP client implementation: More maintenance overhead
3. 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

• [Azure OpenAI Java SDK Deprecation Notice]
• [OpenAI Java Library]
• [Spring AI Documentation]

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

[apappascs]

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

[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.

[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 langchain4j/langchain4j#2508 ), I can volunteer to do it also for Spring AI -> I'm not sure who to ask for validation, @markpollack maybe?).

[apappascs]

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 langchain4j/langchain4j#2508 ), I can volunteer to do it also for Spring AI -> I'm not sure who to ask for validation, @markpollack maybe?).

I think @markpollack or @tzolov could help you!

[jdubois]

@apappascs yes let's discuss this here if possible, and otherwise I'll ping them directly

[jdubois]

OK, it's been more than one month, so I'll start working on this in a draft pull request.

-> @markpollack and @tzolov is this OK for you?

[jdubois]

Following this very interesting conversation at #2962 I might use the responses API instead, I'll have a look.

[markpollack]

It all sounds great. This needs to align with the 2.0 time frame and not go into main now. If it helps @jdubois we can set it up as a community projects and it can incubate there. Thoughts?

[jdubois]

Oh I was starting a PR on this project to have it next to the others -> it's probably easier for me like this as I have everything next to each other, I'll just do a draft PR and then we can move it around depending on how it goes.