Pierwsze kroki z szablonami promptów serwera

W każdym żądaniu wysyłanym do modelu przesyłasz prompt, a opcjonalnie schemat i konfiguracje, aby kontrolować odpowiedź modelu. Gdy używasz Firebase AI Logic, możesz wysyłać wszystkie te informacje bezpośrednio z kodu klienta lub określać je po stronie serwera za pomocą szablonów promptów serwera.

Gdy używasz szablonów promptów serwera, prompt, schemat i konfiguracje są przechowywane po stronie serwera, a baza kodu aplikacji przekazuje z klienta na serwer tylko klucz (identyfikator szablonu) odwołujący się do konkretnego szablonu oraz wymagane dane wejściowe dla tego szablonu. Oto niektóre korzyści tego podejścia:

• Ochrona przed ujawnieniem promptu po stronie klienta

• Aktualizowanie promptu i konfiguracji bez publikowania nowej wersji aplikacji

Z tego przewodnika dowiesz się, jak zacząć korzystać z szablonów promptów serwera.

arrow_downward Przejdź do ogólnego omówienia arrow_downward Przejdź do szczegółowych instrukcji

Obsługiwane modele i możliwości

• Używaj szablonów promptów serwera z dowolnymi modelami Gemini, które Firebase AI Logicobsługują (z wyjątkiem modeli Gemini Live API).

• Zapoznaj się z listą funkcji, które nie są jeszcze obsługiwane.

Ogólny przegląd

Oto podstawowy cykl pracy z szablonami promptów serwera:

1. Utwórz szablon za pomocą interfejsu z instrukcjami w Firebasekonsoli.

2. Przetestuj szablon w ramach rzeczywistego żądania, korzystając z funkcji testowania w Firebasekonsoli.

3. Uzyskaj dostęp do szablonu z kodu aplikacji za pomocą funkcji templateGenerativeModel.

Podstawowy format szablonu prompta serwera

W przypadku Firebase AI Logic Firebase konsola udostępnia interfejs użytkownika z instrukcjami, który umożliwia określenie sekcji z metadanymi i zawartości szablonu.

Szablony promptów serwera korzystają ze składni i formatu opartego na Dotprompt. Więcej informacji znajdziesz w artykule Format, składnia i przykłady szablonów.

Przykładowy szablon poniżej pokazuje najważniejsze komponenty szablonu dla przykładowego żądania do modelu 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}}.

• Górna sekcja w potrójnych myślnikach zawiera nazwę modelu oraz opcjonalnie konfigurację modelu, weryfikację danych wejściowych lub schemat, które chcesz wysłać w żądaniu. Jest on zapisany jako pary klucz-wartość i jest powszechnie nazywany frontmatter w YAML.

• Treść szablonu zawiera prompt. Może też opcjonalnie zawierać instrukcje systemowe i wartości wejściowe (przy użyciu składni Handlebars).

Używanie szablonu w kodzie

Poniższy przykładowy kod klienta pokazuje, jak używać szablonu w kodzie:

// ...

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

Szczegółowe instrukcje

W tej sekcji znajdziesz szczegółowe instrukcje tworzenia, testowania i używania szablonów promptów serwera.

Zanim zaczniesz

• Jeśli jeszcze tego nie zrobisz, zapoznaj się z przewodnikiem dla początkujących, w którym opisujemy, jak skonfigurować projekt Firebase, połączyć aplikację z Firebase, dodać pakiet SDK, zainicjować usługę backendu dla wybranego Gemini APIdostawcy i utworzyć instancję GenerativeModel.

• Sprawdź, czy masz wymagane uprawnienia do tworzenia szablonów promptów serwera i zarządzania nimi. Domyślnie wszystkie te uprawnienia są uwzględnione w roli Właściciel.

  Wyświetl wymagane uprawnienia

  • 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

• Jeśli używasz Agent Platform Gemini API (formerly Vertex AI) i w Twoim przypadku wymagane są ograniczenia oparte na lokalizacji, obsługujemy zaawansowane przepływy pracy w przypadku szablonów.

Krok 1. Utwórz szablon prompta serwera

W większości przypadków szablony promptów serwera tworzy się i zarządza nimi w konsoli Firebase.

1. W konsoli Firebase otwórz Usługi AI > Logika AI > kartę Szablony promptów.

2. Kliknij Utwórz nowy szablon i wybierz szablon początkowy.

   • Te szablony początkowe zawierają format i składnię niektórych typowych przypadków użycia. Niezależnie od wybranej opcji możesz jednak całkowicie zmienić szablon, aby dostosować go do swoich potrzeb.

   • W tym przewodniku zakładamy, że wybrano opcję Input + System Instructions.

