如何使用 Python 恢复指定的 Vertex AI Prompt 版本？

使用 Python 恢复指定的 Vertex AI Prompt 版本，应调用 client.prompts.restore_version(prompt_id=..., version_id=...)。恢复操作的语义不是删除较新的版本，也不是让旧 Version ID 重新成为当前指针，而是把指定历史版本的内容复制为一个新的最新版本。这样既保留完整历史，又能让后续读取当前 Prompt 时得到被恢复的内容。

恢复前先明确资源身份

恢复是会改变服务端状态的操作，必须同时使用 Prompt ID 和目标 Version ID。Prompt ID 标识哪一个提示词资源，Version ID 标识要恢复的历史快照。显示名称只能帮助人识别，不应作为自动化回滚的唯一条件。

import vertexai

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

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

项目和区域必须与 Prompt 创建时一致。若资源位于另一个区域，恢复调用可能返回未找到；这时不应尝试用同名 Prompt 新建替代品，否则会把一次配置错误扩大成资源分叉。

列出版本并确认目标存在

不要直接对人工输入的 Version ID 执行恢复。先列出该 Prompt 的版本引用，确认目标版本确实属于当前 Prompt，并保留恢复前的版本集合用于事后验证。

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

before_by_id = {
    ref.version_id: ref
    for ref in before_refs
}

if TARGET_VERSION_ID not in before_by_id:
    raise RuntimeError(
        f"Prompt {PROMPT_ID} 不存在版本 "
        f"{TARGET_VERSION_ID}"
    )

target_ref = before_by_id[TARGET_VERSION_ID]
assert target_ref.prompt_id == PROMPT_ID

如果版本列表为空，应先检查项目、区域、权限和 Prompt ID，而不是继续恢复。对于发布系统，目标 Version ID 应来自审批记录，并与变更单、测试结果和操作人绑定。

读取并检查目标版本

恢复前调用 get_version() 读取完整目标版本。至少检查模型、模板主体、系统指令和变量结构，确认它确实是准备恢复的内容。

target_prompt = client.prompts.get_version(
    prompt_id=PROMPT_ID,
    version_id=TARGET_VERSION_ID,
)

assert target_prompt.prompt_id == PROMPT_ID
assert target_prompt.version_id == TARGET_VERSION_ID

print("目标模型:", target_prompt.prompt_data.model)
print("目标内容:", target_prompt.prompt_data.contents)

生产环境不应把完整敏感提示词输出到普通日志。可以记录内容哈希、模型名、Prompt ID 和 Version ID，并在受控界面中展示脱敏差异。恢复前的人工确认应明确说明“将生成一个新的最新版本”，避免操作人误以为只是预览历史内容。

执行版本恢复

确认无误后调用 restore_version()。当前接口会返回恢复后的 Prompt 对象。返回对象应保持相同 Prompt ID，并获得一个新的 Version ID。

restored = client.prompts.restore_version(
    prompt_id=PROMPT_ID,
    version_id=TARGET_VERSION_ID,
)

if restored.prompt_id != PROMPT_ID:
    raise RuntimeError(
        "恢复结果属于另一个 Prompt，停止后续发布"
    )

if restored.version_id == TARGET_VERSION_ID:
    raise RuntimeError(
        "恢复未生成新的版本，需检查接口结果"
    )

print("恢复后的新版本:", restored.version_id)

这段代码不假设新版本编号一定是旧编号加一。Version ID 应当作为不透明字符串处理，不能用整数运算预测，也不能用字符串大小判断新旧。

验证恢复确实生成了最新版本

只看到调用成功还不够。恢复后重新列出版本，计算版本集合差集，并确认返回的新 Version ID 位于差集中：

before_ids = {
    ref.version_id for ref in before_refs
}

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

created_ids = after_ids - before_ids

assert restored.version_id in created_ids
assert TARGET_VERSION_ID in after_ids
assert before_ids.issubset(after_ids)

这三项断言分别证明：恢复产生了一个新版本；目标历史版本仍然存在；恢复没有删掉原有历史。它们比“版本数量增加一”更稳健，因为并发操作可能在同一时间窗口创建其他版本。

比较目标版本与恢复结果

恢复的目标是复制内容，而不是复用版本身份。应比较关键内容字段，同时明确忽略 Prompt ID、Version ID 和服务端时间等元数据。

restored_prompt = client.prompts.get_version(
    prompt_id=PROMPT_ID,
    version_id=restored.version_id,
)

