版本：2.0.1

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

OpenAI Embeddings

QWen 3.8 中英对照 OpenAI OpenAI Embeddings

Spring AI 支持 OpenAI 的文本嵌入模型。OpenAI 的文本嵌入用于衡量文本字符串之间的相关性。一个嵌入是浮点数向量（列表）。两个向量之间的距离用于衡量它们的相关性。较小的距离表明相关性较高，较大的距离表明相关性较低。

备注

从 2.0.0-M5 版本开始，Spring AI 底层使用官方 openai-java SDK 来处理所有 OpenAI 模型。此次迁移预计是无缝的，对于现有 OpenAI API 属性和构建器的用户没有破坏性变更。如果您发现任何问题，请通过 Spring AI GitHub Issues 向我们报告。

前提条件

您需要创建一个 OpenAI API，以访问 OpenAI 嵌入模型。

在 OpenAI 注册页面创建账户，并在 API Keys 页面生成 token。

Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，你应当将其设置为从 openai.com 获取的 API Key 的值。

你可以在 application.properties 文件中设置此配置属性：

spring.ai.openai.api-key=<your-openai-api-key>

在 API 密钥等敏感信息处理时，为增强安全性，您可以使用 Spring Expression Language (SpEL) 引用环境变量：

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>

您也可以在应用程序代码中通过编程方式设置此配置：

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");

添加仓库和 BOM

Spring AI 制品已发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅 Artifact Repositories 部分，以将这些仓库添加到你的构建系统中。

为便于依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致版本的 Spring AI。请参见依赖管理部分，将 Spring AI BOM 添加到您的构建系统中。

自动配置

备注

Spring AI 自动配置和 starter 模块的 artifact 名称发生了重大变更。更多信息请参阅升级说明。

Spring AI 为 OpenAI Embedding Model 提供了 Spring Boot 自动配置。要启用此功能，请在项目的 Maven pom.xml 文件中添加以下依赖项：

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

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

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

提示

请参阅依赖管理章节，将 Spring AI BOM 添加到构建文件中。

嵌入属性

重试属性

前缀 spring.ai.retry 用作属性前缀，用于配置 OpenAI Embedding 模型的重试机制。

属性	描述	默认值
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

连接属性

前缀 spring.ai.openai 用作属性前缀，以便连接到 OpenAI。

属性	描述	默认值
spring.ai.openai.base-url	连接地址（URL）	https://api.openai.com
spring.ai.openai.api-key	API Key	-
spring.ai.openai.organization-id	可选，指定用于 API 请求的组织（organization）。	-
spring.ai.openai.project-id	可选，指定用于 API 请求的项目（project）。	-
spring.ai.openai.timeout	OpenAI 客户端的请求超时时间。	60 sec.
spring.ai.openai.max-retries	OpenAI 客户端的最大重试次数。	3
spring.ai.openai.proxy	OpenAI 客户端的代理设置。	-
spring.ai.openai.custom-headers	添加到 OpenAI 客户端请求的自定义 HTTP 头。	empty
spring.ai.openai.connection-pool-metrics-enabled	是否启用底层 OkHttp 客户端的连接池指标。	false

提示

对于属于多个组织（或通过其旧版用户 API 密钥访问其项目）的用户，可以选择性地指定用于 API 请求的组织和项目。来自这些 API 请求的使用量将被计为指定组织和项目的使用量。

配置属性

备注

嵌入式自动配置（embedding auto-configurations）的启用和禁用现在通过以 spring.ai.model.embedding 为前缀的顶层属性进行配置。

启用：spring.ai.model.embedding=openai（默认情况下已启用）

禁用：spring.ai.model.embedding=none（或任何与 openai 不匹配的值）

此项更改旨在允许配置多个模型。

前缀 spring.ai.openai.embedding 是用于配置 OpenAI 的 EmbeddingModel 实现的属性前缀。

