提示管理

本页介绍了如何使用 Vertex AI SDK 提示管理模块，在 Google Cloud 项目中定义、保存、检索和管理提示。

概览

Vertex AI 提供了一些工具来帮助管理提示模板和提示数据。提示模板可以进行版本控制，并与 Vertex AI 上的生成式模型搭配使用。每个提示都可以在 Vertex AI Studio 或 Vertex AI SDK 中组装和版本化。

Vertex AI SDK 中的提示管理功能提供全面的企业支持，包括对客户管理的加密密钥 (CMEK) 和 VPC Service Controls (VPCSC) 的支持。

提示管理功能

如需使用 Vertex AI SDK 中的任何生成式 AI 功能，请执行以下操作：

安装最新版本的 Vertex AI SDK。

pip install --upgrade google-cloud-aiplatform

使用以下 Python 代码示例创建生成式 AI 客户端：

    import vertexai
    from vertexai import types

    # Instantiate GenAI client from Vertex SDK
    # Replace with your project ID and location
    client = vertexai.Client(project='my-project', location='my-location')

创建生成式 AI 客户端后，您可以使用 Vertex AI SDK 中的以下任何提示管理功能：

创建本地提示。
将提示保存到 Google Cloud 项目。
获取已保存的提示。
列出提示和版本。
删除提示。
恢复提示版本。

创建本地提示

本部分提供了一个示例，说明如何定义 types.Prompt 变量以供本页各处使用。

Prompt 类用于定义、组装和使用提示。prompt_data 属性是为 Prompt 类定义的，包含以下内容：

属性
`model`	必需：模型名称。
`contents`	必需：与模型对话的内容。仅支持单轮提示。
`generation_config`	可选：生成配置
`tool_config`	可选：此配置适用于请求中提供的所有工具。
`tools`	可选：模型可能用于生成下一个回答的 `Tools` 列表。`Tool` 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。
`safety_settings`	可选：用于屏蔽不安全内容的请求设置，在 `GenerateContentResponse.candidates` 上强制执行。
`system_instruction`	可选：用户为模型提供的系统指令。
`variables`	可选：如果提示包含模板变量，请提供要用于该变量的值。例如，如果提示文本内容为“Hello, {name}”。您的变量列表应包含一个字典，其中包含“{name}”变量的所有可能值。示例： "variables": [ {"name": {"text": "Alice"}}, {"name": {"text": "Bob"}}, ],

此代码示例演示了如何定义 types.Prompt 变量。

  import vertexai
  from vertexai import types
  from google.genai import types

  prompt = types.Prompt(
      prompt_data=types.PromptData(
        contents=[genai_types.Content(parts=[genai_types.Part(text="Hello, {name}! How are you?")])],
        variables=[
          {"name": genai_types.Part(text="Alice")},
          {"name": genai_types.Part(text="Bob")},
        ],
        model="your-model",
      ),
  )

将提示保存到 Google Cloud 项目

本部分介绍将提示保存到 Google Cloud 项目的参数和示例。

参数

下表介绍了 create 方法使用的参数：

参数
`prompt`	特定提示的数据。
`config`	可选：一个 `types.CreatePromptConfig` 对象，表示用于创建提示的配置。

下表介绍了 create_version 方法使用的参数：

参数
`prompt`	必需：特定提示的数据。
`config`	可选：一个 `types.CreatePromptConfig` 对象，表示用于创建提示版本的配置。

create_version 方法会返回 Prompt。

示例

如需将提示保存到 Google Cloud 项目，请使用 client.prompts.create 和 client.prompts.create_version 方法。

client.prompts.create 方法可在Google Cloud 项目中创建提示资源。client.prompts.create_version 方法会在该资源中创建提示版本，您可以在Google Cloud 控制台中访问该资源。

client.prompts.create 方法接受 Prompt 对象作为输入，并在 Google Cloud 项目中创建提示。client.prompts.create_version 方法还需要传入 prompt_id，即要创建版本的提示资源 ID。系统会返回与 Google Cloud 项目关联的新 Prompt 对象。在调用 create 或 create_version 之前，对 Prompt 对象所做的任何更新都是本地更新。

以下代码示例展示了如何保存提示和提示版本：

  # Save `Prompt` to a Google Cloud project.
  # Returns a new `Prompt` object associated with the saved prompt resource.
  prompt_resource = client.prompts.create(prompt=prompt)
  prompt_version_resource = client.prompts.create_version(prompt=prompt, prompt_id=prompt_resource.prompt_id)

获取已保存的提示

本部分介绍如何获取提示和提示版本的参数和示例。

