Recuperar ejemplos

En esta página se explica cómo obtener ejemplos de tu tienda de ejemplos. Tienes las siguientes opciones para recuperar tus ejemplos:

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

  • SearchExamples: obtiene ejemplos mediante la búsqueda de similitud entre la consulta del usuario y los ejemplos almacenados. Usa esta opción si tienes un gran número de ejemplos.

Requisitos previos

Antes de usar los ejemplos de Python de 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 en Example Store.

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

  2. Usa el siguiente código de ejemplo para importar e inicializar el SDK de Example Store.

    import vertexai
from vertexai.preview import example_stores

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

    Haz los cambios siguientes:

    • PROJECT_ID: tu ID de proyecto.

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

Obtener ejemplos

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

SDK de Vertex AI para Python

El siguiente código devuelve 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()

Puede usar function_names para especificar uno o varios filtros que restrinjan los ejemplos que se devuelven. En el siguiente ejemplo solo se devuelven 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 devuelven 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?"]}
)

Puede usar el filtro example_ids para restringir los ejemplos que se devuelven por su ID. Los IDs de ejemplo tienen el formato exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, donde 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 REST

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

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

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto.
  • LOCATION: la región en la que quieres crear la tienda de ejemplo. La única región admitida es us-central1.
  • EXAMPLE_STORE_ID: el ID de la instancia de Example Store en la que quiere 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, donde 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 la 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 el siguiente código de ejemplo 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 de similitudes.

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