Relax Box

外观

嵌入模型

约 12605 字大约 42 分钟

2026-09-15

合集说明

本篇合并自参考文档「Models / Embedding Models」章节，覆盖嵌入模型 API 与各厂商实现，按官方文档顺序排列：（各篇之间以 --- 分隔）

  1. Embedding Model API（嵌入模型 API）
  2. OpenAI Embeddings（OpenAI 嵌入模型）
  3. Ollama Embeddings（Ollama 嵌入模型）
  4. Azure OpenAI Embeddings（迁移提示）
  5. Bedrock Cohere Embedding（AWS Bedrock + Cohere 嵌入）
  6. Bedrock Titan Embedding（AWS Bedrock + Amazon Titan 嵌入）
  7. (ONNX) Transformers Embedding（ONNX 本地嵌入模型）
  8. Google GenAI Text Embeddings
  9. Mistral AI Embeddings
  10. PostgresML Embeddings
  11. VertexAI Text Embeddings（Google Vertex AI 文本嵌入）
  12. OCI GenAI Embeddings（迁移提示）
  13. VertexAI Multimodal Embeddings（Vertex AI 多模态嵌入）

Embedding Model API（嵌入模型 API）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

Embedding（嵌入）就是把文字、图片、视频变成一串数字（向量）。数字越接近，意思就越相似。Java AI 把所有嵌入模型（OpenAI、Ollama、Cohere、Titan 等）抽象成一个统一的 EmbeddingModel 接口，让你可以轻松切换底层厂商。

1. 简介

嵌入是文本、图像或视频的数值表示，用于表达输入之间的关系。嵌入的工作原理是把原始内容转换为浮点数数组（向量），向量的长度称为"维度"。通过计算两个向量的距离，可以判断它们对应的内容是否相关。

白话解读

想象你有一千篇文章，每篇都被转换成一个 1536 维的向量，扔到一个高维空间里。意思相近的文章在空间里靠得近，意思相反的文章离得远。这样你就可以用"距离"做语义搜索。

EmbeddingModel 接口有两个核心目标：

  • 可移植性：换模型只改少量代码。
  • 简单性：通过 embed(String) 和 embed(Document) 等直观方法调用，屏蔽底层复杂性。

2. API 概述

EmbeddingModel 接口继承自 Model<EmbeddingRequest, EmbeddingResponse>，与 Java AI Model API 一脉相承。

  • EmbeddingRequest：嵌入请求，封装要转换的文本列表 + 可选 options。
  • EmbeddingResponse：嵌入响应，包含结果向量与元数据。
  • Embedding：单个嵌入向量。

Java AI 把这些抽象类作为基础，让不同的底层实现（OpenAI、Titan、Ollama 等）共用同一套 API。

3. EmbeddingModel 接口

public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {

    @Override
    EmbeddingResponse call(EmbeddingRequest request);

    // 把 Document 转成向量
    float[] embed(Document document);

    // 从 Document 抽取要嵌入的文本
    default String getEmbeddingContent(Document document) {
        return document.getText();
    }

    // 把单个字符串转成向量
    default float[] embed(String text) {
        Assert.notNull(text, "Text must not be null");
        return this.embed(List.of(text)).iterator().next();
    }

    // 批量：字符串列表 → 向量列表
    default List<float[]> embed(List<String> texts) {
        Assert.notNull(texts, "Texts must not be null");
        return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY))
                .getResults()
                .stream()
                .map(Embedding::getOutput)
                .toList();
    }

    // 批量并返回完整响应
    default EmbeddingResponse embedForResponse(List<String> texts) {
        Assert.notNull(texts, "Texts must not be null");
        return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
    }

    // 探测嵌入维度
    default int dimensions() {
        return embed("Test String").size();
    }
}

3.1 主要方法说明

方法作用
embed(Document)把 Java AI 的 Document 转成向量
embed(String)把单个字符串转成向量（单元素批量的快捷方式）
embed(List<String>)批量嵌入，返回 List<float[]>
embedForResponse(List<String>)批量嵌入，返回完整 EmbeddingResponse（含元数据）
dimensions()探测嵌入向量维度（用 "Test String" 试一次）
getEmbeddingContent(Document)控制嵌入前如何从 Document 提取文本

3.2 getEmbeddingContent 与 MetadataMode

小技巧

支持 MetadataMode 的实现（OpenAI、Mistral AI）会重写 getEmbeddingContent 返回 Document.getFormattedContent(MetadataMode)，从而把文档元数据一起发给嵌入 API。这能让向量更"懂"上下文。

向量存储（Vector Store）依赖这个方法做批量嵌入路径。

4. EmbeddingRequest

public class EmbeddingRequest implements ModelRequest<List<String>> {
    private final List<String> inputs;          // 待嵌入的文本列表
    private final EmbeddingOptions options;     // 可选的运行时选项
}

5. EmbeddingResponse

public class EmbeddingResponse implements ModelResponse<Embedding> {

    private List<Embedding> embeddings;                // 嵌入结果列表
    private EmbeddingResponseMetadata metadata;        // 响应元数据（model、token usage 等）
}

6. Embedding

public class Embedding implements ModelResult<float[]> {
    private float[] embedding;                         // 向量数据
    private Integer index;                             // 在原输入列表中的位置
    private EmbeddingResultMetadata metadata;          // 单条结果元数据
}

7. 可用的实现

Java AI 已经内置以下 EmbeddingModel 实现：

实现提供方
Java AI OpenAI EmbeddingsOpenAI
Java AI Ollama EmbeddingsOllama
Java AI Transformers (ONNX) Embeddings本地 ONNX 模型
Java AI PostgresML EmbeddingsPostgresML
Java AI Bedrock Cohere EmbeddingsAWS Bedrock + Cohere
Java AI Bedrock Titan EmbeddingsAWS Bedrock + Amazon Titan
Java AI VertexAI EmbeddingsGoogle Vertex AI
Java AI Mistral AI EmbeddingsMistral AI

8. 子页面索引

后续章节会逐一介绍每个提供方的具体配置：

  1. Amazon Bedrock（Cohere、Titan）
  2. Azure OpenAI Embedding
  3. Google GenAI Text Embedding
  4. Mistral AI Embedding
  5. OCI GenAI Embedding
  6. Ollama Embedding
  7. (ONNX) Transformers Embedding
  8. OpenAI Embedding
  9. PostgresML Embedding
  10. VertexAI Text Embedding
  11. VertexAI Multimodal Embedding

9. 小结

EmbeddingModel API 是 Java AI 整个 RAG / 语义搜索 / 向量检索体系的基石。只要理解这一个接口，就能在不同厂商之间无缝切换。后续章节会逐个介绍各厂商的具体配置、模型列表与代码示例。

OpenAI Embeddings（OpenAI 嵌入模型）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/openai-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

OpenAI 的嵌入模型把文本转成向量，用来衡量文本之间的"语义距离"。从 Java AI 2.0.0-M5 起，底层切到官方 openai-java SDK。

1. 简介

OpenAI 提供文本嵌入模型（text-embedding-3-large、text-embedding-3-small、text-embedding-ada-002）。嵌入的输出是一个浮点数列表（向量），两个向量的距离越小，对应文本的相关性越高。

Java AI 2.0.0-M5 起使用官方 openai-java SDK，对老用户无缝切换。

2. 准备工作

  1. 在 https://platform.openai.com 注册账号。
  2. 到 https://platform.openai.com/api-keys 生成 API Key。
  3. 配置 spring.ai.openai.api-key。

2.1 安全做法（环境变量）

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
export OPENAI_API_KEY=<your-openai-api-key>

3. 自动配置

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

Gradle：

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

4. 嵌入属性

4.1 重试属性（继承自 OpenAI 通用）

属性描述默认值
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-errors4xx 错误是否重试false
spring.ai.retry.exclude-on-http-codes不重试的 HTTP 状态码empty
spring.ai.retry.on-http-codes触发重试的 HTTP 状态码empty

4.2 连接属性

属性描述默认值
spring.ai.openai.base-urlAPI 入口https://api.openai.com
spring.ai.openai.api-keyAPI Key-
spring.ai.openai.organization-id组织 ID-
spring.ai.openai.project-id项目 ID-
spring.ai.openai.timeout请求超时60 sec
spring.ai.openai.max-retries客户端内置重试3
spring.ai.openai.proxy代理-
spring.ai.openai.custom-headers自定义 HTTP 头empty
spring.ai.openai.connection-pool-metrics-enabledOkHttp 连接池指标false

4.3 嵌入模型配置

