Pierwsze kroki z szablonami promptów serwera


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

Gdy korzystasz z 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 korzystasz z szablonów promptów serwera, prompt i konfiguracje są przechowywane po stronie serwera, a w kodzie aplikacji podajesz tylko klucz (identyfikator 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.

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

Obsługiwane modele i funkcje


Ogólne omówienie

Oto podstawowy przepływ pracy związany z używaniem szablonów promptów serwera:

  1. Utwórz szablon za pomocą interfejsu z przewodnikiem w Firebase konsoli.

  2. Przetestuj szablon w rzeczywistym żądaniu za pomocą funkcji testowania w konsoli Firebase.

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

Podstawowy format szablonu promptu serwera

W przypadku Firebase AI Logic konsola Firebase udostępnia interfejs z przewodnikiem, w którym możesz określić nagłówek i 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.

Poniższy przykładowy szablon pokazuje najważniejsze komponenty szablonu na potrzeby przykładowego żądania do modelu Gemini:

---
model: 'gemini-3-flash-preview'
---

{{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 między potrójnymi kreskami zawiera nazwę modelu oraz opcjonalnie konfigurację modelu, sprawdzanie poprawności danych wejściowych lub schemat, które chcesz wysłać w żądaniu. Jest ona zapisana jako pary klucz-wartość i zwykle nazywana nagłówkiem 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 swojego dostawcę Gemini API, aby wyświetlić na tej stronie treści i kod specyficzne dla dostawcy.

Poniższy przykładowy kod klienta pokazuje, jak używać 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.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)

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

Dart 


// ...

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

Unity 


// ...

// 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 dotyczące 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 w Firebase, połączyć aplikację z Firebase, dodać pakiet SDK, zainicjować usługę backendu dla wybranego Gemini API dostawcy i utworzyć instancję GenerativeModel.

  • Upewnij się, że masz wymagane uprawnienia do tworzenia szablonów promptów serwera i zarządzania nimi. Domyślnie wszystkie te uprawnienia są zawarte w roli Właściciel.

  • Jeśli używasz interfejsu 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 promptu serwera

W większości przypadków szablony promptów serwera tworzysz i zarządzasz nimi w Firebase konsoli.

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

  2. Kliknij Utwórz nowy szablon i wybierz opcję szablonu początkowego.

    • Te szablony początkowe zawierają format i składnię w przypadku 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 dla początkujących zakładamy, że wybrano opcję Input + System Instructions.

  3. Wpisz identyfikatory szablonu:

    • Nazwa szablonu: jest to nazwa wyświetlana szablonu (np. My First Template). Jest ona widoczna tylko w interfejsach Firebase, takich jak konsola 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 używanie systemu obsługi wersji 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 (nagłówek) szablonu.

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

      ---
model: 'gemini-3-flash-preview'
---

    • Możesz też opcjonalnie określić konfigurację modelu oraz wszelkie elementy sterujące danymi wejściowymi i& wyjściowymi itp. Więcej informacji i opcji znajdziesz w artykule Format, składnia i przykłady szablonów.

  5. W razie potrzeby zmień sekcję Prompt i (w stosownych przypadkach) instrukcje systemowe szablonu.

    • Ta sekcja musi zawierać co najmniej prompt tekstowy, który ma zostać wysłany do modelu.

      Write a story about a magic backpack.

    • Możesz też tworzyć bardziej złożone prompty, np. za pomocą tych opcji. 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"}}, oraz prompt tekstowy za pomocą {{role "user"}} składni.

      • (Opcjonalnie) Określ zmienne wejściowe za pomocą Handlebars składni (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

Konsola Firebase udostępnia funkcję testowania szablonu. Dzięki niej możesz zobaczyć, co się stanie, gdy szablon zostanie użyty – zarówno format żądania, jak i dane wyjściowe rzeczywistego żądania.

  1. Aby móc przetestować szablon, kliknij Zapisz szablon.

    Szablon możesz później edytować lub nawet usunąć. 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 Dane wejściowe testu 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 żądaniu testowym. 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 żądań przesyłanych za pomocą funkcji testowania w Firebase konsoli. W rzeczywistym żądaniu z aplikacji, określasz wybranego dostawcę Gemini API tak samo jak w przypadku każdego żądania.

  4. Kliknij przycisk Utwórz sformatowane żądanie testowe.

    Sprawdź sformatowane żądanie testowe po prawej stronie ekranu i iteruj w dowolnym polu szablonu.

  5. Gdy sformatowane żądanie testowe będzie odpowiednie, kliknij przycisk Uruchom test promptu.

    Sprawdź odpowiedź testową po prawej stronie ekranu i iteruj w dowolnym polu szablonu.

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

  7. Aby zamknąć edytor, kliknij Zamknij.

Krok 3: uzyskaj dostęp do szablonu z kodu

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

Żądanie korzystające z szablonu promptu serwera wygląda podobnie do innych żądań, z tym że trzeba wprowadzić te zmiany:

  • 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 szablon zostanie rozpowszechniony na serwerach Firebase i będzie można uzyskać do niego dostęp z kodu.

Swift

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


// ...

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

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


// ...

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

Java

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


// ...

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

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


// ...

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

Dart

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

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


// ...

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

Unity

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


// ...

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