Comienza a usar las plantillas de instrucciones del servidor


En cada solicitud a un modelo, envías una instrucción y, de manera opcional, un esquema y configuraciones para controlar la respuesta del modelo. Cuando usas Firebase AI Logic, puedes enviar toda esta información directamente desde tu código de cliente o especificarla en el servidor con plantillas de instrucciones del servidor.

Cuando usas plantillas de instrucciones del servidor, almacenas la instrucción, el esquema y las configuraciones en el servidor, y tu app pasa del cliente al servidor solo la clave (el ID de la plantilla) que hace referencia a una plantilla específica, así como las entradas requeridas para esa plantilla.

Cuando usas plantillas de instrucciones del servidor, almacenas la instrucción y las configuraciones en el servidor, y solo proporcionas una clave (el ID de la plantilla) en la base de código de tu app. Estos son algunos de los beneficios de este enfoque:

  • Protección contra la exposición de tu instrucción en el cliente

  • Actualiza tu instrucción y configuración sin lanzar una nueva versión de la app

En esta guía, se describe cómo comenzar a usar las plantillas de instrucciones del servidor.

Ir a la descripción general Ir a las instrucciones detalladas

Modelos y capacidades compatibles


Descripción general

Este es el flujo de trabajo básico para usar plantillas de instrucciones del servidor:

  1. Crea la plantilla con la IU guiada en la consola de Firebase.

  2. Prueba la plantilla en una solicitud real con la experiencia de prueba de la consola de Firebase.

  3. Accede a la plantilla desde tu app.

Formato básico de las plantillas de instrucciones del servidor

En el caso de Firebase AI Logic, la consola 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. Para obtener más detalles, consulta Formato, sintaxis y ejemplos de plantillas.

Estos son los componentes más importantes de una solicitud de ejemplo a un modelo Gemini:

---
model: 'gemini-2.5-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, así como cualquier configuración, validación de entrada o esquema del modelo que desees enviar en la solicitud (opcional). Se escribe como pares clave-valor y se conoce comúnmente como frontmatter 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).

Usa tu plantilla en el código

Haz clic en tu proveedor de Gemini API para ver el contenido y el código específicos del proveedor en esta página.

Sigue estos pasos para usar la plantilla en tu código:

Swift 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.googleAI.templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

Java 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

Web 


// ...