属性描述默认值
spring.ai.model.embedding启用嵌入模型openai
spring.ai.openai.embedding.base-url嵌入专用 URL（覆盖通用）-
spring.ai.openai.embedding.api-key嵌入专用 Key（覆盖通用）-
spring.ai.openai.embedding.organization-id组织 ID（覆盖通用）-
spring.ai.openai.embedding.project-id项目 ID（覆盖通用）-
spring.ai.openai.embedding.metadata-modeDocument 内容提取模式EMBED
spring.ai.openai.embedding.model模型名text-embedding-ada-002
spring.ai.openai.embedding.encoding-format返回格式：float 或 base64-
spring.ai.openai.embedding.user最终用户唯一标识-
spring.ai.openai.embedding.dimensions输出维度（text-embedding-3+ 才支持）-
spring.ai.openai.embedding.extra-bodyOpenAI 兼容服务器额外参数-

小技巧

你可以为 chat 和 embedding 设置不同的 base-url / api-key：

spring:
  ai:
    openai:
      base-url: https://api.openai.com     # 通用 base-url
      chat:
        base-url: https://chat.openai.com  # chat 专用
      embedding:
        base-url: https://embed.openai.com # embedding 专用

专门组织/项目用户用 organization-id / project-id 区分用量计费。

5. 运行时选项

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OpenAiEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name")
            .build()));

6. 示例控制器

spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.embedding.model=text-embedding-ada-002
@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);
    }
}

7. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
</dependency>
var embeddingModel = new OpenAiEmbeddingModel(
        MetadataMode.EMBED,
        OpenAiEmbeddingOptions.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .model("text-embedding-ada-002")
                .user("user-6")
                .build());

EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

8. 自定义 HTTP 客户端

跟 OpenAI Chat 一样，OpenAI Embeddings 也支持 OpenAiHttpClientBuilderCustomizer 拦截 OkHttp 客户端构建：

@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
    void customize(SpringAiOpenAiHttpClient.Builder builder);
}

典型用例：注册 OkHttp Interceptor、配置代理、SSL、连接池大小等。

var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder().model("gpt-4o").build())
    .httpClientBuilderCustomizer(myCustomizer)
    .build();

9. 受支持的模型

模型维度特点
text-embedding-3-large3072（可降维）最新、最强大
text-embedding-3-small1536（可降维）性价比首选
text-embedding-ada-0021536旧版，仍可用

白技巧

text-embedding-3-* 支持 dimensions 参数，可以指定比默认更小的维度（比如 256、512），节省存储空间和搜索时间，同时损失少量精度。

10. 小结

OpenAI Embeddings 是 Java AI 中最常用的嵌入实现，原因有三：

  • 质量好：OpenAI 的嵌入模型在 MTEB 排行榜长期领先
  • 生态成熟：所有向量数据库都兼容
  • 配置简单：跟 Chat 共用 OpenAI starter，零额外依赖

如果你有数据合规或成本要求，可以换成 Ollama（本地）或 ONNX Transformers（离线）。

Ollama Embeddings（Ollama 嵌入模型）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/ollama-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

Ollama 不仅能跑对话模型，也能跑嵌入模型（比如 mxbai-embed-large、nomic-embed-text）。Java AI 提供专用 starter，能自动拉取模型、配置 GPU/CPU 参数，处理长文本截断。

1. 简介

OllamaEmbeddingModel 利用 Ollama 的 Embeddings API 端点，把文本转成向量。Ollama 既支持官方嵌入模型库，也支持所有 GGUF 格式的 HuggingFace 模型。

2. 准备工作

2.1 安装 Ollama

到 https://ollama.com/download 下载安装，或用 Testcontainers 启动。

2.2 拉取嵌入模型

# 官方模型
ollama pull mxbai-embed-large
ollama pull nomic-embed-text

# HuggingFace GGUF 模型
ollama pull hf.co/<username>/<model-repository>

也可以开启"自动拉取"，详见后文。

3. 自动配置

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

4. 基础属性

属性描述默认值
spring.ai.ollama.base-urlOllama API 地址http://localhost:11434
spring.ai.ollama.init.pull-model-strategy启动时拉取模型策略never
spring.ai.ollama.init.timeout拉取超时5m
spring.ai.ollama.init.max-retries拉取重试0
spring.ai.ollama.init.embedding.include是否初始化嵌入模型true
spring.ai.ollama.init.embedding.additional-models额外初始化的模型[]

5. 嵌入属性

5.1 启用开关

spring:
  ai:
    model:
      embedding: ollama     # 默认启用
      # embedding: none    # 禁用

5.2 高级请求参数

属性描述默认值
spring.ai.ollama.embedding.model模型名mxbai-embed-large
spring.ai.ollama.embedding.keep_alive模型在内存中保持加载时长5m
spring.ai.ollama.embedding.truncate超长输入是否截断（false 时返回错误）true

5.3 模型参数（基于 Ollama 原始参数）

属性描述默认值
spring.ai.ollama.embedding.numa是否用 NUMAfalse
spring.ai.ollama.embedding.num-ctx上下文窗口大小2048
spring.ai.ollama.embedding.num-batch提示处理最大批大小512
spring.ai.ollama.embedding.num-gpuGPU 层数（macOS 默认为 1）-1
spring.ai.ollama.embedding.main-gpu多 GPU 时主 GPU0
spring.ai.ollama.embedding.low-vram低显存模式false
spring.ai.ollama.embedding.f16-kv半精度 KVtrue
spring.ai.ollama.embedding.use-mmap内存映射null
spring.ai.ollama.embedding.use-mlock锁定内存false
spring.ai.ollama.embedding.num-thread计算线程数（0 = 运行时决定）0
spring.ai.ollama.embedding.temperature温度0.8
spring.ai.ollama.embedding.top-ktop-k 采样40
spring.ai.ollama.embedding.top-ptop-p 采样0.9
spring.ai.ollama.embedding.seed随机种子-1
spring.ai.ollama.embedding.functions启用的函数列表-

6. 运行时选项

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name")
            .truncate(false)         // 超长不截断，让模型报错
            .build()));

7. 自动拉取模型

三种策略：

  • always：总是拉取（用最新版本）
  • when_missing：只在缺失时拉取
  • never：从不自动拉取
spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1
        embedding:
          additional-models:        # 额外模型也一起初始化
            - mxbai-embed-large
            - nomic-embed-text

如果只想对其他类型（非嵌入）应用拉取策略：

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          include: false            # 嵌入模型不参与自动拉取

注意

模型下载会拖慢应用启动，生产环境请预下载。

8. HuggingFace 模型

Ollama 开箱支持所有 GGUF 格式的 HuggingFace 嵌入模型：

spring.ai.ollama.embedding.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always

或提前手动拉取：

ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1

9. 示例控制器

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

10. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>
var ollamaApi = OllamaApi.builder().build();

var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
        OllamaEmbeddingOptions.builder()
            .model(OllamaModel.MISTRAL.id())    // 这里只是占位，会被请求时覆盖
            .build());

EmbeddingResponse embeddingResponse = this.embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("chroma/all-minilm-l6-v2-f32")
            .truncate(false)
            .build()));

11. 常用嵌入模型

模型维度特点
mxbai-embed-large1024Ollama 默认，质量好
nomic-embed-text768长上下文（8192）
all-minilm384轻量级
snowflake-arctic-embed1024多尺寸可选

12. 注意事项

注意

  • truncate 默认 true：超出上下文长度的输入会被截断。如果想强制模型按完整语义处理，设为 false 让模型报错。
  • 首次拉取模型较慢：用自动拉取时，应用启动会等模型下载完成。
  • 嵌入模型不支持对话：模型名别选错，选对话模型（mistral）做嵌入会很慢或失败。

13. 小结

Ollama Embeddings 是 Java AI 中本地 + 免费的嵌入方案。亮点：

  • 本地运行：数据不出本机
  • 支持 GGUF：兼容几乎所有 HuggingFace 嵌入模型
  • 自动拉取：开发体验好
  • 丰富的 GPU/CPU 调优参数：能跑在各种硬件上

如果你需要私有化部署、降低 API 成本，又不想牺牲太多质量，Ollama Embeddings 是首选。

Azure OpenAI Embeddings（迁移提示）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/azure-openai-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

这一页在 Java AI 2.0.1 中只是个简短迁移通知——Azure OpenAI 嵌入模块已经被合并到 OpenAI Embeddings 里，统一通过 OpenAI 客户端 + Azure endpoint 访问。

1. 官方说明

原文翻译如下：

从 Java AI 2.0.0-M5 开始，访问部署在 Azure / Microsoft Foundry 上的 OpenAI 模型应使用 OpenAI Embeddings 模块。

英文原文：

As of Java AI 2.0.0-M5, OpenAI Embeddings should be used to access OpenAI models deployed on Azure / Microsoft Foundry.

2. 含义解读

这意味着：

  • 不再维护单独的 Azure OpenAI 嵌入 starter
  • 改用通用的 OpenAI Embeddings 模块，把 base-url 指向 Azure endpoint
  • 同时适用于 Azure OpenAI Service 与 Microsoft Foundry（微软的 AI Foundry 服务）

3. 替代方案

3.1 通过 OpenAI Embeddings 访问 Azure