属性	描述	默认值
spring.ai.model.embedding	启用 OpenAI 嵌入模型。	openai
spring.ai.openai.embedding.base-url	可选，覆盖 spring.ai.openai.base-url 以提供嵌入专用的 URL	-
spring.ai.openai.embedding.api-key	可选，覆盖 spring.ai.openai.api-key 以提供嵌入专用的 API 密钥	-
spring.ai.openai.embedding.organization-id	可选，您可以指定用于 API 请求的组织。	-
spring.ai.openai.embedding.project-id	可选，您可以指定用于 API 请求的项目。	-
spring.ai.openai.embedding.metadata-mode	文档内容提取模式。	EMBED
spring.ai.openai.embedding.model	要使用的模型	text-embedding-ada-002 (其他选项: text-embedding-3-large, text-embedding-3-small)
spring.ai.openai.embedding.encoding-format	返回嵌入的格式。可以是 float 或 base64。	-
spring.ai.openai.embedding.user	代表您的最终用户的唯一标识符，有助于 OpenAI 监控和检测滥用行为。	-
spring.ai.openai.embedding.dimensions	输出嵌入应具有的维度数量。仅支持 `text-embedding-3` 及更高版本模型。	-
spring.ai.openai.embedding.extra-body	发送给 OpenAI 兼容提供商的额外 body 属性。	-

备注

您可以覆盖 ChatModel 和 EmbeddingModel 实现中通用的 spring.ai.openai.base-url 和 spring.ai.openai.api-key。如果设置了 spring.ai.openai.embedding.base-url 和 spring.ai.openai.embedding.api-key，则它们优先于通用属性。同样，如果设置了 spring.ai.openai.chat.base-url 和 spring.ai.openai.chat.api-key，则它们也优先于通用属性。这在希望为不同模型和不同的模型端点使用不同的 OpenAI 账户时非常有用。

提示

所有以 spring.ai.openai.embedding 为前缀的属性都可以通过在 EmbeddingRequest 调用中添加特定的 Runtime Options 在运行时进行覆盖。

运行时选项

OpenAiEmbeddingOptions.java 提供了 OpenAI 的配置项，例如所使用的 model 等。

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

在启动时，使用 OpenAiEmbeddingModel 构造函数来设置所有嵌入请求的默认选项。在运行时，你可以在 EmbeddingRequest 中通过传入 OpenAiEmbeddingOptions 实例来覆盖默认选项。

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

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

示例控制器

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

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

手动配置

如果未使用 Spring Boot，则可以手动配置 OpenAI 嵌入模型。为此，请将 spring-ai-openai 依赖项添加到项目的 Maven pom.xml 文件中：

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

或在您的 Gradle build.gradle 构建文件中。

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

提示

请参阅 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

备注

spring-ai-openai 依赖同时也提供对 OpenAiChatModel 的访问。有关 OpenAiChatModel 的更多信息，请参阅 OpenAI Chat Client 部分。

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

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

OpenAiEmbeddingOptions 提供嵌入请求的配置信息。API 和选项类提供了一个 builder() 方法，便于创建选项。

自定义 HTTP 客户端

Spring AI 底层使用官方的 openai-java SDK，并通过由 SpringAiOpenAiHttpClient.Builder 构建的自定义 OkHttp 客户端来配置其 HTTP 传输。您可以通过暴露一个或多个 OpenAiHttpClientBuilderCustomizer Bean，在底层 OkHttpClient 创建之前对该 builder 进行拦截。每个 customizer 都会接收到所有 OpenAI 模型（包括 chat、embedding、image、audio、moderation）所使用的同一个 builder，因此自定义配置将统一应用。

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

典型用例包括：

注册 OkHttp Interceptor 实例（用于身份验证、传播头、自定义日志记录等）；
更换调度器的 ExecutorService（例如，将异步 I/O 路由至虚拟线程）；
配置构建器中暴露的代理、SSL、主机名验证或连接池大小。

当存在多个定制器（customizer）时，它们会按照 @Order / Ordered 的顺序，在 Spring AI 自身的默认值之后被应用，因此用户代码优先。

通过 OpenAi*Model.Builder 手动接入模型时，也可以使用相同的钩子：

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

前提条件​

添加仓库和 BOM​

自动配置​

嵌入属性​

重试属性​

连接属性​

配置属性​

运行时选项​

示例控制器​

手动配置​

自定义 HTTP 客户端​