Início rápido do Gemini com o exemplo de loja

Este tutorial demonstra como criar exemplos de few-shot de forma iterativa e recuperá-los dinamicamente do Example Store para corrigir o comportamento de um LLM. Você vai fazer o seguinte:

  • Criar uma instância do Example Store (ExampleStore).

  • Criar exemplos com base na resposta do Gemini e fazer upload deles para a instância do Example Store.

  • Recuperar dinamicamente os exemplos do Example Store para orientar o LLM em relação ao comportamento esperado.

  • Fazer a limpeza.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro configure o projeto e o ambiente.

Criar o projeto

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.
  8. Se você selecionou um projeto, verifique se tem o papel de usuário da Agent Platform (roles/aiplatform.user) do IAM nele.

Autenticar na Agent Platform

Para usar os exemplos de Python desta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

  1. Instale a Google Cloud CLI.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Saiba mais em Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

Importar bibliotecas

  1. Execute o comando a seguir para instalar o SDK da Agent Platform 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.

Criar uma instância do Example Store

Use o exemplo de código a seguir para criar uma instância do Example Store que usa o modelo de embedding text-embedding-005.

example_store = example_stores.ExampleStore.create(
    example_store_config=example_stores.ExampleStoreConfig(
        vertex_embedding_model="text-embedding-005"
    )
)

A criação de um Example Store leva alguns minutos.

Para mais informações sobre como criar ou reutilizar instâncias do Example Store, consulte Criar uma instância do Example Store.

Fazer upload de exemplos para a instância do Example Store

Siga estas etapas para criar e fazer upload de exemplos para a instância do Example Store. É possível fazer upload de até cinco exemplos por solicitação.

  1. Defina a ferramenta de função get_current_weather. Os exemplos criados nas etapas subsequentes vão orientar o modelo sobre quando invocar essa função e quais argumentos transmitir a ela.

    Para mais informações sobre como os exemplos podem melhorar o desempenho da chamada de função e as respostas do modelo, consulte Usar exemplos para melhorar o desempenho da chamada de função. Para mais informações sobre como criar um aplicativo de chamada de função, consulte Introdução à chamada de função.

    from google.genai import types as genai_types

