Recuperare esempi

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

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

  • SearchExamples: recupera gli esempi utilizzando la ricerca di somiglianza 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 di 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 il negozio di esempio.

    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.

Esempi di recupero

Utilizza i seguenti esempi per recuperare gli esempi. FetchExamples recupera tutti gli esempi che soddisfano esattamente i tuoi 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 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 dalla relativa 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 relativo 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 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 il negozio di esempio. L'unica regione supportata è us-central1.
  • EXAMPLE_STORE_ID: l'ID dell'istanza 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 delle seguenti 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, 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.

Esempi di ricerca

La raccolta di esempi trova gli esempi più pertinenti in base al punteggio di somiglianza tra stored_contents_example_key e le chiavi di ricerca degli esempi archiviati. L'utilizzo di esempi pertinenti alla conversazione aiuta il modello ad apprendere 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 di 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"
    }
  }
)