Exemplo de loja com o início rápido do Gemini

Este tutorial demonstra como criar exemplos few-shot de forma iterativa e recuperá-los dinamicamente do Example Store para corrigir o comportamento de um LLM. Neste tutorial, você vai usar o modelo gemini-1.5-pro-001. Você vai fazer o seguinte:

  • Crie uma instância de exemplo da loja (ExampleStore).

  • Crie exemplos com base na resposta do Gemini e faça o upload deles para a instância da loja de exemplos.

  • Extraia dinamicamente seus exemplos do Example Store para orientar o LLM em direção ao comportamento esperado.

  • Fazer a limpeza.

Antes de começar

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

Criar o projeto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.
  8. Se você selecionou um projeto, verifique se tem o papel do IAM de Usuário da Vertex AI (roles/aiplatform.user) no projeto.

Autenticar na Vertex AI

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

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

Importar bibliotecas

  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.

Criar uma instância de loja de exemplo

Use o exemplo de código abaixo para criar uma instância de loja de exemplo 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 uma loja de exemplo leva alguns minutos.

Para mais informações sobre como criar ou reutilizar instâncias da loja de exemplo, consulte Criar uma instância da loja de exemplo.

Fazer upload de exemplos para a instância da loja de exemplo

Siga as etapas abaixo para criar e fazer upload de exemplos na instância da Example Store. Você pode fazer upload de até cinco exemplos por solicitação.

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

    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 para o Gemini gerar conteúdo usando a função get_current_weather.

    Consulte Criar um cliente para o SDK da 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=[Part(text="What is the weather like in Boston?")],
)
response = client.models.generate_content(
  model="gemini-2.0-flash",
  user_content,
  config=genai_types.GenerateContentConfig(
    tools=[
      genai_types.Tool(function_declarations=[get_current_weather_func])]
  )
)

  3. Siga um destes procedimentos para criar e fazer upload de um exemplo.

    • Se a resposta do LLM mostrar o comportamento esperado, use o exemplo de código abaixo para criar um exemplo com base na resposta e fazer o upload na loja de exemplos.

      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 para corrigir 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. Você pode 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 você precisa fazer upload de outros exemplos, consulte Fazer upload de exemplos.

Extrair e usar exemplos com o Gemini

Pesquise exemplos com base na semelhança com o comando. Inclua esses exemplos no comando para orientar o LLM ao comportamento esperado.

Definir funções auxiliares para formatar exemplos

Use o exemplo de código abaixo 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 ""
        contents_example = example.get("example", {}).get(
          "stored_contents_example", {}).get("contents_example", {})
        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 abaixo para pesquisar exemplos que sejam 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-2.0-flash",
    contents="How do I get to LAX?",
    config=genai_types.GenerateContentConfig(
      system_instruction=prompt,
      tools=[
        genai_types.Tool(function_declarations=[track_flight_status_function])]
  )
)

Melhorar a qualidade da resposta de forma iterativa

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

  1. Crie e faça upload de exemplos na instância da loja de exemplo.

  2. Extrair e usar exemplos com o Gemini

Limpar

Para limpar todos os recursos usados neste projeto, exclua o projeto Google Cloud usado no guia de início rápido.

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

  1. Use o exemplo de código abaixo para excluir a instância da loja de exemplo.

    example_store.delete()

  2. Exclua todos os arquivos criados localmente.

A seguir