上傳樣本

建立樣本儲存庫執行個體後，您就可以開始撰寫並上傳範例。您可以在範例儲存器例項中儲存的範例數量沒有限制。您上傳範例至範例商店執行個體後，範例就會立即可供使用。

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

  • 查詢與現有範例無關。

  • 模型無法順利完成某些推理。

  • 可用的範例未涵蓋您預期的所有函式、結果或推理。

只要編寫符合預期格式的相關範例，即可達成以下目標：

  • 改善 LLM 注意及使用範例的能力，避免因提示內容稍微變更而導致回覆模式發生非預期變化。

  • 減少為不相關查詢新增範例的潛在負面影響。

  • LLM 可正常執行類似查詢。

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

您可以使用本頁的範例，根據 LLM 輸出內容撰寫示例。相較於手動撰寫範例，根據 LLM 輸出內容撰寫範例具有下列優點：

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

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

  • 您可以根據成效良好的模型回覆撰寫範例，改善其他模型的行為。舉例來說，如果 Gemini 1.5 Pro 提供的回覆比 Gemini 1.5 Flash 更優異，但延遲時間較長，您可以使用這些回覆撰寫範例，以便在使用 Gemini 1.5 Flash 時，以較低的延遲時間達到類似的效能。

使用範例改善函式呼叫效能

您可以使用少量範例來改善函式呼叫效能，方法是展示下列項目： * 何時會叫用特定函式。

  • 如何擷取要在函式呼叫中使用的引數。

  • 模型如何根據函式傳回的回應做出回應，或是在多步驟推理情況下傳回多個函式。

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

事前準備

使用本頁 Python 範例前，請先在本機 Python 環境中安裝並初始化 Vertex AI SDK for Python for Example Store。

  1. 執行下列指令，安裝範例商店的 Vertex AI SDK for Python。

    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

您可以使用下列範例，利用從 LLM 收到的回覆，在 Example Store 執行個體中建立及上傳範例，以改善 LLM 行為和函式呼叫效能。使用下列範例前，請先確認您已完成下列步驟：

根據預期回應上傳範例

在 LLM 回應符合預期格式的情況下，使用下列範例撰寫及上傳範例。這個範例可讓您傳送要求、根據回應建立範例，然後將範例上傳至 Example Store 執行個體。

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 未依預期產生回覆，您可以根據修正的回覆建立範例。這有助於 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。

後續步驟