spring:
  ai:
    openai:
      # Azure OpenAI 服务的 endpoint（格式因 region 不同）
      base-url: https://{your-resource}.openai.azure.com/openai/deployments/{your-deployment}
      api-key: ${AZURE_OPENAI_API_KEY}
      embedding:
        # 你的部署名（deployment name）
        model: text-embedding-ada-002
        # 用 OpenAI 兼容格式
        embedding:
          metadata-mode: EMBED

也可以只覆盖 embedding 专用 base-url：

spring:
  ai:
    openai:
      base-url: https://api.openai.com
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-4o
      embedding:
        base-url: https://{your-resource}.openai.azure.com/openai/deployments/{your-deployment}
        api-key: ${AZURE_OPENAI_API_KEY}
        model: text-embedding-ada-002

3.2 通过 Microsoft Foundry 访问

Microsoft Foundry 部署的 OpenAI 模型也走 OpenAI 兼容端点：

spring:
  ai:
    openai:
      base-url: https://{your-foundry-endpoint}/v1
      api-key: ${FOUNDRY_API_KEY}
      embedding:
        model: text-embedding-3-large
        dimensions: 1024    # 可降维

3.3 历史方案（已不推荐）

如果你用的是旧版（Java AI 2.0.0-M5 之前），曾经有过：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>

这个 starter 已经被弃用，请迁移到 OpenAI starter。

4. Azure 部署模型列表（参考）

Azure 上可以部署的常见 OpenAI 嵌入模型：

部署名（举例）实际模型维度
text-embedding-3-smalltext-embedding-3-small1536
text-embedding-3-largetext-embedding-3-large3072
text-embedding-ada-002text-embedding-ada-0021536

白话解读

Azure 上的"部署名"（deployment name）跟实际的 OpenAI 模型名可以不一样。Java AI 用的是 spring.ai.openai.embedding.model 这个字段，它应该是部署名而不是模型 ID。

5. 注意事项

注意

  • Azure endpoint 路径里必须包含 deployments/<your-deployment>，否则 Azure 会拒绝。
  • Azure OpenAI 的 API 路径与 OpenAI 官方略有不同（多 /openai/deployments/<deployment>），注意不要照抄 OpenAI 的 URL。
  • 部分 Azure 区域支持 v1 兼容 API，可直接用 https://<resource>.openai.azure.com/openai/v1 + 部署名作为 model。
  • dimensions 参数只在 text-embedding-3-* 系列支持。

6. 小结

Azure OpenAI Embeddings 在 Java AI 2.0.1 中已经没有独立页面——改用 OpenAI Embeddings 模块加 Azure 端点即可。这种统一入口的设计让 Java AI 在跨厂商（OpenAI 官方、Azure、Microsoft Foundry）时非常省事。

如果你需要更详细的 Azure 特定配置（如 AAD 身份验证、Managed Identity），可参考 OpenAI Embeddings 页面的"连接属性"和"运行时选项"部分，结合 Azure 官方文档。

Bedrock Cohere Embedding（AWS Bedrock + Cohere 嵌入）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/bedrock-cohere-embedding.html 📌 原文版本：Java AI 2.0.1

白话解读

AWS Bedrock 把 Cohere 的嵌入模型（embed-multilingual-v3、embed-english-v3）打包成托管服务。Java AI 通过 AWS SDK 访问它，特别适合已经"住在 AWS"的应用。

1. 简介

BedrockCohereEmbeddingModel 是 Java AI 对 AWS Bedrock 上 Cohere 嵌入模型的封装。它使用 AWS SDK 与 Bedrock 通信，自动处理凭证、区域、签名等。

支持的模型：

  • cohere.embed-multilingual-v3（多语言版，默认）
  • cohere.embed-english-v3（英文版）

完整模型 ID 在 https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html。

2. 准备工作

先按 Java AI 的 Amazon Bedrock 文档 配置 AWS API 访问（凭证、region 等）。

3. 自动配置

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

4. 启用 Cohere Embedding

Cohere embedding 默认禁用。需要显式开启：

spring.ai.model.embedding=bedrock-cohere

或者用环境变量 + SpEL：

spring:
  ai:
    model:
      embedding: ${AI_MODEL_EMBEDDING}
export AI_MODEL_EMBEDDING=bedrock-cohere

或 JVM 参数：

java -Dspring.ai.model.embedding=bedrock-cohere -jar your-application.jar

5. 嵌入属性

5.1 AWS 连接属性

属性描述默认值
spring.ai.bedrock.aws.regionAWS 区域us-east-1
spring.ai.bedrock.aws.access-keyAWS Access Key-
spring.ai.bedrock.aws.secret-keyAWS Secret Key-
spring.ai.bedrock.aws.profile.nameprofile 名-
spring.ai.bedrock.aws.profile.credentials-path凭证文件路径-
spring.ai.bedrock.aws.profile.configuration-pathconfig 文件路径-

5.2 Cohere 模型属性

属性描述默认值
spring.ai.model.embedding启用 Coherebedrock-cohere
spring.ai.bedrock.cohere.embedding.model模型 IDcohere.embed-multilingual-v3
spring.ai.bedrock.cohere.embedding.input-type输入类型（见下）SEARCH_DOCUMENT
spring.ai.bedrock.cohere.embedding.truncate截断策略NONE

5.3 input-type 可选值

Cohere 用特殊 token 区分输入类型，不能混用（除了 search + retrieval 场景）：

值用途
SEARCH_DOCUMENT嵌入文档（用于构建索引）
SEARCH_QUERY嵌入查询（用于搜索）
CLASSIFICATION分类任务
CLUSTERING聚类任务

白话解读

关键技巧：做 RAG 时，文档用 SEARCH_DOCUMENT 嵌入，查询用 SEARCH_QUERY 嵌入，两者向量可比。如果混用类型，搜索质量会明显下降。

5.4 truncate 可选值

值行为
NONE不截断，超长报错（不适用于 Bedrock，见下）
LEFT截断左侧
RIGHT截断右侧

注意

通过 Amazon Bedrock 访问时，Cohere 的 truncate 功能不可用。Java AI 的 BedrockCohereEmbeddingModel 会自动截断到 2048 字符（模型支持的最大长度）。

6. 运行时选项

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        BedrockCohereEmbeddingOptions.builder()
            .inputType(InputType.SEARCH_DOCUMENT)   // 运行时切换类型
            .build()));

7. 示例控制器

spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}

spring.ai.model.embedding=bedrock-cohere
spring.ai.bedrock.cohere.embedding.input-type=search-document
@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);
    }
}

8. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bedrock</artifactId>
</dependency>
var cohereEmbeddingApi = new CohereEmbeddingBedrockApi(
        CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(),
        EnvironmentVariableCredentialsProvider.create(),
        Region.US_EAST_1.id(),
        new JsonMapper());

var embeddingModel = new BedrockCohereEmbeddingModel(this.cohereEmbeddingApi);

EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

9. 底层 CohereEmbeddingBedrockApi

CohereEmbeddingBedrockApi 是底层 Java 客户端，可直接调用：

CohereEmbeddingBedrockApi api = new CohereEmbeddingBedrockApi(
        CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(),
        EnvironmentVariableCredentialsProvider.create(),
        Region.US_EAST_1.id(),
        new JsonMapper());

CohereEmbeddingRequest request = new CohereEmbeddingRequest(
        List.of("I like to eat apples", "I like to eat oranges"),
        CohereEmbeddingRequest.InputType.search_document,    // 输入类型
        CohereEmbeddingRequest.Truncate.NONE);              // 截断策略

CohereEmbeddingResponse response = this.api.embedding(this.request);

10. 小结

Bedrock Cohere Embedding 的特点：

  • AWS 原生集成：如果你已经在 AWS 生态里，不用单独管理 API Key
  • 多语言支持强：embed-multilingual-v3 在多语言搜索上表现优秀
  • input-type 区分：SEARCH_DOCUMENT / SEARCH_QUERY 让 RAG 检索更精准

注意事项：通过 Bedrock 时 Cohere 的 truncate 配置不会生效（Bedrock 限制），Java AI 默认截断到 2048 字符。

Bedrock Titan Embedding（AWS Bedrock + Amazon Titan 嵌入）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/bedrock-titan-embedding.html 📌 原文版本：Java AI 2.0.1

白话解读

Amazon Titan 是 AWS 自家的基础模型系列，提供文本和图像嵌入。Java AI 通过 Bedrock 访问它。注意：Titan Embedding 不支持批量嵌入，一次只能处理一条文本或一张图片。

1. 简介

BedrockTitanEmbeddingModel 是 Java AI 对 AWS Bedrock 上 Amazon Titan 嵌入模型的封装。Amazon Titan 是 AWS 自研的基础模型：

  • 支持文本嵌入（embed-text）
  • 支持图像嵌入（embed-image）
  • 通过完全托管的 API 提供服务

注意

Titan Embedding 不支持批量嵌入（batch embedding），一次只能处理一条输入。如果传入 List，会逐条串行调用。