3. Wpisz identyfikatory szablonu:

   • Nazwa szablonu: wyświetlana nazwa szablonu (np.My First Template). Jest widoczna tylko w interfejsach Firebase, np. w Firebase konsoli.

   • Identyfikator szablonu: musi to być unikalny identyfikator szablonu w projekcie w Firebase (np. my-first-template-v1-0-0). Będziesz się do niego odwoływać w żądaniu z aplikacji.

     • Zalecamy używanie systemu obsługi wersji w przypadku identyfikatorów szablonów.

     • Identyfikatory szablonów mogą mieć maksymalnie 63 znaki i mogą zawierać małe litery, cyfry i łączniki.

4. W razie potrzeby zmień sekcję Konfiguracja (frontmatter) szablonu.

   • Ta sekcja musi zawierać co najmniej nazwę modelu, np.:

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

   • Możesz też opcjonalnie określić konfigurację modelu oraz wszelkie ustawienia wejścia i wyjścia itp. Więcej szczegółów i opcji znajdziesz w sekcji Format, składnia i przykłady szablonów.

5. W razie potrzeby zmodyfikuj sekcję Prompt i (w stosownych przypadkach) instrukcje systemowe w szablonie.

   • Ta sekcja musi zawierać co najmniej prompt tekstowy do wysłania do modelu.

     Write a story about a magic backpack.
     

   • Możesz też tworzyć bardziej złożone prompty, np. te poniżej. Więcej informacji i opcji znajdziesz w artykule Format, składnia i przykłady szablonów.

     • (Opcjonalnie i w stosownych przypadkach) Określ instrukcje systemowe za pomocą składni {{role "system"}} i tekstowy prompt za pomocą składni {{role "user"}}.

     • (Opcjonalnie) określ zmienne wejściowe za pomocą składni Handlebars (np. {{customerName}}). W szablonie możesz podać wartość domyślną, ale wartość tej zmiennej wejściowej jest zwykle przekazywana w żądaniu.

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

Krok 2. Przetestuj szablon w konsoli Firebase.

Firebase Konsola umożliwia testowanie szablonu. Dzięki temu możesz zobaczyć, co się stanie, gdy szablon zostanie użyty – zarówno format żądania, jak i wynik rzeczywistego żądania.

1. Kliknij Zapisz szablon, aby móc go przetestować.

   Zawsze możesz później edytować lub nawet usunąć szablon. Jedyną wartością, której nie można później zmienić, jest identyfikator szablonu.

2. Jeśli prompt używa zmiennych wejściowych, w polu Test input (Test input) podaj wartości testowe. W tym przykładzie:

     {
       "customerName": "Jane"
     }
   

3. Jeśli w projekcie Firebase masz włączonych kilku dostawców Gemini API, możesz wybrać, którego z nich chcesz użyć w przypadku żądania testowego. Jeśli ta opcja jest widoczna w konsoli, wybierz Gemini Developer API lub Agent Platform Gemini API (wcześniej Vertex AI).

   Pamiętaj, że ten wybór dotyczy tylko próśb przesłanych w ramach Firebasetestowania w konsoli. W rzeczywistym żądaniu z aplikacji podajesz wybranego dostawcę Gemini API tak samo jak w przypadku każdego żądania.

4. Kliknij przycisk Utwórz sformatowaną prośbę o test.

   Sprawdź sformatowaną prośbę testową po prawej stronie ekranu i wprowadź zmiany w polach szablonu.

   Rozwiń, aby wyświetlić przykładową sformatowaną prośbę o test

   {
     "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. Gdy sformatowana prośba testowa będzie Ci odpowiadać, kliknij przycisk Uruchom test promptu.

   Sprawdź odpowiedź testową po prawej stronie ekranu i wprowadź zmiany w polach szablonu.

   Rozwiń, aby wyświetlić przykładową odpowiedź na 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. Jeśli chcesz uzyskać dostęp do szablonu z kodu aplikacji, zablokuj go, klikając ikonę lock blokady w prawym górnym rogu szablonu.

7. Aby zamknąć edytor, kliknij Zamknij.

Krok 3. Uzyskaj dostęp do szablonu za pomocą kodu

Żądanie korzystające z szablonu prompta serwera wygląda podobnie do innych żądań, ale z tymi zmianami:

• Użyj templateGenerativeModel.
• Podaj identyfikator szablonu.
• Podaj wartości wszystkich zmiennych wejściowych wymaganych przez szablon.

Pamiętaj, że po utworzeniu lub zaktualizowaniu szablonu może być konieczne odczekanie kilku minut, zanim zostanie on rozpowszechniony na serwerach Firebase i będzie można uzyskać do niego dostęp z poziomu kodu.

// ...

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

Co dalej?

• Dowiedz się więcej o sprawdzonych metodach i kwestiach, które warto wziąć pod uwagę podczas korzystania z szablonów promptów na serwerze.

• Dowiedz się więcej o formacie i składni szablonu oraz zobacz przykłady.

• Dowiedz się więcej o zarządzaniu szablonami, w tym o edytowaniu, blokowaniu i kontroli wersji.

• Dowiedz się więcej o zaawansowanych przepływach pracy, takich jak programowe korzystanie z szablonów za pomocą interfejsu REST API lub wdrażanie szablonów w określonych lokalizacjach.