提示管理

本頁介紹一套統一的功能，可讓您使用 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 功能，請執行下列操作：

  1. 安裝最新版 Vertex AI SDK。

    pip install --upgrade google-cloud-aiplatform

  2. 使用下列 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 中的下列任何提示管理功能：

建立本機提示

本節提供範例，說明如何定義 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 物件。對 Prompt 物件所做的任何更新都是本機更新，直到呼叫 create 或 create_version 為止。

下列程式碼範例說明如何儲存提示和提示版本：

  # 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：

  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')

後續步驟