> ## Documentation Index
> Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OCI GenAI 向量模型

[OCI GenAI 服务](https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/) 提供文本嵌入功能，支持按需模型或专用 AI 集群。

[OCI Embedding 模型页面](https://docs.oracle.com/en-us/iaas/Content/generative-ai/embed-models.htm) 和 [OCI 文本嵌入页面](https://docs.oracle.com/en-us/iaas/Content/generative-ai/use-playground-embed.htm) 提供了有关在 OCI 上使用和托管嵌入模型的详细信息。

## 先决条件

### 添加存储库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。

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

## 自动配置

<Note>
  Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
  有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
</Note>

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

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-oci-genai</artifactId>
</dependency>
```

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

```groovy theme={"system"}
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-oci-genai'
}
```

<Tip>
  请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
</Tip>

### Embedding 属性

前缀 `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` 身份验证时使用。                                                        | 用户主目录/.oci/config |
| spring.ai.oci.genai.profile            | OCI 配置文件名称。在使用 `file` 身份验证时使用。                                                        | DEFAULT           |
| spring.ai.oci.genai.endpoint           | 可选的 OCI GenAI 端点。                                                                     | -                 |

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

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

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

  此更改是为了允许配置多个模型。
</Note>

前缀 `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              | 用于嵌入的模型或模型端点。                             | -         |

<Tip>
  所有以 `spring.ai.oci.genai.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
</Tip>

## 运行时选项

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

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

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

```java theme={"system"}
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` 实现。

```properties theme={"system"}
spring.ai.oci.genai.embedding.model=<你的模型>
spring.ai.oci.genai.embedding.compartment=<你的模型隔间>
```

```java theme={"system"}
@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` 文件中：

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-oci-genai-openai</artifactId>
</dependency>
```

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

```groovy theme={"system"}
dependencies {
    implementation 'org.springframework.ai:spring-oci-genai-openai'
}
```

<Tip>
  请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
</Tip>

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

```java theme={"system"}
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?"));
```

<Card title="文档有误？请协助编辑" icon="pencil" href="https://github.com/javaai-pig4cloud-com/javaai-docs/edit/main/spring-ai/api/embeddings/oci-genai-embeddings.mdx">
  发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
</Card>