Formato, sintassi ed esempi di modelli


Per Firebase AI Logic, la console Firebase fornisce una UI guidata per specificare i contenuti di un template.

I template di prompt del server utilizzano una sintassi e un formato basati su Dotprompt. In questa pagina puoi trovare descrizioni dettagliate del formato e della sintassi del template, oltre ad alcuni esempi.

Ecco i componenti più importanti per una richiesta di esempio a un modello Gemini:

---
model: 'gemini-3.8-flash'
---

{{role "system"}}
All output must be a clearly structured invoice document.
Use a tabular or clearly delineated list format for line items.

{{role "user"}}
Create an example customer invoice for a customer named {{customerName}}.
  • La sezione superiore all'interno dei tre trattini contiene il nome del modello e, facoltativamente, qualsiasi configurazione del modello, convalida dell'input o schema che vuoi inviare nella richiesta. È scritto come coppie chiave/valore ed è comunemente chiamato frontmatter YAML.

  • Il corpo del template contiene il prompt. Facoltativamente, può includere anche istruzioni di sistema e valori di input (utilizzando la sintassi Handlebars).


Questa pagina fornisce descrizioni dettagliate del formato e della sintassi dei modelli, oltre a esempi, per quanto segue:

Tutti gli esempi in questa pagina mostrano template che utilizzano gemini-3.8-flash, ma puoi utilizzare qualsiasi modello Gemini supportato da Firebase AI Logic (ad eccezione dei modelli Gemini Live API).

Hello World

Ecco un esempio minimo di un template di prompt del server:

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
---

Prompt e istruzioni di sistema (se applicabili)

Write a story about a magic backpack.



Controlla la generazione delle risposte

Puoi controllare la generazione delle risposte in vari modi, a seconda del tuo caso d'uso e del livello di controllo di cui hai bisogno.

Configurazione modello

Imposta una configurazione del modello per controllare il modo in cui il modello genera una risposta, ad esempio i token di output massimi, le sequenze di interruzione e così via.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
config:
  maxOutputTokens: 200
  stopSequences: ["red"]
---

Prompt e istruzioni di sistema (se applicabili)

Write a story about a magic backpack.


Configurazione del ragionamento

Specifica una configurazione relativa al ragionamento per i modelli che supportano il ragionamento.

Configurazione (frontmatter)

  • Gemini 3.x e modelli successivi (livelli di ragionamento)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • Modelli Gemini 2.5 (budget di pensiero)

    ---
    model: 'gemini-2.5-flash'
    config:
      thinkingConfig:
        thinkingBudget: 1024
        includeThoughts: true
    ---
    

Prompt e istruzioni di sistema (se applicabili)

Solve x^2 + 4x + 4 = 0


Impostazioni di sicurezza

Utilizza le impostazioni di sicurezza per regolare la probabilità di ricevere risposte che potrebbero essere considerate dannose.

Configurazione (frontmatter)

Esempio con un'impostazione di sicurezza:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
---

Esempio con più impostazioni di sicurezza:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
    - category: HARM_CATEGORY_HATE_SPEECH
      threshold: BLOCK_MEDIUM_AND_ABOVE
---

Prompt e istruzioni di sistema (se applicabili)

Write a story about a magic backpack.


Istruzioni di sistema

Imposta le istruzioni di sistema per guidare il comportamento del modello. Includili nel prompt:

  • Specifica le istruzioni di sistema utilizzando la sintassi {{role "system"}}.

  • Specifica il prompt testuale utilizzando la sintassi {{role "user"}}.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
---

Prompt e istruzioni di sistema (se applicabili)

{{role "system"}}
All output must be a clearly structured invoice document.
Use a tabular or clearly delineated list format for line items.

{{role "user"}}
Create an example customer invoice for a customer.



Variabili di input

Alcuni prompt sono statici, ma spesso è necessario includere alcuni dati dell'utente come parte del prompt.

