Oracle Cloud Infrastructure (OCI) GenAI Embeddings

OCI GenAI Service 提供按需模型或专用 AI 集群的文本嵌入。

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

OCI Embedding Models Page 和 OCI Text Embeddings Page 提供了在 OCI 上使用和托管嵌入模型的详细信息。

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 工件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅“添加 Spring AI 仓库”部分，将这些仓库添加到您的构建系统。

Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. Refer to the Artifact Repositories section to add these repositories to your build system.

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

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 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为 OCI GenAI 嵌入客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的项目的 Maven pom.xml 文件中：

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-starter-model-oci-genai</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-oci-genai'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Embedding Properties

前缀 spring.ai.oci.genai 是用于配置与 OCI GenAI 连接的属性前缀。

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.

-

嵌入自动配置的启用和禁用现在通过前缀为 spring.ai.azure.openai.embedding 的顶级属性进行配置。

Enabling and disabling of the embedding auto-configurations are now configured via top level properties with the prefix spring.ai.model.embedding.

要启用，请设置 spring.ai.model.embedding=oci-genai（默认已启用）。

To enable, spring.ai.model.embedding=oci-genai (It is enabled by default)

要禁用，请设置 spring.ai.model.embedding=none（或任何与 oci-genai 不匹配的值）。

To disable, spring.ai.model.embedding=none (or any value which doesn’t match oci-genai)

此更改旨在允许配置多个模型。

This change is done to allow configuration of multiple models.

前缀 spring.ai.oci.genai.embedding 是属性前缀，用于为 OCI GenAI 配置 EmbeddingModel 实现。

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 (Removed and no longer valid)

Enable OCI GenAI embedding model.

true

spring.ai.model.embedding

Enable OCI GenAI embedding model.

oci-genai

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.

-

所有以 spring.ai.oci.genai.embedding.options 为前缀的属性都可以通过在 EmbeddingRequest 调用中添加请求特定的 Runtime Options 来在运行时覆盖。

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

OCIEmbeddingOptions 提供嵌入请求的配置信息。 OCIEmbeddingOptions 提供了一个构建器来创建选项。

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

在启动时，使用 OCIEmbeddingOptions 构造函数设置所有嵌入请求的默认选项。在运行时，您可以通过向 EmbeddingRequest 请求传递一个带有您的 OCIEmbeddingOptions 实例来覆盖默认选项。

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()
            .model("my-other-embedding-model")
            .build()
));

Sample Code

这将创建一个 EmbeddingModel 实现，您可以将其注入到您的类中。这是一个使用 EmbeddingModel 实现的简单 @Controller 类的示例。

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

如果您不喜欢使用 Spring Boot 自动配置，您可以手动配置应用程序中的 OCIEmbeddingModel 。为此，将 spring-oci-genai-openai 依赖项添加到您的项目的 Maven pom.xml 文件中：

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>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-oci-genai-openai'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

接下来，创建一个 OCIEmbeddingModel 实例并使用它来计算两个输入文本之间的相似度：

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()
    .model(this.EMBEDDING_MODEL)
    .compartment(this.COMPARTMENT_ID)
    .servingMode("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?"));