如何使用 Python 列出 Vertex AI Prompt 的可用版本？

作者：袖梨 2026-09-17

使用 Python 列出 Vertex AI Prompt 的可用版本，核心步骤是先取得稳定的 prompt_id，再调用 client.prompts.list_versions(prompt_id=...)。该方法返回可迭代的版本引用，每个引用包含 Prompt ID、Version ID 等定位信息；需要查看完整提示词内容时，再把这两个 ID 传给 get_version()。版本列表用于发现，精确读取用于使用，两者不要混成一次操作。

准备客户端与认证

运行代码前需要启用 Vertex AI API，并让当前身份拥有读取 Prompt 资源和版本的权限。开发机可使用 Application Default Credentials，云端工作负载应使用绑定到运行环境的服务账号。安装当前客户端：

python -m pip install --upgrade google-cloud-aiplatform

创建客户端时显式指定项目与区域。Prompt Management 的资源查询受项目和区域约束；同一个 Prompt ID 在错误区域中读取，可能表现为资源不存在，而不是返回空版本列表。

import vertexai

PROJECT_ID = "your-project-id"
LOCATION = "us-central1"
PROMPT_ID = "1234567890123456789"

client = vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)

PROMPT_ID 应来自创建 Prompt 时的返回值、受控配置或数据库记录，不应依赖显示名称猜测。显示名称适合给人阅读，资源 ID 才适合程序稳定定位。

列出指定 Prompt 的全部版本

list_versions() 返回迭代器。逐条处理适合版本较多或只需要流式输出的场景；转换为列表便于判空、计数和测试。

version_refs = list(
    client.prompts.list_versions(
        prompt_id=PROMPT_ID,
    )
)

if not version_refs:
    raise RuntimeError(
        f"Prompt {PROMPT_ID} 没有可用版本"
    )

for ref in version_refs:
    print(
        "prompt_id=", ref.prompt_id,
        "version_id=", ref.version_id,
        "model=", ref.model,
    )

列表元素是轻量的版本引用，不等于完整 Prompt。它适合构建版本选择器、审计清单或回归测试输入，但不要假设其中包含完整的模板内容、系统指令和变量。需要这些字段时应进行精确回读。

读取一个具体版本

使用列表返回的 prompt_id 和 version_id 调用 get_version()。同时传入两个标识，可以避免错误地读取当前版本或另一个 Prompt 的同名版本。

selected_ref = version_refs[0]

selected_prompt = client.prompts.get_version(
    prompt_id=selected_ref.prompt_id,
    version_id=selected_ref.version_id,
)

assert selected_prompt.prompt_id == selected_ref.prompt_id
assert selected_prompt.version_id == selected_ref.version_id

print(selected_prompt.prompt_data.model)
print(selected_prompt.prompt_data.contents)

这两个断言不是多余的装饰。它们把“列表中选中的版本”和“实际回读的资源”绑定起来，能及早发现项目、区域、缓存键或参数拼接错误。

不要默认第一个元素就是最新版本

官方样例为了展示接口，直接读取列表中的第一个元素。生产代码不应在没有契约依据时把索引零解释为最新版本。服务端返回顺序可能随 API 实现、分页或筛选条件变化；Version ID 也不一定适合按字符串进行时间排序。

更稳妥的方式是由业务配置明确指定目标 Version ID。如果目标是部署“已批准版本”，配置表应保存 Prompt ID、Version ID、审批状态和发布时间；应用读取明确版本，而不是每次启动时猜测最新项。

APPROVED_VERSION_ID = "2"

matched = next(
    (
        ref for ref in version_refs
        if ref.version_id == APPROVED_VERSION_ID
    ),
    None,
)

if matched is None:
    raise RuntimeError(
        f"未找到已批准版本 {APPROVED_VERSION_ID}"
    )

approved_prompt = client.prompts.get_version(
    prompt_id=matched.prompt_id,
    version_id=matched.version_id,
)

如果团队确实需要“最新版本”，应先确认 API 是否提供明确的排序或过滤能力，再基于服务端定义实现。不能仅凭列表顺序或把 Version ID 强制转成整数排序，否则迁移或格式变化后容易选错。

