Spring AI is a module of Spring that helps us easily work with applications that use AI, integrating with AI providers such as OpenAI, Azure OpenAI, Google Gemini, … In this tutorial, I will introduce to you all the basic knowledge about Spring AI so you can use it in applications that integrate with the AI providers!
First, I will create a new Spring Boot project as an example:
I will make a small application that integrates with OpenAI to query information, so I have declared to use the OpenAI dependency. In addition, we also need to declare Spring Web and Spring Reactive Web dependencies!
Result:
Basic AI concepts
Before going into implementing the example, there are some concepts about AI that you need to understand as follows:
- Models are algorithms to process user request information and generate output appropriate to the request. These algorithms will use a large amount of input data to produce predictions, text, images, and other outputs.
- Prompts can be roughly said as input requests from users, usually text input, for the AI model to rely on to generate output.
- Prompt Templates are templates used to create prompts. We will need to replace the placeholders defined in the template with the values we want to create a prompt from these values.
- Embeddings are objects that will transform user prompts into vector objects in the form of numbers that AI models can use to process requests.
- Tokens are the basic linguistic units that the AI model uses to process prompts. At input, the AI model will convert words to tokens, and at output, the AI model will convert tokens to words.
Understanding the basic concepts above, you will imagine at a high level how an AI application works!
Basic Spring AI
To integrate with AI providers, Spring AI defines an interface ModelClient with ModelRequest and ModelResponse:
|
1 2 3 |
public interface ModelClient<TReq extends ModelRequest<?>, TRes extends ModelResponse<?>> { TRes call(TReq request); } |
There are 3 sub-interfaces from the ModelClient interface:
- ChatClient
- ImageClient
- and EmbeddingClient
Corresponding to each AI provider, there will be its own implementation!
For OpenAI, the implementations for the 3 interfaces ChatClient, ImageClient, EmbeddingClient are OpenAiChatClient, OpenAiImageClient and OpenAiEmbeddingClient respectively:
For my example, I will use the ChatClient class to work with OpenAI!
Implement the example
To integrate with OpenAI, first, you need to create a new API key in the OpenAI platform by going to https://platform.openai.com/api-keys and clicking on the “Create new secret key” button as follows:
This API key is used to authenticate with the OpenAI API! Please save this API key information somewhere so you can use it again later!
To configure OpenAI information with Spring AI, you can use the OpenAiApi class.
There are 4 overloading constructors to initialize the object of this OpenAiApi class with the required information that we need to configure about the API key:
- OpenAiApi(String baseUrl, String openAiToken, RestClient.Builder restClientBuilder, ResponseErrorHandler responseErrorHandler)
- OpenAiApi(String baseUrl, String openAiToken, RestClient.Builder restClientBuilder)
- OpenAiApi(String baseUrl, String openAiToken)
- OpenAiApi(String openAiToken)
The first constructor will allow us to configure OpenAI’s baseUrl to query information, openAiToken is the API key we just created above, restClientBuilder and responseErrorHandler allow us to define configurations related to requests to OpenAI and handle errors when receiving response from OpenAI.
The following constructors will use Spring’s default configurations with the OpenAI API baseUrl defaulting to “https://api.openai.com”.
You can use the default configuration and only define the API key information using the last constructor as follows:
|
1 |
OpenAiApi oaa = new OpenAiApi("sk-proj-uINhZPv5UgFn3WMjeUVgT3BlbkF23uSGLDlnfcjdwsjvSQkO"); |
And initialize the object of the ChatClient class from the object of the OpenAiApi class as follows:
|
1 |
ChatClient chatClient = new OpenAiChatClient(oaa); |
For the Spring Boot project, you only need to define API key information using the property:
|
1 |
spring.ai.openai.api-key=sk-proj-uINhZPv5UgFn3WMjeUVgT3BlbkF23uSGLDlnfcjdwsjvSQkO |
Spring Boot will automatically create the OpenAiApi object, then the ChatClient object in the Spring container, we just need to ingest it and use it:
|
1 2 |
@Autowired private ChatClient chatClient; |
Now we will use the ChatClient class to query information from OpenAI.
My example is as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
package com.huongdanjava.springai; import org.springframework.ai.chat.ChatClient; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.CommandLineRunner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class SpringAiExampleApplication implements CommandLineRunner { @Autowired private ChatClient chatClient; public static void main(String[] args) { SpringApplication.run(SpringAiExampleApplication.class, args); } @Override public void run(String... args) { String output = chatClient.call("Do you know about Huong Dan Java website?"); System.out.println(output); } } |
Please try to check the results! Mine is exceeded the free quota, so when I run it, I get the following error:
|
1 2 3 4 5 6 7 8 |
org.springframework.ai.retry.NonTransientAiException: 429 - { "error": { "message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors.", "type": "insufficient_quota", "param": null, "code": "insufficient_quota" } } |