Recuperare esempi

Questa pagina mostra come recuperare gli esempi dall'Example Store. Hai le seguenti opzioni per recuperare gli esempi:

  • FetchExamples: recupera tutti gli esempi che corrispondono esattamente ai criteri di filtro. Utilizza questa opzione se hai solo pochi esempi o se hai bisogno di una latenza inferiore.

  • SearchExamples: recupera gli esempi utilizzando la ricerca di similarità tra la query dell'utente e gli esempi archiviati. Utilizza questa opzione se hai un numero elevato di esempi.

Prerequisiti

Prima di utilizzare gli esempi Python in questa pagina, installa e inizializza l'SDK Agent Platform nel tuo ambiente Python locale.

  1. Esegui il comando seguente per installare l'SDK Agent Platform per l'Example Store.

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

  2. Utilizza il seguente esempio di codice per importare e inizializzare l'SDK per l'Example Store.

    import vertexai
from vertexai.preview import example_stores

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

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.

    • LOCATION: la tua regione. È supportata solo us-central1.

Recupera esempi

Utilizza i seguenti esempi per recuperare gli esempi. FetchExamples recupera tutti gli esempi che corrispondono esattamente ai criteri di filtro.

SDK Agent Platform

Il seguente codice restituisce tutti gli esempi nell'Example Store, fino a 100 per pagina:

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

Puoi utilizzare function_names per specificare uno o più filtri che limitano gli esempi restituiti. Il seguente esempio restituisce solo gli esempi che includono le funzioni flight_booking_tool e 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"
        }
    }
)

Puoi utilizzare il filtro search_keys per limitare gli esempi restituiti in base alla chiave di ricerca.

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

Puoi utilizzare il filtro example_ids per limitare gli esempi restituiti in base all'ID esempio. Gli ID esempio utilizzano il formato exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, dove EXAMPLE_ID rappresenta l'ID numerico generato per l'esempio.

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

API REST

Per recuperare gli esempi, invia una richiesta POST utilizzando il metodo exampleStores.fetchExamples.

Il filtro function_names specificato nel corpo JSON della richiesta di esempio restituisce solo gli esempi che includono le funzioni flight_booking_tool e hotel_booking_tool:

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui vuoi creare l'example store. L'unica regione supportata è us-central1.
  • EXAMPLE_STORE_ID: l'ID dell'istanza dell'Example Store in cui vuoi caricare l'esempio.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente, dove EXAMPLE_ID rappresenta l'ID generato per l'esempio.

Cerca esempi

L'Example Store trova gli esempi più pertinenti in base al punteggio di similarità tra stored_contents_example_key e le chiavi di ricerca degli esempi archiviati. L'utilizzo di esempi pertinenti alla conversazione aiuta il modello a imparare il comportamento previsto.

SDK Agent Platform

Utilizza il seguente esempio di codice per cercare esempi pertinenti utilizzando l'SDK Agent Platform per 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}]}
"""

Puoi utilizzare il filtro function_names per limitare gli esempi inclusi nella ricerca di 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"
    }
  }
)