2. 准备工作

先按 Java AI 的 Amazon Bedrock 文档 配置 AWS API 访问。

3. 自动配置

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

4. 启用 Titan Embedding

Titan embedding 默认禁用。开启方式：

spring.ai.model.embedding=bedrock-titan

或用环境变量：

export AI_MODEL_EMBEDDING=bedrock-titan

或 JVM 参数：

java -Dspring.ai.model.embedding=bedrock-titan -jar your-application.jar

5. 嵌入属性

5.1 AWS 连接属性（同 Cohere）

属性描述默认值
spring.ai.bedrock.aws.regionAWS 区域us-east-1
spring.ai.bedrock.aws.access-keyAWS Access Key-
spring.ai.bedrock.aws.secret-keyAWS Secret Key-
spring.ai.bedrock.aws.profile.nameprofile 名-
spring.ai.bedrock.aws.profile.credentials-path凭证文件路径-
spring.ai.bedrock.aws.profile.configuration-pathconfig 文件路径-

5.2 Titan 模型属性

属性描述默认值
spring.ai.model.embedding启用 Titanbedrock-titan
spring.ai.bedrock.titan.embedding.model模型 IDamazon.titan-embed-image-v1

支持的模型 ID：

模型 ID类型说明
amazon.titan-embed-image-v1图像多模态嵌入
amazon.titan-embed-text-v1文本1536 维
amazon.titan-embed-text-v2:0文本支持 dimensions 和 normalize 参数

小技巧

amazon.titan-embed-text-v2:0 支持可选的 dimensions 与 normalize 参数，可在运行时通过 BedrockTitanEmbeddingOptions 传入。

6. 运行时选项

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        BedrockTitanEmbeddingOptions.builder()
            .inputType(InputType.TEXT)
            .build()));

7. 示例控制器

spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}

spring.ai.model.embedding=bedrock-titan
@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);
    }
}

8. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bedrock</artifactId>
</dependency>
var titanEmbeddingApi = new TitanEmbeddingBedrockApi(
        TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(),
        Region.US_EAST_1.id());

var embeddingModel = new BedrockTitanEmbeddingModel(this.titanEmbeddingApi);

// 注意：Titan 不支持批量嵌入，所以只传单条文本
EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World"));

9. 底层 TitanEmbeddingBedrockApi

9.1 文本嵌入

TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi(
        TitanEmbeddingModel.TITAN_EMBED_TEXT_V1.id(),
        Region.US_EAST_1.id());

TitanEmbeddingRequest request = TitanEmbeddingRequest.builder()
        .withInputText("I like to eat apples.")
        .build();

TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request);

9.2 图像嵌入

图像必须转成 base64 字符串：

TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi(
        TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(),
        Region.US_EAST_1.id());

byte[] image = new DefaultResourceLoader()
        .getResource("classpath:/spring_framework.png")
        .getContentAsByteArray();

TitanEmbeddingRequest request = TitanEmbeddingRequest.builder()
        .withInputImage(Base64.getEncoder().encodeToString(this.image))
        .build();

TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request);

10. 自动配置类全限定名参考

启动器 / 类Maven 坐标
Java AI Bedrock 启动器org.springframework.ai:spring-ai-starter-model-bedrock
Java AI Bedrock 核心库org.springframework.ai:spring-ai-bedrock

关键类：

  • org.springframework.ai.bedrock.titan.embedding.BedrockTitanEmbeddingProperties
  • org.springframework.ai.bedrock.titan.embedding.BedrockTitanEmbeddingModel
  • org.springframework.ai.bedrock.titan.embedding.BedrockTitanEmbeddingOptions
  • org.springframework.ai.bedrock.titan.embedding.TitanEmbeddingBedrockApi
  • org.springframework.ai.bedrock.titan.embedding.TitanEmbeddingModel（枚举：TITAN_EMBED_IMAGE_V1、TITAN_EMBED_TEXT_V1）

11. 注意事项

注意

  • 不支持批量嵌入：一次只能一条输入。Java AI 内部会逐条调用，不是一次性发一个 batch。
  • 图像嵌入需要 base64：底层 API 不接受 URL，必须先把图像字节流读出来编码。
  • inputType 默认值：Titan Embedding 的 inputType 默认是 TEXT，跟 Cohere 不同。

12. 小结

Bedrock Titan Embedding 适合：

  • 已经在 AWS 生态的应用，统一鉴权和计费
  • 需要多模态嵌入（同时处理文本和图像）的场景
  • 对数据合规有要求的企业（AWS 托管）

主要限制是不支持批量嵌入——每次只能一条。如果你的应用对吞吐量敏感，建议换 OpenAI Embeddings 或 Cohere Embeddings。

(ONNX) Transformers Embedding（ONNX 本地嵌入模型）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/onnx.html 📌 原文版本：Java AI 2.0.1

白话解读

ONNX Transformers 让 Java AI 直接在 JVM 里加载本地嵌入模型（比如 HuggingFace 上的 sentence-transformers 模型），不依赖任何云服务。数据不出本机，完全离线可用。

1. 简介

TransformersEmbeddingModel 是 Java AI 提供的本地嵌入模型实现，使用选定的 sentence transformer 在本地计算句子嵌入。它能加载任何 HuggingFace 上的 sentence transformer 模型。

底层使用：

  • Deep Java Library（DJL）——DJL 的 ONNX Runtime
  • Microsoft ONNX Java Runtime——在 Java 中运行 ONNX 模型

白话解读

ONNX 是"开放神经网络交换格式"，把模型从 PyTorch/TensorFlow 序列化后，可以在任何支持 ONNX 的运行时（包括 Java）加载执行。你可以把 HuggingFace 上的 PyTorch 模型用 optimum-cli 转成 ONNX，然后用 Java AI 在 JVM 里直接跑。

2. 先决条件

2.1 把模型转成 ONNX 格式

用 optimum-cli 命令行工具（需要 Python 环境）：

python3 -m venv venv
source ./venv/bin/activate
(venv) pip install --upgrade pip
(venv) pip install optimum onnx onnxruntime sentence-transformers
(venv) optimum-cli export onnx --model sentence-transformers/all-MiniLM-L6-v2 onnx-output-folder

执行后，onnx-output-folder 目录会有：

  • tokenizer.json（分词器）
  • model.onnx（模型权重）

你可以用任何 HuggingFace 模型标识符替换 all-MiniLM-L6-v2。

3. 自动配置

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

Gradle：

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

4. 嵌入属性

4.1 启用开关

spring:
  ai:
    model:
      embedding: transformers     # 默认启用
      # embedding: none         # 禁用

4.2 配置属性

属性描述默认值
spring.ai.embedding.transformer.tokenizer.uri分词器 URI（tokenizer.json）onnx/all-MiniLM-L6-v2/tokenizer.json
spring.ai.embedding.transformer.tokenizer.options分词器选项（addSpecialTokens、modelMaxLength、truncation、padding、maxLength、stride、padToMultipleOf）empty
spring.ai.embedding.transformer.cache.enabled启用远程资源缓存true
spring.ai.embedding.transformer.cache.directory远程资源缓存目录${java.io.tmpdir}/spring-ai-onnx-model
spring.ai.embedding.transformer.onnx.model-uriONNX 模型 URIonnx/all-MiniLM-L6-v2/model.onnx
spring.ai.embedding.transformer.onnx.model-output-name模型输出节点名last_hidden_state
spring.ai.embedding.transformer.onnx.gpu-device-idGPU 设备 ID（需要 onnxruntime_gpu 依赖）-1
spring.ai.embedding.transformer.metadata-mode文档元数据提取模式NONE

4.3 配置示例

用 intfloat/e5-small-v2 模型：

spring.ai.embedding.transformer.onnx.model-uri=https://huggingface.co/intfloat/e5-small-v2/resolve/main/model.onnx
spring.ai.embedding.transformer.tokenizer.uri=https://huggingface.co/intfloat/e5-small-v2/raw/main/tokenizer.json

5. 错误处理与特殊情况

5.1 Ragged Array 错误

如果看到 Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..，需要开启 tokenizer padding：

spring.ai.embedding.transformer.tokenizer.options.padding=true

5.2 输出节点名错误

如果看到 The generative output names don't contain expected: last_hidden_state. Consider one of the available model outputs: token_embeddings, ...，根据报错里的名字设置：

spring.ai.embedding.transformer.onnx.model-output-name=token_embeddings

5.3 大于 2GB 的模型

如果看到 ai.onnxruntime.OrtException: Error code - ORT_FAIL - message: Deserialize tensor onnx::MatMul_10319 failed.GetFileLength for ./model.onnx_data failed:Invalid fd was supplied: -1：

模型 > 2GB 时，ONNX Runtime 会拆成两个文件：

  • model.onnx
  • model.onnx_data（外部数据，external data）

解决方法：把 model.onnx_data 复制到运行 Boot 应用的同一个文件夹下。

