智谱 AI 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

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

先决条件

你需要创建智谱 AI API 以访问其语言模型。

请前往 智谱AI注册页面 创建账户，并在 API密钥管理页面 生成访问令牌。

Spring AI 项目定义了名为 spring.ai.zhipu.api-key 的配置属性，需设置为从 API Key 页面获取的密钥值。

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

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

为提升 API 密钥等敏感信息的安全性，可使用 Spring 表达式语言 （SpEL） 引用环境变量：

# In application.yml
spring:
  ai:
    zhipu:
      api-key: ${ZHIPU_API_KEY}
# In your environment or .env file
export ZHIPU_API_KEY=<your-zhipu-api-key>

你也可以在应用代码中以编程方式配置：

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

添加仓库和 BOM

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 “Artifact 仓库” 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本。请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建系统。

自动配置

Spring AI 自动配置及 starter 模块的构件命名已发生重大变更，详情请参阅 升级说明文档。

Spring AI 为 Azure 智谱 AI 嵌入模型提供 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 文件中添加以下依赖：

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

或添加到你的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-zhipuai'
}
请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建文件。

嵌入配置

重试配置

前缀 spring.ai.retry 是用于配置智谱 AI 嵌入模型重试机制的属性前缀。

属性 说明 默认值

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.zhipuai 是用于连接智谱 AI 的属性前缀。

属性 说明 默认值

spring.ai.zhipuai.base-url

要连接到的 URL

open.bigmodel.cn/api/paas

spring.ai.zhipuai.api-key

API Key

-

配置属性

嵌入自动配置的启用与禁用现在通过顶级属性配置，前缀为 spring.ai.model.embedding。

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

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

此变更为支持多模型配置。

前缀 spring.ai.zhipuai.embedding 是用于配置智谱 AI 嵌入模型 （EmbeddingModel） 实现的属性前缀。

属性 说明 默认值

spring.ai.zhipuai.embedding.enabled （已移除且不再有效）

启用智谱AI 嵌入模型。

true

spring.ai.model.embedding

启用智谱AI 嵌入模型。

zhipuai

spring.ai.zhipuai.embedding.base-url

可选，覆盖 spring.ai.zhipuai.base-url 以指定嵌入专用 URL。

-

spring.ai.zhipuai.embedding.api-key

可选，覆盖 spring.ai.zhipuai.api-key 以提供 embedding 专用的 api-key

-

spring.ai.zhipuai.embedding.options.model

要使用的模型

embedding-2

spring.ai.zhipuai.embedding.options.dimensions

dimensions 的数量，当 model 为 embedding-3 时默认值为 2048

-
你可以覆盖通用的 spring.ai.zhipuai.base-url 和 spring.ai.zhipuai.api-key 以用于 ChatModel 和 EmbeddingModel 实现。如果设置了 spring.ai.zhipuai.embedding.base-url 和 spring.ai.zhipuai.embedding.api-key 属性，它们将优先于通用属性。同样地，如果设置了 spring.ai.zhipuai.chat.base-url 和 spring.ai.zhipuai.chat.api-key 属性，它们也将优先于通用属性。如果你希望为不同的 model 和不同的模型端点使用不同的智谱 AI 账户，这将非常有用。
所有以 spring.ai.zhipuai.embedding.options 为前缀的属性都可以在运行时通过向 EmbeddingRequest 调用添加特定请求的 运行时选项 来覆盖。

运行时选项

ZhiPuAiEmbeddingOptions.java 提供了智谱 AI 的配置项，例如要使用的模型等。

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

在启动时，使用 ZhiPuAiEmbeddingModel 构造函数来设置用于所有嵌入请求的默认选项。在运行时，你可以通过将 ZhiPuAiEmbeddingOptions 实例作为 EmbeddingRequest 的一部分来覆盖默认选项。

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

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

示例 Controller

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

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(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手动配置

如果你没有使用 Spring Boot，可以手动配置智谱 AI 嵌入模型。为此，请将 spring-ai-zhipuai 依赖添加到项目的 Maven pom.xml 文件中：

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

或添加到你的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-zhipuai'
}
请参考 “依赖管理” 部分将 Spring AI BOM 添加到你的构建文件中。
spring-ai-zhipuai 依赖也提供了对 ZhiPuAiChatModel 的访问权限。有关 ZhiPuAiChatModel 的更多信息，请参阅 “智谱 AI 聊天客户端” 部分。

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

var zhiPuAiApi = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));

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

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

ZhiPuAiEmbeddingOptions 为嵌入请求提供配置信息。该选项类提供了 builder() 方法，便于轻松创建配置选项。