Skip to content

Add support for OpenAI Java SDK (official Java library from OpenAI) #4688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 49 commits into from
Closed

Add support for OpenAI Java SDK (official Java library from OpenAI) #4688

wants to merge 49 commits into from

Conversation

@jdubois
Copy link
Contributor

@jdubois jdubois commented Oct 21, 2025

This follows the discussion on ticket #3368

This is a draft PR as the work is pretty big, I'll start with the simpler implementations (Embeddings) and finish with the more complex one (Chat).

@jdubois
Copy link
Contributor Author

jdubois commented Oct 22, 2025

With today's commit, we now have:

  • Support for EmbeddingModel
  • Support for ImageModel

And some basic shared configuration, that will be improved next, so we're ready for the more complex stuff (ChatModel).

@jdubois
Copy link
Contributor Author

jdubois commented Oct 23, 2025

The setup logic for the OpenAI SDK should be very similar to this class from LangChain4, because it's basically doing the same thingj:

https://github.com/langchain4j/langchain4j/blob/main/langchain4j-open-ai-official/src/main/java/dev/langchain4j/model/openaiofficial/InternalOpenAiOfficialHelper.java

I'm very careful before taking code from another project, but I believe this is fine: I'm the author of that other class, so I have the copyright on this code. Also, it's simple logic to connect to Azure/GitHub Models/OpenAI, nothing that is very specific or critical.

However, if this causes problems:

  • I can talk to OpenAI to check if that can be included into their code (I don't think they'll agree as they try to have something generic)
  • I can create my own library, but having both projects depend on a small library that I would maintain doesn't seem a good idea to me

Happy to discuss this if needed.

@jdubois
Copy link
Contributor Author

jdubois commented Nov 4, 2025

Argh, I updated my fork and now my commit history is all wrong!!!! I'll do my best to fix this.

@jdubois
Copy link
Contributor Author

jdubois commented Nov 4, 2025

I had to force push my fork, sorry if anyone had this pulled on their side! I'll check if everything is good, otherwise I have a backup on my laptop.

@tzolov tzolov self-assigned this Nov 18, 2025
@jdubois jdubois marked this pull request as ready for review November 18, 2025 10:59
@jdubois
Copy link
Contributor Author

jdubois commented Nov 18, 2025

Thanks @tzolov for our discussion -> I've just added a few more tests, I've put this "ready for review" and I'll be happy to discuss this with you

@jdubois
Copy link
Contributor Author

jdubois commented Nov 18, 2025

I've fixed some of the Checkstyle issues but there's a ton of them, so this is far from finished. Does it really make sense to follow of all of those rules?

tzolov
tzolov requested changes Nov 20, 2025
View reviewed changes
Copy link
Contributor

@tzolov tzolov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jdubois thanks for the great work! The preliminary review looks very good. Almost ready :)

Here are my observations and suggestions so far:

Naming Convention

  • Please replace the official suffix with sdk throughout (artifacts, packages, and class names)
  • Examples: spring-ai-openai-sdk, .openaisdk., OpenAiSdkChatModel

Test Failures

  • OpenAiOfficialEmbeddingIT#defaultEmbedding - receives "text-embedding-ada-002-v2" instead of expected "text-embedding-ada-002"
  • OpenAiOfficialImageModelObservationIT - passes individually but fails in full test suite with: InvalidObservation: Metrics backends may require that all observations with the same name have the same set of low cardinality keys... (observation mismatch between image and other operations)
  • Haven't tested the Azure OpenAI support yet (don't have an azure account for testing yet)

Additional Items

  • Checkstyle - Issues need resolution
  • Missing Documentation - Please add OpenAI SDK docs similar to https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html
    • I've attached, an initial version (openai-sdk-chat.adoc) - add it to /spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/ and link in nav.adoc
    • Build with: ./mvnw -pl spring-ai-docs antora
  • Missing Auto-configurations - I'd recommend adding these in a separate PR
  • Missing Audio (Speech/Transcription) and Moderation API integration - can be added in follow-up PRs
    openai-sdk-chat.RENAME_EXT_TO_adoc.md

@tzolov
Copy link
Contributor

tzolov commented Nov 22, 2025

@jdubois,
I've pushed the jdubois@2e706f1 to add auto-configuration and boot starter. Also tried to improve the chat-options a bit.

@tzolov
Copy link
Contributor

tzolov commented Nov 23, 2025

Also fixed the audio output support: 9427442

@jdubois
Copy link
Contributor Author

jdubois commented Nov 24, 2025

Thanks a lot @tzolov !

@jdubois
Copy link
Contributor Author

