Recuperar exemplos

Esta página mostra como recuperar exemplos da sua loja de exemplos. Você tem as seguintes opções para recuperar seus exemplos:

  • FetchExamples: recupera todos os exemplos que correspondem exatamente aos critérios de filtragem. Use essa opção quando você tiver apenas alguns exemplos ou precisar de latência mais baixa.

  • SearchExamples: recupera exemplos usando a pesquisa por similaridade entre a consulta do usuário e os exemplos armazenados. Use essa opção se você tiver um grande número de exemplos.

Pré-requisitos

Antes de usar os exemplos de Python nesta página, instale e inicialize o SDK da Vertex AI para Python no seu ambiente local.

  1. Execute o seguinte comando para instalar o SDK da Vertex AI para Python na Example Store.

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

  2. Use o exemplo de código abaixo para importar e inicializar o SDK da Example Store.

    import vertexai
from vertexai.preview import example_stores

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

    Substitua:

    • PROJECT_ID: o ID do projeto.

    • LOCATION: sua região. Somente us-central1 é aceito.

Buscar exemplos

Use os exemplos a seguir para buscar exemplos. FetchExamples recupera todos os exemplos que correspondem exatamente aos seus critérios de filtragem.

SDK da Vertex AI para Python

O código a seguir retorna todos os exemplos na sua loja de exemplo, até 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()

Você pode usar function_names para especificar um ou mais filtros que restringem quais exemplos são retornados. O exemplo a seguir retorna apenas exemplos que incluem as funções 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"
        }
    }
)

É possível usar o filtro search_keys para restringir quais exemplos são retornados pela chave de pesquisa.

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

Você pode usar o filtro example_ids para restringir quais exemplos são retornados pelo ID do exemplo. Os exemplos de ID usam o formato exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, em que EXAMPLE_ID representa o ID numérico gerado para o exemplo.

# 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 buscar exemplos, envie uma solicitação POST usando o método exampleStores.fetchExamples.

O filtro function_names especificado no corpo JSON da solicitação de exemplo só retorna exemplos que incluem as funções flight_booking_tool e hotel_booking_tool:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região em que você quer criar a loja de exemplo. A única região com suporte é us-central1.
  • EXAMPLE_STORE_ID: o ID da instância da loja de exemplo para fazer upload do exemplo.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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

Você vai receber uma resposta JSON semelhante a esta, em que EXAMPLE_ID representa o ID gerado para o exemplo.

Exemplos de pesquisa

A loja de exemplos encontra os exemplos mais relevantes com base na pontuação de similaridade entre o stored_contents_example_key e as chaves de pesquisa dos exemplos armazenados. Usar exemplos relevantes para a conversa ajuda o modelo a aprender o comportamento esperado.

SDK da Vertex AI para Python

Use o exemplo de código abaixo para pesquisar exemplos relevantes usando o SDK da 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}]}
"""

É possível usar o filtro function_names para restringir quais exemplos são incluídos na pesquisa de similaridade.

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