Oracle Cloud 基础设施（OCI）GenAI 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

OCI GenAI 服务 提供基于按需模型或专用 AI 集群的文本嵌入功能。

OCI 嵌入模型页面 和 OCI 文本嵌入页面 详细介绍了在 OCI 上使用和托管嵌入模型的相关信息。

先决条件

添加仓库和 BOM

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 “构件仓库” 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本。请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 自动配置及 starter 模块的构件命名已发生重大变更，详情请参阅 升级说明 文档。

Spring AI 为 OCI GenAI 嵌入客户端提供 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 添加到你的构建文件。

嵌入配置

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

属性 说明 默认值

spring.ai.oci.genai.authenticationType

连接 OCI 时使用的认证类型。可选值为：file、instance-principal、workload-identity 或 simple。

file

spring.ai.oci.genai.region

OCI 服务区域。

us-chicago-1

spring.ai.oci.genai.tenantId

OCI 租户 OCID（在使用 simple 认证时需配置）。

-

spring.ai.oci.genai.userId

OCI 用户 OCID（在使用 simple 认证时需配置）。

-

spring.ai.oci.genai.fingerprint

私钥指纹（在使用 simple 认证时需配置）。

-

spring.ai.oci.genai.privateKey

私钥内容（在使用 simple 认证时需配置）。

-

spring.ai.oci.genai.passPhrase

可选私钥密码（在使用 simple 认证且私钥受密码保护时需配置）。

-

spring.ai.oci.genai.file

OCI 配置文件路径（在使用 file 认证时需配置）。

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

spring.ai.oci.genai.profile

OCI 配置文件名（在使用 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 （已移除且不再有效）

Enable OCI GenAI embedding model.

true

spring.ai.model.embedding

启用 OCI GenAI 嵌入模型。

oci-genai

spring.ai.oci.genai.embedding.compartment

模型所属区间（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 为嵌入请求提供配置信息，其内置的构建器 （builder）可用于创建配置选项。

初始化时通过 OCIEmbeddingOptions 构造函数设置所有嵌入请求的默认选项。运行时可通过向 EmbeddingRequest 传递 OCIEmbeddingOptions 实例来覆盖默认配置。

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

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=<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);
    }
}

手动配置

若不使用 Spring Boot 自动配置，你可以在应用中手动配置 OCIEmbeddingModel。为此，需在项目的 Maven pom.xml 文件中添加 spring-oci-genai-openai 依赖：

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