// Initialize the Gemini Developer API backend service
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent(
  // Specify your template ID
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

const response = response.result;
const text = response.text();

Dart

Pronto, el complemento de Flutter admitirá plantillas de instrucciones del servidor.

Unity

Pronto, el paquete de Unity admitirá plantillas de instrucciones del servidor.


Instrucciones detalladas

En esta sección, se proporcionan instrucciones detalladas para crear, probar y usar plantillas de mensajes del servidor.

Antes de comenzar

  • Si aún no lo has hecho, completa la guía de introducción, en la que se describe cómo configurar tu proyecto de Firebase, conectar tu app a Firebase, agregar el SDK, inicializar el servicio de backend para el proveedor de Gemini API que elijas y crear una instancia de GenerativeModel.

  • Asegúrate de tener los permisos necesarios para crear y administrar plantillas de instrucciones del servidor. De forma predeterminada, todos estos permisos se incluyen en el rol de propietario.

  • Si usas Vertex AI Gemini API y si tu caso de uso requiere restricciones basadas en la ubicación, admitimos flujos de trabajo avanzados para plantillas.

Paso 1: Crea una plantilla de instrucciones del servidor

En la mayoría de los casos de uso, crearás y administrarás plantillas de instrucciones del servidor en la consola de Firebase.

  1. En la consola de Firebase, ve a la pestaña Plantillas de instrucciones de Firebase AI Logic.

  2. Haz clic en Crear plantilla nueva y selecciona una opción de plantilla de inicio.

    • Estas plantillas de inicio proporcionan el formato y la sintaxis para algunos casos de uso comunes. Sin embargo, independientemente de la opción que selecciones, puedes cambiar por completo la plantilla para que se adapte a tus necesidades.

    • En esta guía de inicio, se supone que seleccionaste la opción Input + System Instructions.

  3. Ingresa los identificadores de la plantilla:

    • Nombre de la plantilla: Es un nombre visible para la plantilla (por ejemplo, My First Template). Solo es visible en las interfaces de Firebase, como la consola de Firebase.

    • ID de plantilla: Debe ser un ID único para la plantilla dentro de tu proyecto de Firebase (por ejemplo, my-first-template-v1-0-0). Harás referencia a este ID en la solicitud de tu app.

      • Te recomendamos usar un sistema de control de versiones para los IDs de tus plantillas.

      • Los IDs de plantilla pueden tener un máximo de 63 caracteres y pueden contener letras en minúscula, números y guiones.

  4. Modifica la sección Configuración (frontmatter) de la plantilla según sea necesario.

    • Esta sección debe incluir, como mínimo, un nombre de modelo, como el siguiente:

      ---
model: 'gemini-2.5-flash'
---

    • De manera opcional, también puedes especificar la configuración del modelo y cualquier control de entrada y salida, etcétera. Para obtener más detalles y opciones, consulta Formato, sintaxis y ejemplos de plantillas.

  5. Modifica la sección Instrucción y (según corresponda) las instrucciones del sistema de la plantilla según sea necesario.

    • Esta sección debe incluir, como mínimo, la instrucción de texto que se enviará al modelo.

      Write a story about a magic backpack.

    • También puedes crear instrucciones más complejas, como las siguientes opciones. Para obtener más detalles y opciones, consulta Formato, sintaxis y ejemplos de plantillas.

      • (Opcional y según corresponda) Especifica las instrucciones del sistema con la sintaxis {{role "system"}} y la instrucción de texto con la sintaxis {{role "user"}}.

      • (Opcional) Especifica variables de entrada con la sintaxis de Handlebars (como {{customerName}}). Puedes proporcionar un valor predeterminado en la plantilla, pero el valor de esta variable de entrada suele pasarse en la solicitud.

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

Paso 2: Prueba tu plantilla en la consola de Firebase

La consola de Firebase proporciona una experiencia de prueba para tu plantilla. Esta experiencia te permite ver qué sucederá cuando se use tu plantilla, tanto el formato de la solicitud como el resultado de una solicitud real.

  1. Haz clic en Guardar plantilla para que puedas probarla.

    Siempre podrás editar o incluso borrar la plantilla más adelante. El único valor que no podrás cambiar más adelante es el ID de la plantilla.

  2. Si tu instrucción usa variables de entrada, incluye valores de prueba en el campo Entrada de prueba. En este ejemplo, se aplica lo siguiente:

      {
    "customerName": "Jane"
  }

  3. Si tienes varios proveedores de Gemini API habilitados en tu proyecto de Firebase, puedes elegir cuál usar para la solicitud de prueba. Si esta opción se muestra en la consola, selecciona Gemini Developer API o Vertex AI Gemini API.

    Ten en cuenta que esta selección solo se aplica a las solicitudes enviadas a través de la experiencia de prueba de la consola Firebase. En la solicitud real de tu app, especifica el proveedor de Gemini API que elegiste, tal como lo harías para cualquier solicitud.

  4. Haz clic en el botón Crear solicitud de prueba con formato.

    Revisa la Solicitud de prueba con formato resultante en el lado derecho de la pantalla y realiza iteraciones en cualquiera de los campos de tu plantilla.

  5. Cuando estés conforme con la solicitud de prueba con formato, haz clic en el botón Ejecutar prueba de mensaje.

    Revisa la Respuesta de prueba resultante en el lado derecho de la pantalla y realiza iteraciones en cualquiera de los campos de tu plantilla.

  6. Si ya puedes acceder a la plantilla desde el código de tu app, bloquéala haciendo clic en el ícono de candado en la esquina superior derecha de la plantilla.

  7. Haz clic en Cerrar para salir de la experiencia de edición.

Paso 3: Accede a tu plantilla desde el código

Haz clic en tu proveedor de Gemini API para ver el contenido y el código específicos del proveedor en esta página.

Una solicitud que usa una plantilla de instrucción del servidor es similar a otras solicitudes, con los siguientes ajustes:

  • Usa un templateGenerativeModel (o templateImagenModel, según sea necesario).
  • Proporciona el ID de la plantilla.
  • Proporciona los valores de las entradas de variables que requiere tu plantilla.

Ten en cuenta que, después de crear o actualizar tu plantilla, es posible que debas esperar unos minutos para que se propague en los servidores de Firebase antes de acceder a ella desde tu código.

Swift

Crea una instancia templateGenerativeModel (o templateImagenModel) para usar una plantilla en tu solicitud.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin

Crea una instancia templateGenerativeModel (o templateImagenModel) para usar una plantilla en tu solicitud.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.googleAI.templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

Java

Crea una instancia templateGenerativeModel (o templateImagenModel) para usar una plantilla en tu solicitud.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

Web

Crea una instancia templateGenerativeModel (o templateImagenModel) para usar una plantilla en tu solicitud.


// ...

// Initialize the Gemini Developer API backend service
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent(
  // Specify your template ID
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

const response = response.result;
const text = response.text();

Dart

Pronto, el complemento de Flutter admitirá plantillas de instrucciones del servidor.

Unity

Pronto, el paquete de Unity admitirá plantillas de instrucciones del servidor.


Próximos pasos