SDK/Java SDK/快速开始
快速开始
更新于: 2026-06-24 15:45:09
AI 助手
扣子 AI 帮助与支持
你好，我是 扣子 文档问答助手 🎉
你在阅读当前文档的过程中，无论对文档概念的解释，还是文档内容方面的疑问，都可以随时向我提问，我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容？
有哪些近期更新的重点文档？
我应该从哪些文档开始阅读？
文档反馈
快速开始
本文档旨在帮助你快速集成扣子罗盘 Java SDK，实现从 SDK 初始化、Trace 数据上报到 Prompt 调用的完整流程。
环境准备
系统要求
在开始集成 SDK 前，请确保开发环境满足以下要求：
- Java Development Kit: 1.8 或更高版本。
- 构建工具: Maven 3.6 或更高版本。
鉴权配置
使用扣子罗盘 Java SDK 前需完成鉴权配置。详细说明请参考 SDK 鉴权。
SDK 支持以下两种鉴权方式：
方式一：Personal Access Token (PAT)
适用于本地开发与测试环境。通过环境变量配置：
export COZELOOP_WORKSPACE_ID="your_workspace_id"
export COZELOOP_API_TOKEN="your_pat_token"
- COZELOOP_WORKSPACE_ID: 目标工作空间 ID。
- COZELOOP_API_TOKEN: 个人访问令牌。
方式二：OAuth JWT (推荐)
适用于生产环境，提供更高的安全性。需配置以下环境变量：
export COZELOOP_WORKSPACE_ID="your_workspace_id"
export COZELOOP_JWT_OAUTH_CLIENT_ID="your_client_id"
export COZELOOP_JWT_OAUTH_PRIVATE_KEY="your_private_key"
export COZELOOP_JWT_OAUTH_PUBLIC_KEY_ID="your_public_key_id"
SDK 安装
根据项目类型选择对应的 Maven 依赖。
版本提示：下面示例代码中使用的 SDK 版本为 0.1.6。请查阅 Maven Central 获取最新版本号：https://mvnrepository.com/artifact/com.coze/cozeloop-java/versions。
标准 Java 项目
对于非 Spring Boot 项目，引入 cozeloop-core：
<dependency>
<groupId>com.coze</groupId>
<artifactId>cozeloop-core</artifactId>
<version>0.1.6</version>
</dependency>
Spring Boot 项目
推荐使用 Starter 简化配置：
<dependency>
<groupId>com.coze</groupId>
<artifactId>cozeloop-spring-boot-starter</artifactId>
<version>0.1.6</version>
</dependency>
初始化 SDK
非 Spring Boot 环境
使用 CozeLoopClientBuilder 构建实例。若已配置环境变量，无需手动传入凭证。
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;
public class Application {
public static void main(String[] args) {
// 推荐：使用 try-with-resources 自动关闭 client，确保 Trace 数据完整上报
try (CozeLoopClient client = new CozeLoopClientBuilder()
.serviceName("my-java-app") // 设置当前服务名称，便于在平台区分数据来源
.build()) {
System.out.println("SDK 初始化成功");
// 执行业务逻辑...
} catch (Exception e) {
e.printStackTrace();
}
}
}
Spring Boot 环境
使用 cozeloop-spring-boot-starter 时，SDK 将自动注入 CozeLoopClient Bean。
- 启用自动配置
在启动类添加 @Import(CozeLoopAutoConfiguration.class) 注解。
import com.coze.loop.spring.autoconfigure.CozeLoopAutoConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;
@SpringBootApplication
@Import(CozeLoopAutoConfiguration.class)
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
- 配置文件设置 (可选)
在 application.yml 中配置服务名称等信息。
cozeloop:
# (可选) 如果未设置环境变量，可在此处指定
# workspace-id: your_workspace_id
# auth:
# token: your_pat_token # pat token 和 jwt 二选一即可
# jwt:
# clientId: your_client_id
# privateKey: your_private_key
# publicKeyId: your_public_key
service-name: my-spring-boot-app
trace:
enabled: true
Trace 上报
通过 Span 追踪代码执行链路，上报数据至扣子罗盘，实现全链路可观测性。
最佳实践：始终使用 try-with-resources 管理 Span，确保在异常发生时 Span 也能正确关闭并上报。
上报 Root Span
Root Span 是调用链路的起点，通常对应一个完整的请求处理过程。
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.trace.CozeLoopSpan;
import com.coze.loop.client.CozeLoopClientBuilder;
// client 初始化
CozeLoopClient client = new CozeLoopClientBuilder().build();
try (CozeLoopSpan rootSpan = client.startSpan("process_user_request", "custom")) {
rootSpan.setTag("user.id", "user-123");
rootSpan.setInput("User query: tell me a joke");
// 执行业务逻辑...
rootSpan.setOutput("Why don't scientists trust atoms? Because they make up everything!");
rootSpan.setStatusCode(0); // 0: 成功, 1: 失败
} catch (Exception e) {
// 异常会自动被 SDK 捕获并记录
}
上报自定义 Span
在 Root Span 内部创建子 Span，用于追踪细粒度的操作（如数据库查询、外部 API 调用）。
try (CozeLoopSpan rootSpan = client.startSpan("main_process", "custom")) {
// 创建子 Span，自动关联父级 Span
try (CozeLoopSpan childSpan = client.startSpan("database_query", "db")) {
childSpan.setTag("db.statement", "SELECT * FROM users;");
// 执行数据库查询...
}
}
上报 Model Span
调用 LLM 时，使用 model 类型的 Span 记录输入输出和 Token 消耗。
import com.coze.loop.spec.tracespec.*;
import java.util.Collections;
try (CozeLoopSpan modelSpan = client.startSpan("llm_call_openai", "model")) {
// 1. 设置输入与元数据
ModelInput input = new ModelInput();
input.setMessages(Collections.singletonList(new ModelMessage("user", "上海天气")));
modelSpan.setInput(input);
modelSpan.setModelProvider("openai");
modelSpan.setModelName("gpt-4");
// 2. 执行 LLM 调用 (伪代码)
// Response resp = openAiClient.chat(...)
// 3. 记录输出与 Token
ModelOutput output = new ModelOutput();
output.setChoices(Collections.singletonList(
new ModelChoice(new ModelMessage("assistant", "晴，28度"), "stop", 0L)
));
modelSpan.setOutput(output);
modelSpan.setInputTokens(10);
modelSpan.setOutputTokens(20);
}
Prompt 管理与执行
使用 SDK 拉取并执行在扣子罗盘平台定义的 Prompt。
拉取并格式化 Prompt
在使用 SDK 拉取 Prompt 前，需要在扣子罗盘的 Prompt 开发页面获取 Prompt Key 和版本号。
动态填充 Prompt 变量，获取格式化后的消息内容。
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;
import com.coze.loop.entity.Message;
import com.coze.loop.entity.Prompt;
import com.coze.loop.prompt.GetPromptParam;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
CozeLoopClient client = new CozeLoopClientBuilder().build();
try {
// 1. 获取 Prompt 对象
Prompt prompt = client.getPrompt(
GetPromptParam.builder()
.promptKey("your_prompt_key")
.build()
);
if (prompt != null) {
// 2. 准备变量并格式化
Map variables = new HashMap<>();
variables.put("query", "什么是机器学习？");
List formattedMessages = client.formatPrompt(prompt, variables);
// 3. 使用格式化后的消息（如用于日志打印或调试）
formattedMessages.forEach(msg ->
System.out.println(msg.getRole() + ": " + msg.getContent())
);
}
} catch (Exception e) {
e.printStackTrace();
}
执行 Prompt
直接调用 SDK 执行 Prompt，支持流式与非流式。流式调用的详情请参阅 调用 Prompt。
// 非流式调用示例
try (CozeLoopClient client = new CozeLoopClientBuilder().build()) {
Map variables = new HashMap<>();
variables.put("query", "你好");
ExecuteParam param = ExecuteParam.builder()
.promptKey("yourPromptKey")
.variableVals(variables)
.build();
ExecuteResult result = client.execute(param);
if (result.getMessage() != null) {
System.out.println(result.getMessage().getContent());
}
}
示例资源
更多完整示例代码，请访问 GitHub 仓库：