助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容?
有哪些近期更新的重点文档?
我应该从哪些文档开始阅读?
文档反馈

通过版本标识拉取 Prompt 版本

更新于: 2026-06-24 15:45:09

功能概述

扣子罗盘 Java SDK 支持通过版本标识(label)来拉取和执行指定的 Prompt 版本。这一特性使得你能够灵活管理生产环境(production)、预发布环境(staging)等不同环境下的 Prompt 版本,实现平滑发布与回滚。

版本解析规则

在拉取或执行 Prompt 时,可以通过 versionlabel 参数指定目标版本。SDK 遵循以下优先级规则:

  • 显式指定 Version:如果参数中包含 version,SDK 将忽略 label,直接使用指定的版本号。
  • 仅指定 Label:如果未指定 version 但指定了 label,SDK 将解析该 label 当前指向的 Prompt 版本。
  • 默认行为:如果 versionlabel 均未指定,SDK 将默认拉取该 Prompt 的最新已发布版本

代码示例

说明

前置条件:运行以下示例前,请确保已初始化 CozeLoopClient 并正确配置了鉴权环境变量。

通过 Label 拉取 Prompt

适用于需要获取 Prompt 内容进行本地处理或查看的场景。

import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.entity.Prompt;
import com.coze.loop.prompt.GetPromptParam;

// ... 初始化 client

try {
    // 场景:拉取线上环境(production)对应的 Prompt 版本
    Prompt prompt = client.getPrompt(GetPromptParam.builder()
            .promptKey("your_prompt_key")
            .label("production")
            .build());

    System.out.println("当前 production 对应的版本: " + prompt.getVersion());

} catch (Exception e) {
    e.printStackTrace();
}

Version 优先级演示

当同时指定 versionlabel 时,version 具有最高优先级。
示例场景:假设 Prompt 的 production 标签指向 0.0.2 版本,但代码中显式指定了 0.0.1 版本。

Prompt prompt = client.getPrompt(GetPromptParam.builder()
        .promptKey("your_prompt_key")
        .version("0.0.1") // 显式指定版本,优先级最高
        .label("production")      // 此参数将被忽略
        .build());

// 输出结果为 "0.0.1"
System.out.println("实际拉取的版本: " + prompt.getVersion()); 

通过 Label 执行 Prompt

在执行 Prompt 时使用 label,可以确保应用始终使用特定环境配置的 Prompt 版本,无需修改代码即可实现版本切换。

import com.coze.loop.client.CozeLoopClient;
import com.coze.loop.entity.ExecuteParam;
import com.coze.loop.entity.ExecuteResult;
import java.util.HashMap;
import java.util.Map;

// ... 初始化 client

try {
    Map variables = new HashMap<>();
    variables.put("query", "介绍一下自己");

    // 构建执行参数,指定使用 "production" 环境版本
    ExecuteParam param = ExecuteParam.builder()
            .promptKey("your_prompt_key")
            .label("production") 
            .variableVals(variables)
            .build();

    ExecuteResult result = client.execute(param);

    System.out.println("执行结果: " + result.getMessage().getContent());

} catch (Exception e) {
    e.printStackTrace();
}