Formato, sintaxis y ejemplos de plantillas


En el caso de Firebase AI Logic, la consola de Firebase proporciona una IU guiada para que especifiques el contenido de una plantilla.

Las plantillas de instrucciones del servidor usan una sintaxis y un formato basados en Dotprompt. En esta página, puedes encontrar descripciones detalladas del formato y la sintaxis de la plantilla, junto con ejemplos.

Estos son los componentes más importantes de una solicitud de ejemplo a un modelo 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 sección superior dentro de los guiones triples contiene el nombre del modelo y, de manera opcional, cualquier configuración del modelo, validación de entrada o esquema que desees enviar en la solicitud. Se escribe como pares clave-valor y, por lo general, se denomina metadatos iniciales de YAML.

  • El cuerpo de la plantilla contiene la instrucción. También puede incluir, de forma opcional, instrucciones del sistema y valores de entrada (con la sintaxis de Handlebars).


En esta página, se proporcionan descripciones detalladas del formato y la sintaxis de las plantillas, junto con ejemplos, para lo siguiente:

En todos los ejemplos de esta página, se muestran plantillas que usan gemini-3.8-flash, pero puedes usar cualquier modelo de Gemini compatible con Firebase AI Logic (excepto los modelos de Gemini Live API).

Hello World

Este es un ejemplo mínimo de una plantilla de instrucciones del servidor:

Configuración (metadatos iniciales)

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

Instrucción y (si corresponde) instrucciones del sistema

Write a story about a magic backpack.



Controla la generación de respuestas

Puedes controlar la generación de respuestas de varias maneras según tu caso de uso y el nivel de control que necesites.

Configuración del modelo

Establece una configuración del modelo para controlar cómo genera una respuesta, como la cantidad máxima de tokens de salida, las secuencias de detención, etcétera.

Configuración (metadatos iniciales)

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

Instrucciones del sistema (según corresponda) y de la instrucción

Write a story about a magic backpack.


Configuración de pensamiento

Especifica un parámetro de configuración relacionado con el razonamiento para los modelos que lo admiten.

Configuración (metadatos iniciales)

  • Gemini 3.x y modelos posteriores (niveles de razonamiento)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • Gemini 2.5 modelos (presupuestos de pensamiento)

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

Instrucciones del sistema (según corresponda) y de la instrucción

Solve x^2 + 4x + 4 = 0


Configuración de seguridad

Usa la configuración de seguridad para ajustar la probabilidad de obtener respuestas que se puedan considerar dañinas.

Configuración (metadatos iniciales)

Ejemplo con un parámetro de configuración de seguridad:

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

Ejemplo con varios parámetros de configuración de seguridad:

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

Instrucción y (si corresponde) instrucciones del sistema

Write a story about a magic backpack.


Instrucciones del sistema

Establecer instrucciones del sistema para dirigir el comportamiento del modelo Los incluyes como parte de la instrucción:

  • Especifica las instrucciones del sistema con la sintaxis {{role "system"}}.

  • Especifica la instrucción de texto con la sintaxis {{role "user"}}.

Configuración (frontmatter)

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

Instrucciones del sistema (según corresponda) y de la instrucción

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



Variables de entrada

Algunas instrucciones son estáticas, pero, a menudo, debes incluir algunos datos del usuario como parte de la instrucción.

Puedes incluir variables de entrada dinámicas en la instrucción con expresiones de Handlebars, que se encuentran dentro de las etiquetas {{ }} en el formato de {{variableName}} o {{object.propertyName}} (por ejemplo, Hello, {{name}} from {{address.city}}).

Configuración (frontmatter)

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

Instrucción y (si corresponde) instrucciones del sistema

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

Puedes proporcionar un valor predeterminado en la plantilla, pero el cliente suele proporcionar el valor de una variable de entrada como parte de la solicitud.



Flujos de control (bucles y condicionales)

Para escribir instrucciones más complejas, puedes usar bloques condicionales (como #if, else y #unless) y la iteración (#each).

Puedes proporcionar información contextual adicional como variables con un prefijo @ especial:

  • @first: Es verdadero cuando se itera el primer elemento de un bloque #each.
  • @last: Es verdadero cuando se itera el último elemento de un bloque #each.
  • @index: Proporciona la posición del índice (basado en cero) del elemento actual.

Consulta la documentación de Handlebars para obtener información sobre todos los ayudantes lógicos integrados.

Configuración (frontmatter)

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

Instrucciones del sistema (según corresponda) y de la instrucción

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}}

