例を取得する

このページでは、Example Store からサンプルを取得する方法について説明します。サンプルを取得する方法は次のとおりです。

  • FetchExamples: フィルタ条件に完全に一致するすべてのサンプルを取得します。このオプションは、サンプルが少ない場合や低レイテンシが必要な場合に使用します。

  • SearchExamples: ユーザーのクエリと保存済みの例との類似性検��を使用して、例を取得します。サンプルが多い場合は、このオプションを使用します。

前提条件

このページの Python サンプルを使用する前に、ローカルの Python 環境に Vertex AI SDK for Python をインストールして初期化します。

  1. 次のコマンドを実行して、Vertex AI SDK for Python for Example Store をインストールします。

    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 のみがサポートされています。

例を取得する

次のサンプルを使用して、サンプルを取得します。FetchExamples は、フィルタ条件に完全に一致するすべてのサンプルを取得します。

Vertex AI SDK for Python

次のコードは、Example Store 内のすべてのサンプルを返します（1 ページあたり最大 100 個）。

from vertexai.preview import example_stores

example_store = example_stores.ExampleStore(EXAMPLE_STORE_NAME)
# Returns the dictionary representation of FetchExamplesResponse.
examples = example_store.fetch_examples()

function_names を使用すると、返されるサンプルを制限するフィルタを 1 つ以上指定できます。次の例では、flight_booking_tool 関数と hotel_booking_tool 関数を含む例のみを返します。

# Returns examples that include either tool.
example_store.fetch_examples(
    filter={
        "function_names": {
            "values": ["flight_booking_tool", "hotel_booking_tool"],
            "array_operator": "CONTAINS_ANY"
        }
    }
)

# Returns examples that include *both* tools.
example_store.fetch_examples(
    filter={
        "function_names": {
            "values": ["flight_booking_tool", "hotel_booking_tool"],
            "array_operator": "CONTAINS_ALL"
        }
    }
)

search_keys フィルタを使用すると、検索キーによって返される例を制限できます。

# Returns examples that include any of the following search keys.
example_store.fetch_examples(
    filter={"search_keys": ["How do I get to the airport?"]}
)

example_ids フィルタを使用すると、Example ID で返されるサンプルを制限できます。サンプル ID の形式は exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var> です。ここで、EXAMPLE_ID はサンプル用に生成された数値 ID を表します。

# Returns examples that have any of the following Example IDs.
example_store.fetch_examples(
  example_ids=["exampleTypes/stored_contents_example/examples/09b1d383f92c47e7a2583a44ebbc7854"]
)

REST API

サンプルを取得するには、exampleStores.fetchExamples メソッドを使用して POST リクエストを送信します。

リクエストの JSON 本文の例で指定された function_names フィルタは、関数 flight_booking_tool と hotel_booking_tool を含む例のみを返します。

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

  • 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:fetchExamples

リクエストの本文（JSON）: 

{
  "stored_contents_example_filter": {
    "function_names": {
      "values": ["flight_booking_tool", "hotel_booking_tool"],
      "array_operator": "CONTAINS_ANY"
     }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

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:fetchExamples"

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:fetchExamples" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。ここで、EXAMPLE_ID はサンプル用に生成された ID を表します。

検索の例

サンプルストアは、stored_contents_example_key と保存されているサンプルの検索キーの類似度スコアに基づいて、最も関連性の高いサンプルを見つけます。会話に関連する例を使用すると、モデルが想定される動作を学習しやすくなります。

Vertex AI SDK for Python

次のコードサンプルを使用して、Vertex AI SDK for Python で関連する例を検索します。

example_store.search_examples(
    parameters={
        "stored_contents_example_key": "what's the weather in nyc"
    },
    # Only fetch the most similar examaple. The default value is 3.
    top_k=1
)

"""
Response -- dictionary representation of SearchExamplesResponse.
{'results': [{'example': {'exampleId': 'exampleTypes/stored_contents_example/examples/16834837b178453783e471b459d99195',
    'storedContentsExample': {'searchKey': 'What is the weather like in Boston?',
    'contentsExample': {'contents': [{'role': 'user',
        'parts': [{'text': 'What is the weather like in Boston?'}]}],
      'expectedContents': [{'content': {'parts': [{'functionCall': {'name': 'get_current_weather',
            'args': {'location': 'New York, NY'}}}]}},
      {'content': {'parts': [{'functionResponse': {'name': 'get_current_weather',
            'response': {'humidity': 65.0,
            'description': 'Partly Cloudy',
            'icon': 'partly-cloudy',
            'temperature': 38.0,
            'location': 'Boston, MA',
            'wind': {'speed': 10.0, 'direction': 'NW'}}}}]}},
      {'content': {'role': 'model',
        'parts': [{'text': 'The weather in Boston is 38 degrees and partly cloudy.'}]}}]}}},
  'similarityScore': 0.73527116}]}
"""

function_names フィルタを使用すると、類似性検索に含めるサンプルを制限できます。

example_store.search_examples(
  parameters={
    "stored_contents_example_key": "What's the weather in nyc",
    "function_names": {
      "values": ["weather_tool", "hotel_booking_tool"],
      "array_operator": "CONTAINS_ANY"
    }
  }
)