如何使用 Python 创建并保存 Vertex AI Prompt？

使用 Python 创建并保存 Vertex AI Prompt，当前更稳妥的做法是把提示词定义为结构化的 Prompt 对象，再调用 client.prompts.create_version()。这个方法会创建 Prompt 资源及其初始版本，返回值中的 prompt_id 和 version_id 是确认保存成功的关键。不要把“在内存中构造 Prompt”“调用模型生成内容”和“将 Prompt 持久化到 Prompt Management”混为一个动作。

准备环境与认证

代码需要 Google Cloud 项目、已启用的 Vertex AI API、可用的计费账号以及具备相应权限的身份。开发机推荐使用 Application Default Credentials；部署到 Cloud Run、GKE 或 Compute Engine 时，应让工作负载使用服务账号，不要把服务账号密钥写进源码。安装 Prompt Management 客户端和生成内容所需的 Gen AI SDK：

python -m pip install --upgrade google-cloud-aiplatform google-genai
gcloud auth application-default login

项目和区域应显式配置。Prompt 是区域资源，创建、读取和后续更新应使用相同的项目与区域，否则常见现象是列表为空、读取返回未找到，或者开发者误以为保存失败。

创建结构化 Prompt

新版接口接受字典或 types.Prompt。字典写法依赖更少，也能清楚展示请求结构。下面的模板包含模型、用户内容、系统指令和变量值。模板中的 {topic} 是占位符，变量集合提供一次可组装的实际输入。

import vertexai

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

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

prompt = {
    "prompt_data": {
        "model": "gemini-2.5-flash",
        "contents": [
            {
                "role": "user",
                "parts": [
                    {"text": "请用三个要点解释 {topic}。"}
                ],
            }
        ],
        "system_instruction": {
            "parts": [
                {"text": "你是面向开发者的技术编辑，回答要准确简洁。"}
            ]
        },
        "variables": [
            {"topic": {"text": "向量检索"}}
        ],
    }
}

contents 保存提示词主体，system_instruction 保存稳定的角色和输出约束，variables 保存一组用于组装模板的值。变量名必须和花括号中的名称一致。生产代码应把模板结构放在版本控制中，把真实用户输入在调用时注入，避免把敏感数据作为示例变量永久保存。

保存初始版本

如果希望从第一天起就拥有可追踪的版本资源，应直接调用 create_version()。当前 API 文档明确推荐这个入口；单独的 create() 只创建 Prompt，不创建版本化资源。

saved_prompt = client.prompts.create_version(prompt=prompt)

print("prompt_id:", saved_prompt.prompt_id)
print("version_id:", saved_prompt.version_id)

不传 prompt_id 表示创建一个全新的 Prompt，并为它生成初始版本。成功返回并不只是得到一个本地对象：服务端已经分配 Prompt ID 和 Version ID。应用应把这两个标识写入自己的配置或数据库，但不要只记录显示名称，因为显示名称不适合作为稳定的资源主键。

回读并验证保存结果

可靠的验证不应依赖控制台页面是否立即刷新，而应使用返回的 ID 调用读取和版本列表接口。先读取 Prompt，再确认版本集合中包含刚创建的版本：

retrieved = client.prompts.get(
    prompt_id=saved_prompt.prompt_id,
)

versions = list(
    client.prompts.list_versions(
        prompt_id=saved_prompt.prompt_id,
    )
)

assert retrieved.prompt_id == saved_prompt.prompt_id
assert any(
    item.version_id == saved_prompt.version_id
    for item in versions
)

print("已保存版本数:", len(versions))

这组断言同时验证了资源归属和版本归属。如果只打印对象而不保存 ID，后续任务很难判断自己是在更新原资源，还是意外创建了另一个 Prompt。列表操作返回迭代器，转换为列表适合小规模验证；Prompt 很多时应按客户端提供的分页和过滤能力处理。

用已保存 Prompt 生成内容

Prompt Management 负责保存和版本管理，真正调用 Gemini 时使用 Google Gen AI SDK。读取到的 Prompt 对象可以通过 assemble_contents() 展开变量，然后把模型名和组装后的内容交给 Gen AI 客户端。