jdubois commented Nov 24, 2025

@tzolov

  • I improved the authentication configuration in the Options* files (adding them to the Builder), and wrote documentation in the README.md file for authentication, as it's the non-obvious thing.
    You should be able to run tests on GitHub Models when the model is available ("dall-e-3" isn't available so it won't work, for example).
  • We got a big renaming last week, from Azure OpenAI to Microsoft Foundry, so I refactored everything to take this into account. This will prevent from having to do it later....

@jdubois
Copy link
Contributor Author

jdubois commented Nov 24, 2025

@tzolov concerning the remaining issues in your review:

  • For Azure OpenAI (now Microsoft Foundry), it should be good. I'm testing on it, but I don't have a normal subscription, so the only risk is in that difference between my subscription and what normal people have. That should be pretty limited, we're using some very big common models here.
  • The failing test in OpenAiOfficialImageModelObservationIT is all I have left, and to be honest I don't understand much about it.

@jdubois
Copy link
Contributor Author

jdubois commented Nov 25, 2025

@jdubois OpenAiOfficialImageModelObservationIT is fixed, everything should be green now!

@tzolov
Copy link
Contributor

tzolov commented Nov 25, 2025

@jdubois I've updated the openai-sdk chat docs: https://github.com/jdubois/spring-ai/blob/openaiofficial/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-sdk-chat.adoc.
Can you please check if they make sense?

Usually the README contains only a reference to the official doc page.

If you want you can generate the docs with ./mvnw -pl spring-ai-docs antora and then navigate to spring-ai-docs/target/antora/site/api/chat/openai-sdk-chat.html

In the meantime I will try to add doc pages for the opneai-sdk embedding and image models.

@tzolov
Copy link
Contributor

tzolov commented Nov 25, 2025

I've pushed the openai-skd-embedding.adoc and openai-sdk-image.adoc as well.

jdubois added 10 commits November 25, 2025 20:08
@jdubois @tzolov
First implementation of the OpenAI Java SDK, supporting only Embeddings
6e2e988 
Fix spring-projects#3368

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
f0278fa 
- Add support for ImageModel
- Refactor the existing code now that we have support for 2 models

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
e9d7382 
- Added support for authentication with OpenAI, Azure OpenAI and GitHub models.
- Added support for complex OpenAI client configuration
- Refactored the existing code to use those new methods

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
2bc511d 
Create the OpenAiOfficialChatOptions class to prepare for the implementation of the Chat Model

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
54fe12b 
Create the OpenAiOfficialChatModel class:
- This is a first implementation that is not of good quality yet
- Tests do not pass yet

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
eeba408 
- Improve authentication, mostly with Azure OpenAI

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
68df074 
- First tests passing for ChatModel

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
4653f05 
- More tests passing for ChatModel

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
e80d37b 
- More tests passing for ChatModel

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
dfa333c 
- More tests passing for ChatModel

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
tzolov and others added 18 commits November 25, 2025 20:08
@tzolov
feat: Add audio output support and improve OpenAI SDK chat configuration
5c2194b 
- Change default temperature from 0.7 to 1.0 in OpenAiSdkChatProperties to align with OpenAI defaults
- Add support for audio output modalities with new AudioParameters type
  - Introduce Voice enum (ALLOY, ASH, BALLAD, CORAL, ECHO, FABLE, ONYX, NOVA, SAGE, SHIMMER)
  - Introduce AudioResponseFormat enum (MP3, FLAC, OPUS, PCM16, WAV, AAC)
  - Replace ChatCompletionAudioParam with custom AudioParameters record
- Add outputModalities field to support text and audio output combinations
- Enhance buildGeneration method to handle audio content in responses
  - Extract audio data from base64 encoded response
  - Create Media objects with proper MIME types
  - Include audio transcript and metadata (audioId, audioExpiresAt)