封装成可复用的查询函数

将列表和精确读取封装起来，可以统一处理空集合、重复 ID 与错误上下文。下面的函数返回以 Version ID 为键的引用映射，并在发现异常数据时立即失败。

def list_prompt_versions(client, prompt_id: str):
    refs = list(
        client.prompts.list_versions(
            prompt_id=prompt_id,
        )
    )

    result = {}
    for ref in refs:
        if ref.prompt_id != prompt_id:
            raise RuntimeError(
                "版本引用属于其他 Prompt: "
                f"{ref.prompt_id}"
            )
        if not ref.version_id:
            raise RuntimeError("版本引用缺少 version_id")
        if ref.version_id in result:
            raise RuntimeError(
                f"出现重复版本: {ref.version_id}"
            )
        result[ref.version_id] = ref

    return result


versions_by_id = list_prompt_versions(
    client,
    PROMPT_ID,
)
print("版本数量:", len(versions_by_id))

这类校验尤其适合 CI 或发布流水线。与其在后续模型调用时报出模糊错误，不如在选择 Prompt 版本时就验证资源归属和标识完整性。

批量读取时控制请求数量

列出版本只需一次逻辑查询，但为每个引用调用 get_version() 会产生额外网络请求。构建审计页面时，如果只展示 Version ID 和模型信息，就直接使用引用数据；只有用户展开某个版本或后台确实需要检查模板内容时，才读取完整对象。

def get_prompt_version(client, prompt_id, version_id):
    versions = list_prompt_versions(client, prompt_id)
    if version_id not in versions:
        raise KeyError(
            f"Prompt {prompt_id} 不存在版本 {version_id}"
        )
    return client.prompts.get_version(
        prompt_id=prompt_id,
        version_id=version_id,
    )

可以按 Prompt ID 和 Version ID 缓存读取结果，但缓存键必须同时包含项目与区域。只用 Version ID 作为键可能把不同 Prompt 的版本混在一起。管理工具还应设置合理超时，并把权限错误、资源不存在和临时网络故障区分记录。

版本列表在发布流程中的用法

更新 Prompt 前先保存一次版本集合，更新后再次列出，然后计算 Version ID 差集，可以验证操作是否在原 Prompt 下生成了新版本：

before = {
    ref.version_id
    for ref in client.prompts.list_versions(
        prompt_id=PROMPT_ID,
    )
}

updated = client.prompts.update(
    prompt_id=PROMPT_ID,
    prompt={
        "prompt_data": {
            "model": "gemini-2.5-flash",
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {"text": "请总结以下内容：{text}"}
                    ],
                }
            ],
            "variables": [
                {"text": {"text": "示例文本"}}
            ],
        }
    },
)

after = {
    ref.version_id
    for ref in client.prompts.list_versions(
        prompt_id=PROMPT_ID,
    )
}

created_ids = after - before
assert updated.prompt_id == PROMPT_ID
assert updated.version_id in created_ids

这里同时验证 Prompt ID 不变、新 Version ID 出现在原资源的版本集合中。只检查返回对象不够，因为误用创建接口时可能得到一个看似正常的新对象，却已经属于新的 Prompt。

常见问题排查

返回空列表或找不到资源

先核对创建资源时的项目和区域，再核对当前认证身份。确认 Prompt ID 没有包含资源路径前缀、空格或展示名称。若 Prompt 是刚创建的，优先用创建返回的 ID 立即回读，不要从人工复制的控制台文本开始排查。

有列表但读取具体版本失败

确保调用的是 get_version()，并同时传入引用中的 Prompt ID 与 Version ID。不要把 Prompt 的当前版本读取接口与历史版本读取接口混用。还要检查版本是否已被删除，以及客户端项目和区域是否在两个调用之间发生变化。

旧示例中的接口名称不同

部分样例仍使用 vertexai.preview.prompts.list_versions() 和模块级 prompts.get()。当前新项目应优先使用 vertexai.Client 下的 client.prompts.list_versions() 与 client.prompts.get_version()。旧生成式 AI 模块已进入弃用和移除阶段，不宜作为新系统的长期依赖。