get_current_weather_func = genai_types.FunctionDeclaration(
  name="get_current_weather",
  description="Get the current weather in a given location",
  parameters={
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city name of the location for which to get the weather."
      }
    },
  },
)

  2. Envie uma solicitação ao Gemini para gerar conteúdo usando a função get_current_weather.

    Consulte Criar um cliente para o SDK de IA generativa.

    from google import genai

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="What is the weather like in Boston?")],
)
response = client.models.generate_content(
  model="gemini-3.5-flash",
  user_content,
  config=genai_types.GenerateContentConfig(
    tools=[
      genai_types.Tool(function_declarations=[get_current_weather_func])]
  )
)

  3. Faça uma das seguintes ações para criar e fazer upload de um exemplo.

    • Se a resposta do LLM mostrar o comportamento esperado, use o exemplo de código a seguir para criar um exemplo com base na resposta e fazer upload dele para o Example Store.

      function_response = genai_types.Content(
  parts=[
    genai_types.Part(
      function_response={
        "name": "get_current_weather",
        "response": {
          "location": "New York, NY", "temperature": 38,
          "description": "Partly Cloudy",
          "icon": "partly-cloudy", "humidity": 65,
          "wind": { "speed": 10, "direction": "NW" }
        }
      }
    )
  ]
)
final_model_response = genai_types.Content(
  role="model",
  parts=[genai_types.Part(text="The weather in NYC is 38 degrees and partly cloudy.")],
)
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": response.candidates[0].content.to_json_dict()},
      {"content": function_response.to_json_dict()},
      {"content": final_model_response.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

    • Como alternativa, se a resposta não abranger todas as funções ou resultados esperados ou se o modelo tiver dificuldades com o raciocínio, use o exemplo de código a seguir para criar uma resposta que corrija o comportamento do modelo.

      expected_function_call = genai_types.Content(
  parts=[
    genai_types.Part(
      function_call={
        "name": "get_current_weather",
        "args": {"location": "New York, NY"}
      }
    )
  ]
)
function_response = genai_types.Content(
  parts=[
    genai_types.Part(
      function_response={
        "name": "get_current_weather",
        "response": {
          "location": "New York, NY", "temperature": 38,
          "description": "Partly Cloudy",
          "icon": "partly-cloudy", "humidity": 65,
          "wind": { "speed": 10, "direction": "NW" }
        }
      }
    )
  ]
)
final_model_response = genai_types.Content(
  role="model",
  parts=[genai_types.Part(text="The weather in NYC is 38 degrees and partly cloudy.")],
)
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": expected_function_call.to_json_dict()},
      {"content": function_response.to_json_dict()},
      {"content": final_model_response.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

  4. Repita as etapas 2 e 3 para criar e fazer upload de vários exemplos, conforme necessário. É possível fazer upload de outros exemplos se o modelo mostrar um comportamento inesperado ou se os exemplos enviados não abrangerem todas as funções, resultados ou raciocínios esperados. Para mais informações sobre quando é necessário fazer upload de outros exemplos, consulte Fazer upload de exemplos.

Recuperar e usar exemplos com o Gemini

Pesquise exemplos com base na semelhança com o comando. Em seguida, inclua esses exemplos no comando para orientar o LLM em relação ao comportamento esperado.

Definir funções auxiliares para formatar exemplos

Use o exemplo de código a seguir para definir uma classe ExampleStorePrompt e funções auxiliares que permitem pesquisar e buscar exemplos.

import abc
import jinja2
import json

from google.protobuf import json_format
# --BOILERPLATE CODE FOR FORMATTING--

EXAMPLES_PREAMBLE = """<EXAMPLES>
The following are examples of user queries and model responses using the available python libraries.

Begin few-shot
"""

EXAMPLES_POSTAMBLE = """
End few-shot

Now, try to follow these examples and complete the following conversation:
</EXAMPLES>
"""

EXAMPLE_PREAMBLE = "EXAMPLE"

TEMPLATE = """
"""

class ExampleStorePrompt:

    def __init__(
          self, template = TEMPLATE, example_preamble = EXAMPLE_PREAMBLE,
          examples_preamble = EXAMPLES_PREAMBLE,
          examples_postamble = EXAMPLES_POSTAMBLE):

        self.template = jinja2.Template(template)
        self.example_preamble = example_preamble
        self.examples_preamble = examples_preamble
        self.examples_postamble = examples_postamble

    @abc.abstractmethod
    def process_function_response(self, function_response):
        return json.dumps(function_response)

    @abc.abstractmethod
    def process_function_call(self, function_call):
        args_list = []
        for key, value in function_call.get("args", []).items():
            if isinstance(value, str):
                # Wrap strings in quotes.
                value = f'"{value}"'
            if isinstance(value, list):
                value = ', '.join(
                    f'"{item}"' if isinstance(item, str)
                    else str(item) for item in value)
                value = f"[{value}]"
            if isinstance(value, dict):
                value = json.dumps(value)
            args_list.append(f'{key}={value}')
        args = ", ".join(args_list)
        return f"```\n{function_call.get('name')}({args})\n```"

    @abc.abstractmethod
    def process_part(self, part):
        if "function_call" in part:
            return self.process_function_call(part["function_call"])
        if "text" in part:
            return part.get("text")
        if "function_response" in part:
            return self.process_function_response(part["function_response"])

    @abc.abstractmethod
    def process_content(self, content):
        response = []
        for part in content.get("parts", []):
            response.append(self.process_part(part))
        return [content.get("role"), response]

    @abc.abstractmethod
    def example_formatter(self, example: dict):
        response = []
        for content in example.get("contents", []):
            response.append(self.process_content(content))
        for content in example.get("expected_contents", []):
            content = content.get("content", {})
            response.append(self.process_content(content))
        return response

    def get_prompt(self, examples: list):
        if not examples:
          return ""
        examples = [self.example_formatter(example) for example in examples]
        return self.template.render(
            examples=examples,
            example_preamble=self.example_preamble,
            examples_preamble=self.examples_preamble,
            examples_postamble=self.examples_postamble
        )

Pesquisar exemplos relevantes

Use o exemplo de código a seguir para pesquisar exemplos relevantes para a conversa em andamento com o LLM. Em seguida, use as funções auxiliares para incluir esses exemplos nos comandos.

query = "what's the fastest way to get to disney from lax"

# Search for relevant examples.
examples = example_store.search_examples(
  {"stored_contents_example_key": query}, top_k=3)

prompt = ExampleStorePrompt().get_prompt(examples.get("results", []))

model_response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="How do I get to LAX?",
    config=genai_types.GenerateContentConfig(
      system_instruction=prompt,
      tools=[
        genai_types.Tool(function_declarations=[get_current_weather_func])]
  )
)

Melhorar iterativamente a qualidade da resposta

Para melhorar os padrões de resposta do Gemini usando exemplos de few-shot, repita as etapas nas seções a seguir:

  1. Criar e fazer upload de exemplos para a instância do Example Store.

  2. Recuperar e usar exemplos com o Gemini

Limpar

Para limpar todos os recursos usados neste projeto, você pode excluir o Google Cloud projeto usado no início rápido.

Caso contrário, exclua os recursos individuais criados neste tutorial, da seguinte maneira:

  1. Use o exemplo de código a seguir para excluir a instância do Example Store.

    example_store.delete()

  2. Exclua todos os arquivos criados localmente.

A seguir