> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

## 功能概述 {#bc92e216}
扣子罗盘 Java SDK 提供了调用扣子罗盘平台已发布 Prompt 的能力。你可以根据业务需求，选择以下两种调用模式：

* **非流式调用 (Non-Streaming)**：同步等待模型执行完成，一次性返回完整的响应结果。适用于对响应延迟不敏感或需要完整内容进行后续处理的场景。
* **流式调用 (Streaming)**：建立长连接，实时分段接收模型生成的响应内容。适用于聊天机器人、实时生成等需要快速反馈的交互式场景，能显著提升用户体验。

## 前置条件 {#f720d016}
在集成 Prompt 调用功能前，请确保满足以下条件：

* **SDK 集成**：项目已正确引入扣子罗盘 Java SDK 依赖。建议使用最新版本。
* **鉴权配置**：运行环境已配置必要的访问凭证：
   * `COZELOOP_WORKSPACE_ID`：目标工作空间 ID。
   * `COZELOOP_API_TOKEN`：拥有 `executePrompt` 权限的 API 令牌（PAT 或 OAuth Token）。
* **资源准备**：已在扣子罗盘平台完成 Prompt 的创建与调试，并至少提交了一个可用版本。请获取该 Prompt 的 **Prompt Key** 用于后续调用。

## 代码示例 {#2c8c54d2}
以下示例展示了如何在 Java 应用中通过 SDK 调用已发布的 Prompt。
### 非流式调用示例 {#fe5603fb}
使用 `client.execute(param)` 方法发起请求，该方法会阻塞直到模型生成结束，并返回包含完整结果的 `ExecuteResult` 对象。
```Java
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;
import com.coze.loop.entity.ExecuteParam;
import com.coze.loop.entity.ExecuteResult;

import java.util.HashMap;
import java.util.Map;

public class NonStreamingExecuteExample {

    public static void main(String[] args) {
        // 推荐使用 try-with-resources 模式，确保 client 在使用结束后自动关闭并释放资源
        try (CozeLoopClient client = new CozeLoopClientBuilder().build()) {
            
            // 1. 准备 Prompt 变量
            // 变量名需与平台 Prompt 中定义的变量保持一致
            Map variableVals = new HashMap<>();
            variableVals.put("topic", "人工智能");
            variableVals.put("user_request", "请解释一下什么是机器学习");

            // 2. 构建执行参数
            ExecuteParam param = ExecuteParam.builder()
                    .promptKey("your_prompt_key") // 必填：替换为实际的 Prompt Key
                    // .version("0.0.1") // 可选：指定具体版本号，不传默认使用最新发布版本
                    // .label("production") // 可选：通过环境标识指定版本（如 production/staging）
                    .variableVals(variableVals)
                    .build();

            // 3. 发起非流式调用
            System.out.println("正在进行非流式调用...");
            ExecuteResult result = client.execute(param);

            // 4. 处理响应结果
            if (result != null) {
                if (result.getMessage() != null) {
                    System.out.println("模型响应: " + result.getMessage().getContent());
                }
                System.out.println("结束原因: " + result.getFinishReason());
                
                // 打印 Token 消耗统计
                if (result.getUsage() != null) {
                    System.out.println("Token用量: " 
                        + "Prompt Tokens: " + result.getUsage().getPromptTokens()
                        + ", Completion Tokens: " + result.getUsage().getCompletionTokens());
                }
            }

        } catch (Exception e) {
            System.err.println("调用失败: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
```

### 流式调用示例 {#5d70b0dc}
使用 `client.executeStreaming(param)` 方法发起请求，返回 `StreamReader`。通过循环调用 `recv()` 方法逐块获取增量内容，直至返回 `null` 标识流结束。
```Java
import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.client.CozeLoopClientBuilder;
import com.coze.loop.entity.ExecuteParam;
import com.coze.loop.entity.ExecuteResult;
import com.coze.loop.stream.StreamReader;

import java.util.HashMap;
import java.util.Map;

public class StreamingExecuteExample {

    public static void main(String[] args) {
        // 使用 try-with-resources 自动管理客户端生命周期
        try (CozeLoopClient client = new CozeLoopClientBuilder().build()) {

            // 1. 构造执行参数
            Map variableVals = new HashMap<>();
            variableVals.put("topic", "人工智能");
            variableVals.put("user_request", "请解释一下什么是机器学习");

            ExecuteParam param = ExecuteParam.builder()
                    .promptKey("your_prompt_key") // 替换为你的 Prompt Key
                    .variableVals(variableVals)
                    .build();

            // 2. 发起流式调用
            System.out.println("正在进行流式调用...");
            // StreamReader 也支持 try-with-resources，确保流被正确关闭
            try (StreamReader streamReader = client.executeStreaming(param)) {
                ExecuteResult result;
                // 3. 循环接收数据块
                while ((result = streamReader.recv()) != null) {
                    // 实时打印增量内容
                    if (result.getMessage() != null && result.getMessage().getContent() != null) {
                        System.out.print(result.getMessage().getContent());
                    }
                    
                    // 处理流结束信号
                    if (result.getFinishReason() != null) {
                         System.out.println("\n结束原因: " + result.getFinishReason());
                    }
                    
                    // 统计信息通常在最后一个数据块中返回
                    if (result.getUsage() != null) {
                        System.out.println("Token用量: "
                            + "Prompt Tokens: " + result.getUsage().getPromptTokens()
                            + ", Completion Tokens: " + result.getUsage().getCompletionTokens());
                    }
                }
                System.out.println("\n流式调用结束。");
            }

        } catch (Exception e) {
            System.err.println("调用失败: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
```