Fazer upload de exemplos

Depois de criar uma instância do Example Store, você pode começar a criar e fazer upload de exemplos. Não há limite para o número de exemplos que podem ser armazenados em uma instância do Example Store. Os exemplos ficam disponíveis imediatamente após o upload para a instância do Example Store.

Alguns cenários em que você precisaria fazer upload de exemplos incluem o seguinte:

  • As consultas são irrelevantes para os exemplos atuais.

  • O modelo tem dificuldades com alguns raciocínios.

  • Os exemplos disponíveis não abrangem todas as funções, resultados ou raciocínios esperados.

Ao criar exemplos relevantes no formato esperado, você pode:

  • Melhorar a capacidade do LLM de prestar atenção aos exemplos e usá-los, evitando mudanças inesperadas nos padrões de resposta que resultam de pequenas mudanças no comando.

  • Reduzir o possível impacto negativo da adição de exemplos para consultas irrelevantes.

  • O LLM funciona conforme o esperado para consultas semelhantes.

Se o LLM mostrar um comportamento ou raciocínio inesperado, você poderá fazer upload de uma resposta corrigida para orientar o modelo a seguir o padrão ou raciocínio esperado em solicitações subsequentes.

Os exemplos nesta página permitem criar exemplos com base na saída do LLM. A criação de exemplos com base na saída de um LLM tem as seguintes vantagens em relação à criação manual de exemplos:

  • A criação de exemplos com base na saída esperada do LLM envolve menos esforço manual.

  • Ao criar exemplos com base no comportamento inesperado do LLM, você pode corrigir diretamente os casos de falha.

  • É possível criar exemplos com base em respostas de modelos de bom desempenho para melhorar o comportamento de outros modelos. Por exemplo, se o Gemini 1.5 Pro fornecer respostas melhores do que o Gemini 1.5 Flash, mas com maior latência, você poderá criar exemplos usando essas respostas para alcançar um desempenho semelhante com latências mais baixas usando o Gemini 1.5 Flash.

Usar exemplos para melhorar a performance da chamada de função

É possível usar exemplos de poucos disparos para melhorar a performance da chamada de função, demonstrando o seguinte: * quando uma função específica é invocada.

  • Como extrair os argumentos a serem usados na chamada de função.

  • Como o modelo responde com base na resposta retornada pela função ou por várias funções em caso de raciocínio em várias etapas.

Para saber mais sobre a chamada de função, consulte a documentação de chamada de função.

Pré-requisitos

Antes de usar os exemplos do Python nesta página, instale e inicialize o SDK da plataforma do agente para o Example Store no ambiente Python local.

  1. Execute o comando a seguir para instalar o SDK da plataforma do agente para o Example Store.

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

  2. Use o exemplo de código a seguir para importar e inicializar o SDK do 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 é compatível.

Fazer upload de exemplos

Use os exemplos a seguir para fazer upload de exemplos para uma instância do Example Store. É possível fazer upload de até cinco exemplos por solicitação.

Python

Os exemplos a seguir permitem melhorar o comportamento do LLM e a performance da chamada de função criando e fazendo upload de exemplos para uma instância do Example Store, usando respostas recebidas de um LLM. Antes de usar os exemplos a seguir, verifique se você fez o seguinte:

Siga as instruções de configuração do Python em Instalar as bibliotecas de cliente e configurar a autenticação usando o Application Default Credentials.

Para mais informações, consulte a documentação de referência da API Python da plataforma do agente.

Fazer upload de um exemplo com base em uma resposta esperada

Use o exemplo a seguir para criar e fazer upload de um exemplo em um cenário em que a resposta do LLM está no formato esperado. Esse exemplo permite enviar uma solicitação, criar um exemplo com base na resposta e fazer upload do exemplo para uma instância do Example Store.

from vertexai.preview.example_stores import ContentsExample, StoredContentsExample

client = genai.Client(
    http_options=genai_types.HttpOptions(api_version="v1"),
    vertexai=True,
    project="PROJECT_ID",
    location="LOCATION")

user_content = genai_types.Content(
    role="user",
    parts=[genai_types.Part(text="EXAMPLE_QUERY")],
)

response = client.models.generate_content(
    model="MODEL_NAME",
    user_content,
    config=genai_types.GenerateContentConfig(
      tools=[FUNCTION_OR_FUNCTION_DECLARATION]
    )
  )

# Upload example.
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": response.candidates[0].content.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

Substitua:

  • PROJECT_ID: o ID do projeto.

  • LOCATION: sua região. Somente us-central1 é compatível.

  • EXAMPLE_QUERY: a solicitação ou consulta do usuário para o LLM ou agente.

  • MODEL_NAME: o nome do modelo. Por exemplo, gemini-2.0-flash.

  • FUNCTION_OR_FUNCTION_DECLARATION: a função ou declaração de função a ser usada na solicitação. Consulte a documentação do SDK da GenAI para chamada de função para receber ajuda na definição de uma função como uma ferramenta.

  • EXPECTED_FUNCTION_RESPONSE: a resposta de função esperada (um objeto FunctionResponse) para a chamada de função esperada. Consulte a documentação do SDK da GenAI para chamada de função para receber ajuda na definição de uma resposta de função.

  • EXPECTED_FINAL_MODEL_RESPONSE: a resposta final esperada do modelo (um objeto Content) para a chamada e resposta de função esperadas.

Fazer upload de um exemplo para corrigir uma resposta inesperada

Se o LLM não gerar a resposta conforme o esperado, você poderá criar um exemplo com base na resposta corrigida. Isso ajuda o LLM a seguir o raciocínio esperado para solicitações subsequentes.

Use o exemplo a seguir para fazer upload de um exemplo com a resposta corrigida para a instância do Example Store.

user_content = genai_types.Content(
    role="user",
    parts=[genai_types.Part(text="EXAMPLE_QUERY")],
)

example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": EXPECTED_FUNCTION_CALL.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}

example_store.upsert_examples(examples=[example])

Substitua:

REST

Para fazer upload de um exemplo para uma instância do Example Store, envie uma POST solicitação usando o exampleStores.upsertExamples método.

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 o example store. A única região compatível é us-central1.
  • EXAMPLE_STORE_ID: o ID da instância do Example Store em que você quer 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:upsertExamples

Corpo JSON da solicitação: 

{
  "examples": [
      {
          "stored_contents_example": {
              "contents_example": {
                  "contents": [
                      {
                          "role": "user",
                          "parts": [
                              {
                                  "text": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?"
                              }
                          ]
                      }
                  ],
                  "expected_contents": [
                      {
                          "content": {
                              "role": "model",
                              "parts": [
                                  {
                                      "text": ""Yes, there is a store located at 2000 N Shoreline Blvd, Mountain View, CA 94043, US."
                                  }
                              ]
                          }
                      }
                  ]
              },
              "search_key_generation_method": {
                  "last_entry": {}
              }
          }
      }
  ]
}

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:upsertExamples"

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:upsertExamples" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante à seguinte, em que EXAMPLE_ID representa o ID numérico gerado para o exemplo.

A seguir