This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.0.0-SNAPSHOT! |
Azure OpenAI Embeddings
Azure’s OpenAI extends the OpenAI capabilities, offering safe text generation and Embeddings computation models for various task:
-
Similarity embeddings are good at capturing semantic similarity between two or more pieces of text.
-
Text search embeddings help measure whether long documents are relevant to a short query.
-
Code search embeddings are useful for embedding code snippets and embedding natural language search queries.
The Azure OpenAI embeddings rely on cosine similarity
to compute similarity between documents and a query.
Prerequisites
Obtain your Azure OpenAI endpoint
and api-key
from the Azure OpenAI Service section on the Azure Portal.
Spring AI defines a configuration property named spring.ai.azure.openai.api-key
that you should set to the value of the API Key
obtained from Azure.
There is also a configuration property named spring.ai.azure.openai.endpoint
that you should set to the endpoint URL obtained when provisioning your model in Azure.
Exporting environment variables is one way to set these configuration properties:
export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT KEY HERE>
export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>
Add Repositories and BOM
Spring AI artifacts are published in Spring Milestone and Snapshot repositories. Refer to the Repositories section to add these repositories to your build system.
To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the Dependency Management section to add the Spring AI BOM to your build system.
Auto-configuration
Spring AI provides Spring Boot auto-configuration for the Azure OpenAI Embedding Client.
To enable it add the following dependency to your project’s Maven pom.xml
file:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>
or to your Gradle build.gradle
build file.
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai-spring-boot-starter'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file. |
Embedding Properties
The prefix spring.ai.azure.openai
is the property prefix to configure the connection to Azure OpenAI.
Property | Description | Default |
---|---|---|
spring.ai.azure.openai.api-key |
The Key from Azure AI OpenAI |
- |
spring.ai.azure.openai.endpoint |
The endpoint from the Azure AI OpenAI |
- |
The prefix spring.ai.azure.openai.embedding
is the property prefix that configures the EmbeddingModel
implementation for Azure OpenAI
Property | Description | Default |
---|---|---|
spring.ai.azure.openai.embedding.enabled |
Enable Azure OpenAI embedding model. |
true |
spring.ai.azure.openai.embedding.metadata-mode |
Document content extraction mode |
EMBED |
spring.ai.azure.openai.embedding.options.deployment-name |
This is the value of the 'Deployment Name' as presented in the Azure AI Portal |
text-embedding-ada-002 |
spring.ai.azure.openai.embedding.options.user |
An identifier for the caller or end user of the operation. This may be used for tracking or rate-limiting purposes. |
- |
All properties prefixed with spring.ai.azure.openai.embedding.options can be overridden at runtime by adding a request specific Runtime Options to the EmbeddingRequest call.
|
Runtime Options
The AzureOpenAiEmbeddingOptions
provides the configuration information for the embedding requests.
The AzureOpenAiEmbeddingOptions
offers a builder to create the options.
At start time use the AzureOpenAiEmbeddingModel
constructor to set the default options used for all embedding requests.
At run-time you can override the default options, by passing a AzureOpenAiEmbeddingOptions
instance with your to the EmbeddingRequest
request.
For example to override the default model name for a specific request:
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
AzureOpenAiEmbeddingOptions.builder()
.withModel("Different-Embedding-Model-Deployment-Name")
.build()));
Sample Code
This will create a EmbeddingModel
implementation that you can inject into your class.
Here is an example of a simple @Controller
class that uses the EmbeddingModel
implementation.
spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.embedding.options.model=text-embedding-ada-002
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
Manual Configuration
If you prefer not to use the Spring Boot auto-configuration, you can manually configure the AzureOpenAiEmbeddingModel
in your application.
For this add the spring-ai-azure-openai
dependency to your project’s Maven pom.xml
file:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-openai</artifactId>
</dependency>
or to your Gradle build.gradle
build file.
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file. |
The spring-ai-azure-openai dependency also provide the access to the AzureOpenAiEmbeddingModel . For more information about the AzureOpenAiChatModel refer to the Azure OpenAI Embeddings section.
|
Next, create an AzureOpenAiEmbeddingModel
instance and use it to compute the similarity between two input texts:
var openAIClient = OpenAIClientBuilder()
.credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
.buildClient();
var embeddingModel = new AzureOpenAiEmbeddingModel(openAIClient)
.withDefaultOptions(AzureOpenAiEmbeddingOptions.builder()
.withModel("text-embedding-ada-002")
.withUser("user-6")
.build());
EmbeddingResponse embeddingResponse = embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
the text-embedding-ada-002 is actually the Deployment Name as presented in the Azure AI Portal.
|