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 LLM. In questo tutorial utilizzi il modello gemini-2.0-flash. Ecco cosa devi fare:

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

  • Crea esempi di autori in base alla risposta di Gemini e caricali nell'istanza dell'Example Store.

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

  • Eseguire la pulizia.

Prima di iniziare

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

Configura il progetto

  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. 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 hai selezionato un progetto, assicurati di disporre del ruolo IAM Vertex AI User (roles/aiplatform.user) sul progetto.

    9. Autenticarsi in Vertex AI

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

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

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

    Importare librerie

    1. Esegui il seguente comando per installare l'SDK Vertex AI Python 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. È supportato 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 Creare un'istanza di Example Store.

    Carica esempi nell'istanza Example Store

    Per creare e caricare esempi nell'istanza 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 le prestazioni della chiamata di funzione e le risposte del modello, consulta Utilizzare esempi per migliorare le prestazioni della chiamata di funzione. Per saperne di più su come creare un'applicazione di chiamata di funzione, consulta la pagina 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 Creare 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=[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 nell'archivio degli esempi.

        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 che ti aspettavi o se noti che il modello ha difficoltà con il ragionamento, utilizza il seguente esempio di codice per creare una risposta che corregga 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 esempi aggiuntivi, consulta Caricare esempi.

    Recuperare e utilizzare esempi con Gemini

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

    Definisci funzioni di supporto per formattare gli esempi

    Utilizza il seguente esempio di codice per definire una classe ExampleStorePrompt e funzioni helper che ti consentono di cercare e recuperare 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 ""
        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
        )

    Cercare esempi pertinenti

    Utilizza il seguente esempio di codice per cercare esempi pertinenti alla conversazione in corso con l'LLM. Puoi quindi utilizzare le funzioni helper per includere questi esempi nei tuoi 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=[track_flight_status_function])]
  )
)

    Migliorare in modo iterativo la qualità delle risposte

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

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

    2. Recuperare e utilizzare esempi con Gemini

    Esegui la pulizia

    Per eliminare 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 nel seguente modo:

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

      example_store.delete()

    2. Elimina tutti i file creati localmente.

    Passaggi successivi