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 Agent Platform en tu entorno de Python local.

  1. Ejecuta el siguiente comando para instalar el SDK de Agent Platform para Example Store.

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

  2. Usa la 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 Agent Platform

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 qué ejemplos 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 qué ejemplos 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 qué ejemplos 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 stored_contents_example_key y las claves de búsqueda de los ejemplos almacenados. Usar ejemplos que sean relevantes para la conversación ayuda al modelo a aprender el comportamiento esperado.

SDK de Agent Platform

Usa la siguiente muestra de código para buscar ejemplos relevantes con el SDK de Agent Platform 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 qué ejemplos 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"
    }
  }
)