智谱 AI 聊天

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

前提条件

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

在 智谱 AI 注册页面 创建账户，并在 API 密钥页面 生成令牌。Spring AI 项目定义了一个名为 spring.ai.zhipuai.api-key 的配置属性，您应该将其设置为从 API 密钥页面 获取的 API Key 值。导出环境变量是设置该配置属性的一种方法

export SPRING_AI_ZHIPU_AI_API_KEY=<INSERT KEY HERE>

添加仓库和 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 密钥

-

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

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

-

spring.ai.zhipuai.chat.options.temperature

要使用的采样温度，介于 0 和 1 之间。较高的值（如 0.8）会使输出更随机，而较低的值（如 0.2）会使其更集中和确定。我们通常建议只调整此参数或 top_p，但不要同时调整两者。

0.7

spring.ai.zhipuai.chat.options.topP

一种替代温度采样的技术，称为 nucleus 采样，模型考虑 top_p 概率质量的 token 结果。因此，0.1 表示只考虑概率质量在前 10% 的 token。我们通常建议只调整此参数或 temperature，但不要同时调整两者。

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 外，您还可以使用通过 ChatOptionsBuilder#builder() 创建的可移植 ChatOptions 实例。

示例控制器

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

在 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，并使用 低级 ZhiPuAiApi 客户端 连接到智谱 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 添加到您的构建文件中。

接下来，创建一个 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."));

// Or with streaming responses
Flux<ChatResponse> streamResponse = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

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

低级 ZhiPuAiApi 客户端

ZhiPuAiApi 是用于 智谱 AI API 的轻量级 Java 客户端。

以下是如何以编程方式使用此 API 的简单片段

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

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

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

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

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

ZhiPuAiApi 示例

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