5.4 GPU 缺少依赖

如果看到 ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared provider，说明你设置了 GPU 设备 ID 但缺 onnxruntime_gpu 依赖：

<dependency>
    <groupId>com.microsoft.onnxruntime</groupId>
    <artifactId>onnxruntime_gpu</artifactId>
</dependency>

注意

onnxruntime_gpu 版本必须与你的 CUDA 版本匹配。

6. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-transformers</artifactId>
</dependency>
TransformersEmbeddingModel embeddingModel = new TransformersEmbeddingModel();

// (可选) 默认 classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json
embeddingModel.setTokenizerResource("classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json");

// (可选) 默认 classpath:/onnx/all-MiniLM-L6-v2/model.onnx
embeddingModel.setModelResource("classpath:/onnx/all-MiniLM-L6-v2/model.onnx");

// (可选) 默认 ${java.io.tmpdir}/spring-ai-onnx-model，只缓存 http/https 资源
embeddingModel.setResourceCacheDirectory("/tmp/onnx-zoo");

// (可选) 遇到 ragged array 错误时开启
embeddingModel.setTokenizerOptions(Map.of("padding", "true"));

embeddingModel.afterPropertiesSet();   // 必须手动初始化

List<List<Double>> embeddings = this.embeddingModel.embed(List.of("Hello world", "World is big"));

注意

手动创建 TransformersEmbeddingModel 后必须调用 afterPropertiesSet() 才能用。

首次调用 embed() 会下载大模型并缓存到本地，第一次会比较慢。

更优雅的方式是创建成 Bean：

@Bean
public EmbeddingModel embeddingModel() {
    return new TransformersEmbeddingModel();
}

这样 Spring 会自动调用 afterPropertiesSet()。

7. 默认模型：all-MiniLM-L6-v2

未指定模型时，默认用 sentence-transformers/all-MiniLM-L6-v2：

维度384
平均性能（MTEB）58.80
速度~14200 sentences/sec
模型大小~80 MB

适合轻量级语义搜索，CPU 上也能跑。

8. 常见可用模型

模型维度特点
sentence-transformers/all-MiniLM-L6-v2384默认，轻量
intfloat/e5-small-v2384微软出品，质量稍好
intfloat/e5-base-v2768平衡
intfloat/e5-large-v21024高质量
BAAI/bge-base-en-v1.5768智源出品，中文友好
BAAI/bge-large-en-v1.51024大模型版

9. 注意事项

注意

  • 首次加载会下载大模型（几百 MB），请提前预热或预下载。
  • CPU 上跑 MiniLM 类小模型很快，跑大模型（e5-large、bge-large）会比较慢，建议用 GPU。
  • Tokenizer padding、模型输出节点名等参数因模型而异，遇到错误先看错误信息里的提示。

10. 小结

ONNX Transformers Embedding 的特点：

  • 完全本地：数据不出本机，断网可用
  • 零 API 成本：一次下载模型，长期使用
  • 生态丰富：兼容 HuggingFace 上几乎所有 sentence transformer
  • CPU/GPU 灵活：轻模型 CPU 即可，重模型 GPU 加速

适用场景：

  • 隐私敏感：医疗、金融、政府等
  • 离线环境：内网部署、无外网
  • 小规模 RAG：对吞吐量要求不高的内部应用

主要限制是首次启动慢（要下载模型），以及大模型需要 GPU。

Google GenAI Text Embeddings

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/google-genai-embeddings-text.html 📌 原文版本：Java AI 2.0.1

白话解读

Google GenAI Text Embedding 是新版 Google 嵌入 API，既能走 Gemini Developer API（API Key 简单接入）又能走 Vertex AI（GCP 正式部署）。它支持 task_type 参数，能针对不同场景（搜索文档、搜索查询、分类、聚类）优化嵌入质量。

1. 简介

Google GenAI Embeddings API 用稠密向量表示文本，能捕获文本的语义信息，比传统的词法匹配更适合语义搜索。

支持两种鉴权模式：

  • Gemini Developer API：用 API Key 接入，适合快速开发
  • Vertex AI：用 Google Cloud 凭证接入，适合生产部署

白话解读

目前 Google GenAI SDK 只支持文本嵌入，多模态嵌入还在路线图上。

2. 准备工作

方式 A：Gemini Developer API（API Key）

  1. 到 https://aistudio.google.com/apikey 申请 API Key。
  2. 设置环境变量或在 application.properties 里配置。

方式 B：Vertex AI（GCP）

gcloud config set project <PROJECT_ID>
gcloud auth application-default login <ACCOUNT>

3. 自动配置

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

4. 连接属性

连接属性与 Google GenAI Chat 共用一份配置。

属性描述默认值
spring.ai.google.genai.embedding.api-keyGemini Developer API Key（设置后走 Developer API）-
spring.ai.google.genai.embedding.project-idGCP 项目 ID（Vertex AI 模式必填）-
spring.ai.google.genai.embedding.locationGCP 区域（Vertex AI 模式必填）-
spring.ai.google.genai.embedding.credentials-uriGCP 凭证 URI（可选）-

5. 启用开关

spring:
  ai:
    model:
      embedding:
        text: google-genai       # 默认启用
        # text: none           # 禁用

6. Text Embedding 属性

属性描述默认值
spring.ai.model.embedding.text启用 GenAI Text Embeddinggoogle-genai
spring.ai.google.genai.embedding.text.model模型名text-embedding-004
spring.ai.google.genai.embedding.text.task-type任务类型（见下）RETRIEVAL_DOCUMENT
spring.ai.google.genai.embedding.text.title文档标题（仅 RETRIEVAL_DOCUMENT）-
spring.ai.google.genai.embedding.text.dimensions输出维度（004+ 才支持）-
spring.ai.google.genai.embedding.text.auto-truncate超长是否截断true

6.1 Task Type 可选值

值用途
RETRIEVAL_QUERY搜索查询（用于检索）
RETRIEVAL_DOCUMENT文档索引（用于被检索）
SEMANTIC_SIMILARITY衡量文本语义相似度
CLASSIFICATION文本分类
CLUSTERING文本聚类
QUESTION_ANSWERING问答系统
FACT_VERIFICATION事实核查

白话解读

关键技巧：做 RAG 时文档用 RETRIEVAL_DOCUMENT，查询用 RETRIEVAL_QUERY，两种向量可比，搜索质量才高。

6.2 支持的模型

  • text-embedding-004（默认，最新）
  • text-multilingual-embedding-002（多语言版）

7. 示例控制器

7.1 使用 Gemini Developer API

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.model=text-embedding-004

7.2 使用 Vertex AI

spring.ai.google.genai.embedding.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.embedding.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.embedding.text.model=text-embedding-004
@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);
    }
}

8. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai-embedding</artifactId>
</dependency>

8.1 使用 API Key

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .build();

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = embeddingModel
    .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

8.2 使用 Vertex AI

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails,
    GoogleGenAiTextEmbeddingOptions.builder()
        .model("text-embedding-004")
        .taskType(TaskType.RETRIEVAL_DOCUMENT)
        .build());

EmbeddingResponse embeddingResponse = embeddingModel
    .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

9. Task Types 用法示例

// 给文档建索引
GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("Product Documentation")    // 可选：文档标题
    .build();

// 给查询做嵌入
GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

10. 降维（节省存储）

004 模型支持自定义维度：

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .dimensions(256)   // 默认 768 降到 256，节省 2/3 存储
    .build();

小技巧

降维会损失少量精度，但对大规模向量库非常有用——存储成本和搜索时间都大幅下降。

11. 从 Vertex AI Text Embeddings 迁移

如果你之前用 spring-ai-vertex-ai-embedding，迁移到 GenAI 的改动：

项Vertex AIGoogle GenAI
SDKVertex AI SDKcom.google.genai.Client
鉴权仅 Google Cloud 凭证支持 API Key + GCP 凭证
包名org.springframework.ai.vertexai.embeddingorg.springframework.ai.google.genai.text
配置前缀spring.ai.vertex.ai.embeddingspring.ai.google.genai.embedding
连接详情VertexAiEmbeddingConnectionDetailsGoogleGenAiEmbeddingConnectionDetails

GenAI 模块的最大优势：既能快速原型（API Key），又能生产部署（Vertex AI），一套代码两边用。

12. 小结

Google GenAI Text Embedding 的亮点：

  • task_type 优化：根据下游任务选合适的类型，搜索质量更高
  • 降维支持：大规模向量库能省存储
  • 双鉴权模式：开发用 API Key，生产用 Vertex AI
  • 多语言支持：text-multilingual-embedding-002 适合跨语言搜索

如果你已经在 GCP 生态、或者需要中文等多语言支持，Google GenAI Embedding 是 OpenAI 之外的好选择。

Mistral AI Embeddings

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/mistralai-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

Mistral 提供两种嵌入模型：通用文本版（mistral-embed）和代码专用版（codestral-embed）。后者专门针对代码语义做了优化，适合做代码搜索和代码仓库 RAG。

