Pierwsze kroki z szablonami promptów serwera


W każdym żądaniu wysyłanym do modelu przesyłasz prompt oraz opcjonalnie schemat i konfiguracje, aby kontrolować odpowiedź modelu. Jeśli 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 aplikacja przekazuje z klienta na serwer tylko klucz (identyfikator szablonu) odwołujący się do konkretnego szablonu oraz wymagane dane wejściowe dla tego szablonu.

Gdy używasz szablonów promptów serwera, prompt i konfiguracje są przechowywane po stronie serwera, a w kodzie aplikacji podajesz tylko klucz (identyfikator szablonu). Oto kilka zalet 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.

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

Obsługiwane modele i możliwości


Ogólny przegląd

Oto podstawowy proces korzystania z szablonów promptów serwera:

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

  2. Przetestuj szablon w rzeczywistym żądaniu za pomocą Firebasekonsoli.

  3. Otwórz szablon w aplikacji.

Podstawowy format szablonów promptów serwera

W przypadku Firebase AI Logic konsola Firebase udostępnia interfejs z instrukcjami, który pozwala określić zawartość szablonu.

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

Oto najważniejsze komponenty przykładowego żądania do modelu 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}}.

  • 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 frontmatterem 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

Kliknij Gemini API dostawcę, aby wyświetlić na tej stronie treści i kod specyficzne dla tego dostawcy.

Oto jak użyć szablonu w kodzie:

Swift 


// ...

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

Kotlin 


// ...

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

Java 


// ...

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

Web 


// ...

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

Dart

Wtyczka Flutter wkrótce będzie obsługiwać szablony promptów serwera.

Unity

Pakiet Unity wkrótce będzie obsługiwać szablony promptów serwera.


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 zrobiono, 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 dostawcy Gemini API 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ściciela.

  • Jeśli używasz Vertex AI Gemini API i Twój przypadek użycia wymaga ograniczeń opartych 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 kartę Firebase AI Logic 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 konsoli Firebase.

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

      • Zalecamy korzystanie z systemu 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-2.5-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 zmień sekcję Prompt and (as applicable) system instructions (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) podaj instrukcje systemowe, używając składni {{role "system"}}, a tekstowy prompt – 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 prośby, jak i wynik rzeczywistej prośby.

  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, podaj wartości testowe w polu Test input (Testowe dane wejściowe). 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 testu. Jeśli ta opcja jest widoczna w konsoli, wybierz Gemini Developer API lub Vertex AI Gemini API.

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

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

    Sprawdź sformatowane żądanie testowe po prawej stronie ekranu i wprowadź zmiany w polach szablonu.

  5. Gdy sformatowana prośba testowa będzie gotowa, kliknij przycisk Uruchom test promptu.

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

  6. Jeśli chcesz uzyskać dostęp do szablonu z kodu aplikacji, zablokuj go, klikając ikonę blokady w prawym górnym rogu szablonu.

  7. Aby wyjść z trybu edycji, kliknij Zamknij.

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

Kliknij Gemini API dostawcę, aby wyświetlić na tej stronie treści i kod specyficzne dla tego dostawcy.

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

  • Użyj templateGenerativeModel (lub w razie potrzeby templateImagenModel).
  • Podaj identyfikator szablonu.
  • Podaj wartości wszystkich zmiennych wejściowych wymaganych przez szablon.

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

Swift

Utwórz instancję templateGenerativeModel (lub templateImagenModel), aby użyć szablonu w żądaniu.


// ...

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

Kotlin

Utwórz instancję templateGenerativeModel (lub templateImagenModel), aby użyć szablonu w żądaniu.


// ...

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

Java

Utwórz instancję templateGenerativeModel (lub templateImagenModel), aby użyć szablonu w żądaniu.


// ...

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

Web

Utwórz instancję templateGenerativeModel (lub templateImagenModel), aby użyć szablonu w żądaniu.


// ...

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

Dart

Wtyczka Flutter wkrótce będzie obsługiwać szablony promptów serwera.

Unity

Pakiet Unity wkrótce będzie obsługiwać szablony promptów serwera.


Co dalej?