Oracle Cloud Infrastructure (OCI) GenAI Embeddings

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

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

前提条件(Prerequisites)

添加存储库和 BOM

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

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

自动配置(Auto-configuration)

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'
}

嵌入属性(Embedding Properties)

Retry 属性(Retry Properties)

前缀 spring.ai.retry 用作属性前缀,允许您为 Mistral AI 模型配置 retry 机制。

属性 描述 默认值
spring.ai.retry.max-attempts 最大重试次数。 10
spring.ai.retry.backoff.initial-interval 指数退避策略的初始睡眠持续时间。 2 sec.
spring.ai.retry.backoff.multiplier 退避间隔乘数。 5
spring.ai.retry.backoff.max-interval 最大退避持续时间。 3 min.
spring.ai.retry.on-client-errors 如果为false,抛出NonTransientAiException,并且不会对4xx客户端错误码进行重试。 false
spring.ai.retry.exclude-on-http-codes 不应触发重试的HTTP状态码列表(例如抛出NonTransientAiException)。 empty
spring.ai.retry.on-http-codes 应触发重试的HTTP状态码列表(例如抛出TransientAiException)。 empty
连接属性(Connection Properties)

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

属性 描述 默认值
spring.ai.oci.genai.authenticationType OCI认证类型,可选fileinstance-principalworkload-identitysimple 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认证 <用户主目录>/.oci/config
spring.ai.oci.genai.profile OCI配置文件名,用于file认证 DEFAULT
spring.ai.oci.genai.endpoint 可选OCI GenAI端点 -
配置属性(Configuration Properties)

前缀 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-demanddedicated on-demand
spring.ai.oci.genai.embedding.truncate 文本超出嵌入上下文时的截断方式,可选STARTEND END
spring.ai.oci.genai.embedding.model 用于嵌入的模型或模型端点 -

运行时选项(Runtime Options )

OCIEmbeddingOptions.java 提供了嵌入请求的配置信息,并提供了一个构建器来创建这些选项。

默认选项也可以通过配置 spring.ai.minimax.embedding.options 属性来进行设置。

在启动时,使用 OCIEmbeddingModel 构造函数来设置所有嵌入请求默认使用的选项。在运行时,您可以通过在 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()
));

示例控制器(Sample Controller)

创建一个新的 Spring Boot 项目,并将 spring-ai-starter-model-oci-genai 添加到 pom (或 gradle) 依赖项中。

src/main/resources 目录下添加 application.properties 文件,以启用和配置 OCI GenAI Embedding 模型:

spring.ai.oci.genai.embedding.model=<your model>
spring.ai.oci.genai.embedding.compartment=<your model compartment>

这将创建一个 OCIEmbeddingModel 的实现,你可以将其注入到你的类中。下面是一个简单的 @Controller 类的示例,它使用聊天模型进行文本生成。

@RestController
public class EmbeddingController {

    private final OCIEmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(OCIEmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/v1/embedding")
    public Map<String, Object> embedding(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("embeddings", embeddingModel.embed(message));
    }

}

手动配置(Manual Configuration)

OCIEmbeddingModel 实现了 EmbeddingModel , 并使用轻量级 OllamaApi 客户端连接到 Ollama 服务。

要启用它,添加 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'
}

接下来,创建一个 OllamaEmbeddingModel 实例,并使用专用的 chroma/all-minilm-l6-v2-f32 嵌入模型来计算两段输入文本的嵌入向量:

var ollamaApi = OllamaApi.builder().build();

var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
        OllamaOptions.builder()
            .model(OllamaModel.MISTRAL.id())
            .build());

EmbeddingResponse embeddingResponse = this.embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaOptions.builder()
            .model("chroma/all-minilm-l6-v2-f32"))
            .truncate(false)
            .build());
作者:Jeebiz  创建时间:2025-08-08 00:48
最后编辑:Jeebiz  更新时间:2025-08-31 23:07