Ten en cuenta que los condicionales solo aceptan una referencia de variable, no cualquier tipo de expresión, por ejemplo:

  • La siguiente opción funciona: {{#if isVipCustomer}} ... {{/if}}
  • Lo siguiente no funciona: {{#if customer.type == 'vip'}} ... {{/if}}

Si la variable es booleana, la condición funciona como se espera. Si la variable no es un booleano, la condicional es, en efecto, una verificación de "no es nulo". Esto puede ser útil para controlar entradas opcionales, por ejemplo:

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



Validación de entradas y esquema

Si tienes datos que provienen del cliente, te recomendamos que uses el esquema de entrada para protegerte contra la inserción de instrucciones y garantizar que los datos que se pasan en la solicitud coincidan con tus expectativas.

  • Puedes proporcionar valores predeterminados en caso de que el cliente no proporcione un valor.

  • El esquema admite los tipos escalares string, integer, number, boolean y object. Los objetos, arrays y enums se denotan con un paréntesis después del nombre del campo.

  • Todas las propiedades se consideran obligatorias, a menos que las indiques como opcionales con ?. Cuando una propiedad se marca como opcional, también se hace anulable para proporcionar más legibilidad para que los LLMs devuelvan un valor nulo en lugar de omitir un campo.

Este es un ejemplo básico para proporcionar un esquema de entrada. A continuación, encontrarás un esquema más avanzado.

Configuración (metadatos iniciales)

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

Instrucción y (si corresponde) instrucciones del sistema

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}}



Esquema de salida

Si quieres que el modelo genere un resultado JSON estructurado, puedes especificar un esquema de salida. Si especificas format: json, restringes el modelo para que siempre devuelva una respuesta JSON que siga el esquema especificado.

  • El esquema admite los tipos escalares string, integer, number, boolean y object. Los objetos, arrays y enums se denotan con un paréntesis después del nombre del campo.

  • Todas las propiedades se consideran obligatorias, a menos que las indiques como opcionales con ?. Cuando una propiedad se marca como opcional, también se hace anulable para proporcionar más legibilidad para que los LLMs devuelvan un valor nulo en lugar de omitir un campo.

Este es un ejemplo básico para generar resultados JSON estructurados. Puedes encontrar un esquema más avanzado justo debajo.

Configuración (metadatos iniciales)

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

Instrucciones del sistema (según corresponda) y de la instrucción

Create an example customer invoice.



Entrada multimodal

Las instrucciones multimodales que se envían a un modelo de Gemini pueden incluir varios tipos de entrada, como archivos (como texto junto con imágenes, PDFs, archivos de texto sin formato, audio y video).

  • Proporciona un archivo con su URL con la sintaxis {{media url}}.

  • Proporciona un archivo intercalado con la sintaxis {{media type="mime_type" data="contents"}}.

Ejemplo básico (entrada multimodal)

Este es un ejemplo básico para proporcionar una entrada multimodal. A continuación, puedes encontrar un ejemplo más complejo.

Configuración (metadatos iniciales)

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

Instrucción y (si corresponde) instrucciones del sistema

Describe this image

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

Ejemplo complejo (entrada multimodal)

Aquí tienes un ejemplo más complejo para proporcionar entrada multimodal.

Configuración (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
---

Instrucciones del sistema (según corresponda) y de la instrucción

{{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}}



Uso de herramientas

Las plantillas de instrucciones del servidor admiten las siguientes herramientas.

Si quieres que tus usuarios proporcionen información adicional para la solicitud al modelo, usa variables de entrada dentro de la plantilla de instrucciones del servidor, junto con la validación de entrada.

Llamada a función

Consulta la guía completa para llamar a funciones con plantillas de instrucciones del servidor.

Ejecución de código

La herramienta de ejecución de código permite que el modelo genere y ejecute código de Python.

Configuración (metadatos iniciales)

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

Instrucciones del sistema (según corresponda) y de instrucción

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

Contexto de URL

La herramienta Contexto de URL te permite proporcionar contexto adicional al modelo en forma de URLs. Este ejemplo también muestra cómo puedes especificar la validación de entrada para las URLs si el usuario las proporciona.

Configuración (metadatos iniciales)

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

Instrucción y (si corresponde) instrucciones del sistema

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

La herramienta Fundamentación con Google Search conecta el modelo con contenido web disponible públicamente y en tiempo real.

Configuración (metadatos iniciales)

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

Instrucciones del sistema (según corresponda) y de la instrucción

Who won the Euro 2024?

Fundamentación con Google Maps

La herramienta Fundamentación con Google Maps proporciona al modelo datos geoespaciales para la funcionalidad basada en la ubicación.

Para usar la herramienta googleMaps, inclúyela en el objeto tools de los metadatos iniciales de la plantilla. En el siguiente ejemplo, se muestran algunas configuraciones opcionales adicionales:

  • Permite variables de entrada desde el código del cliente y realiza la validación de entrada y el esquema de esa entrada (en este ejemplo, un question).

  • Configura la herramienta de googleMaps proporcionando las coordenadas de una ubicación o un código de idioma en tu código del cliente con un TemplateToolConfig.

Debajo de la plantilla de ejemplo, encontrarás una sección expandible que muestra muestras de código del cliente para trabajar con estos parámetros de configuración opcionales.

Configuración (metadatos iniciales)

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

Instrucciones del sistema (según corresponda) y de instrucción

{{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}}