Desde el 29 de abril del 2025, los modelos Gemini 1.5 Pro y Gemini 1.5 Flash no están disponibles en proyectos donde no se hayan utilizado previamente, incluidos los proyectos nuevos. Para obtener más información, consulta Versiones y ciclo de vida de los modelos.

Esta página se ha traducido con Cloud Translation API.

Guía de inicio rápido de Example Store con Gemini

En este tutorial se muestra cómo puedes crear ejemplos de pocas oportunidades de forma iterativa y cómo puedes recuperarlos dinámicamente de Example Store para corregir el comportamiento de un LLM. En este tutorial, usarás el modelo gemini-2.0-flash. Debes hacer lo siguiente:

Crea una instancia de Example Store (ExampleStore).
Crea ejemplos basados en la respuesta de Gemini y sube esos ejemplos a la instancia de Example Store.
Recupera dinámicamente tus ejemplos de Example Store para guiar al LLM hacia el comportamiento esperado.
Limpiar.

Antes de empezar

Para completar los pasos que se muestran en este tutorial, primero debes configurar tu proyecto y tu entorno.

Configurar el proyecto

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

Si has seleccionado un proyecto, asegúrate de tener el rol de gestión de identidades y accesos Usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Autenticarse en Vertex AI

Para usar las Python muestras de esta página en un entorno de desarrollo local, instala e inicializa la CLI de gcloud y, a continuación, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

Instala Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando 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 obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación Google Cloud .

Importar bibliotecas

Ejecuta el siguiente comando para instalar el SDK de Vertex AI para Python en Example Store.
```
pip install --upgrade google-cloud-aiplatform>=1.87.0
```
Usa el siguiente código de ejemplo para importar e inicializar el SDK de Example Store.
```
import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)
```
Haz los cambios siguientes:
- PROJECT_ID: tu ID de proyecto.
- LOCATION: tu región. Solo se admite us-central1.

Crear una instancia de Example Store

Usa el siguiente código de ejemplo para crear una instancia de Example Store que utilice el modelo de inserción text-embedding-005.

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

Ten en cuenta que crear una tienda de ejemplo lleva unos minutos.

Para obtener más información sobre cómo crear o reutilizar instancias de Example Store, consulta Crear una instancia de Example Store.

Subir ejemplos a la instancia de Example Store

Sigue estos pasos para crear y subir ejemplos a la instancia de Example Store. Puedes subir un máximo de cinco ejemplos por solicitud.

Define la herramienta de función get_current_weather. Los ejemplos que crees en los pasos siguientes indicarán al modelo cuándo invocar esta función y qué argumentos pasarle.

Para obtener más información sobre cómo pueden mejorar los ejemplos el rendimiento de la llamada de función y las respuestas del modelo, consulta Usar ejemplos para mejorar el rendimiento de la llamada de función. Para obtener más información sobre cómo crear una aplicación de llamadas a funciones, consulta la introducción a las llamadas a funciones.
```
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."
      }
    },
  },
)
```

Envía una solicitud a Gemini para que genere contenido mediante la función get_current_weather.

Consulta Crear un cliente para el 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=[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])]
  )
)

Para crear y subir un ejemplo, siga uno de estos pasos.

Si la respuesta del LLM muestra el comportamiento esperado, usa el siguiente código de ejemplo para crear un ejemplo basado en la respuesta y subirlo 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])

Si la respuesta no abarca todas las funciones o los resultados que esperabas, o si ves que el modelo tiene dificultades para razonar, usa el siguiente ejemplo de código para redactar una respuesta que corrija el comportamiento del 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])

Repite los pasos 2 y 3 para crear y subir varios ejemplos, según sea necesario. Puedes subir más ejemplos si el modelo muestra un comportamiento inesperado o si los ejemplos que has subido no abarcan todas las funciones, los resultados o el razonamiento que esperas. Para obtener más información sobre cuándo debe subir ejemplos adicionales, consulte Subir ejemplos.

Consultar y usar ejemplos con Gemini

Busca ejemplos en función de su similitud con tu petición. Después, puedes incluir estos ejemplos en tu petición para guiar al LLM hacia el comportamiento esperado.

Definir funciones auxiliares para dar formato a los ejemplos

Usa el siguiente código de muestra para definir una clase ExampleStorePrompt y funciones auxiliares que te permitan buscar y obtener ejemplos.

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
        )

Buscar ejemplos relevantes

Usa el siguiente código de ejemplo para buscar ejemplos que sean relevantes para la conversación en curso con el LLM. Después, puedes usar las funciones auxiliares para incluir estos ejemplos en tus peticiones.

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

Mejorar la calidad de las respuestas de forma iterativa

Para mejorar los patrones de respuesta de Gemini mediante ejemplos de pocas oportunidades, repite los pasos de las siguientes secciones:

Crea y sube ejemplos a la instancia de Example Store.
Recuperar y usar ejemplos con Gemini

Limpieza

Para limpiar todos los recursos utilizados en este proyecto, puedes eliminar el proyecto Google Cloud que has usado en la guía de inicio rápido.

De lo contrario, puedes eliminar los recursos que has creado en este tutorial de la siguiente manera:

Usa el siguiente código de ejemplo para eliminar la instancia Example Store.
```
example_store.delete()
```
Elimina los archivos creados localmente.

Siguientes pasos

Consulta cómo crear una instancia de Example Store.