Recupere exemplos

Esta página mostra como obter exemplos da sua loja de exemplos. Tem as seguintes opções para obter os seus exemplos:

  • FetchExamples: obtém todos os exemplos que se enquadram exatamente nos seus critérios de filtragem. Use esta opção quando tiver apenas alguns exemplos ou precisar de uma latência mais baixa.

  • SearchExamples: obtém exemplos através da pesquisa de semelhanças entre a consulta do utilizador e os exemplos armazenados. Use esta opção se tiver um grande número de exemplos.

Pré-requisitos

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

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

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

  2. Use o seguinte exemplo de código para importar e inicializar o SDK para a loja de exemplo.

    import vertexai
from vertexai.preview import example_stores

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto.

    • LOCATION: a sua região. Apenas us-central1 é suportado.

Exemplos de obtenção

Use os seguintes exemplos para obter exemplos. FetchExamples obtém todos os exemplos que se enquadram exatamente nos seus critérios de filtragem.

SDK Vertex AI para Python

O código seguinte devolve 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()

Pode usar function_names para especificar um ou mais filtros que restringem os exemplos devolvidos. O exemplo seguinte devolve 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"
        }
    }
)

Pode usar o filtro search_keys para restringir os exemplos devolvidos pela respetiva 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?"]}
)

Pode usar o filtro example_ids para restringir os exemplos devolvidos pelo respetivo ID do exemplo. Os IDs de exemplo 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 obter exemplos, envie um pedido POST através do método exampleStores.fetchExamples.

O filtro function_names especificado no corpo JSON do pedido de exemplo devolve apenas exemplos que incluem as funções flight_booking_tool e hotel_booking_tool:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • LOCATION: a região onde quer criar a loja de exemplo. A única região suportada é us-central1.
  • EXAMPLE_STORE_ID: o ID da instância da loja de exemplo onde quer carregar o 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 do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte, em que EXAMPLE_ID representa o ID gerado para o exemplo.

Exemplos de pesquisa

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

SDK Vertex AI para Python

Use o seguinte exemplo de código para pesquisar exemplos relevantes através do SDK 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}]}
"""

Pode usar o filtro function_names para restringir os exemplos incluídos na pesquisa de semelhanças.

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