智谱 AI 聊天

Spring AI 支持智谱 AI 的各种 AI 语言模型。您可以使用智谱 AI 语言模型进行交互，并基于智谱 AI 模型创建多语言对话助手。

前提条件

您需要创建智谱 AI 的 API 来访问智谱 AI 语言模型。

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

Spring AI 项目定义了一个名为 spring.ai.zhipuai.api-key 的配置属性，您应该将其设置为从 API Keys 页面获取的 API Key 值。

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

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

为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言（SpEL）引用自定义环境变量：

# 在 application.yml 中
spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY}
# 在您的环境或 .env 文件中
export ZHIPUAI_API_KEY=<your-zhipuai-api-key>

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

// 从安全源或环境变量获取 API 密钥
String apiKey = System.getenv("ZHIPUAI_API_KEY");

添加仓库和 BOM

Spring AI 构件发布在 Maven Central 和 Spring Snapshot 仓库中。 请参阅 构件仓库 部分，将这些仓库添加到您的构建系统中。

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

自动配置

Spring AI 自动配置和启动器模块的构件名称发生了重大变化。 请参阅 升级说明 了解更多信息。

Spring AI 为智谱 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 秒

spring.ai.retry.backoff.multiplier

退避间隔乘数。

5

spring.ai.retry.backoff.max-interval

最大退避持续时间。

3 分钟

spring.ai.retry.on-client-errors

如果为 false，则抛出 NonTransientAiException，并且不对 4xx 客户端错误代码进行重试

false

spring.ai.retry.exclude-on-http-codes

不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。

空

spring.ai.retry.on-http-codes

应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。

空

连接属性

前缀 spring.ai.zhiPu 用作连接到智谱 AI 的属性前缀。

属性 描述 默认值

spring.ai.zhipuai.base-url

连接 URL

open.bigmodel.cn/api/paas

spring.ai.zhipuai.api-key

API 密钥

-

配置属性

聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶级属性进行配置。

要启用，spring.ai.model.chat=zhipuai（默认启用）

要禁用，spring.ai.model.chat=none（或任何不匹配 zhipuai 的值）

此更改是为了允许多个模型的配置。

前缀 spring.ai.zhipuai.chat 是用于配置智谱 AI 聊天实现的属性前缀。

属性 描述 默认值

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

启用智谱 AI 聊天模型。

true

spring.ai.model.chat

启用智谱 AI 聊天模型。

zhipuai

spring.ai.zhipuai.chat.base-url

可选，覆盖 spring.ai.zhipuai.base-url 以提供聊天特定的 url

open.bigmodel.cn/api/paas

spring.ai.zhipuai.chat.api-key

可选，覆盖 spring.ai.zhipuai.api-key 以提供聊天特定的 api-key

-

spring.ai.zhipuai.chat.options.model

这是要使用的智谱 AI 聊天模型

GLM-3-Turbo（GLM-3-Turbo、GLM-4、GLM-4-Air、GLM-4-AirX、GLM-4-Flash 和 GLM-4V 指向最新的模型版本）

spring.ai.zhipuai.chat.options.maxTokens

在聊天完成中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。

-

spring.ai.zhipuai.chat.options.temperature

使用什么采样温度，在 0 到 1 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定性。我们通常建议更改此值或 top_p，但不要同时更改两者。

0.7

spring.ai.zhipuai.chat.options.topP

温度采样的替代方案，称为核采样，其中模型考虑具有 top_p 概率质量的标记结果。因此 0.1 意味着只考虑构成前 10% 概率质量的标记。我们通常建议更改此值或温度，但不要同时更改两者。

1.0

spring.ai.zhipuai.chat.options.stop

模型将停止生成由 stop 指定的字符，目前仅支持单个停止词，格式为 ["stop_word1"]

-

spring.ai.zhipuai.chat.options.user

代表您的最终用户的唯一标识符，可以帮助智谱 AI 监控和检测滥用。

-

spring.ai.zhipuai.chat.options.requestId

该参数由客户端传递，必须确保唯一性。它用于区分每个请求的唯一标识符。如果客户端未提供，平台将默认生成。

-

spring.ai.zhipuai.chat.options.doSample