assert (
    restored_prompt.prompt_data.model
    == target_prompt.prompt_data.model
)
assert (
    restored_prompt.prompt_data.contents
    == target_prompt.prompt_data.contents
)
assert (
    restored_prompt.prompt_data.system_instruction
    == target_prompt.prompt_data.system_instruction
)

如果 Prompt 还包含变量、生成配置、安全设置或工具配置，应将这些字段纳入比较。大型对象可以先规范化为稳定 JSON，再计算哈希；不要直接比较日志中的字符串表示，因为字段顺序和展示格式可能变化。

确认当前 Prompt 已指向恢复内容

官方恢复样例在操作后通过 Prompt ID 读取当前 Prompt。新版客户端可以调用 get()，再核对它的 Version ID 和内容：

current = client.prompts.get(
    prompt_id=PROMPT_ID,
)

assert current.prompt_id == PROMPT_ID
assert current.version_id == restored.version_id
assert (
    current.prompt_data.contents
    == target_prompt.prompt_data.contents
)

如果业务系统固定使用明确 Version ID，它不会因为恢复操作自动切换，仍需更新应用配置并走部署流程。如果业务系统总是读取当前 Prompt，恢复可能立即影响后续请求，因此应在低风险窗口执行，并提前准备监控和回退方案。

封装成受控回滚函数

将前置验证和后置断言封装到一个函数中，可以防止脚本只完成一半。下面的实现要求目标存在，并返回新生成的 Version ID：

def restore_prompt_version(
    client,
    prompt_id: str,
    target_version_id: str,
) -> str:
    before = list(
        client.prompts.list_versions(
            prompt_id=prompt_id,
        )
    )
    before_ids = {ref.version_id for ref in before}

    if target_version_id not in before_ids:
        raise ValueError(
            f"目标版本不存在: {target_version_id}"
        )

    result = client.prompts.restore_version(
        prompt_id=prompt_id,
        version_id=target_version_id,
    )

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

    if result.prompt_id != prompt_id:
        raise RuntimeError("恢复结果 Prompt ID 不一致")
    if result.version_id not in after_ids - before_ids:
        raise RuntimeError("未验证到恢复产生的新版本")

    return result.version_id

函数返回的新 Version ID 应写入审计记录。记录还应包括目标旧 Version ID、操作者、原因、变更单、项目、区域、开始时间、完成时间和验证结果。

并发更新与幂等性

恢复是写操作，不应假设天然幂等。脚本因网络超时而无法确定结果时，不能立刻重试，否则可能连续生成多个内容相同的新版本。应重新列出版本，通过操作前快照、内容哈希和审计标记确认是否已完成，再决定是否重试。

如果其他团队成员可能同时更新 Prompt，应在外部变更系统中加锁，或在恢复前后检查预期的当前 Version ID。发现并发新版本时，应停止自动切换，让操作者重新审查，而不是静默覆盖其他人的变更。

恢复失败后的处理

资源不存在

核对 Prompt ID、Version ID、项目和区域。不要用创建新 Prompt 作为自动兜底，因为新资源会获得不同 Prompt ID，现有应用仍然指向旧资源。

权限不足

确认运行身份既能读取版本，也能执行恢复写操作。读取成功不代表拥有恢复权限。生产环境应给自动化账号最小必要权限，并保留审计日志。

返回成功但应用行为未变化

检查应用是读取当前 Prompt，还是固定到某个 Version ID。若固定版本，需要显式更新配置。还要检查应用的项目、区域与缓存键，避免读取了另一个环境或旧缓存。

旧 preview 示例与当前接口不同

旧样例使用模块级 prompts.restore_version() 和 prompts.get()。新代码应优先使用 vertexai.Client 下的 client.prompts.restore_version()、get()、get_version() 与 list_versions()。不要在同一流程里混用两套对象模型。

生产恢复的验收清单

一次可审计的恢复至少要证明：目标版本在操作前存在；目标内容已被审查；恢复结果保持相同 Prompt ID；恢复生成新的 Version ID；原有版本没有消失；新版本内容与目标历史版本一致；当前 Prompt 或应用配置已按预期切换。

把恢复理解为“从历史快照创建新的当前版本”，而不是“把时间线倒回去”，就能正确设计验证、并发控制和回退流程。这样既保留完整版本历史，也能在提示词变更导致质量下降时快速、安全地恢复服务。