サンプルをアップロードする

Example Store インスタンスを作成したら、サンプルの作成とアップロードを開始できます。Example Store インスタンスに保存できるサンプルの数に制限はありません。サンプルは、Example Store インスタンスにアップロードするとすぐに使用できるようになります。

次のような場合に、サンプルをアップロードする必要があります。

クエリが既存のサンプルと無関係である。
モデルが推論に苦戦している。
利用可能なサンプルでは、想定されるすべての関数、結果、推論が網羅されているわけではありません。

期待される形式で関連するサンプルを作成することで、次のことを実現できます。

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 をインストールして初期化する必要があります。

次のコマンドを実行して、Vertex AI SDK for Python for Example Store をインストールします。
```
pip install --upgrade google-cloud-aiplatform>=1.87.0
```
次のコードサンプルを使用し、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 インスタンスにアップロードします。リクエストごとにアップロードできるサンプルは 5 つまでです。

Python

次のサンプルでは、LLM から受信したレスポンスを使用することで、サンプルを作成して Example Store インスタンスにアップロードし、LLM の動作と関数呼び出しのパフォーマンスを改善します。次のサンプルを使用する前に、次の操作を完了していることを確認してください。

クライアントライブラリを使用した Vertex AI のクイックスタートの Python の設定手順に沿って操作します。詳細については、Vertex AI Python API のリファレンスドキュメントをご覧ください。
アプリケーションのデフォルト認証情報を設定して、Vertex AI に対する認証を行います。詳細については、ローカル開発環境の認証を設定するをご覧ください。

想定されるレスポンスに基づいてサンプルをアップロードする

次のサンプルを使用して、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: リクエストで使用する関数または関数宣言。関数をツールとして定義する方法については、生成 AI SDK の関数呼び出しに関するドキュメントをご覧ください。
EXPECTED_FUNCTION_RESPONSE: 想定される関数呼び出しに対する関数レスポンス（FunctionResponse オブジェクト）。関数レスポンスの定義については、関数呼び出しの生成 AI 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])

次のように置き換えます。

EXAMPLE_QUERY: LLM またはエージェントに対するユーザーリクエストまたはクエリ。
EXPECTED_FUNCTION_CALL: 指定されたユーザークエリの想定される関数呼び出し（FunctionCall オブジェクト）。関数呼び出しの定義については、関数呼び出しの生成 AI SDK ドキュメントをご覧ください。
EXPECTED_FUNCTION_RESPONSE: 想定される関数呼び出しに対する関数レスポンス（FunctionResponse オブジェクト）。関数レスポンスの定義については、関数呼び出しの生成 AI SDK ドキュメントをご覧ください。
EXPECTED_FINAL_MODEL_RESPONSE: 想定される関数呼び出しとレスポンスに対する最終モデルのレスポンス（Content オブジェクト）。

REST

サンプルを Example Store インスタンスにアップロードするには、exampleStores.upsertExamples メソッドを使用して POST リクエストを送信します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID。
LOCATION: example store を作成するリージョン。サポートされているリージョンは us-central1 のみです。
EXAMPLE_STORE_ID: サンプルをアップロードする Example Store インスタンスの ID。

HTTP メソッドと URL:

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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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 を表します。

レスポンス

{
  "results": [
    {
      "example": {
        "exampleId": "exampleTypes/stored_contents_example/examples/EXAMPLE_ID",
        "storedContentsExample": {
          "searchKey": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?",
          "contentsExample": {
            "contents": [
              {
                "role": "user",
                "parts": [
                  {
                    "text": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?"
                  }
                ]
              }
            ],
            "expectedContents": [
              {
                "content": {
                  "role": "model",
                  "parts": [
                    {
                      "text": ""Yes, there is a store located at 2000 N Shoreline Blvd, Mountain View, CA 94043, US."
                    }
                  ]
                }
              }
            ]
          },
          "searchKeyGenerationMethod": {
            "lastEntry": {}
          }
        }
      }
    }
  ]
}

次のステップ

例の取得方法を確認する。

サンプルをアップロードする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サンプルを使用して関数呼び出しのパフォーマンスを改善する

前提条件

サンプルをアップロードする

Python

想定されるレスポンスに基づいてサンプルをアップロードする

予期しない回答を修正するためのサンプルをアップロードする

REST

curl

PowerShell

レスポンス

次のステップ

サンプルをアップロードする