1. 简介

Java AI 支持 Mistral AI 的文本嵌入模型。Mistral AI Embeddings API 提供业界领先的文本嵌入，可用于语义搜索、聚类、文本相似度等 NLP 任务。

2. 可用模型

模型维度用途描述
mistral-embed1024通用文本适合自然语言内容的通用嵌入模型
codestral-embed1536代码针对代码相似度、代码搜索、代码仓库 RAG 优化，提供专门理解代码语义的更高维嵌入

白话解读

选择建议：

  • 文档、文章、用户查询等通用文本 → mistral-embed
  • 代码、技术文档、代码感知的 RAG → codestral-embed

3. 准备工作

  1. 在 https://console.mistral.ai 注册账号。
  2. 在 API Keys 页面生成令牌。
  3. 配置 spring.ai.mistralai.api-key。

3.1 安全做法

spring:
  ai:
    mistralai:
      api-key: ${MISTRALAI_API_KEY}
export MISTRALAI_API_KEY=<your-mistralai-api-key>

4. 自动配置

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

5. 嵌入属性

5.1 重试属性

属性描述默认值
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-errors4xx 错误是否重试false
spring.ai.retry.exclude-on-http-codes不重试的 HTTP 状态码empty
spring.ai.retry.on-http-codes触发重试的 HTTP 状态码empty

5.2 连接属性

属性描述默认值
spring.ai.mistralai.base-urlMistral API 入口api.mistral.ai
spring.ai.mistralai.api-keyAPI Key-

5.3 嵌入模型配置

属性描述默认值
spring.ai.model.embedding启用 Mistral 嵌入mistral
spring.ai.mistralai.embedding.base-url嵌入专用 URL（覆盖通用）-
spring.ai.mistralai.embedding.api-key嵌入专用 Key（覆盖通用）-
spring.ai.mistralai.embedding.metadata-mode文档内容提取模式EMBED
spring.ai.mistralai.embedding.model模型名mistral-embed
spring.ai.mistralai.embedding.encoding-format返回格式：float 或 base64-

小技巧

可以为 chat 和 embedding 设置不同的 base-url / api-key：

spring:
  ai:
    mistralai:
      base-url: https://api.mistral.ai
      api-key: ${MISTRALAI_KEY}
      chat:
        model: mistral-large-latest
      embedding:
        base-url: https://api.mistral.ai
        api-key: ${MISTRALAI_KEY}
        model: codestral-embed

这样 chat 和 embedding 走不同账户，方便计费管理。

6. 启用开关

spring:
  ai:
    model:
      embedding: mistral     # 默认启用
      # embedding: none    # 禁用

7. 运行时选项

// 通用文本嵌入
EmbeddingResponse textEmbeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        MistralAiEmbeddingOptions.builder()
            .withModel("mistral-embed")
            .build()));

// 代码嵌入
EmbeddingResponse codeEmbeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("public class HelloWorld {}", "def hello_world():"),
        MistralAiEmbeddingOptions.builder()
            .withModel("codestral-embed")
            .build()));

8. 示例控制器

spring.ai.mistralai.api-key=YOUR_API_KEY
spring.ai.mistralai.embedding.model=mistral-embed
@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) {
        var embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

9. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mistral-ai</artifactId>
</dependency>
var mistralAiApi = new MistralAiApi(System.getenv("MISTRAL_AI_API_KEY"));

var embeddingModel = new MistralAiEmbeddingModel(this.mistralAiApi,
        MistralAiEmbeddingOptions.builder()
                .withModel("mistral-embed")
                .withEncodingFormat("float")
                .build());

EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

10. 代码嵌入实战

如果你的应用涉及代码搜索（比如 IDE 插件、内部代码仓库），codestral-embed 比通用嵌入模型表现好得多：

@RestController
public class CodeSearchController {

    private final EmbeddingModel embeddingModel;
    private final VectorStore vectorStore;

    // 索引代码片段
    @PostMapping("/index")
    public void indexCode(@RequestBody List<String> codeSnippets) {
        List<Document> docs = codeSnippets.stream()
            .map(code -> new Document(code, Map.of("type", "code")))
            .toList();

        // 用 codestral-embed 嵌入
        vectorStore.add(docs);    // 默认用 chat 配置的嵌入模型
    }

    // 代码搜索
    @GetMapping("/search")
    public List<Document> search(@RequestParam String query) {
        return vectorStore.similaritySearch(query);
    }
}

11. 小结

Mistral AI Embeddings 的特点：

  • 两个模型各有专攻：通用 vs 代码
  • 欧洲合规：GDPR 严格的场景合适
  • 通过 MistralAiApi 复用：chat 和 embedding 共用一个 starter
  • 编码格式灵活：可选 float 或 base64

适用场景：

  • 通用 RAG：用 mistral-embed
  • 代码仓库搜索 / IDE 插件：用 codestral-embed
  • 欧洲用户 / GDPR 合规：Mistral 是法国厂商，天然合规

PostgresML Embeddings

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/postgresml-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

PostgresML 是个 PostgreSQL 扩展，能直接在数据库里跑机器学习模型（包括嵌入模型）。Java AI 通过 JDBC 调用，让你的向量和数据都存在一个 Postgres 里，免去额外的数据传输。

1. 简介

PostgresML 把大量预训练 LLM 直接集成到 PostgreSQL 里。Java AI 通过 JDBC 连接 Postgres，让你在数据库里直接生成嵌入。

优势：

  • 数据不动：数据已经在 Postgres 里了，嵌入也在 Postgres 里生成，免去网络传输
  • 支持任意 HuggingFace transformer：distilbert、e5、bge 等等
  • 向量类型灵活：可选 PG_ARRAY（数组）或 PG_VECTOR（pgvector 扩展）

白话解读

适合"已经重度使用 PostgreSQL + pgvector"的项目。一站式搞定数据 + 向量 + 嵌入生成，不用多个数据库来回倒腾。

2. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-postgresml-embedding</artifactId>
</dependency>

3. 启用开关

spring:
  ai:
    model:
      embedding: postgresml     # 默认启用
      # embedding: none       # 禁用

4. 嵌入属性

属性描述默认值
spring.ai.postgresml.embedding.create-extension启动时是否执行 CREATE EXTENSION IF NOT EXISTS pgmlfalse
spring.ai.postgresml.embedding.transformerHuggingFace transformer 模型distilbert-base-uncased
spring.ai.postgresml.embedding.kwargstransformer 特定参数empty
spring.ai.postgresml.embedding.vector-type向量类型：PG_ARRAY 或 PG_VECTORPG_ARRAY
spring.ai.postgresml.embedding.metadata-mode文档元数据模式EMBED

注意

  • PG_VECTOR 类型需要额外安装 pgvector 扩展（CREATE EXTENSION vector;）。
  • create-extension=true 时 Java AI 会自动帮你建扩展，但需要数据库用户有 superuser 权限。

5. 运行时选项

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
            PostgresMlEmbeddingOptions.builder()
                .transformer("intfloat/e5-small")    // 用 e5-small
                .vectorType(VectorType.PG_ARRAY)
                .kwargs(Map.of("device", "gpu"))    // 用 GPU 推理
                .build()));

6. 示例控制器

spring.ai.postgresml.embedding.transformer=distilbert-base-uncased
spring.ai.postgresml.embedding.vector-type=PG_ARRAY
spring.ai.postgresml.embedding.metadata-mode=EMBED
spring.ai.postgresml.embedding.kwargs.device=cpu
@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);
    }
}

7. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-postgresml</artifactId>
</dependency>
var jdbcTemplate = new JdbcTemplate(dataSource);    // PostgresML 数据源

PostgresMlEmbeddingModel embeddingModel = new PostgresMlEmbeddingModel(this.jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
            .transformer("distilbert-base-uncased")    // HuggingFace 模型名
            .vectorType(VectorType.PG_VECTOR)            // 用 pgvector 类型
            .kwargs(Map.of("device", "cpu"))              // CPU 推理
            .metadataMode(MetadataMode.EMBED)
            .build());

embeddingModel.afterPropertiesSet();   // 必须调用，初始化 JDBC 模板和数据库

EmbeddingResponse embeddingResponse = this.embeddingModel
        .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

更优雅的方式是创建成 Bean（这样不用手动调 afterPropertiesSet()）：

@Bean
public EmbeddingModel embeddingModel(JdbcTemplate jdbcTemplate) {
    return new PostgresMlEmbeddingModel(jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
            .transformer("intfloat/e5-small")
            .vectorType(VectorType.PG_VECTOR)
            .build());
}

8. 常用 transformer 模型

模型维度特点
distilbert-base-uncased768默认，英文通用
intfloat/e5-small384微软，质量好
intfloat/e5-base-v2768平衡
BAAI/bge-base-en-v1.5768智源，中文友好
sentence-transformers/all-MiniLM-L6-v2384轻量

