Erste Schritte mit Server-Promptvorlagen

In jeder Anfrage an ein Modell senden Sie einen Prompt und optional ein Schema und Konfigurationen, um die Antwort des Modells zu steuern. Wenn Sie Firebase AI Logic verwenden, können Sie alle diese Informationen direkt aus Ihrem Clientcode senden oder diese Informationen serverseitig mit Server-Prompt-Vorlagen angeben.

Wenn Sie Server-Prompt-Vorlagen verwenden, speichern Sie Ihren Prompt, Ihr Schema und Ihre Konfigurationen serverseitig. Die Codebasis Ihrer Anwendung übergibt vom Client an den Server nur einen Schlüssel (die Vorlagen-ID), der auf eine bestimmte Vorlage verweist, sowie die erforderlichen Eingaben für diese Vorlage. Hier sind einige Vorteile dieses Ansatzes:

• Prompt vor Offenlegung auf der Clientseite schützen

• Prompt und Konfiguration aktualisieren, ohne eine neue App-Version zu veröffentlichen

In dieser Anleitung wird beschrieben, wie Sie mit Server-Prompt-Vorlagen beginnen.

arrow_downward Zur Übersicht arrow_downward Zur detaillierten Anleitung

Unterstützte Modelle und Funktionen

• Sie können Server-Prompt-Vorlagen mit allen Gemini-Modellen verwenden, die von Firebase AI Logic unterstützt werden, mit Ausnahme von Gemini Live API-Modellen.

• Sehen Sie sich die Liste der noch nicht unterstützten Funktionen an.

Gesamtübersicht

Der grundlegende Workflow für die Verwendung von Server-Promptvorlagen sieht so aus:

1. Erstellen Sie die Vorlage mithilfe der geführten Benutzeroberfläche in der Firebase-Console.

2. Testen Sie die Vorlage in einer echten Anfrage mit der Testumgebung in der Firebase-Konsole.

3. Greifen Sie mit templateGenerativeModel über den Code Ihrer App auf die Vorlage zu.

Grundlegendes Format einer Server-Prompt-Vorlage

Für Firebase AI Logic bietet die Firebase-Console eine geführte Benutzeroberfläche, auf der Sie die Frontmatter und den Inhalt der Vorlage angeben können.

Server-Prompt-Vorlagen verwenden eine Dotprompt-basierte Syntax und ein Dotprompt-basiertes Format. Weitere Informationen finden Sie unter Format, Syntax und Beispiele für Vorlagen.

Die folgende Beispielvorlage zeigt die wichtigsten Komponenten einer Vorlage für eine Beispielanfrage an ein Gemini-Modell:

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

• Der obere Abschnitt innerhalb der drei Bindestriche enthält den Modellnamen sowie optional die Modellkonfiguration, die Eingabevalidierung oder das Schema, das Sie in der Anfrage senden möchten. Die Daten werden in Schlüssel/Wert-Paaren angeordnet und werden im Allgemeinen als Frontmatter bezeichnet.

• Der Text der Vorlage enthält den Prompt. Optional können auch Systemanweisungen und Eingabewerte (mit Handlebars-Syntax) enthalten sein.

Vorlage im Code verwenden

Der folgende Beispiel-Clientcode zeigt, wie Sie die Vorlage in Ihrem Code verwenden:

// ...

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

Detaillierte Anleitung

In diesem Abschnitt finden Sie eine detaillierte Anleitung zum Erstellen, Testen und Verwenden von Server-Prompt-Vorlagen.

Hinweis

• Falls noch nicht geschehen, folgen Sie dem Startleitfaden. Dort wird beschrieben, wie Sie Ihr Firebase-Projekt einrichten, Ihre App mit Firebase verbinden, das SDK hinzufügen, den Backend-Dienst für den ausgewählten Gemini API-Anbieter initialisieren und eine GenerativeModel-Instanz erstellen.

• Prüfen Sie, ob Sie die erforderlichen Berechtigungen zum Erstellen und Verwalten von Server-Prompt-Vorlagen haben. Standardmäßig sind alle diese Berechtigungen in der Rolle „Inhaber“ enthalten.

  Erforderliche Berechtigungen ansehen

  • 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

• Wenn Sie Agent Platform Gemini API (formerly Vertex AI) verwenden und Ihr Anwendungsfall standortbasierte Einschränkungen erfordert, unterstützen wir erweiterte Workflows für Vorlagen.

Schritt 1: Server-Prompt-Vorlage erstellen

In den meisten Anwendungsfällen erstellen und verwalten Sie Server-Prompt-Vorlagen in der Firebase-Konsole.

1. Rufen Sie in der Firebase-Konsole die Seite KI-Dienste > AI Logic > Tab Prompt-Vorlagen auf.

2. Klicken Sie auf Neue Vorlage erstellen und wählen Sie eine Startvorlage aus.

   • Diese Startvorlagen enthalten das Format und die Syntax für einige gängige Anwendungsfälle. Unabhängig davon, welche Option Sie auswählen, können Sie die Vorlage vollständig an Ihre Anforderungen anpassen.

   • In diesem Startleitfaden wird davon ausgegangen, dass Sie die Option Input + System Instructions ausgewählt haben.

