Recuperare esempi

Questa pagina mostra come recuperare esempi dall'Example Store. Per recuperare gli esempi, hai a disposizione le seguenti opzioni:

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

  • SearchExamples: recupera esempi utilizzando la ricerca per somiglianza tra la query dell'utente e gli esempi memorizzati. 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 Vertex AI per Python nel tuo ambiente Python locale.

  1. Esegui il seguente comando per installare l'SDK Vertex AI Python per 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 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. È supportato solo us-central1.

Recuperare esempi

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

SDK Vertex AI per Python

Il seguente codice restituisce tutti gli esempi nel tuo negozio di esempio, 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 al loro ID esempio. Gli ID di 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 esempi che includono le funzioni flight_booking_tool e hotel_booking_tool:

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui vuoi creare lo store di esempio. L'unica regione supportata è us-central1.
  • EXAMPLE_STORE_ID: L'ID dell'istanza di 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, ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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

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

Esempi di ricerca

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 Vertex AI per Python

Utilizza il seguente esempio di codice per cercare esempi pertinenti utilizzando l'SDK Vertex AI 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 per somiglianza.

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