Cómo recuperar ejemplos

En esta página, se muestra cómo recuperar ejemplos de tu Example Store. Tienes las siguientes opciones para recuperar tus ejemplos:

  • FetchExamples: Recupera todos los ejemplos que se ajustan exactamente a tus criterios de filtrado. Usa esta opción cuando solo tengas algunos ejemplos o necesites una latencia más baja.

  • SearchExamples: Recupera ejemplos con la búsqueda por similitud entre tu consulta de usuario y tus ejemplos almacenados. Usa esta opción si tienes una gran cantidad de ejemplos.

Requisitos previos

Antes de usar las muestras de Python en esta página, instala e inicializa el SDK de Vertex AI para Python en tu entorno de Python local.

  1. Ejecuta el siguiente comando para instalar el SDK de Vertex AI para Python para Example Store:

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

  2. Usa el siguiente muestra de código para importar y, luego, inicializar el SDK para Example Store:

    import vertexai
from vertexai.preview import example_stores

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

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto

    • LOCATION: Tu región. Solo se admite us-central1.

Recupera ejemplos

Usa los siguientes ejemplos para recuperar ejemplos. FetchExamples recupera todos los ejemplos que se ajustan exactamente a tus criterios de filtrado.

SDK de Vertex AI para Python

El siguiente código muestra todos los ejemplos de tu Example Store, hasta 100 por página:

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()

Puedes usar function_names para especificar uno o más filtros que restrinjan los ejemplos que se muestran. En el siguiente ejemplo, solo se muestran los ejemplos que incluyen las funciones flight_booking_tool y 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"
        }
    }
)

Puedes usar el filtro search_keys para restringir los ejemplos que se muestran por su clave de búsqueda.

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

Puedes usar el filtro example_ids para restringir los ejemplos que se muestran por su ID de ejemplo. Los IDs de ejemplo usan el formato exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, en el que EXAMPLE_ID representa el ID numérico generado para el ejemplo.

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

API de REST

Para recuperar ejemplos, envía una solicitud POST con el método exampleStores.fetchExamples.

El filtro function_names especificado en el cuerpo JSON de la solicitud de ejemplo solo muestra los ejemplos que incluyen las funciones flight_booking_tool y hotel_booking_tool:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: La región en la que deseas crear el example store. La única región admitida es us-central1.
  • EXAMPLE_STORE_ID: El ID de la instancia de Example Store en la que deseas subir el ejemplo.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json, y ejecuta el siguiente comando: 

$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

Deberías recibir una respuesta JSON similar a la siguiente, en la que EXAMPLE_ID representa el ID generado para el ejemplo.

Busca ejemplos

Example Store encuentra los ejemplos más relevantes según la puntuación de similitud entre la stored_contents_example_key y las claves de búsqueda de los ejemplos almacenados. El uso de ejemplos que son relevantes para la conversación ayuda al modelo a aprender el comportamiento esperado.

SDK de Vertex AI para Python

Usa el siguiente muestra de código para buscar ejemplos relevantes con el SDK de Vertex AI para 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}]}
"""

Puedes usar el filtro function_names para restringir los ejemplos que se incluyen en la búsqueda por similitud.

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"
    }
  }
)