- Improve chunkToChatCompletion to handle missing choices in streaming responses
- Add integration tests for audio output (blocking and streaming)
- Update documentation for output-audio and stream-options configuration
- Add streamUsage helper method to StreamOptions builder

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
3bdcf90 
- Fix test with the default Embedding model

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
a59c811 
- Added authentication support in the *Options classes
- Added documentation for authentication in the README.md file
- Added Chat Models in the configuration script

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
4c995fd 
- Reactored Azure OpenAI to Microsoft Foundry (new name announced last week)

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
3578bd5 
- Change test case as the default URL for GitHub Models changed

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
5c4c439 
- Update the custom HTTP Headers

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
533e426 
- Fix the custom HTTP Headers

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@tzolov
Fix format
fb8bad1 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov
Fix checkstyle
4a65611 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
1c42563 
- Improve authentication

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
27e5f78 
- Fix OpenAiOfficialImageModelObservationIT

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@tzolov
checkstyle fix
21b0f31 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@jdubois @tzolov
Implementation of the OpenAI Java SDK
d0dc52c 
- Support GitHub Models for specific orgs

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@tzolov
Improve test robustness
fa316b1 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov
Update openai-sdk chat docs
6f84f5a 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov
Add embeding and image docs
f20b80b 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@jdubois @tzolov
Update to use Microsoft Foundry everywhere in the documentation
8c32436 
Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@jdubois @tzolov
Update to use Microsoft Foundry everywhere in the documentation
e88c09f 
Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
@tzolov
Add native structured output support
8bfdb47 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov
improve test resilience
bd52277 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
tzolov
tzolov approved these changes Nov 26, 2025
View reviewed changes
Copy link
Contributor

@tzolov tzolov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@tzolov tzolov added the openai label Nov 26, 2025
@tzolov tzolov added this to the 2.0.0.M1 milestone Nov 26, 2025
tzolov pushed a commit that referenced this pull request Nov 26, 2025
@jdubois @tzolov
feat: add official OpenAI Java SDK integration (#4688)
15df47d 
Introduces support for the official OpenAI Java SDK (openai-java) as an alternative
to the existing Spring AI OpenAI implementation.

New modules:
- models/spring-ai-openai-sdk: Core SDK implementation
- auto-configurations/models/spring-ai-autoconfigure-model-openai-sdk: Auto-configuration
- spring-ai-spring-boot-starters/spring-ai-starter-model-openai-sdk: Starter module

Features:
- OpenAiSdkChatModel/OpenAiSdkChatOptions with streaming, tool calling, and multimodal support
- OpenAiSdkEmbeddingModel/OpenAiSdkEmbeddingOptions with configurable dimensions
- OpenAiSdkImageModel/OpenAiSdkImageOptions with DALL-E integration
- Native support for OpenAI, Microsoft Foundry (Azure), and GitHub Models
- Auto-detection of service provider based on base URL
- Passwordless authentication for Microsoft Foundry (via azure-identity)
- Comprehensive test suite with integration tests
- Complete documentation for Chat, Embedding, and Image models
- Update AiProvider enum to include OPENAI_SDK
- Update SpringAIModels constants
- Update documentation navigation and model comparison table

Fix #3368

Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov
Copy link
Contributor

tzolov commented Nov 26, 2025

Great stuff. Thanks @jdubois

@tzolov
Copy link
Contributor

tzolov commented Nov 26, 2025

Rebased, squashed and merged at 15df47d

@tzolov tzolov closed this Nov 26, 2025
@jdubois
Copy link
Contributor Author

jdubois commented Nov 26, 2025

Awesome, thanks for all your help @tzolov !!!

ericbottard pushed a commit to ericbottard/spring-ai that referenced this pull request Dec 1, 2025
@jdubois @ericbottard
feat: add official OpenAI Java SDK integration (spring-projects#4688)
81287db 
Introduces support for the official OpenAI Java SDK (openai-java) as an alternative
to the existing Spring AI OpenAI implementation.

New modules:
- models/spring-ai-openai-sdk: Core SDK implementation
- auto-configurations/models/spring-ai-autoconfigure-model-openai-sdk: Auto-configuration
- spring-ai-spring-boot-starters/spring-ai-starter-model-openai-sdk: Starter module

Features:
- OpenAiSdkChatModel/OpenAiSdkChatOptions with streaming, tool calling, and multimodal support
- OpenAiSdkEmbeddingModel/OpenAiSdkEmbeddingOptions with configurable dimensions
- OpenAiSdkImageModel/OpenAiSdkImageOptions with DALL-E integration
- Native support for OpenAI, Microsoft Foundry (Azure), and GitHub Models
- Auto-detection of service provider based on base URL
- Passwordless authentication for Microsoft Foundry (via azure-identity)
- Comprehensive test suite with integration tests
- Complete documentation for Chat, Embedding, and Image models
- Update AiProvider enum to include OPENAI_SDK
- Update SpringAIModels constants
- Update documentation navigation and model comparison table

Fix spring-projects#3368

Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>

Signed-off-by: Julien Dubois <julien.dubois@gmail.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tzolov tzolov tzolov approved these changes

Assignees

@tzolov tzolov

Labels

openai

Projects

None yet

Milestone

2.0.0.M1

Development

Successfully merging this pull request may close these issues.

2 participants

@jdubois @tzolov