|
此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3! |
智谱 AI 聊天
Spring AI 支持智谱 AI(ZhiPu AI)的多种大语言模型。您可以与智谱 AI 的大语言模型进行交互,并基于智谱 AI 模型创建多语言对话助手。
如果您不是中文使用者,您可以访问智谱 AI 的国际站点 Z.ai
前置条件
您需要创建一个智谱 AI 的 API 以访问智谱大语言模型。
在 智谱 AI 注册页面(或 Z.ai 注册页面)创建账户,并在 API 密钥页面(或 Z.ai API 密钥页面)生成Tokens。
The Spring AI 项目定义了一个配置属性名为spring.ai.zhipuai.api-key,你应该将其设置为从API密钥页面获得的API Key的值。
您可以在您的application.properties文件中设置此配置属性:
spring.ai.zhipuai.api-key=<your-zhipuai-api-key>
处理敏感信息(如API密钥)时,为了增强安全性,您可以使用Spring表达式语言(SpEL)引用自定义环境变量:
# In application.yml
spring:
ai:
zhipuai:
api-key: ${ZHIPUAI_API_KEY}
# In your environment or .env file
export ZHIPUAI_API_KEY=<your-zhipuai-api-key>
您也可以在应用程序代码中通过编程方式设置此配置:
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("ZHIPUAI_API_KEY");
Auto-configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
Spring AI 为智谱 AI(ZhiPuAI)聊天客户端提供 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 聊天模型的重试机制。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
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 min. |
spring.ai.retry.on-client-errors |
如果为假,则抛出一个NonTransientAiException,并且不尝试重试 |
false |
spring.ai.retry.exclude-on-http-codes |
不应当触发重试的HTTP状态码列表(例如,抛出NonTransientAiException)。 |
<p>空内容</p> |
spring.ai.retry.on-http-codes |
应触发重试的HTTP状态码列表(例如,抛出TransientAiException)。 |
<p>空内容</p> |
连接属性
前缀 spring.ai.zhipuai 用作属性前缀,让您能够连接到智谱 AI(ZhiPuAI)。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.zhipuai.base-url |
连接至智谱 AI API 的 URL。 |
|
spring.ai.zhipuai.api-key |
API密钥 |
- |
配置属性
|
现在通过带有前缀 要启用,请设置 spring.ai.model.chat=zhipuai(默认已启用) 要禁用,请设置 spring.ai.model.chat=none(或任何不匹配 zhipuai 的值) 此更改是为了允许配置多个模型。 |
前缀 spring.ai.zhipuai.chat 是属性前缀,用于配置智谱 AI(ZhiPuAI)的聊天模型实现。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.zhipuai.chat.enabled(已移除且不再生效) |
启用智谱 AI 聊天模型。 |
true |
spring.ai.model.chat |
启用智谱 AI 聊天模型。 |
语雀 AI |
spring.ai.zhipuai.chat.base-url |
可选地覆盖 spring.ai.zhipuai.base-url 以提供特定于聊天的 URL。 |
|
spring.ai.zhipuai.chat.api-key |
可选地覆盖 spring.ai.zhipuai.api-key 以提供特定于聊天的 API 密钥。 |
- |
spring.ai.zhipuai.chat.options.model |
这是要使用的智谱 AI 聊天模型。您可以在以下模型之间进行选择: |
|
spring.ai.zhipuai.chat.options.maxTokens |
生成聊天补全时的最大token数。输入token和生成token的总长度受限于模型的上下文长度。 |
- |
spring.ai.zhipuai.chat.options.temperature |
要使用的采样温度,范围在 0 到 1 之间。较高的值(如 0.8)会使输出更随机,而较低的值(如 0.2)会使输出更集中且确定性更强。我们通常建议调整此参数或 top_p,但不要同时调整两者。 |
- |
spring.ai.zhipuai.chat.options.topP |
一种替代温度采样的方法,称为核采样(nucleus sampling),其中模型仅考虑累积概率达到 top_p 的Tokens结果。例如,0.1 表示只考虑累积概率前 10% 的Tokens。我们通常建议调整此参数或温度参数,但不要同时调整两者。 |
1.0 |
spring.ai.zhipuai.chat.options.stop |
该模型会在生成指定的停止字符时停止,目前仅支持格式为<code>[ |
- |
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.response-format.type |
控制模型输出的格式。设置为 |
- |
spring.ai.zhipuai.chat.options.thinking.type |
控制是否启用大模型的思维链。可用选项: |
- |
spring.ai.zhipuai.chat.options.tool-names |
使用名称标识的工具列表,以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。 |
- |
spring.ai.zhipuai.chat.options.tool-callbacks |
使用回调注册与ChatModel相关的工具。 |
- |
spring.ai.zhipuai.chat.options.internal-tool-execution-enabled |
如果为假,Spring AI 将不会内部处理工具调用,而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数,并返回结果。如果为真(默认值),Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。 |
true |
您可以为 ChatModel 实现覆盖通用的 spring.ai.zhipuai.base-url 和 spring.ai.zhipuai.api-key。
如果设置了 spring.ai.zhipuai.chat.base-url 和 spring.ai.zhipuai.chat.api-key 属性,它们的优先级将高于通用属性。
如果您希望针对不同的模型和不同的模型端点使用不同的智谱 AI(ZhiPuAI)账户,这将非常有用。 |
所有以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_4_Air.getValue())
.temperature(0.5)
.build()
));
| 除了模型特定的 ZhiPuAiChatOptions 之外,您还可以使用通过 ChatOptions#builder() 创建的可移植 ChatOptions 实例。 |
样本控制器
创建一个新的Spring Boot项目,并在pom(或gradle)依赖中添加spring-ai-starter-model-zhipuai。
在 src/main/resources 目录下添加一个 application.properties 文件,以启用并配置智谱 AI(ZhiPuAi)聊天模型:
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(value = "/ai/generateStream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
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_4_Air.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."));
The ZhiPuAiChatOptions 提供了聊天请求的配置信息。
The 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_4_Air.getValue(), 0.7, false));
// Streaming request
Flux<ChatCompletionChunk> streamResponse = this.zhiPuAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_4_Air.getValue(), 0.7, true));
请查阅 ZhiPuAiApi.java 的 JavaDoc 以获取更多信息。
ZhiPuAiApi 示例
-
ZhiPuAiApiIT.java 测试提供了一些如何使用该轻量级库的通用示例。