Esta página foi traduzida pela API Cloud Translation.

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

Este tutorial demonstra como pode criar iterativamente exemplos de poucos disparos e obtê-los dinamicamente da loja de exemplos para corrigir o comportamento de um MDG. Neste tutorial, usa o modelo gemini-2.0-flash. Vai fazer o seguinte:

Crie uma instância da loja de exemplo (ExampleStore).
Criar exemplos com base na resposta do Gemini e carregar esses exemplos para a instância da loja de exemplos.
Recupere dinamicamente os seus exemplos da Example Store para orientar o MDG para o comportamento esperado.
Limpar.

Antes de começar

Para concluir os passos demonstrados neste tutorial, tem de configurar primeiro o projeto e o ambiente.

Configure o seu projeto

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Se selecionou um projeto, certifique-se de que tem a função de IAM Utilizador do Vertex AI (roles/aiplatform.user) no projeto.

Autentique-se no Vertex AI

Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

Instale a CLI Google Cloud.

Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

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, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

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

Importe bibliotecas

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
```
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.

Crie uma instância da loja de exemplo

Use o seguinte exemplo de código para criar uma instância da loja de exemplo que usa o modelo de incorporação text-embedding-005.

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

Tenha em atenção que a criação de uma loja de exemplo demora alguns minutos.

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

Carregue exemplos para a instância da loja de exemplos

Execute os passos seguintes para criar e carregar exemplos para a instância da loja de exemplos. Pode carregar um máximo de cinco exemplos por pedido.

Defina a ferramenta de função get_current_weather. Os exemplos que criar nos passos seguintes vão orientar o modelo sobre quando invocar esta função e que argumentos transmitir-lhe.

Para mais informações sobre como os exemplos podem melhorar o desempenho da chamada de funções e as respostas do modelo, consulte o artigo Use exemplos para melhorar o desempenho da chamada de funções. Para mais informações sobre como criar uma aplicação de chamadas de funções, consulte o artigo Introdução às chamadas de funções.
```
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."
      }
    },
  },
)
```

Envie um pedido ao Gemini para gerar conteúdo através da função get_current_weather.

Consulte o artigo Crie um cliente para o SDK de IA gen.

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])]
  )
)

Realize uma das seguintes ações para criar e carregar um exemplo.

Se a resposta do MDI/CE mostrar o comportamento esperado, use o exemplo de código seguinte para criar um exemplo com base na resposta e carregá-lo para a 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])

Em alternativa, se a resposta não abranger todas as funções ou resultados que esperava, ou se vir que o modelo tem dificuldades com o raciocínio, use o seguinte exemplo de código 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])

Repita os passos 2 e 3 para criar e carregar vários exemplos, conforme necessário. Pode carregar exemplos adicionais se o modelo apresentar um comportamento inesperado ou se os exemplos carregados não abrangerem todas as funções, resultados ou raciocínios que espera. Para mais informações sobre quando tem de carregar exemplos adicionais, consulte o artigo Carregue exemplos.

Obtenha e use exemplos com o Gemini

Pesquise exemplos com base na respetiva semelhança com o seu comando. Em seguida, pode incluir estes exemplos no seu comando para orientar o MDG para o comportamento esperado.

Defina funções auxiliares para formatar exemplos

Use o seguinte exemplo de código para definir uma classe ExampleStorePrompt e funções auxiliares que lhe permitem pesquisar e obter 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
        )

Pesquise exemplos relevantes

Use o seguinte exemplo de código para pesquisar exemplos relevantes para a conversa em curso com o MDI/CE. Em seguida, pode usar as funções auxiliares para incluir estes exemplos nos seus 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])]
  )
)

Melhore iterativamente a qualidade das respostas

Para melhorar os padrões de resposta do Gemini com exemplos de poucos disparos, repita os passos nas secções seguintes:

Crie e carregue exemplos na instância da loja de exemplos.
Recupere e use exemplos com o Gemini

Limpar

Para limpar todos os recursos usados neste projeto, pode eliminar o Google Cloud projeto que usou para o início rápido.

Caso contrário, pode eliminar os recursos individuais que criou neste tutorial, da seguinte forma:

Use o seguinte exemplo de código para eliminar a instância da loja de exemplo.
```
example_store.delete()
```
Elimine todos os ficheiros criados localmente.

O que se segue?

Saiba como criar uma instância da loja de exemplo.