完整列表请到 https://huggingface.co/models?pipeline_tag=feature-extraction 查阅。

9. 注意事项

注意

  • 首次加载模型慢：PostgresML 会下载 transformer 模型，第一次嵌入调用会比较慢。
  • GPU 依赖：要用 device=gpu 需要 PostgresML 装 GPU 支持。
  • PG_VECTOR 性能更好：如果项目已经用 pgvector，强烈推荐选 PG_VECTOR（向量压缩、索引、相似度搜索都快很多）。
  • 数据源配置：需要在 application.properties 里配置 PostgresML 数据库的 JDBC 数据源（url、username、password）。

10. 小结

PostgresML Embeddings 的最大卖点是数据库一体化——数据存在 Postgres，向量也由 Postgres 生成，配合 pgvector 一站式搞定。适合：

  • 已经重度使用 PostgreSQL 的项目
  • 不想引入额外服务（如 Ollama、ONNX 独立部署）
  • 数据敏感、不能出库的场景

主要限制：

  • 需要安装 PostgresML 扩展（不是标准 PostgreSQL）
  • 模型加载慢，扩展需要 GPU 才能跑大模型
  • 嵌入生成速度受限于数据库（不适用于高吞吐量场景）

VertexAI Text Embeddings（Google Vertex AI 文本嵌入）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/vertexai-embeddings-text.html 📌 原文版本：Java AI 2.0.1

白话解读

Vertex AI 是 Google Cloud 上的 AI 平台，Java AI 提供原生的 VertexAI Embedding 集成。如果你的应用跑在 GCP 上、或者用 GCP 托管服务，这个模块比 Google GenAI Embedding 更合适。

1. 简介

Vertex AI 提供两种嵌入模型：

  • 文本嵌入（text-embedding）
  • 多模态嵌入（multimodal-embedding，可处理文本 + 图像 + 视频）

本页介绍文本嵌入，多模态嵌入见 VertexAI Multimodal Embeddings。

文本嵌入 API 使用稠密向量表示文本，比稀疏向量（直接映射词到数字）更适合语义搜索。

2. 前置条件

  1. 安装适合操作系统的 gcloud CLI。
  2. 鉴权：
gcloud config set project <PROJECT_ID>
gcloud auth application-default login <ACCOUNT>

3. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-vertex-ai-embedding</artifactId>
</dependency>

4. 连接属性

属性描述默认值
spring.ai.vertex.ai.embedding.project-idGCP 项目 ID-
spring.ai.vertex.ai.embedding.location区域-
spring.ai.vertex.ai.embedding.api-endpointVertex AI Embedding API 端点-

5. 启用开关

spring:
  ai:
    model:
      embedding:
        text: vertexai     # 默认启用
        # text: none      # 禁用

6. Text Embedding 属性

属性描述默认值
spring.ai.model.embedding.text启用 VertexAI Text Embeddingvertexai
spring.ai.vertex.ai.embedding.text.model模型名text-embedding-004
spring.ai.vertex.ai.embedding.text.task-type任务类型（类似 Google GenAI）RETRIEVAL_DOCUMENT
spring.ai.vertex.ai.embedding.text.title文档标题（仅 RETRIEVAL_DOCUMENT）-
spring.ai.vertex.ai.embedding.text.dimensions输出维度（004+ 支持）-
spring.ai.vertex.ai.embedding.text.auto-truncate超长是否截断true

6.1 Task Type 可选值

跟 Google GenAI 一样：

  • RETRIEVAL_QUERY：搜索查询
  • RETRIEVAL_DOCUMENT：文档索引
  • SEMANTIC_SIMILARITY：语义相似度
  • CLASSIFICATION：分类
  • CLUSTERING：聚类
  • QUESTION_ANSWERING：问答
  • FACT_VERIFICATION：事实核查

7. 示例控制器

spring.ai.vertex.ai.embedding.project-id=<YOUR_PROJECT_ID>
spring.ai.vertex.ai.embedding.location=<YOUR_PROJECT_LOCATION>
spring.ai.vertex.ai.embedding.text.model=text-embedding-004
@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);
    }
}

8. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-embedding</artifactId>
</dependency>
VertexAiEmbeddingConnectionDetails connectionDetails =
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("VERTEX_AI_GEMINI_PROJECT_ID"))
        .location(System.getenv("VERTEX_AI_GEMINI_LOCATION"))
        .build();

VertexAiTextEmbeddingOptions options = VertexAiTextEmbeddingOptions.builder()
    .model(VertexAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .build();

var embeddingModel = new VertexAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = this.embeddingModel
    .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

9. 从 Google 服务账号加载凭证

如果需要从服务账号 JSON 文件加载凭证：

GoogleCredentials credentials = GoogleCredentials.fromStream(<INPUT_STREAM_TO_CREDENTIALS_JSON>)
        .createScoped("https://www.googleapis.com/auth/cloud-platform");
credentials.refreshIfExpired();

VertexAiEmbeddingConnectionDetails connectionDetails =
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("VERTEX_AI_GEMINI_PROJECT_ID"))
        .location(System.getenv("VERTEX_AI_GEMINI_LOCATION"))
        .apiEndpoint(endpoint)
        .predictionServiceSettings(
            PredictionServiceSettings.newBuilder()
                .setEndpoint(endpoint)
                .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
                .build());

10. VertexAI vs Google GenAI

项VertexAIGoogle GenAI
鉴权仅 GCP 凭证API Key + GCP 凭证
SDKVertex AI SDKGoogle GenAI SDK
包名org.springframework.ai.vertexai.embeddingorg.springframework.ai.google.genai.text
适用GCP 内部部署跨云 + GCP

白话解读

选择建议：

  • 已经在 GCP 生态、想用 Vertex AI 统一管理 → 用 VertexAI
  • 需要快速原型（API Key）、也想走 Vertex AI → 用 Google GenAI

11. 注意事项

注意

  • GCP 项目必填：Vertex AI 必须有 GCP 项目 ID 和区域。
  • API 端点：默认用全局 endpoint；如果项目开了 Private Service Connect，可能需要指定 api-endpoint。
  • 首次调用慢：Vertex AI 会冷启动模型，第一次嵌入会比后续慢。
  • 不支持的部分模型：部分预览版模型可能不在 Vertex AI 上可用。

12. 小结

VertexAI Text Embedding 的特点：

  • GCP 原生集成：身份、计费、网络全走 GCP
  • task_type 优化：根据任务类型优化嵌入质量
  • 降维支持：004+ 支持自定义维度
  • 支持自定义端点：Private Service Connect、自管 VPC

适用场景：

  • GCP 生态项目：Vertex AI + BigQuery + Cloud Storage 全家桶
  • 数据合规：使用 GCP 的合规资质
  • 企业级部署：需要 IAM、VPC-SC 等安全特性

如果你的项目不在 GCP 上、或者只需要 API Key 快速接入，建议改用 Google GenAI Text Embedding。

OCI GenAI Embeddings（迁移提示）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/oci-genai-embeddings.html 📌 原文版本：Java AI 2.0.1

白话解读

跟 OCI GenAI Chat 一样，OCI GenAI Embeddings 在 Java AI 2.0.1 中只是个简短迁移通知——已经由社区维护。

1. 官方说明

原文翻译如下：

Oracle Cloud Infrastructure Generative AI 集成目前已由社区维护，请参阅相关文档了解详情。

英文原文：

The Oracle Cloud Infrastructure Generative AI integration is now maintained by the community, please see the related documentation for more details.

2. 含义解读

  • Java AI 主项目不再维护 OCI GenAI Embeddings 模块
  • 2.0.1 版本的当前页面只保留导航入口，没有具体技术内容
  • Maven 坐标、auto-configuration 类、配置属性等已迁移到社区仓库

3. 替代方案

3.1 旧版文档

切换到 Java AI 1.0.9 或 1.1.8 版本，可能保留完整文档：

https://docs.spring.io/spring-ai/reference/1.0.x/api/embeddings/oci-genai-embeddings.html
https://docs.spring.io/spring-ai/reference/1.1.x/api/embeddings/oci-genai-embeddings.html

3.2 社区维护仓库

按官方提示，去 Java AI 社区文档仓库查找新位置。

3.3 直接使用 OCI Java SDK

OCI 官方提供 Java SDK（oci-java-sdk），可绕过 Java AI 直接调用 OCI 上的 Cohere、Meta Llama 嵌入模型：

  1. 引入 com.oracle.oci.sdk:oci-java-sdk。
  2. 用 GenerativeAi 客户端调用 OCI 嵌入模型。
  3. 把 SDK 返回结果适配到 Java AI 的 EmbeddingResponse。

3.4 OpenAI 兼容协议

OCI Generative AI 部分嵌入模型支持 OpenAI 兼容端点，可以复用 Java AI 的 OpenAI Embeddings 客户端：

