Iniziare a utilizzare i modelli di prompt del server

Anteprima: l'utilizzo dei template di prompt del server è una funzionalità in anteprima, il che significa che non è soggetta a SLA (accordo sul livello del servizio) o a norme sul ritiro e potrebbe essere modificata in modi incompatibili con le versioni precedenti.

In ogni richiesta a un modello, invii un prompt e, facoltativamente, uno schema e configurazioni per controllare la risposta del modello. Quando utilizzi Firebase AI Logic, puoi inviare tutte queste informazioni direttamente dal codice client oppure puoi specificarle lato server utilizzando i template di prompt del server.

Quando utilizzi i template di prompt del server, puoi archiviare il prompt, lo schema e le configurazioni lato server e la tua app passa dal client al server solo la chiave (l'ID del template) che fa riferimento a un template specifico, nonché gli input richiesti per quel template.

Quando utilizzi i template di prompt del server, puoi archiviare il prompt e le configurazioni lato server e fornire solo una chiave (l'ID del template) nel codebase dell'app. Ecco alcuni vantaggi di questo approccio:

• Protezione dall'esposizione del prompt lato client

• Aggiornamento del prompt e della configurazione senza rilasciare una nuova versione dell'app

Questa guida descrive come iniziare a utilizzare i template di prompt del server.

Vai alla panoramica generale Vai alle istruzioni dettagliate

Modelli e funzionalità supportati

• Utilizza i template di prompt del server con uno qualsiasi dei Gemini e Imagen modelli che Firebase AI Logic supporta, ad eccezione dei modelli Gemini Live.

• Consulta l' elenco delle funzionalità non ancora supportate.

Nota: per utilizzare i template di prompt del server con interazioni multi-turn (come chat e chiamate di funzioni), segui questa guida introduttiva per familiarizzare con il funzionamento dei template di prompt del server in uno scenario "Hello World". Poi, scopri le indicazioni specifiche per le interazioni multi-turn.

---

Panoramica generale

Di seguito è riportato il flusso di lavoro di base per l'utilizzo dei template di prompt del server:

1. Crea il template utilizzando l'interfaccia utente guidata nella Firebase console.

2. Testa il template in una richiesta reale utilizzando l'esperienza di test nella Firebase console.

3. Accedi al template dal codice dell'app utilizzando templateGenerativeModel.

Formato di base di un template di prompt del server

Per Firebase AI Logic, la Firebase console fornisce un'interfaccia utente guidata per specificare il frontmatter e i contenuti del template.

I template di prompt del server utilizzano una sintassi e un formato basati su Dotprompt. Per maggiori dettagli, vedi Formato, sintassi ed esempi dei template.

Il template di esempio riportato di seguito mostra i componenti più importanti di un template per una richiesta di esempio a un Gemini modello:

---
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 sezione superiore all'interno dei tripli 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 e viene comunemente chiamato frontmatter YAML.

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

Utilizzare il template nel codice

Fai clic sul tuo fornitore Gemini API per visualizzare contenuti specifici del fornitore e codice in questa pagina. API Gemini per sviluppatori API Gemini in Vertex AI

Il seguente codice client di esempio mostra come utilizzare il template nel codice:

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

Dart

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.googleAI().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);

Unity

// ...

// Initialize the Gemini Developer API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// 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}");
}

Importante: ti consigliamo vivamente di utilizzare Firebase Remote Config con i template di prompt del server in modo da poter modificare più facilmente l'ID del template e altri valori nella richiesta.

---

Istruzioni dettagliate

Questa sezione fornisce istruzioni dettagliate per la creazione, il test e l'utilizzo dei template di prompt del server.

Prima di iniziare

• Se non l'hai già fatto, completa la guida introduttiva, che descrive come configurare il progetto Firebase, collegare l'app a Firebase, aggiungere l'SDK, inizializzare il servizio di backend per il fornitore Gemini API scelto e creare un'istanza GenerativeModel.

• Assicurati di disporre delle autorizzazioni necessarie per creare e gestire i template di prompt del server. Per impostazione predefinita, tutte queste autorizzazioni sono incluse nel ruolo Proprietario.

  Visualizza le autorizzazioni obbligatorie

  • 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

• Se utilizzi Vertex AI Gemini API e se il tuo caso d'uso richiede restrizioni basate sulla località, supportiamo workflow avanzati per i template.

Passaggio 1: crea un template di prompt del server

Per la maggior parte dei casi d'uso, puoi creare e gestire i template di prompt del server nella Firebase console.

1. Nella console Firebase, vai alla scheda Servizi AI > Logica AI > Template di prompt.

2. Fai clic su Crea nuovo template e seleziona un'opzione di template di avvio.

   • Questi modelli di avvio forniscono il formato e la sintassi per alcuni casi d'uso comuni. Tuttavia, indipendentemente dall'opzione selezionata, puoi modificare completamente il template in base alle tue esigenze.

   • Questa guida introduttiva presuppone che tu abbia selezionato l'opzione Input + System Instructions.

3. Inserisci gli identificatori del template:

   • Nome del template: è un nome visualizzato per il template (ad es. My First Template). Risulta visibile solo all'interno delle interfacce Firebase, come la Firebase console.

   • ID del template: deve essere un ID univoco per il template all'interno del tuo progetto Firebase (ad es. my-first-template-v1-0-0). Farai riferimento a questo ID nella richiesta dalla tua app.

     • Ti consigliamo di utilizzare un sistema di controllo delle versioni per gli ID dei template.

     • Gli ID dei template possono contenere al massimo 63 caratteri e possono contenere lettere minuscole, numeri e trattini.

