SpringAI-ZhiPuAI Embeddings

Spring AI 支持智谱AI的文本嵌入模型。该模型用于衡量文本字符串之间的相关性。嵌入结果是一个浮点数向量（列表），向量间的距离反映其相关程度：距离越小表示相关性越高，距离越大则相关性越低。

前置条件

使用智谱AI语言模型需先创建API密钥：

1. 访问智谱AI注册页面创建账户

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

在Spring AI项目中：

• 配置属性 spring.ai.zhipu.api-key 需设置为API密钥值

可通过 application.properties 配置：

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

或使用SpEL引用环境变量增强安全性（YAML配置示例）：

spring:
  ai:
    zhipu:
      api-key: ${ZHIPU_API_KEY}

环境变量设置：

export ZHIPU_API_KEY=<your-zhipu-api-key>

代码动态配置：

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

添加仓库与BOM
Spring AI构件发布在Maven中央仓库和Spring快照仓库，需在构建系统中添加。通过Spring AI提供的BOM（物料清单）可统一管理依赖版本，详见依赖管理章节。

自动配置说明

Spring AI自动配置及启动器模块的构件名称有重大变更，请参考升级说明。

启用智谱AI嵌入模型需添加依赖：

• Maven配置：

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

• Gradle配置：

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

---

嵌入模型属性配置
重试机制属性（前缀 spring.ai.retry）

连接属性（前缀 spring.ai.zhipuai）

---

模型启用配置
嵌入模型开关通过顶级属性 spring.ai.model.embedding 控制：

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

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

注意：spring.ai.zhipuai.embedding.enabled 属性已弃用

嵌入模型专属属性（前缀 spring.ai.zhipuai.embedding）

提示：

1. 专属base-url/api-key优先级高于通用配置

2. 所有spring.ai.zhipuai.embedding.options前缀属性支持运行时覆盖

---

运行时选项

ZhiPuAiEmbeddingOptions 提供模型配置（如模型名称等），默认值可通过属性配置。运行时可通过 EmbeddingRequest 覆盖选项：

EmbeddingResponse response = embeddingModel.call(
    new EmbeddingRequest(List.of("文本1", "文本2"),
        ZhiPuAiEmbeddingOptions.builder()
            .model("自定义嵌入模型")
        .build()));

---

示例控制器

配置示例：

spring.ai.zhipuai.api-key=YOUR_API_KEY
spring.ai.zhipuai.embedding.options.model=embedding-2

控制器实现：

@RestController
public class EmbeddingController {
    private final EmbeddingModel embeddingModel;

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

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(defaultValue = "Tell me a joke") 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-zhipuai</artifactId>
  </dependency>

• Gradle：

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

实例化模型示例：

var api = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
var embeddingModel = new ZhiPuAiEmbeddingModel(api, MetadataMode.EMBED,
        ZhiPuAiEmbeddingOptions.builder()
            .model("embedding-3")
            .dimensions(1536)
            .build());

EmbeddingResponse response = embeddingModel.embedForResponse(
    List.of("文本A", "文本B"));

注：spring-ai-zhipuai 依赖同时包含对话模型支持，详见智谱AI对话客户端章节。