OCI GenAI 服务 提供文本嵌入功能，支持按需模型或专用 AI 集群。

OCI Embedding 模型页面 和 OCI 文本嵌入页面 提供了有关在 OCI 上使用和托管嵌入模型的详细信息。

​
先决条件

​
添加存储库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。 请参阅工件存储库部分，将这些存储库添加到您的构建系统中。

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

​
自动配置

Spring AI 自动配置和启动器模块的工件名称已发生重大更改。 有关更多信息，请参阅升级说明。

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

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

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

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

​
Embedding 属性

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

属性描述默认值
spring.ai.oci.genai.authenticationType用于向 OCI 进行身份验证的身份验证类型。可以是 file、instance-principal、workload-identity 或 simple。file
spring.ai.oci.genai.regionOCI 服务区域。us-chicago-1
spring.ai.oci.genai.tenantIdOCI 租户 OCID，在使用 simple 身份验证时使用。-
spring.ai.oci.genai.userIdOCI 用户 OCID，在使用 simple 身份验证时使用。-
spring.ai.oci.genai.fingerprint私钥指纹，在使用 simple 身份验证时使用。-
spring.ai.oci.genai.privateKey私钥内容，在使用 simple 身份验证时使用。-
spring.ai.oci.genai.passPhrase可选的私钥密码短语，在使用 simple 身份验证和受密码短语保护的私钥时使用。-
spring.ai.oci.genai.fileOCI 配置文件路径。在使用 file 身份验证时使用。用户主目录/.oci/config
spring.ai.oci.genai.profileOCI 配置文件名称。在使用 file 身份验证时使用。DEFAULT
spring.ai.oci.genai.endpoint可选的 OCI GenAI 端点。-

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

要启用，请设置 spring.ai.model.embedding=oci-genai (默认情况下启用)

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

此更改是为了允许配置多个模型。

前缀 spring.ai.oci.genai.embedding 是配置 OCI GenAI 的 EmbeddingModel 实现的属性前缀。

属性描述默认值
spring.ai.oci.genai.embedding.enabled (已删除且不再有效)启用 OCI GenAI 嵌入模型。true
spring.ai.model.embedding启用 OCI GenAI 嵌入模型。oci-genai
spring.ai.oci.genai.embedding.compartment模型隔间 OCID。-
spring.ai.oci.genai.embedding.servingMode要使用的模型服务模式。可以是 on-demand 或 dedicated。on-demand
spring.ai.oci.genai.embedding.truncate如果文本超出嵌入上下文，如何截断文本。可以是 START 或 END。END
spring.ai.oci.genai.embedding.model用于嵌入的模型或模型端点。-

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

​
运行时选项

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

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

例如，要覆盖特定请求的默认模型名称：

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()
));

​
示例代码

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

spring.ai.oci.genai.embedding.model=<你的模型>
spring.ai.oci.genai.embedding.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);
    }
}

​
手动配置

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

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

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

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

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

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?"));

文档有误？请协助编辑

发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！