spring:
  ai:
    openai:
      base-url: https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/v1
      api-key: ${OCI_CONFIG_PROFILE_TOKEN}
      embedding:
        model: cohere.embed-multilingual-v3

注意

OpenAI 兼容协议是 OCI 后来加的能力，不一定覆盖所有模型，请参考 OCI 官方文档确认。

4. OCI Generative AI 嵌入模型简介

模型维度特点
cohere.embed-multilingual-v31024多语言
cohere.embed-english-v31024英文
cohere.embed-multilingual-light-v3384多语言轻量版

完整列表请到 https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm 查阅。

5. 注意事项

注意

  • 2.0.1 主项目页面没有实质技术内容。
  • 旧版（1.0.x / 1.1.x）可能有完整文档可参考。
  • 关注社区仓库的新版本以获取最新文档。

6. 小结

OCI GenAI Embeddings 在 Java AI 2.0.1 中没有独立文档。如果你需要使用：

  • 查阅旧版文档
  • 关注社区仓库
  • 或直接用 OCI Java SDK + 自定义适配
  • 或走 OpenAI 兼容协议复用 Java AI OpenAI Embeddings

随着 Java AI 演进，OCI 模块可能重新整合，目前以社区文档为准。

VertexAI Multimodal Embeddings（Vertex AI 多模态嵌入）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/embeddings/vertexai-embeddings-multimodal.html 📌 原文版本：Java AI 2.0.1

白话解读

Vertex AI 的多模态嵌入模型能把图像、文本、视频统一转成 1408 维向量，三种向量在同一语义空间里。这意味着你可以用文本搜图像、用图像搜视频，或者用视频搜文本——非常强大但实验性。

实验性功能

此模块是实验性的，仅用于实验目的，目前与 VectorStores 不兼容。

1. 简介

Vertex AI 的多模态嵌入模型（multimodalembedding@001）会根据输入内容生成 1408 维向量，输入可以是图像、文本、视频的任意组合。这些向量适合用于：

  • 图像分类
  • 视频内容审核
  • 以文搜图
  • 以图搜视频

关键特性：图像向量和文本向量在同一语义空间，所以可以互相替代——比如用文本向量搜图像，或者用图像向量搜视频。

2. 前置条件

  1. 安装 gcloud CLI。
  2. 鉴权：
gcloud config set project <PROJECT_ID>
gcloud auth application-default login <ACCOUNT>

3. API 限制

VertexAI Multimodal API 施加了一些限制：

  • 仅支持 multimodalembedding@001 模型
  • 视频片段默认最长 120 秒
  • 多模态向量与文本专用向量不通用——纯文本场景建议用 text-embedding-004

注意

与 VectorStores 不兼容：这是实验性功能，Java AI 的 VectorStore 抽象还未适配多模态嵌入，需要你自己处理向量的存储与检索。

4. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-vertex-ai-embedding</artifactId>
</dependency>

5. 嵌入属性

5.1 连接属性（与 Text Embedding 共用）

属性描述默认值
spring.ai.vertex.ai.embedding.project-idGCP 项目 ID-
spring.ai.vertex.ai.embedding.location区域-
spring.ai.vertex.ai.embedding.api-endpointVertex AI Embedding API 端点-

5.2 启用开关

spring:
  ai:
    model:
      embedding:
        multimodal: vertexai     # 默认启用
        # multimodal: none     # 禁用

5.3 Multimodal 配置属性

属性描述默认值
spring.ai.model.embedding.multimodal启用 VertexAI Multimodalvertexai
spring.ai.vertex.ai.embedding.multimodal.model模型名multimodalembedding@001
spring.ai.vertex.ai.embedding.multimodal.dimensions降维（可选 128、256、512）1408
spring.ai.vertex.ai.embedding.multimodal.video-start-offset-sec视频片段起始偏移（秒）按 max(0, endOffsetSec - 120) 计算
spring.ai.vertex.ai.embedding.multimodal.video-end-offset-sec视频片段结束偏移（秒）按 min(video length, startOffSec + 120) 计算
spring.ai.vertex.ai.embedding.multimodal.video-interval-sec视频采样间隔（最小 4 秒）16

小技巧

降维：可以把 1408 维降到 128、256 或 512，节省存储。注意：降维可能影响精度，特别是细粒度搜索场景。

5.4 视频片段规则

  • 默认最长 120 秒（startOffSec 到 endOffSec）
  • interval_sec 最小 4 秒，更小会报错
  • interval_sec 最大无限制，但超过 120 秒会影响嵌入质量

6. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-embedding</artifactId>
</dependency>
VertexAiEmbeddingConnectionDetails connectionDetails =
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("VERTEX_AI_GEMINI_PROJECT_ID"))
        .location(System.getenv("VERTEX_AI_GEMINI_LOCATION"))
        .build();

VertexAiMultimodalEmbeddingOptions options = VertexAiMultimodalEmbeddingOptions.builder()
    .model(VertexAiMultimodalEmbeddingOptions.DEFAULT_MODEL_NAME)
    .build();

var embeddingModel = new VertexAiMultimodalEmbeddingModel(connectionDetails, options);

// 同时嵌入图像 + 视频 + 文本
Media imageMedia = new Media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/test.image.png"));
Media videoMedia = new Media(new MimeType("video", "mp4"), new ClassPathResource("/test.video.mp4"));

var document = new Document("Explain what do you see on this video?",
        List.of(imageMedia, videoMedia),
        Map.of());

DocumentEmbeddingRequest embeddingRequest = new DocumentEmbeddingRequest(List.of(document),
        EmbeddingOptions.EMPTY);

EmbeddingResponse embeddingResponse = multiModelEmbeddingModel.call(embeddingRequest);

assertThat(embeddingResponse.getResults()).hasSize(3);

白话解读

注意代码里 EmbeddingResponse.getResults() 有 3 个元素——因为这个 Document 同时包含 1 个文本 + 1 张图像 + 1 个视频，每个都被单独嵌入。

这也是为什么"多模态"难以直接对接 VectorStore——传统的向量库按"一条向量 = 一条文档"组织，多模态情况下一个 Document 可能产生多条向量。

7. 典型应用场景

7.1 图像分类

用文本向量当分类器：

// 1. 给每个分类生成一段描述，做嵌入
List<String> categories = List.of("dog", "cat", "car", "tree");
EmbeddingResponse categoryEmbeddings = embeddingModel.call(
    new EmbeddingRequest(categories, EmbeddingOptions.EMPTY));

// 2. 给图像做嵌入
EmbeddingResponse imageEmbedding = embeddingModel.call(
    new EmbeddingRequest(List.of("A photo of a golden retriever playing in the park."),
            EmbeddingOptions.EMPTY));

// 3. 用余弦相似度找最近的分类

7.2 以文搜图

把图像和文本嵌入到同一空间后，可以用文本搜图像。

7.3 视频内容审核

Media videoMedia = new Media(new MimeType("video", "mp4"), videoResource);

var doc = new Document("Is this video safe?",
        List.of(videoMedia),
        Map.of("start", "0", "end", "60"));

EmbeddingResponse response = embeddingModel.call(
    new DocumentEmbeddingRequest(List.of(doc), EmbeddingOptions.EMPTY));

// 跟"安全内容"的向量比相似度

8. 与 Text Embedding 的区别

维度Text EmbeddingMultimodal Embedding
输入纯文本文本 + 图像 + 视频
默认维度768 (text-embedding-004)1408
语义空间文本专用文本/图像/视频统一空间
模型text-embedding-004multimodalembedding@001
VectorStore 兼容✅ 完全兼容❌ 不兼容
生产可用度稳定实验性

9. 注意事项

注意

  • 实验性功能：API 可能变更，不建议生产环境使用。
  • VectorStores 不兼容：需要自己处理向量存储和检索。
  • 视频时长：单次最长 120 秒，需要更长请分段。
  • 降维影响精度：降到 128 维损失大，建议至少 256 维。
  • 不推荐纯文本：纯文本请用 text-embedding-004，多模态嵌入对纯文本效果不如专用文本模型。

10. 小结

VertexAI Multimodal Embeddings 的特点：

  • 真正的多模态：文本 + 图像 + 视频统一语义空间
  • 强大的搜索能力：以文搜图、以图搜视频、以视频搜文本
  • 降维灵活：可降维到 128/256/512
  • GCP 原生集成：鉴权、计费、Quota 全走 Vertex AI

主要限制：

  • 实验性：API 可能变更
  • VectorStore 不兼容：需要自己实现向量存储层
  • 视频时长限制：单次 120 秒

如果你需要构建多模态内容理解系统（图像库搜索、视频审核、跨模态检索），这个模型是非常前沿的选择，但要注意生产部署的稳定性。

版权归属：今朝· Liushigong · Relax Box

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)

贡献者: Jinzhao
「放轻松，慢慢来」盒子 — 记录日常思考、学习笔记与技术总结
Copyright © 2023 - 2026 今朝（Liushigong） | 京ICP备20031061号