Iniziare a utilizzare i modelli di prompt del server

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

Quando utilizzi i template di prompt del server, archivi il prompt, lo schema e le configurazioni lato server e il codebase della tua app passa dal client al server solo una chiave (l'ID del template) che fa riferimento a un template specifico, nonché gli input richiesti per quel template. Ecco alcuni vantaggi di questo approccio:

• Proteggiti dall'esposizione del prompt lato client

• Aggiorna il prompt e la configurazione senza rilasciare una nuova versione dell'app

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

arrow_downward Vai alla panoramica generale arrow_downward Vai alle istruzioni dettagliate

Modelli e funzionalità supportati

• Utilizza i template di prompt del server con uno qualsiasi dei modelli Gemini supportati da Firebase AI Logic, ad eccezione dei modelli Gemini Live API.

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

Panoramica generale

Ecco il flusso di lavoro di base per l'utilizzo dei template di prompt del server:

1. Crea il template utilizzando la UI guidata nella consoleFirebase.

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

3. Accedi al template dal codice della tua app utilizzando templateGenerativeModel.

Formato di base di un template di prompt del server

Per Firebase AI Logic, la consoleFirebase 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, consulta Formato, sintassi ed esempi dei modelli.

Il template di esempio riportato di seguito mostra i componenti più importanti di un template 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).

Utilizza il template nel codice

Il codice client di esempio riportato di seguito mostra come utilizzare il modello nel codice:

// ...

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

// ...

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

// ...

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

// ...

// 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.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    customerName: customerName,
  },
});

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

// ...

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

// ...

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

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, connettere l'app a Firebase, aggiungere l'SDK, inizializzare il servizio di backend per il provider 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
  • firebasevertexai.googleapis.com/promptTemplates.updateLock

• Se utilizzi Agent Platform Gemini API (formerly Vertex AI) e il tuo caso d'uso richiede limitazioni basate sulla località, supportiamo workflow avanzati per i modelli.

Passaggio 1: crea un template di prompt del server

Per la maggior parte dei casi d'uso, i template di prompt del server vengono creati e gestiti nella console Firebase.

1. Nella consoleFirebase, vai a Servizi AI > AI Logic > scheda Template di prompt.

2. Fai clic su Crea nuovo modello e seleziona un'opzione di modello iniziale.

   • Questi modelli di partenza forniscono il formato e la sintassi per alcuni casi d'uso comuni. Tuttavia, indipendentemente dall'opzione selezionata, puoi modificare completamente il modello 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 esempio, My First Template). Risulta visibile solo all'interno delle interfacce Firebase, come la console Firebase.

   • ID template: deve essere un ID univoco per il template all'interno del tuo progetto Firebase (ad esempio, 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 modelli.

     • Gli ID template possono contenere un massimo di 63 caratteri e possono includere lettere minuscole, numeri e trattini.

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

   • Questa sezione deve includere almeno un nome del modello, ad esempio:

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

   • Facoltativamente, puoi anche specificare la configurazione del modello, i controlli di input e output e così via. Per ulteriori dettagli e opzioni, consulta Formato, sintassi ed esempi dei template.

5. Modifica la sezione Prompt e istruzioni di sistema (se applicabili) del modello, in base alle esigenze.

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

     Write a story about a magic backpack.
     

   • Puoi anche creare prompt più complessi, come le seguenti opzioni. Per ulteriori dettagli e opzioni, consulta Formato, sintassi ed esempi dei modelli.

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

     • (Facoltativo) Specifica le variabili di input utilizzando la sintassi Handlebars (ad esempio {{customerName}}). Puoi fornire un valore predefinito nel template, ma il valore di questa variabile di input viene solitamente 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 modello nella console Firebase

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

1. Fai clic su Salva modello per poterlo testare.

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

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 abilitati più provider Gemini API, puoi scegliere quale utilizzare per la richiesta di test. Se questa opzione viene visualizzata nella console, seleziona Gemini Developer API o Agent Platform Gemini API (in precedenza Vertex AI).

   Tieni presente che questa selezione si applica solo alle richieste inviate tramite l'esperienza di test della console Firebase. Nella richiesta effettiva della tua app, specifica il provider 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 sul lato destro dello schermo e ripeti l'operazione per tutti i campi del modello.

   Espandi per visualizzare un esempio di richiesta di test formattata

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3.8-flash",
     "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 la richiesta di test formattata ti soddisfa, fai clic sul pulsante Esegui test del prompt.

   Esamina la Risposta di test risultante sul lato destro dello schermo e ripeti l'operazione per tutti i campi del modello.

   Espandi per visualizzare la risposta di test di esempio

   {
     "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.8-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Se vuoi accedere al modello dal codice della tua app, blocca il modello facendo clic sull'icona lock lucchetto nell'angolo in alto a destra del modello.

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

Passaggio 3: accedi al modello dal codice

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

• Utilizza un templateGenerativeModel.
• Fornisci l'ID template.
• Fornisci i valori di tutti gli input delle variabili richiesti dal template.

Tieni presente che dopo aver creato o aggiornato il template, potresti dover attendere un paio di minuti affinché il template venga propagato sui server Firebase prima di accedervi dal codice.

// ...

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

// ...

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

// ...

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

// ...

// 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.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    customerName: customerName,
  },
});

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

// ...

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

// ...

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

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 del modello, insieme ad alcuni esempi.

• Scopri di più sulla gestione dei modelli, tra cui la modifica, il blocco e il controllo della versione.

• Scopri i workflow avanzati, ad esempio come lavorare con i template in modo programmatico utilizzando la nostra API REST o come eseguire il deployment dei template in località specifiche.