Cómo recuperar ejemplos

En esta página, se muestra cómo recuperar ejemplos de tu tienda de ejemplos. 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 mediante la búsqueda de similitud entre la consulta del usuario y los 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 y, luego, 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 la siguiente muestra de código para importar y, luego, inicializar el SDK de 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.

Ejemplos de recuperación

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 tienda de ejemplos, 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 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 muestra su valor 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 según 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 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: Es la región en la que deseas crear la tienda de ejemplo. La única región compatible es us-central1.
  • EXAMPLE_STORE_ID: Es el ID de la instancia de Example Store a 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.

Ejemplos de búsqueda

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

SDK de Vertex AI para Python

Usa la 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 qué ejemplos se incluyen en la búsqueda de 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"
    }
  }
)