当 do_sample 设置为 true 时，启用采样策略。如果 do_sample 为 false，则采样策略参数 temperature 和 top_p 将不会生效。

true

spring.ai.zhipuai.chat.options.proxy-tool-calls

如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理给客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于支持函数调用的聊天模型

false

注意：您可以覆盖 ChatModel 实现的通用 spring.ai.zhipuai.base-url 和 spring.ai.zhipuai.api-key。 如果设置了 spring.ai.zhipuai.chat.base-url 和 spring.ai.zhipuai.chat.api-key 属性，它们将优先于通用属性。 如果您想为不同的模型和不同的模型端点使用不同的智谱 AI 账户，这很有用。

提示：所有以 spring.ai.zhipuai.chat.options 为前缀的属性都可以通过在 Prompt 调用中添加请求特定的 运行时选项 在运行时被覆盖。

运行时选项

ZhiPuAiChatOptions.java 提供模型配置，如要使用的模型、温度、频率惩罚等。

在启动时，默认选项可以通过 ZhiPuAiChatModel(api, options) 构造函数或 spring.ai.zhipuai.chat.options.* 属性进行配置。

在运行时，您可以通过在 Prompt 调用中添加新的、请求特定的选项来覆盖默认选项。 例如，要覆盖特定请求的默认模型和温度：

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        ZhiPuAiChatOptions.builder()
            .model(ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue())
            .temperature(0.5)
        .build()
    ));

提示：除了模型特定的 ZhiPuAiChatOptions 外，您还可以使用可移植的 ChatOptions 实例，使用 ChatOptionsBuilder#builder() 创建。

示例控制器

创建 一个新的 Spring Boot 项目，并在您的 pom（或 gradle）依赖项中添加 spring-ai-starter-model-zhipuai。

在 src/main/resources 目录下添加 application.properties 文件，以启用和配置智谱 AI 聊天模型：

spring.ai.zhipuai.api-key=YOUR_API_KEY
spring.ai.zhipuai.chat.options.model=glm-4-air
spring.ai.zhipuai.chat.options.temperature=0.7

提示：将 api-key 替换为您的智谱 AI 凭据。

这将创建一个 ZhiPuAiChatModel 实现，您可以将其注入到您的类中。 以下是一个使用聊天模型进行文本生成的简单 @Controller 类示例。

@RestController
public class ChatController {

    private final ZhiPuAiChatModel chatModel;

    @Autowired
    public ChatController(ZhiPuAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        var prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

手动配置

ZhiPuAiChatModel 实现了 ChatModel 和 StreamingChatModel，并使用 低级智谱 AI API 客户端 连接到智谱 AI 服务。

在项目的 Maven pom.xml 文件中添加 spring-ai-zhipuai 依赖：

<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 添加到您的构建文件中。

接下来，创建 ZhiPuAiChatModel 并使用它进行文本生成：

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

var chatModel = new ZhiPuAiChatModel(this.zhiPuAiApi, ZhiPuAiChatOptions.builder()
                .model(ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue())
                .temperature(0.4)
                .maxTokens(200)
                .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// 或者使用流式响应
Flux<ChatResponse> streamResponse = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

ZhiPuAiChatOptions 提供聊天请求的配置信息。 ZhiPuAiChatOptions.Builder 是流畅的选项构建器。

低级智谱 AI API 客户端

ZhiPuAiApi 提供了 智谱 AI API 的轻量级 Java 客户端。

以下是一个简单的代码片段，展示如何以编程方式使用 API：

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

ChatCompletionMessage chatCompletionMessage =
    new ChatCompletionMessage("Hello world", Role.USER);

// 同步请求
ResponseEntity<ChatCompletion> response = this.zhiPuAiApi.chatCompletionEntity(
    new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue(), 0.7, false));

// 流式请求
Flux<ChatCompletionChunk> streamResponse = this.zhiPuAiApi.chatCompletionStream(
        new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue(), 0.7, true));

请参阅 ZhiPuAiApi.java 的 JavaDoc 获取更多信息。

智谱 AI API 示例

  • ZhiPuAiApiIT.java 测试提供了一些关于如何使用轻量级库的一般示例。