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. Jeśli korzystasz z 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.

W przypadku 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 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 i Imagen, które Firebase AI Logic obsługuje, z wyjątkiem modeli Gemini Live.

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

Ogólne omówienie

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, 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 z instrukcjami, który pomaga określić metadane 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.

Przykładowy szablon poniżej pokazuje najważniejsze komponenty szablonu dla przykładowego żądania do modelu Gemini:

---
model: 'gemini-3.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 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 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.

  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

• 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 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ę w przypadku niektórych typowych zastosowań. 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 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.5-flash'
     ---
     

   • Możesz też opcjonalnie określić konfigurację modelu oraz wszelkie elementy sterujące danymi wejściowymi i wyjściowymi 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 Firebase konsoli.

Firebase Konsola umożliwia testowanie szablonu. Dzięki temu możesz sprawdzić, 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, 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 żądań przesyłanych w ramach testów w Firebasekonsoli. W rzeczywistym żądaniu z aplikacji wybierasz Gemini APIdostawcę 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.

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

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3.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. Gdy sformatowana prośba testowa będzie odpowiednia, 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.5-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 wyjść z trybu edycji, 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ń, z tymi zmianami:

• Użyj znaku templateGenerativeModel (lub templateImagenModel, w zależności od potrzeb).
• 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.

// ...

// 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ą naszego interfejsu REST API czy wdrażanie szablonów w określonych lokalizacjach.