Oracle Cloud Infrastructure (OCI) GenAI Embeddings

OCI GenAI Service offers text embedding with on-demand models, or dedicated AI clusters.

The OCI Embedding Models Page and OCI Text Embeddings Page provide detailed information about using and hosting embedding models on OCI.

Prerequisites

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 OCI GenAI 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-oci-genai-spring-boot-starter</artifactId>
</dependency>

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-oci-genai-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.oci.genai is the property prefix to configure the connection to OCI GenAI.

Property Description Default

spring.ai.oci.genai.authenticationType

The type of authentication to use when authenticating to OCI. May be file, instance-principal, workload-identity, or simple.

file

spring.ai.oci.genai.region

OCI service region.

us-chicago-1

spring.ai.oci.genai.tenantId

OCI tenant OCID, used when authenticating with simple auth.

-

spring.ai.oci.genai.userId

OCI user OCID, used when authenticating with simple auth.

-

spring.ai.oci.genai.fingerprint

Private key fingerprint, used when authenticating with simple auth.

-

spring.ai.oci.genai.privateKey

Private key content, used when authenticating with simple auth.

-

spring.ai.oci.genai.passPhrase

Optional private key passphrase, used when authenticating with simple auth and a passphrase protected private key.

-

spring.ai.oci.genai.file

Path to OCI config file. Used when authenticating with file auth.

<user’s home directory>/.oci/config

spring.ai.oci.genai.profile

OCI profile name. Used when authenticating with file auth.

DEFAULT

spring.ai.oci.genai.endpoint

Optional OCI GenAI endpoint.

-

The prefix spring.ai.oci.genai.embedding is the property prefix that configures the EmbeddingModel implementation for OCI GenAI

Property Description Default

spring.ai.oci.genai.embedding.enabled

Enable OCI GenAI embedding model.

true

spring.ai.oci.genai.embedding.compartment

Model compartment OCID.

-

spring.ai.oci.genai.embedding.servingMode

The model serving mode to be used. May be on-demand, or dedicated.

on-demand

spring.ai.oci.genai.embedding.truncate

How to truncate text if it overruns the embedding context. May be START, or END.

END

spring.ai.oci.genai.embedding.model

The model or model endpoint used for embeddings.

-
All properties prefixed with spring.ai.oci.genai.embedding.options can be overridden at runtime by adding a request specific Runtime Options to the EmbeddingRequest call.

Runtime Options

The OCIEmbeddingOptions provides the configuration information for the embedding requests. The OCIEmbeddingOptions offers a builder to create the options.

At start time use the OCIEmbeddingOptions constructor to set the default options used for all embedding requests. At run-time you can override the default options, by passing a OCIEmbeddingOptions 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"),
        OCIEmbeddingOptions.builder()
            .withModel("my-other-embedding-model")
            .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.oci.genai.embedding.model=<your model>
spring.ai.oci.genai.embedding.compartment=<your model compartment>
@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 OCIEmbeddingModel in your application. For this add the spring-oci-genai-openai dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-oci-genai-openai</artifactId>
</dependency>

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-oci-genai-openai'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Next, create an OCIEmbeddingModel instance and use it to compute the similarity between two input texts:

final String EMBEDDING_MODEL = "cohere.embed-english-light-v2.0";
final String CONFIG_FILE = Paths.get(System.getProperty("user.home"), ".oci", "config").toString();
final String PROFILE = "DEFAULT";
final String REGION = "us-chicago-1";
final String COMPARTMENT_ID = System.getenv("OCI_COMPARTMENT_ID");

var authProvider = new ConfigFileAuthenticationDetailsProvider(
		this.CONFIG_FILE, this.PROFILE);
var aiClient = GenerativeAiInferenceClient.builder()
    .region(Region.valueOf(this.REGION))
    .build(this.authProvider);
var options = OCIEmbeddingOptions.builder()
    .withModel(this.EMBEDDING_MODEL)
    .withCompartment(this.COMPARTMENT_ID)
    .withServingMode("on-demand")
    .build();
var embeddingModel = new OCIEmbeddingModel(this.aiClient, this.options);
List<Double> embedding = this.embeddingModel.embed(new Document("How many provinces are in Canada?"));