检索示例

本页面介绍了如何从 Example Store 中检索样本。您可以通过以下方法检索样本：

  • FetchExamples：检索完全符合过滤条件的所有样本。如果您只有少量样本或需要更低的延迟，请使用此方法。

  • SearchExamples：使用用户查询与存储的样本之间的相似度搜索来检索样本。如果您有大量样本，请使用此选项。

前提条件

在使用本页面上的 Python 示例之前，请在本地 Python 环境中安装并初始化 Vertex AI SDK for Python。

  1. 运行以下命令以安装适用于示例商店的 Python 版 Vertex AI SDK。

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

  2. 使用以下代码示例导入并初始化适用于示例商店的 SDK。

    import vertexai
from vertexai.preview import example_stores

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

    替换以下内容：

    • PROJECT_ID：您的项目 ID。

    • LOCATION：您的区域。 仅支持 us-central1。

提取样本

使用以下示例可提取样本。FetchExamples 会检索完全符合过滤条件的所有样本。

Python 版 Vertex AI SDK

以下代码会返回 Example Store 中的所有样本，每页最多 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 指定一个或多个过滤条件，以限制返回哪些样本。以下示例仅返回包含函数 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 过滤条件按样本 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：要在其中创建示例商店的区域。仅支持区域 us-central1。
  • EXAMPLE_STORE_ID：要上传示例的示例商店实例的 ID。

HTTP 方法和网址：

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。

搜索样本

Example Store 会根据 stored_contents_example_key 与存储样本的搜索键之间的相似度得分，找到最相关的样本。使用与对话相关的样本有助于模型学习预期的行为。

Python 版 Vertex AI SDK

使用以下代码示例通过 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"
    }
  }
)