Puoi includere variabili di input dinamiche nel prompt utilizzando le espressioni Handlebars, che sono contenute nei tag {{ }} nel formato {{variableName}} o {{object.propertyName}} (ad esempio, Hello, {{name}} from {{address.city}}).

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
---

Prompt e istruzioni di sistema (se applicabili)

Create an example customer invoice for a customer named {{customerName}}.

Puoi fornire un valore predefinito nel template, ma il valore di una variabile di input viene solitamente fornito dal client nell'ambito della richiesta.



Flussi di controllo (loop e condizionali)

Per scrivere prompt più complessi, puoi utilizzare blocchi condizionali (come #if, else e #unless) e l'iterazione (#each).

Puoi fornire informazioni contestuali aggiuntive come variabili con un prefisso @ speciale:

  • @first: true quando si esegue l'iterazione del primo elemento di un blocco #each.
  • @last: true durante l'iterazione dell'ultimo elemento di un blocco #each.
  • @index: restituisce la posizione dell'indice (basato su zero) dell'elemento corrente.

Per informazioni su tutti gli helper logici integrati, consulta la documentazione di Handlebars.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
---

Prompt e istruzioni di sistema (se applicabili)

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}

Tieni presente che i condizionali accettano solo un riferimento a una variabile, non qualsiasi tipo di espressione, ad esempio:

  • Le seguenti opere: {{#if isVipCustomer}} ... {{/if}}
  • Il seguente comando non funziona: {{#if customer.type == 'vip'}} ... {{/if}}

Se la variabile è un valore booleano, la condizione funziona come previsto. Se la variabile non è un valore booleano, la condizione è effettivamente un controllo "is-not-null". Questo può essere utile per gestire input facoltativi, ad esempio:

{{#if customerName}}
Hello {{customerName}}
{{else}}
Hello Guest
{{/if}}



Convalida dell'input e schema

Se i dati provengono dal client, ti consigliamo vivamente di utilizzare lo schema di input per proteggerti dal prompt injection e garantire che i dati passati nella richiesta corrispondano alle tue aspettative.

  • Puoi fornire valori predefiniti nel caso in cui il client non ne fornisca uno.

  • Lo schema supporta i tipi scalari string, integer, number, boolean e object. Gli oggetti, gli array e gli enum sono indicati tra parentesi dopo il nome del campo.

  • Tutte le proprietà sono considerate obbligatorie, a meno che non le indichi come facoltative con ?. Quando una proprietà è contrassegnata come facoltativa, viene anche resa nullable per offrire agli LLM una maggiore flessibilità nel restituire null anziché omettere un campo.

Ecco un esempio di base per fornire lo schema di input. Di seguito è riportato uno schema più avanzato.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  default:
    isVipCustomer: false
  schema:
    customerName: string, the customers name  # string, number, and boolean types are defined like this
    productNames?(array, list of products to include in the invoice): string  # optional fields are marked with a ?
    isVipCustomer?: boolean, whether or not the customer is a VIP
---

Prompt e istruzioni di sistema (se applicabili)

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}



Schema di output

Se vuoi che il modello generi un output JSON strutturato, puoi specificare uno schema di output. Specificando format: json, vincoli il modello a restituire sempre una risposta JSON che segue lo schema specificato.

  • Lo schema supporta i tipi scalari string, integer, number, boolean e object. Gli oggetti, gli array e gli enum sono indicati tra parentesi dopo il nome del campo.

  • Tutte le proprietà sono considerate obbligatorie, a meno che non le indichi come facoltative con ?. Quando una proprietà è contrassegnata come facoltativa, viene anche resa nullable per offrire agli LLM una maggiore flessibilità nel restituire null anziché omettere un campo.

Ecco un esempio di base per generare un output JSON strutturato. Puoi trovare uno schema più avanzato di seguito.

Configurazione (frontmatter)

---
model: gemini-3.8-flash
output:
  format: json
  schema:
    invoiceId: string
    invoiceFile(object, an invoice file):
      url?: string
      contents: string
      mimeType: string
---

Prompt e istruzioni di sistema (se applicabili)

Create an example customer invoice.



Input multimodale

I prompt multimodali inviati a un modello Gemini possono includere più tipi di input, tra cui file (come testo insieme a immagini, PDF, file di testo normale, audio e video).

  • Fornisci un file utilizzando il suo URL con la sintassi {{media url}}.

  • Fornisci un file incorporato con la sintassi {{media type="mime_type" data="contents"}}.

Esempio di base (input multimodale)

Ecco un esempio di base per fornire un input multimodale. Di seguito è riportato un esempio più complesso.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
---

Prompt e istruzioni di sistema (se applicabili)

Describe this image

{{media type="mimeType" data="imageData"}}

Esempio complesso (input multimodale)

Ecco un esempio più complesso per fornire un input multimodale.

Configurazione (frontmatter)

---
model: gemini-3.8-flash
input:
  schema:
    image_urls?(array, urls of external images): string
    inline_images?(array, inline image data):
      type: object
      properties:
        mime_type: string
        contents: string  # inline data must be base64-encoded
---

Prompt e istruzioni di sistema (se applicabili)

{{role "system"}}
Use the following image as the basis for comparisons
{{media url="http://example.com/reference_img.bmp"}}

{{role "user"}}
What do the following images have in common?

{{#each image_urls}}
  {{media url="this"}}
{{/each}}

{{#each inline_images}}
  {{media type="mime_type" data="contents"}}
{{/each}}



Utilizzo degli strumenti

I template di prompt del server supportano i seguenti strumenti.

Se vuoi che gli utenti forniscano informazioni aggiuntive per la richiesta al modello, utilizza le variabili di input all'interno del template di prompt del server, insieme alla convalida dell'input.

Chiamata di funzione

Consulta la guida completa per la chiamata di funzione utilizzando i template di prompt del server.

Eseguire il codice

Lo strumento di esecuzione di codice consente al modello di generare ed eseguire codice Python.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - codeExecution
---

Prompt e istruzioni di sistema (se applicabili)

What is the sum of the first 50 prime numbers?
Generate and run code for the calculation, and make sure you get all 50.

Contesto URL

Lo strumento Contesto URL ti consente di fornire al modello un contesto aggiuntivo sotto forma di URL. Questo esempio mostra anche come specificare la convalida dell'input per gli URL se vengono forniti dall'utente.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  schema:
    url1:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
    url2:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
tools:
  - urlContext
---

Prompt e istruzioni di sistema (se applicabili)

Compare the ingredients and cooking times from the recipes at {{url1}} and {{url2}}

Lo strumento Grounding con Google Search collega il modello ai contenuti web disponibili pubblicamente in tempo reale.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleSearch
---

Prompt e istruzioni di sistema (se applicabili)

Who won the Euro 2024?

Grounding con Google Maps

Lo strumento Grounding con Google Maps fornisce al modello dati geospaziali per funzionalità basate sulla posizione.

Per utilizzare lo strumento googleMaps, inseriscilo nell'oggetto tools del frontmatter del template. L'esempio seguente mostra alcune configurazioni facoltative aggiuntive:

  • Consenti le variabili di input dal codice lato client ed esegui la convalida dell'input e dello schema di questo input (in questo esempio, un question).

  • Configura lo strumento googleMaps fornendo le coordinate di una località e/o un codice lingua nel codice lato client utilizzando un TemplateToolConfig.

Sotto il modello di esempio, troverai una sezione espandibile che mostra esempi di codice lato client per l'utilizzo di queste configurazioni facoltative.

Configurazione (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleMaps
input:
  schema:
    question: string
---

Prompt e istruzioni di sistema (se applicabili)

{{role "system"}}
You are a helpful tour guide. Use the Google Maps tool with the provided coordinates to answer the user's question based on their location.

{{role "user"}}
{{question}}