from google import genai

genai_client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location=LOCATION,
)

response = genai_client.models.generate_content(
    model=retrieved.prompt_data.model,
    contents=retrieved.assemble_contents(),
)

print(response.text)

把保存与推理解耦有两个好处：保存操作不会因为模型输出波动而难以判断是否成功，推理服务也可以在运行时选择某个已验证版本。上线系统通常应在配置中固定 prompt_id 与 version_id，而不是永远读取“最新版本”，这样回滚和复现实验结果更容易。

后续修改应使用 update

首次保存和修改既有资源的语义不同。首次调用 create_version() 时不传 Prompt ID，会创建新 Prompt 和初始版本；修改既有 Prompt 时，应显式调用 update() 并提供原来的 prompt_id。当前接口会为该 Prompt 创建新版本。

updated_prompt_data = {
    "prompt_data": {
        **prompt["prompt_data"],
        "contents": [
            {
                "role": "user",
                "parts": [
                    {"text": "请用五个要点解释 {topic}，并给出一个代码示例。"}
                ],
            }
        ],
    }
}

new_version = client.prompts.update(
    prompt_id=saved_prompt.prompt_id,
    prompt=updated_prompt_data,
)

assert new_version.prompt_id == saved_prompt.prompt_id
assert new_version.version_id != saved_prompt.version_id

这两个断言表达了版本更新的契约：Prompt ID 保持不变，Version ID 发生变化。如果调用更新后 Prompt ID 也变化，应立即停止发布流程，检查是否误用了创建接口、错误项目或错误区域。

旧 preview 示例为什么不宜直接复制

部分官方样例仍使用 vertexai.preview.prompts.Prompt、vertexai.init() 和模块级 prompts.create_version()。该样例能解释“构造、组装、生成、保存”的基本过程，但 Vertex AI SDK 的旧生成式 AI 模块已经进入弃用和移除阶段。新项目应优先采用 vertexai.Client 下的 Prompt Management 接口，并用 Google Gen AI SDK 发起模型调用。

不要为了让旧代码继续运行而固定一个过时依赖版本并长期使用。短期迁移时可以保留旧实现作为回归基线，但需要为新版路径补齐创建、读取、列出版本、生成内容和更新版本的集成测试。

常见错误与排查顺序

认证或权限失败

先确认 Application Default Credentials 对应的身份，再确认项目 ID、API 启用状态和 IAM 权限。命令行能登录不代表运行 Python 的容器或虚拟环境使用了同一身份。生产环境应检查服务账号绑定，而不是反复执行本地登录命令。

保存后列表中找不到 Prompt

优先比较创建和读取客户端的项目与区域。随后检查返回的 prompt_id，用该 ID 直接读取。不要先用名称模糊搜索，因为名称重复或区域不一致会掩盖真正问题。

变量无法组装

检查模板占位符与 variables 的键是否完全一致，并保证变量值使用 API 接受的 Part 结构。先用一组固定变量调用 assemble_contents()，确认组装结果，再进行模型调用，可以把模板错误与模型请求错误分开定位。

每次修改都出现新的 Prompt

这通常是把首次创建接口当成更新接口使用。持久化首次返回的 Prompt ID，后续修改调用 client.prompts.update(prompt_id=..., prompt=...)，然后通过版本列表确认新 Version ID 仍属于同一个 Prompt。

生产环境的最小验收标准

一套可交付的流程至少应验证五件事：创建返回非空 Prompt ID；创建返回非空 Version ID；按 Prompt ID 可以回读；版本列表包含刚创建的 Version ID；使用回读对象组装内容后可以完成一次受控的模型请求。更新测试还应断言 Prompt ID 不变且 Version ID 改变。

同时记录项目、区域、模型名、Prompt ID、Version ID 和应用发布版本。日志不应包含完整敏感提示词或用户数据。做到这些后，“创建并保存 Prompt”就不再只是一次成功的 SDK 调用，而是一条可验证、可回滚、可审计的版本化工作流。