3. Geben Sie die IDs der Vorlage ein:

   • Vorlagenname: Dies ist ein Anzeigename für die Vorlage (z. B. My First Template). Er ist nur in Firebase-Oberflächen wie der Firebase Console sichtbar.

   • Vorlagen-ID: Dies muss eine eindeutige ID für die Vorlage in Ihrem Firebase-Projekt sein (z. B. my-first-template-v1-0-0). Sie verweisen in der Anfrage von Ihrer App auf diese ID.

     • Wir empfehlen, für Ihre Vorlagen-IDs ein Versionssystem zu verwenden.

     • Vorlagen-IDs dürfen maximal 63 Zeichen lang sein und können Kleinbuchstaben, Ziffern und Bindestriche enthalten.

4. Ändern Sie den Abschnitt Konfiguration (Frontmatter) der Vorlage nach Bedarf.

   • Dieser Abschnitt muss mindestens einen Modellnamen enthalten, z. B.:

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

   • Optional können Sie auch die Konfiguration des Modells und beliebige Ein- und Ausgabesteuerelemente usw. angeben. Weitere Informationen und Optionen finden Sie unter Vorlagenformat, Syntax und Beispiele.

5. Ändern Sie den Abschnitt Prompt und (falls zutreffend) Systemanweisungen der Vorlage nach Bedarf.

   • Dieser Abschnitt muss mindestens den Text-Prompt enthalten, der an das Modell gesendet werden soll.

     Write a story about a magic backpack.
     

   • Sie können auch komplexere Prompts erstellen, wie die folgenden Optionen zeigen. Weitere Informationen und Optionen finden Sie unter Format, Syntax und Beispiele für Vorlagen.

     • (Optional und falls zutreffend) Geben Sie Systemanweisungen mit der Syntax {{role "system"}} und den Text-Prompt mit der Syntax {{role "user"}} an.

     • (Optional) Geben Sie Eingabevariablen mit der Handlebars-Syntax an (z. B. {{customerName}}). Sie können einen Standardwert in der Vorlage angeben, aber der Wert dieser Eingabevariablen wird normalerweise in der Anfrage übergeben.

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

Schritt 2: Testen Sie Ihre Vorlage in der Firebase-Konsole.

Die Firebase-Konsole bietet eine Testumgebung für Ihre Vorlage. So können Sie sehen, was passiert, wenn Ihre Vorlage verwendet wird – sowohl das Format der Anfrage als auch die Ausgabe einer tatsächlichen Anfrage.

1. Klicken Sie auf Vorlage speichern, um die Vorlage zu testen.

   Sie können die Vorlage später jederzeit bearbeiten oder sogar löschen. Der einzige Wert, den Sie später nicht mehr ändern können, ist die Vorlagen-ID.

2. Wenn Ihr Prompt Eingabevariablen verwendet, geben Sie Testwerte in das Feld Testeingabe ein. In diesem Beispiel:

     {
       "customerName": "Jane"
     }
   

3. Wenn Sie in Ihrem Firebase-Projekt mehrere Gemini API-Anbieter aktiviert haben, können Sie auswählen, welcher für die Testanfrage verwendet werden soll. Wenn diese Option in der Console angezeigt wird, wählen Sie entweder Gemini Developer API oder Agent Platform Gemini API (früher Vertex AI) aus.

   Diese Auswahl gilt nur für Anfragen, die über die Testumgebung der Firebase Console gesendet werden. In der tatsächlichen Anfrage Ihrer App geben Sie den ausgewählten Gemini API-Anbieter wie bei jeder anderen Anfrage an.

4. Klicken Sie auf den Button Formatierte Testanfrage erstellen.

   Sehen Sie sich die resultierende Formatierte Testanfrage auf der rechten Seite des Bildschirms an und iterieren Sie über die Felder Ihrer Vorlage.

   Maximieren, um ein Beispiel für eine formatierte Testanfrage anzusehen

   {
     "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. Wenn Sie mit der formatierten Testanfrage zufrieden sind, klicken Sie auf den Button Prompt-Test ausführen.

   Sehen Sie sich die resultierende Testantwort auf der rechten Seite des Bildschirms an und passen Sie die Felder Ihrer Vorlage an.

   Maximieren, um die Beispielantwort des Tests anzusehen

   {
     "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. Wenn Sie bereit sind, über den Code Ihrer Anwendung auf die Vorlage zuzugreifen, sperren Sie die Vorlage, indem Sie rechts oben in der Vorlage auf das lock-Schlosssymbol klicken.

7. Klicken Sie auf Schließen, um den Bearbeitungsmodus zu verlassen.

Schritt 3: Über den Code auf die Vorlage zugreifen

Eine Anfrage mit einer Server-Prompt-Vorlage sieht ähnlich aus wie andere Anfragen, mit den folgenden Anpassungen:

• Verwenden Sie einen templateGenerativeModel.
• Geben Sie die Vorlagen-ID an.
• Geben Sie die Werte aller Variableneingaben an, die für Ihre Vorlage erforderlich sind.

Nachdem Sie Ihre Vorlage erstellt oder aktualisiert haben, müssen Sie möglicherweise einige Minuten warten, bis die Vorlage auf den Firebase-Servern bereitgestellt wurde, bevor Sie über Ihren Code darauf zugreifen können.

// ...

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

Nächste Schritte

• Best Practices und Überlegungen für die Verwendung von Server-Promptvorlagen

• Details zum Vorlagenformat und zur Syntax sowie Beispiele

• Vorlagen verwalten, einschließlich Bearbeitung, Sperrung und Versionsverwaltung

• Erweiterte Workflows, z. B. programmatisch mit Vorlagen über die REST API arbeiten oder Vorlagen an bestimmten Standorten bereitstellen