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 Keys and Endpoint section under Resource Management

-

spring.ai.azure.openai.endpoint

The endpoint from the Azure AI OpenAI Keys and Endpoint section under Resource Management

-

The prefix spring.ai.azure.openai.embeddings is the property prefix that configures the EmbeddingClient implementation for Azure OpenAI

Property Description Default

spring.ai.azure.openai.embedding.enabled

Enable Azure OpenAI embedding client.

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 Embedding Options to the EmbeddingRequest call.

Embedding 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 AzureOpenAiEmbeddingClient 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 = embeddingClient.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 EmbeddingClient implementation that you can inject into your class. Here is an example of a simple @Controller class that uses the EmbeddingClient 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 EmbeddingClient embeddingClient;

    @Autowired
    public EmbeddingController(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingClient.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 AzureOpenAiEmbeddingClient 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 AzureOpenAiEmbeddingClient. For more information about the AzureOpenAiChatClient refer to the Azure OpenAI Embeddings section.

Next, create an AzureOpenAiEmbeddingClient 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 embeddingClient = new AzureOpenAiEmbeddingClient(openAIClient)
    .withDefaultOptions(AzureOpenAiEmbeddingOptions.builder()
        .withModel("text-embedding-ada-002")
        .withUser("user-6")
        .build());

EmbeddingResponse embeddingResponse = embeddingClient
	.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.