4. Modifica la sezione Configurazione (frontmatter) del template, se necessario.

   • Questa sezione deve includere almeno un nome del modello, come questo:

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

   • Facoltativamente, puoi anche specificare la configurazione del modello e qualsiasi controllo di input & output e così via. Per maggiori dettagli e opzioni, vedi Formato, sintassi ed esempi dei template.

5. Modifica la sezione Prompt e (se applicabile) istruzioni di sistema del template, se necessario.

   • Questa sezione deve includere almeno il prompt di testo da inviare al modello.

     Write a story about a magic backpack.
     

   • Puoi anche creare prompt più complessi, come le seguenti opzioni. Per maggiori dettagli e opzioni, vedi Formato, sintassi ed esempi dei template.

     • (Facoltativo e se applicabile) Specifica le istruzioni di sistema utilizzando la {{role "system"}} sintassi e il prompt di testo utilizzando la {{role "user"}} sintassi.

     • (Facoltativo) Specifica le variabili di input utilizzando Handlebars sintassi (ad es. {{customerName}}). Puoi fornire un valore predefinito nel template, ma il valore di questa variabile di input viene in genere passato nella richiesta.

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

Passaggio 2: testa il template nella console Firebase

La console Firebase fornisce un'esperienza di test per il tuo template. Questa esperienza ti consente di vedere cosa accadrà quando il template verrà utilizzato, sia il formato della richiesta sia l'output di una richiesta effettiva.

1. Fai clic su Salva template per poter testare il template.

   Puoi sempre modificare o persino eliminare il template in un secondo momento. L'unico valore che non puoi modificare in un secondo momento è l'ID del template.

2. Se il prompt utilizza variabili di input, includi i valori di test nel campo Input di test. Per questo esempio:

     {
       "customerName": "Jane"
     }
   

3. Se nel tuo progetto Firebase sono attivi più fornitori Gemini API, puoi scegliere quale utilizzare per la richiesta di test. Se questa opzione viene visualizzata nella console, seleziona Gemini Developer API o Vertex AI Gemini API.

   Tieni presente che questa selezione si applica solo alle richieste inviate tramite l' Firebase esperienza di test della console. Nella richiesta effettiva dalla tua app, specifichi il fornitore Gemini API scelto come faresti per qualsiasi richiesta.

4. Fai clic sul pulsante Crea richiesta di test formattata.

   Esamina la richiesta di test formattata risultante nella parte destra dello schermo e apporta modifiche ai campi del template.

   Espandi per visualizzare un esempio di richiesta di test formattata

   {
     "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. Quando sei soddisfatto della richiesta di test formattata, fai clic sul pulsante Esegui test del prompt.

   Esamina la risposta di test risultante nella parte destra dello schermo e apporta modifiche ai campi del template.

   Importante: ogni volta che fai clic su Esegui test del prompt, potrebbero essere addebitati costi a seconda del fornitore Gemini API e del piano tariffario scelti.

   Espandi per visualizzare un esempio di risposta di test

   {
     "candidates": [{
       "content": {
         "parts": [{
           "text": "```\n--------------------------------------------------------------------------------\n                         **INVOICE**\n--------------------------------------------------------------------------------\n\n**Creative Solutions Inc.**\n123 Business Lane, Suite 100\nAnytown, USA 12345\nPhone: [phone]\nEmail: [e-mail]\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: [phone]\nEmail: [e-mail]\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. Se sei pronto per accedere al template dal codice dell'app, bloccalo facendo clic sull' icona del lucchetto nell' angolo in alto a destra del template.

7. Fai clic su Chiudi per uscire dall'esperienza di modifica.

Passaggio 3: accedi al template dal codice

Fai clic sul tuo fornitore Gemini API per visualizzare contenuti specifici del fornitore e codice in questa pagina. API Gemini per sviluppatori API Gemini in Vertex AI

Una richiesta che utilizza un template di prompt del server è simile ad altre richieste, con le seguenti modifiche:

• Utilizza un templateGenerativeModel (o templateImagenModel, se necessario).
• Fornisci l'ID del template.
• Fornisci i valori di tutti gli input delle variabili richiesti dal template.

Tieni presente che dopo aver creato o aggiornato il template, potrebbe essere necessario attendere qualche minuto prima che il template venga propagato sui server Firebase prima di accedervi dal codice.

Swift

Crea un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

// 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 un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.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 un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

// 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 un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

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

Dart

Il plug-in Flutter supporterà presto i template di prompt del server.

Crea un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
var _model = FirebaseAI.googleAI().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);

Unity

Crea un'istanza templateGenerativeModel (o templateImagenModel) per utilizzare un template nella richiesta.

// ...

// Initialize the Gemini Developer API backend service
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// 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}");
}

**Importante** :ti consigliamo vivamente di utilizzare Firebase Remote Config con i template di prompt del server in modo da poter modificare più facilmente il template e altri valori nella richiesta.

---

Passaggi successivi

• Scopri di più sulle best practice e sulle considerazioni per l'utilizzo dei template di prompt del server.

• Scopri i dettagli sul formato e sulla sintassi dei template, insieme agli esempi.

• Gestisci i template, inclusi la modifica, il blocco e il controllo delle versioni.