Récupérer des exemples

Cette page explique comment récupérer des exemples à partir de votre Example Store. Vous disposez des options suivantes pour récupérer vos exemples:

  • FetchExamples: récupère tous les exemples qui correspondent exactement à vos critères de filtrage. Utilisez cette option si vous n'avez que quelques exemples ou si vous avez besoin d'une latence plus faible.

  • SearchExamples: récupère des exemples à l'aide d'une recherche de similarité entre votre requête utilisateur et vos exemples stockés. Utilisez cette option si vous avez un grand nombre d'exemples.

Prérequis

Avant d'utiliser les exemples Python de cette page, installez et initialisez le SDK Vertex AI pour Python dans votre environnement Python local.

  1. Exécutez la commande suivante pour installer le SDK Vertex AI pour Python pour Example Store.

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

  2. Utilisez l'exemple de code suivant pour importer et initialiser le SDK pour Example Store.

    import vertexai
from vertexai.preview import example_stores

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet

    • LOCATION : votre région. Seule l'option us-central1 est acceptée.

Exemples de récupération

Utilisez les exemples suivants pour extraire des exemples. FetchExamples récupère tous les exemples correspondant exactement à vos critères de filtrage.

SDK Vertex AI pour Python

Le code suivant renvoie tous les exemples de votre Example Store, jusqu'à 100 par page:

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

Vous pouvez utiliser function_names pour spécifier un ou plusieurs filtres qui limitent les exemples renvoyés. L'exemple suivant ne renvoie que les exemples qui incluent les fonctions flight_booking_tool et 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"
        }
    }
)

Vous pouvez utiliser le filtre search_keys pour limiter les exemples renvoyés par leur clé de recherche.

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

Vous pouvez utiliser le filtre example_ids pour limiter les exemples renvoyés par leur ID d'exemple. Les exemples d'ID utilisent le format exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, où EXAMPLE_ID représente l'ID numérique généré pour l'exemple.

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

API REST

Pour extraire des exemples, envoyez une requête POST à l'aide de la méthode exampleStores.fetchExamples.

Le filtre function_names spécifié dans l'exemple de corps de requête JSON ne renvoie que des exemples qui incluent les fonctions flight_booking_tool et hotel_booking_tool:

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet
  • LOCATION: région dans laquelle vous souhaitez créer l'exemple de boutique. La seule région compatible est us-central1.
  • EXAMPLE_STORE_ID: ID de l'instance Example Store dans laquelle vous souhaitez importer l'exemple.

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON semblable à celle-ci, où EXAMPLE_ID représente l'ID généré pour l'exemple.

Exemples de recherches

Example Store trouve les exemples les plus pertinents en fonction du score de similarité entre les clés de recherche de stored_contents_example_key et des exemples stockés. L'utilisation d'exemples pertinents pour la conversation aide le modèle à apprendre le comportement attendu.

SDK Vertex AI pour Python

Utilisez l'exemple de code suivant pour rechercher des exemples pertinents à l'aide du SDK Vertex AI pour 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}]}
"""

Vous pouvez utiliser le filtre function_names pour limiter les exemples inclus dans la recherche de similarité.

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