Iniziare a utilizzare i modelli di prompt del server

In ogni richiesta a un modello, invii un prompt e, facoltativamente, lo schema e le 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, puoi archiviare prompt, schema e configurazioni lato server e il codebase della tua app passa dal client al server solo una chiave (l'ID modello) che fa riferimento a un modello specifico, nonché gli input richiesti per quel modello. Ecco alcuni vantaggi di questo approccio:

• Proteggersi 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 modelli di prompt del server.

arrow_downward Vai alla panoramica di alto livello arrow_downward Vai alle istruzioni dettagliate

Modelli e funzionalità supportati

• Utilizza i modelli 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 di alto livello

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

1. Crea il modello utilizzando la UI guidata nella console Firebase.

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

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

Formato di base di un template di prompt del server

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

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

Il modello di esempio riportato di seguito mostra i componenti più importanti di un modello 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 delle tre lineette contiene il nome del modello e, facoltativamente, qualsiasi configurazione, convalida dell'input o schema del modello che vuoi inviare nella richiesta. È scritto come coppie chiave/valore e viene comunemente chiamato frontmatter YAML.

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

Utilizzare il modello 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.
  '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 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 ancora 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 Gemini API provider scelto e creare un'istanza GenerativeModel.

• Assicurati di disporre delle autorizzazioni necessarie per creare e gestire i modelli 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 se il tuo caso d'uso richiede limitazioni basate sulla posizione, supportiamo flussi di lavoro avanzati per i modelli.

Passaggio 1: crea un template di prompt del server

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

1. Nella console Firebase, vai a Servizi AI > AI Logic > scheda Modelli di prompt.

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

   • Questi modelli iniziali forniscono il formato e la sintassi per alcuni casi d'uso comuni. 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 modello:

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

   • ID modello: deve essere un ID univoco per il modello 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 modello.

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

4. Modifica la sezione Configurazione (frontespizio) del modello in base alle tue esigenze.

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

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

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

5. Modifica la sezione Prompt e (se applicabile) istruzioni di sistema 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, vedi Formato, sintassi ed esempi dei modelli.

     • (Facoltativo e a seconda dei casi) 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 modello, ma il valore di questa variabile di input viene in genere trasmesso 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 modello. Questa esperienza ti consente di vedere cosa succederà quando verrà utilizzato il tuo modello, sia il formato della richiesta sia l'output di una richiesta effettiva.

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

   Puoi sempre modificare o 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 Test input. 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 dalla tua app, devi specificare 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 itera su uno qualsiasi dei 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 itera su uno qualsiasi dei campi del modello.

   Espandi per visualizzare la risposta di esempio al test

   {
     "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 alle altre richieste, con i seguenti aggiustamenti:

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

Tieni presente che dopo aver creato o aggiornato il modello, potrebbe essere necessario attendere un paio di minuti prima che 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.
  '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 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 considerazioni per l'utilizzo dei modelli di prompt del server.

• Scopri i dettagli su formato e sintassi dei modelli, insieme ad alcuni esempi.

• Scopri di più sulla gestione dei modelli, inclusi la modifica, il blocco e il controllo delle versioni.

• Scopri di più sui workflow avanzati, ad esempio come utilizzare i modelli in modo programmatico utilizzando la nostra API REST o come eseguire il deployment dei modelli in posizioni specifiche.