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! |
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 |
spring.ai.oci.genai.region |
OCI service region. |
us-chicago-1 |
spring.ai.oci.genai.tenantId |
OCI tenant OCID, used when authenticating with |
- |
spring.ai.oci.genai.userId |
OCI user OCID, used when authenticating with |
- |
spring.ai.oci.genai.fingerprint |
Private key fingerprint, used when authenticating with |
- |
spring.ai.oci.genai.privateKey |
Private key content, used when authenticating with |
- |
spring.ai.oci.genai.passPhrase |
Optional private key passphrase, used when authenticating with |
- |
spring.ai.oci.genai.file |
Path to OCI config file. Used when authenticating with |
<user’s home directory>/.oci/config |
spring.ai.oci.genai.profile |
OCI profile name. Used when authenticating with |
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 |
spring.ai.oci.genai.embedding.truncate |
How to truncate text if it overruns the embedding context. May be |
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(
CONFIG_FILE, PROFILE);
var aiClient = GenerativeAiInferenceClient.builder()
.region(Region.valueOf(REGION))
.build(authProvider);
var options = OCIEmbeddingOptions.builder()
.withModel(EMBEDDING_MODEL)
.withCompartment(COMPARTMENT_ID)
.withServingMode("on-demand")
.build();
var embeddingModel = new OCIEmbeddingModel(aiClient, options);
List<Double> embedding = embeddingModel.embed(new Document("How many provinces are in Canada?"));