上傳樣本

建立樣本儲存庫執行個體後，即可開始撰寫及上傳樣本。範例商店執行個體可儲存的範例數量沒有限制。將範例上傳至範例商店執行個體後，即可立即使用。

以下列舉幾個需要上傳範例的狀況：

  • 查詢與現有範例無關。

  • 模型在某些推理方面有困難。

  • 提供的範例未涵蓋您預期的所有功能、結果或推理。

只要以預期格式撰寫相關範例，即可達成下列目標：

  • 提升 LLM 注意並使用範例的能力，避免因提示的微小變更而導致回覆模式出現非預期的變化。

  • 減少為不相關查詢新增範例可能造成的負面影響。

  • LLM 對類似查詢的執行結果符合預期。

如果 LLM 顯示非預期的行為或推理，您可以上傳修正後的回覆，引導模型在後續要求中遵循預期的模式或推理。

本頁面的範例可讓您根據 LLM 輸出內容製作範例。根據 LLM 的輸出內容製作範例，相較於手動製作範例，有以下優點：

  • 根據預期的 LLM 輸出內容製作範例，可減少手動作業。

  • 根據 LLM 的非預期行為編寫範例，即可直接修正失敗案例。

  • 您可以根據表現良好的模型回覆製作範例，藉此改善其他模型的行為。舉例來說，如果 Gemini 1.5 Pro 的回覆比 Gemini 1.5 Flash 更實用，但延遲時間較長，您可以使用這些回覆編寫範例，透過 Gemini 1.5 Flash 達到類似的效能，但延遲時間較短。

使用範例提升函式呼叫成效

您可以提供少量範例，說明下列事項，藉此提升函式呼叫成效： * 呼叫特定函式的時機。

  • 如何擷取引數，以便在函式呼叫中使用。

  • 模型如何根據函式傳回的回覆內容做出回應，如果是多步驟推理，則會根據多個函式傳回的回覆內容做出回應。

如要進一步瞭解函式呼叫功能，請參閱函式呼叫說明文件。

必要條件

如要使用本頁的 Python 範例，您必須先在本地 Python 環境中，安裝並初始化 Example Store 適用的 Vertex AI SDK for Python。

  1. 執行下列指令，為 Example Store 安裝 Python 適用的 Vertex AI SDK。

    pip install --upgrade google-cloud-aiplatform>=1.87.0

  2. 使用下列程式碼範例，匯入及初始化 Example Store 的 SDK。

    import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)

    更改下列內容：

    • PROJECT_ID：您的專案 ID。

    • LOCATION：您的區域。系統僅支援 us-central1。

上傳樣本

使用下列範例將範例上傳至 Example Store 執行個體。每個要求最多可上傳五個範例。

Python

您可以建立範例並上傳至 Example Store 執行個體，然後使用從 LLM 收到的回覆，藉此改善 LLM 行為和函式呼叫效能。使用下列範例前，請先確認您已完成下列事項：

根據預期回覆上傳範例

在 LLM 回應格式符合預期的情境中，請使用下列範例製作及上傳範例。這個範例可讓您傳送要求、根據回應建立範例，然後將範例上傳至範例商店執行個體。

from vertexai.preview.example_stores import ContentsExample, StoredContentsExample

client = genai.Client(
    http_options=genai_types.HttpOptions(api_version="v1"),
    vertexai=True,
    project="PROJECT_ID",,
    location="LOCATION")

user_content = Content(
    role="user",
    parts=[Part(text="EXAMPLE_QUERY")],
)

response = client.models.generate_content(
    model="MODEL_NAME",
    user_content,
    config=genai_types.GenerateContentConfig(
      tools=[FUNCTION_OR_FUNCTION_DECLARATION]
    )
  )

# Upload example.
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": response.candidates[0].content.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

更改下列內容：

  • PROJECT_ID：您的專案 ID。

  • LOCATION：您的區域。系統僅支援 us-central1。

  • EXAMPLE_QUERY：使用者對 LLM 或代理程式的要求或查詢。

  • MODEL_NAME：模型名稱。例如：gemini-2.0-flash。

  • FUNCTION_OR_FUNCTION_DECLARATION：要在要求中使用的函式或函式宣告。如需將函式定義為工具的相關說明，請參閱 GenAI SDK 函式呼叫文件。

  • EXPECTED_FUNCTION_RESPONSE：預期函式呼叫的預期函式回應 (FunctionResponse物件)。如需定義函式回應的相關說明，請參閱 GenAI SDK 函式呼叫說明文件。

  • EXPECTED_FINAL_MODEL_RESPONSE：預期的最終模型回應 (Content 物件)，適用於預期的函式呼叫和回應。

上傳範例，修正非預期的回覆

如果 LLM 未產生預期回覆，您可以根據修正後的回覆建立範例。這有助於大型語言模型在後續要求中，遵循預期的推理過程。

使用下列範例，將含有修正後回應的範例上傳至 Example Store 執行個體。

user_content = Content(
    role="user",
    parts=[Part(text="EXAMPLE_QUERY")],
)

example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": EXPECTED_FUNCTION_CALL.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}

example_store.upsert_examples(examples=[example])

更改下列內容：

REST

如要將樣本上傳至 Example Store 執行個體，請使用 exampleStores.upsertExamples 方法傳送 POST 要求。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID：您的專案 ID。
  • LOCATION：要建立範例商店的區域。目前僅支援 us-central1 區域。
  • EXAMPLE_STORE_ID：您要上傳範例的 Example Store 執行個體 ID。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples

JSON 要求主體：

{
  "examples": [
      {
          "stored_contents_example": {
              "contents_example": {
                  "contents": [
                      {
                          "role": "user",
                          "parts": [
                              {
                                  "text": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?"
                              }
                          ]
                      }
                  ],
                  "expected_contents": [
                      {
                          "content": {
                              "role": "model",
                              "parts": [
                                  {
                                      "text": ""Yes, there is a store located at 2000 N Shoreline Blvd, Mountain View, CA 94043, US."
                                  }
                              ]
                          }
                      }
                  ]
              },
              "search_key_generation_method": {
                  "last_entry": {}
              }
          }
      }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應，其中 EXAMPLE_ID 代表為範例產生的數字 ID。

後續步驟