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 el código del cliente o puedes 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 beneficios de este enfoque:

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

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

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

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

Modelos y capacidades compatibles

• Usa plantillas de instrucciones del servidor con cualquiera de los Gemini y Imagen modelos que Firebase AI Logic admite, con la excepción de los modelos de Gemini Live.

• Consulta la lista de funciones que aún no son 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 Firebase consola.

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

3. Accede a la plantilla desde el código de tu app con templateGenerativeModel.

Formato básico de una plantilla de instrucciones del servidor

En el caso de Firebase AI Logic, la Firebase consola proporciona una IU guiada para que especifiques el frontmatter y el contenido de la 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.

En la siguiente plantilla de ejemplo, se muestran los componentes más importantes de una plantilla para una solicitud de ejemplo a un modelo Gemini:

---
model: 'gemini-3-flash-preview'
---

{{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, 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 se suele llamar frontmatter de YAML.

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

Usa tu plantilla en el código

En el siguiente código de cliente de ejemplo, se muestra cómo usar la plantilla en tu código:

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .vertexAI()).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")

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.vertexAI()).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)

// ...

// Initialize the Vertex AI Gemini 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);

// ...

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

// 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 = result.response;
const text = response.text();

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.vertexAI().templateGenerativeModel()

var customerName = 'Jane';

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

var text = response?.text;
print(text);

// ...

// Initialize the Vertex AI Gemini API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI());

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Instrucciones detalladas

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

Antes de comenzar

• Si aún no lo hiciste, 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 la API de Gemini que elijas y crear una instancia de GenerativeModel.Gemini API

• 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 Propietario.

  Ver permisos necesarios

  • firebasevertexai.googleapis.com/promptTemplates.create
  • firebasevertexai.googleapis.com/promptTemplates.get
  • firebasevertexai.googleapis.com/promptTemplates.update
  • firebasevertexai.googleapis.com/promptTemplates.delete
  • firebasevertexai.googleapis.com/promptTemplates.list

• Si usas la Vertex AI Gemini API y 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, creas y administras plantillas de instrucciones del servidor en la Firebase consola.

1. En la consola de Firebase, ve a la pestaña Servicios de IA > Lógica de IA > Plantillas de instrucciones.

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, sin importar qué opción selecciones, puedes cambiar por completo la plantilla para satisfacer tus necesidades.

   • En esta guía de introducción, 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 Firebase.

   • ID de la 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 que uses un sistema de control de versiones para los IDs de tus plantillas.

     • Los IDs de las plantillas pueden tener un máximo de 63 caracteres y pueden contener letras minúsculas, 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 este:

     ---
     model: 'gemini-3-flash-preview'
     ---
     

   • 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 Instrucciones del sistema y (según corresponda) de la instrucción de la plantilla según sea necesario.

   • Esta sección debe incluir, como mínimo, la instrucción de texto para 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 {{role "system"}} sintaxis y la instrucción de texto con la {{role "user"}} sintaxis.

     • (Opcional) Especifica las 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 Firebase consola

La Firebase consola 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 poder probarla.

   Siempre puedes editar o incluso borrar la plantilla más adelante. El único valor que no puedes 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. Para este ejemplo:

     {
       "customerName": "Jane"
     }
   

3. Si tienes varios Gemini API proveedores 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 Firebase experiencia de prueba de la consola. En la solicitud real de tu app, especificas el proveedor Gemini API que elegiste de la misma manera que 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.

   Expandir para ver un ejemplo de solicitud de prueba con formato

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3-flash-preview",
     "contents": [{
       "parts": [{
         "text": "Create an example customer invoice for a customer named Jane"
       }],
       "role": "user"
     }],
     "systemInstruction": {
       "parts": [{
         "text": "All output must be a clearly structured invoice document.\nUse a tabular or clearly delineated list format for line items."
       }]
     }
   }
   

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

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

   Expandir para ver un ejemplo de respuesta de prueba

   {
     "candidates": [{
       "content": {
         "parts": [{
           "text": "```\n--------------------------------------------------------------------------------\n                         **INVOICE**\n--------------------------------------------------------------------------------\n\n**Creative Solutions Inc.**\n123 Business Lane, Suite 100\nAnytown, USA 12345\nPhone: (555) 123-4567\nEmail: info@creativesolutions.com\n\n**INVOICE NO:** INV-2023-001\n**INVOICE DATE:** October 26, 2023\n**DUE DATE:** November 25, 2023\n\n**BILL TO:**\nJane\n456 Client Street, Apt 2B\nAnytown, USA 12346\nPhone: (555) 987-6543\nEmail: jane@example.com\n\n--------------------------------------------------------------------------------\n**ITEM DESCRIPTION**               **QTY**   **UNIT PRICE**   **AMOUNT**\n--------------------------------------------------------------------------------\nWebsite Design Services            1         $800.00          $800.00\nContent Creation (Blog Posts)      4         $120.00          $480.00\nMonthly Hosting \u0026 Maintenance      1         $50.00           $50.00\nConsultation Fee                   2         $75.00           $150.00\n--------------------------------------------------------------------------------\n\n**SUMMARY:**\nSubtotal:                                                     $1,480.00\nSales Tax (8%):                                               $118.40\n--------------------------------------------------------------------------------\n**TOTAL DUE:**                                                **$1,598.40**\n--------------------------------------------------------------------------------\n\n**PAYMENT TERMS:**\nPayment is due within 30 days of the invoice date. Please make checks payable to Creative Solutions Inc. For electronic payments, please contact us for details.\n\nThank you for your business!\n```"
         }],
         "role": "model"
       },
       "finishReason": "STOP",
       "index": 0
     }],
     "usageMetadata": {
       "promptTokenCount": 34,
       "candidatesTokenCount": 418,
       "totalTokenCount": 890,
       "promptTokensDetails": [{
         "modality": "TEXT",
         "tokenCount": 34
       }],
       "thoughtsTokenCount": 438
     },
     "modelVersion": "gemini-3-flash-preview",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Si estás listo para acceder a la plantilla desde el código de tu app, haz clic en el ícono de candado en la esquina superior derecha de la plantilla para lock bloquearla.

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

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

Una solicitud que usa una plantilla de instrucciones del servidor se ve 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 cualquier entrada de variable que requiera 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.

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .vertexAI()).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")

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.vertexAI()).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)

// ...

// Initialize the Vertex AI Gemini 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);

// ...

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

// 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 = result.response;
const text = response.text();

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.vertexAI().templateGenerativeModel()

var customerName = 'Jane';

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

var text = response?.text;
print(text);

// ...

// Initialize the Vertex AI Gemini API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI());

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Próximos pasos

• Obtén información sobre las prácticas recomendadas y las consideraciones para usar plantillas de instrucciones del servidor.

• Obtén detalles sobre el formato y la sintaxis de las plantillas, junto con ejemplos.

• Obtén información sobre la administración de plantillas, incluida la edición, el bloqueo y el control de versiones.

• Obtén información sobre los flujos de trabajo avanzados, como trabajar con plantillas de forma programática con nuestra API de REST o implementar tus plantillas en ubicaciones específicas.