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 modelli 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 modello) che fa riferimento a un modello specifico, nonché gli input richiesti per quel modello.

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

• Proteggere 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 e Imagen che Firebase AI Logic supporta, ad eccezione dei modelli Gemini Live.

• 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 della console Firebase.

3. Accedi al modello dalla tua app.

Formato di base dei modelli di prompt del server

Per Firebase AI Logic, la console Firebase fornisce un'interfaccia utente guidata per specificare i contenuti di un 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.

Di seguito sono riportati i componenti più importanti per una richiesta di esempio a un modello 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 sezione superiore all'interno delle tre lineette 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 modello contiene il prompt. Può anche includere facoltativamente istruzioni di sistema e valori di input (utilizzando la sintassi Handlebars).

Utilizzare il modello nel codice

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

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 provider Gemini API 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

• Se utilizzi Vertex AI Gemini API e se il tuo caso d'uso richiede limitazioni basate sulla posizione, supportiamo flussi di lavoro avanzati per i modelli.

Passaggio 1: crea un modello 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 alla scheda Firebase AI Logic 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 (frontmatter) del modello in base alle tue esigenze.

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

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

   • Puoi anche specificare facoltativamente la configurazione del modello e qualsiasi controllo di input e output e così via. Per ulteriori dettagli e opzioni, vedi Formato, sintassi ed esempi di template.

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

   • 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 ulteriori dettagli e opzioni, vedi Formato, sintassi ed esempi di 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 di solito 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 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 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 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 Vertex AI Gemini API.

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

6. Se vuoi accedere al modello dal codice della tua app, bloccalo 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 modello di prompt del server è simile alle altre richieste, con i seguenti aggiustamenti:

• Utilizza un templateGenerativeModel (o un templateImagenModel, se necessario).
• 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, potresti dover attendere un paio di minuti prima che venga propagato sui server Firebase prima di potervi accedere 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.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 = response.result;
const text = response.text();

Passaggi successivi

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

• Scopri i dettagli su formato e sintassi del modello, insieme ad alcuni esempi.

• Gestisci i modelli, inclusi modifica, blocco e controllo delle versioni.