Negozio di esempio con la guida di avvio rapido di Gemini

Questo tutorial mostra come creare in modo iterativo esempi few-shot e recuperarli dinamicamente da Example Store per correggere il comportamento di un modello LLM. In questo tutorial utilizzerai il modello gemini-2.0-flash. Ecco cosa farai:

  • Crea un'istanza di Example Store (ExampleStore).

  • Crea esempi basati sulla risposta di Gemini e caricali nell'istanza di Example Store.

  • Recupera dinamicamente gli esempi da Example Store per guidare il modello LLM verso il comportamento previsto.

  • Libera spazio.

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima configurare il progetto e l'ambiente.

Configura il progetto

  1. Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.
  8. Se hai selezionato un progetto, assicurati di disporre del ruolo IAM utente di Agent Platform (roles/aiplatform.user) sul progetto.

Autenticati ad Agent Platform

Per utilizzare gli esempi di Python in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

  1. Installa Google Cloud CLI.

  2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente: 

    gcloud auth application-default login

    Non devi eseguire questa operazione se utilizzi Cloud Shell.

    Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione di. Google Cloud

Importa le librerie

  1. Esegui il comando seguente per installare l'SDK di Agent Platform per Example Store.

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

  2. Utilizza il seguente esempio di codice per importare e inizializzare l'SDK per Example Store.

    import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.

    • LOCATION: la tua regione. È supportata solo us-central1.

Crea un'istanza di Example Store

Utilizza il seguente esempio di codice per creare un'istanza di Example Store che utilizza il modello di incorporamento text-embedding-005.

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

Tieni presente che la creazione di un Example Store richiede alcuni minuti.

Per saperne di più sulla creazione o sul riutilizzo delle istanze di Example Store, consulta Crea un'istanza di Example Store.

Carica esempi nell'istanza di Example Store

Segui questi passaggi per creare e caricare esempi nell'istanza di Example Store. Puoi caricare un massimo di cinque esempi per richiesta.

  1. Definisci lo strumento della funzione get_current_weather. Gli esempi che crei nei passaggi successivi guideranno il modello su quando richiamare questa funzione e quali argomenti trasmetterle.

    Per saperne di più su come gli esempi possono migliorare il rendimento della chiamata di funzione e le risposte del modello, consulta Utilizza gli esempi per migliorare il rendimento della chiamata di funzione. Per saperne di più su come creare un'applicazione di chiamata di funzione, consulta Introduzione alla chiamata di funzione.

    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. Invia una richiesta a Gemini per generare contenuti utilizzando la funzione get_current_weather.

    Consulta Crea un client per l'SDK Gen AI.

    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-2.0-flash",
  user_content,
  config=genai_types.GenerateContentConfig(
    tools=[
      genai_types.Tool(function_declarations=[get_current_weather_func])]
  )
)

  3. Esegui una delle seguenti operazioni per creare e caricare un esempio.

    • Se la risposta del modello LLM mostra il comportamento previsto, utilizza il seguente esempio di codice per creare un esempio basato sulla risposta e caricarlo in 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])

    • In alternativa, se la risposta non copre tutte le funzioni o i risultati previsti o se il modello ha difficoltà con il ragionamento, utilizza il seguente esempio di codice per creare una risposta per correggere il comportamento del modello.

      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. Ripeti i passaggi 2 e 3 per creare e caricare più esempi, se necessario. Puoi caricare altri esempi se il modello mostra un comportamento imprevisto o se gli esempi caricati non coprono tutte le funzioni, i risultati o il ragionamento che ti aspetti. Per saperne di più su quando devi caricare altri esempi, consulta Carica esempi.

Recupera e utilizza gli esempi con Gemini

Cerca gli esempi in base alla loro somiglianza con il prompt. Puoi quindi includere questi esempi nel prompt per guidare il modello LLM verso il comportamento previsto.

Definisci le funzioni di assistenza per formattare gli esempi

Utilizza il seguente esempio di codice per definire una classe ExampleStorePrompt e le funzioni di assistenza che ti consentono di cercare e recuperare gli esempi.

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
        )

Cerca esempi pertinenti

Utilizza il seguente esempio di codice per cercare gli esempi pertinenti alla conversazione in corso con il modello LLM. Puoi quindi utilizzare le funzioni di assistenza per includere questi esempi nei prompt.

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=[get_current_weather_func])]
  )
)

Migliora in modo iterativo la qualità delle risposte

Per migliorare i pattern di risposta di Gemini utilizzando esempi few-shot, ripeti i passaggi nelle sezioni seguenti:

  1. Crea e carica esempi nell'istanza di Example Store.

  2. Recupera e utilizza gli esempi con Gemini

Libera spazio

Per liberare spazio da tutte le risorse utilizzate in questo progetto, puoi eliminare il Google Cloud progetto utilizzato per la guida introduttiva.

In alternativa, puoi eliminare le singole risorse che hai creato in questo tutorial, come segue:

  1. Utilizza il seguente esempio di codice per eliminare l'istanza di Example Store.

    example_store.delete()

  2. Elimina tutti i file creati localmente.

Passaggi successivi