369 lines
9.8 KiB
Markdown
369 lines
9.8 KiB
Markdown
# Z.ai Open Platform Java SDK
|
||
|
||
[](https://search.maven.org/artifact/ai.z.openapi/zai-sdk)
|
||
[](LICENSE)
|
||
[](https://www.oracle.com/java/)
|
||
|
||
[English Readme](README.md)
|
||
|
||
Z.ai AI 平台官方 Java SDK，提供统一接口访问强大的AI能力，包括对话补全、向量嵌入、图像生成、音频处理等功能。
|
||
|
||
## ✨ 特性
|
||
|
||
- 🚀 **类型安全**: 所有接口完全类型封装，无需查阅API文档即可完成接入
|
||
- 🔧 **简单易用**: 简洁直观的API设计，快速上手
|
||
- ⚡ **高性能**: 基于现代Java库构建，性能优异
|
||
- 🛡️ **安全可靠**: 内置身份验证和令牌管理
|
||
- 📦 **轻量级**: 最小化依赖，易于项目集成
|
||
|
||
## 📦 安装
|
||
|
||
### 环境要求
|
||
- Java 1.8 或更高版本
|
||
- Maven 或 Gradle
|
||
- 尚不支持在 Android 平台运行
|
||
|
||
### Maven 依赖
|
||
在您的 `pom.xml` 中添加以下依赖：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>ai.z.openapi</groupId>
|
||
<artifactId>zai-sdk</artifactId>
|
||
<version>0.3.3</version>
|
||
</dependency>
|
||
```
|
||
|
||
### Gradle 依赖
|
||
在您的 `build.gradle` 中添加以下依赖（适用于 Groovy DSL）：
|
||
|
||
```groovy
|
||
dependencies {
|
||
implementation 'ai.z.openapi:zai-sdk:0.3.3'
|
||
}
|
||
```
|
||
|
||
### 📋 核心依赖
|
||
|
||
本SDK使用以下核心依赖库：
|
||
|
||
| Library | Version |
|
||
|-----------|---------|
|
||
| OkHttp3 | 3.14.9 |
|
||
| Java JWT | 4.2.2 |
|
||
| Jackson | 2.19.0 |
|
||
| Retrofit2 | 2.12.0 |
|
||
| RxJava3 | 3.1.10 |
|
||
| SLF4J | 2.0.17 |
|
||
|
||
## 🚀 快速开始
|
||
|
||
**智谱AI API 地址 https://open.bigmodel.cn/api/paas/v4/**
|
||
|
||
**Z.ai API 地址 https://api.z.ai/api/paas/v4/**
|
||
|
||
### 基本用法
|
||
|
||
1. **使用API凭证创建ZaiClient**
|
||
2. **通过客户端访问服务**
|
||
3. **使用类型化参数调用API方法**
|
||
|
||
```java
|
||
import ai.z.openapi.ZaiClient;
|
||
import ai.z.openapi.ZhipuAiClient;
|
||
import ai.z.openapi.service.model.*;
|
||
import ai.z.openapi.core.Constants;
|
||
|
||
// 创建客户端 推荐使用环境变量设置API凭证
|
||
// export ZAI_API_KEY=your.api.key
|
||
|
||
// 使用 Z.ai 平台客户端 https://api.z.ai/api/paas/v4/
|
||
ZaiClient client = ZaiClient.builder().ofZAI().build();
|
||
|
||
// 使用 智谱 AI 平台客户端 https://open.bigmodel.cn/api/paas/v4/
|
||
ZhipuAiClient zhipuClient = ZhipuAiClient.builder().ofZHIPU().build();
|
||
|
||
// 或代码设置凭证
|
||
ZaiClient client = ZaiClient.builder()
|
||
.ofZAI()
|
||
.apiKey("your.api.key")
|
||
.build();
|
||
|
||
// 或为智谱AI平台 bigmodel.cn 创建客户端
|
||
ZhipuAiClient zhipuClient = ZhipuAiClient.builder().ofZHIPU().apiKey("your.api.key").build();
|
||
```
|
||
|
||
### 客户端配置
|
||
|
||
SDK提供了灵活的构建器模式来自定义您的客户端：
|
||
|
||
```java
|
||
ZaiClient client = ZaiClient.builder()
|
||
.apiKey("your.api.key")
|
||
.baseUrl("https://api.z.ai/api/paas/v4/")
|
||
.enableTokenCache()
|
||
.tokenExpire(3600000) // 1小时
|
||
.connectionPool(10, 5, TimeUnit.MINUTES)
|
||
.build();
|
||
```
|
||
|
||
## 💡 使用示例
|
||
|
||
### 对话补全
|
||
|
||
```java
|
||
import ai.z.openapi.ZaiClient;
|
||
import ai.z.openapi.service.model.*;
|
||
import ai.z.openapi.core.Constants;
|
||
import java.util.Arrays;
|
||
|
||
// 创建客户端
|
||
ZaiClient client = ZaiClient.builder()
|
||
.ofZAI()
|
||
.apiKey("your.api.key")
|
||
.build();
|
||
|
||
// 创建对话请求
|
||
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
|
||
.model("glm-5")
|
||
.messages(Arrays.asList(
|
||
ChatMessage.builder()
|
||
.role(ChatMessageRole.USER.value())
|
||
.content("你好，你怎么样？")
|
||
.build()
|
||
))
|
||
.stream(false)
|
||
.temperature(1.0f)
|
||
.maxTokens(1024)
|
||
.build();
|
||
|
||
// 执行请求
|
||
ChatCompletionResponse response = client.chat().createChatCompletion(request);
|
||
|
||
if (response.isSuccess()) {
|
||
String content = response.getData().getChoices().get(0).getMessage().getContent().toString();
|
||
System.out.println("回复: " + content);
|
||
} else {
|
||
System.err.println("错误: " + response.getMsg());
|
||
}
|
||
```
|
||
|
||
### 流式对话
|
||
|
||
```java
|
||
// 创建流式请求
|
||
ChatCompletionCreateParams streamRequest = ChatCompletionCreateParams.builder()
|
||
.model("glm-5")
|
||
.messages(Arrays.asList(
|
||
ChatMessage.builder()
|
||
.role(ChatMessageRole.USER.value())
|
||
.content("给我讲个故事")
|
||
.build()
|
||
))
|
||
.stream(true) // 启用流式
|
||
.build();
|
||
|
||
// 执行流式请求
|
||
ChatCompletionResponse response = client.chat().createChatCompletion(streamRequest);
|
||
|
||
if (response.isSuccess() && response.getFlowable() != null) {
|
||
response.getFlowable().subscribe(
|
||
data -> {
|
||
// 处理流式数据块
|
||
if (data.getChoices() != null && !data.getChoices().isEmpty()) {
|
||
String content = data.getChoices().get(0).getDelta().getContent();
|
||
if (content != null) {
|
||
System.out.print(content);
|
||
}
|
||
}
|
||
},
|
||
error -> System.err.println("\n流式错误: " + error.getMessage()),
|
||
() -> System.out.println("\n流式完成")
|
||
);
|
||
}
|
||
```
|
||
|
||
### 函数调用
|
||
|
||
```java
|
||
// 定义函数
|
||
ChatTool weatherTool = ChatTool.builder()
|
||
.type(ChatToolType.FUNCTION.value())
|
||
.function(ChatFunction.builder()
|
||
.name("get_weather")
|
||
.description("获取指定地点的当前天气")
|
||
.parameters(ChatFunctionParameters.builder()
|
||
.type("object")
|
||
.properties(new HashMap<String, ChatFunctionParameterProperty>() {
|
||
{
|
||
put("location", ChatFunctionParameterProperty.builder()
|
||
.type("string")
|
||
.description("城市名称")
|
||
.build());
|
||
}
|
||
})
|
||
.required(Arrays.asList("location"))
|
||
.build())
|
||
.build())
|
||
.build();
|
||
|
||
// 创建带函数的请求
|
||
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
|
||
.model(Constants.ModelChatGLM4)
|
||
.messages(Arrays.asList(
|
||
ChatMessage.builder()
|
||
.role(ChatMessageRole.USER.value())
|
||
.content("北京的天气怎么样？")
|
||
.build()
|
||
))
|
||
.tools(Arrays.asList(weatherTool))
|
||
.toolChoice("auto")
|
||
.build();
|
||
|
||
ChatCompletionResponse response = client.chat().createChatCompletion(request);
|
||
```
|
||
|
||
### 向量嵌入
|
||
|
||
```java
|
||
import ai.z.openapi.service.embedding.*;
|
||
|
||
// 创建嵌入请求
|
||
EmbeddingCreateParams request = EmbeddingCreateParams.builder()
|
||
.model(Constants.ModelEmbedding3)
|
||
.input(Arrays.asList("你好世界", "你好吗？"))
|
||
.build();
|
||
|
||
// 执行请求
|
||
EmbeddingResponse response = client.embeddings().createEmbeddings(request);
|
||
|
||
if (response.isSuccess()) {
|
||
response.getData().getData().forEach(embedding -> {
|
||
System.out.println("嵌入向量: " + embedding.getEmbedding());
|
||
});
|
||
}
|
||
```
|
||
|
||
### 图像生成
|
||
|
||
```java
|
||
import ai.z.openapi.service.image.*;
|
||
|
||
// 创建图像生成请求
|
||
CreateImageRequest request = CreateImageRequest.builder()
|
||
.model(Constants.ModelCogView3Plus)
|
||
.prompt("山间美丽的日落")
|
||
.size("1024x1024")
|
||
.build();
|
||
|
||
// 执行请求
|
||
ImageResponse response = client.images().createImage(request);
|
||
|
||
if (response.isSuccess()) {
|
||
response.getData().getData().forEach(image -> {
|
||
System.out.println("图像URL: " + image.getUrl());
|
||
});
|
||
}
|
||
```
|
||
|
||
### Spring Boot 集成
|
||
|
||
```java
|
||
@RestController
|
||
public class AIController {
|
||
|
||
private final ZaiClient zaiClient;
|
||
|
||
public AIController() {
|
||
this.zaiClient = ZaiClient.builder()
|
||
.ofZAI()
|
||
.apiKey("your.api.key")
|
||
.enableTokenCache()
|
||
.build();
|
||
}
|
||
|
||
@PostMapping("/chat")
|
||
public ResponseEntity<String> chat(@RequestBody ChatRequest request) {
|
||
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
|
||
.model("glm-5")
|
||
.messages(Arrays.asList(
|
||
ChatMessage.builder()
|
||
.role(ChatMessageRole.USER.value())
|
||
.content(request.getMessage())
|
||
.build()
|
||
))
|
||
.build();
|
||
|
||
ChatCompletionResponse response = zaiClient.chat().createChatCompletion(params);
|
||
|
||
if (response.isSuccess()) {
|
||
String content = response.getData().getChoices().get(0).getMessage().getContent();
|
||
return ResponseEntity.ok(content);
|
||
} else {
|
||
return ResponseEntity.badRequest().body(response.getMsg());
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 可用服务
|
||
|
||
### Chat 服务
|
||
- 对话补全（同步/异步）
|
||
- 流式对话
|
||
- 函数调用
|
||
- 多模态对话（文本+图像）
|
||
|
||
### Embeddings 服务
|
||
- 文本向量化
|
||
- 批量嵌入
|
||
- 多种嵌入模型
|
||
|
||
### Images 服务
|
||
- 文本到图像生成
|
||
- 图像编辑
|
||
- 图像变体
|
||
|
||
### Audio 服务
|
||
- 语音转文本
|
||
- 文本转语音
|
||
- 语音翻译
|
||
|
||
### Files 服务
|
||
- 文件上传
|
||
- 文件管理
|
||
- 文件检索
|
||
|
||
### Assistants 服务
|
||
- AI助手创建
|
||
- 助手管理
|
||
- 对话线程
|
||
|
||
### Agents 服务
|
||
- 智能代理
|
||
- 工作流管理
|
||
- 任务执行
|
||
|
||
### Batch 服务
|
||
- 批量处理
|
||
- 异步任务
|
||
- 结果管理
|
||
|
||
## 📈 版本更新
|
||
|
||
详细的版本更新记录和历史信息，请查看 [Release-Note.md](Release-Note.md)。
|
||
|
||
## 📄 许可证
|
||
|
||
本项目基于 MIT 许可证开源 - 详情请查看 [LICENSE](LICENSE) 文件。
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献代码！请随时提交 Pull Request。
|
||
|
||
## 📞 支持
|
||
|
||
如有问题和技术支持:
|
||
- Visit [Z.ai Platform](https://z.ai/)
|
||
- Visit [ZHIPU AI Open Platform](http://open.bigmodel.cn/)
|
||
- Check our [Architecture Documentation](ARCHITECTURE.md)
|