SpringAI-OpenAI Embeddings

Spring AI 支持OpenAI文本嵌入模型。OpenAI文本嵌入用于衡量文本字符串的相关性。嵌入是由浮点数组成的向量（列表），向量间的距离反映其相关性：距离小表示高相关性，距离大表示低相关性。

前提条件

需在OpenAI创建API以访问嵌入模型：

1. 在OpenAI注册页面创建账户

2. 于API密钥页面生成令牌

Spring AI定义了配置属性 spring.ai.openai.api-key，需设置为从openai.com获取的API密钥值。
在application.properties中配置：

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

为增强API密钥等敏感信息的安全性，可使用SpEL引用环境变量：

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

# 环境变量或.env文件  
export OPENAI_API_KEY=<your-openai-api-key>  

也可在代码中配置：

String apiKey = System.getenv("OPENAI_API_KEY");  

添加仓库与BOM

Spring AI构件发布于Maven中央仓库和Spring快照仓库。请参考"构件仓库"章节将其添加到构建系统。
为统一依赖版本，Spring AI提供BOM（物料清单）。参考"依赖管理"章节添加至构建系统。

自动配置

Spring AI自动配置及starter模块名称有重大变更，详见升级说明。
启用OpenAI嵌入模型需添加依赖：

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

嵌入属性

重试属性

前缀 spring.ai.retry 用于配置OpenAI嵌入模型的重试机制：

连接属性

前缀 spring.ai.openai 用于连接OpenAI：

多组织用户可通过这些属性指定API请求归属

配置属性

嵌入自动配置启用状态通过顶级属性 spring.ai.model.embedding 配置：

• 启用：spring.ai.model.embedding=openai（默认）

• 禁用：spring.ai.model.embedding=none

前缀 spring.ai.openai.embedding 配置OpenAI嵌入模型实现：

嵌入/聊天模型可分别通过 spring.ai.openai.embedding.* 和 spring.ai.openai.chat.* 覆盖通用配置
带 spring.ai.openai.embedding.options 前缀的属性支持运行时覆盖

运行时选项

OpenAiEmbeddingOptions 提供模型配置，默认选项可通过 spring.ai.openai.embedding.options 配置。
启动时通过构造函数设置默认选项，运行时可通过 EmbeddingRequest 覆盖：

EmbeddingResponse response = embeddingModel.call(  
  new EmbeddingRequest(List.of("Hello World"),  
    OpenAiEmbeddingOptions.builder()  
      .model("Different-Embedding-Model")  
      .build()));  

示例

@RestController  
public class EmbeddingController {  

  private final EmbeddingModel embeddingModel;  

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

  @GetMapping("/ai/embedding")  
  public Map embed(@RequestParam String message) {  
    EmbeddingResponse response = this.embeddingModel.embedForResponse(List.of(message));  
    return Map.of("embedding", response);  
  }  
}  

手动配置

非Spring Boot项目需手动添加依赖：

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

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

创建实例示例：

var openAiApi = OpenAiApi.builder()  
                .apiKey(System.getenv("OPENAI_API_KEY"))  
                .build();  

var embeddingModel = new OpenAiEmbeddingModel(  
  openAiApi,  
  MetadataMode.EMBED,  
  OpenAiEmbeddingOptions.builder()  
    .model("text-embedding-ada-002")  
    .user("user-6")  
    .build(),  
  RetryUtils.DEFAULT_RETRY_TEMPLATE);  

EmbeddingResponse response = embeddingModel.embedForResponse(  
  List.of("Hello World"));  

OpenAiEmbeddingOptions 通过builder模式配置请求参数。