有两种方法：client.prompts.get 和 client.prompts.get_version。

参数

下表介绍了 client.prompts.get 方法使用的参数：

参数
`prompt_id`	必需：要检索的提示的 ID。
`config`	可选：一个 `types.GetPromptConfig` 对象，表示用于获取提示的配置。

下表介绍了 client.prompts.get_version 方法使用的参数：

参数
`prompt_id`	必需：要检索的提示的 ID。
`version_id`	必需：您要检索的提示版本的 ID。
`config`	可选：一个 `types.GetPromptConfig` 对象，表示用于获取提示的配置。

get 和 get_version 方法会返回 Prompt。

示例

如需获取（加载）已保存到 Google Cloud 项目的提示，请使用 client.prompts.get 方法。此方法接受提示 ID 作为输入，并返回相应的 Prompt 对象。此代码示例展示了如何加载已保存的提示：

  # Get prompt
  retrieved_prompt = client.prompts.get(prompt_id=prompt_resource.prompt_id)

以下代码示例展示了如何获取提示的版本。

  retrieved_prompt_version = client.prompts.get_version(prompt_id='your-prompt-id', version_id='your-prompt-version-id')

以下代码演示了如何转换提示，以便在生成式 AI SDK 中调用 generate_content。

  from google import genai
  from google.genai import types as genai_types

  genai_client = genai.Client(vertexai=True, project="my-project", location="my-location")

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

列出提示和版本

本部分介绍列出提示和提示版本的参数以及示例。

有两种方法：client.prompts.list 和 client.prompts.list_versions。

参数

下表介绍了 list 方法使用的参数：

参数
`config`	可选：一个 `types.ListPromptsConfig` 对象，表示列出提示的配置。

下表介绍了 list_versions 方法使用的参数：

参数
`prompt_id`	必需：要列出版本的提示的 ID。
`config`	可选：一个 `types.ListPromptsConfig` 对象，表示列出提示版本的配置。

list 和 list_versions 方法都会返回一个包含 types.PromptRef 对象的 Iterator。PromptRef 包含对提示的引用。

示例

如需查看 Google Cloud 项目中保存的所有提示的提示 ID 和模型，请使用 list 方法。

以下代码示例演示了如何检索当前项目中所有已保存提示的 PromptRef：

  prompt_refs = list(client.prompts.list())

  # Get a prompt from the list
  prompt1 = client.prompts.get(prompt_id=prompt_refs[0].prompt_id)

以下代码示例演示了如何列出提示中保存的所有提示版本的提示 ID 和版本 ID：

  prompt_versions_metadata = client.prompts.list_versions(prompt_id="123456789")

  # Get a specific prompt version from the versions metadata list
  prompt1 = client.prompts.get_version(
      prompt_id=prompt_versions_metadata[0].prompt_id,
      version_id=prompt_versions_metadata[0].version_id
  )

删除提示

本部分介绍用于删除提示的参数以及示例。

有两种方法：delete 和 delete_version。

参数

下表介绍了 delete 方法使用的参数：

参数
`prompt_id`	要删除的提示的 ID。
`config`	可选：一个 `types.DeletePromptConfig` 对象，表示用于删除提示的配置。

下表介绍了 delete_version 方法使用的参数：

参数
`prompt_id`	要从中删除版本的提示的 ID。
`version_id`	要删除的提示的版本。
`config`	可选：一个 `types.DeletePromptConfig` 对象，表示用于删除提示版本的配置。

示例

如需删除提示及其所有版本，请使用 delete 方法。

  client.prompts.delete(prompt_id=retrieved_prompt.prompt_id)

如需从提示资源中删除特定版本，请使用 delete_version 方法。

  client.prompts.delete_version(prompt_id=retrieved_prompt.prompt_id, version_id='your-version-id')

恢复提示版本

本部分介绍用于恢复提示版本的参数以及示例。

参数

下表介绍了 restore_version 方法使用的参数：

参数
`prompt_id`	特定提示的 ID。
`version_id`	要恢复的提示的版本。
`config`	用于恢复提示版本的配置。

restore_version 方法会返回一个 Prompt 对象。

示例

提示资源还包含用于存储之前保存的提示版本的版本历史记录。您可以使用 restore_version() 方法将旧版本恢复为提示的最新版本。此方法会返回一个 Prompt 对象。

  # Restore to prompt version id 1
  restored_prompt = client.prompts.restore_version(prompt_id=retrieved_prompt.prompt_id, version_id='1')

后续步骤

如需详细了解支持函数调用的提示，请参阅函数调用简介。