Pierwsze kroki z szablonami promptów serwera

W każdym żądaniu do modelu wysyłasz prompta i opcjonalnie schemat oraz 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ślić je po stronie serwera za pomocą szablonów promptów serwera.

Gdy używasz szablonów promptów serwera, przechowujesz prompt, schemat i konfiguracje 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 zalety tego podejścia:

• Ochrona przed ujawnieniem prompta po stronie klienta

• Aktualizowanie prośby 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 obsługuje Firebase AI Logic, z wyjątkiem modeli Gemini Live API.

• 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 konsoli Firebase.

2. Przetestuj szablon w prawdziwym żądaniu, korzystając z funkcji testowania w konsoli Firebase.

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

Podstawowy format szablonu prompta serwera

W przypadku Firebase AI Logic konsola Firebase udostępnia interfejs z instrukcjami, który umożliwia określenie sekcji z metadanymi i treści 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 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 między potrójnymi kreskami zawiera nazwę modelu oraz opcjonalnie konfigurację modelu, walidację danych wejściowych lub schemat, który chcesz wysłać w żądaniu. Jest on zapisany jako pary klucz-wartość i jest powszechnie nazywany sekcją z metadanymi 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.
  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}");
}

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 nie korzystasz z tej usługi, zapoznaj się z przewodnikiem dla początkujących, w którym opisano, jak skonfigurować projekt w Firebase, połączyć aplikację z Firebase, dodać pakiet SDK, zainicjować usługę backendu dla wybranego dostawcy Gemini API 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ą 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
  • firebasevertexai.googleapis.com/promptTemplates.updateLock

• Jeśli używasz Agent Platform Gemini API (formerly Vertex AI) i Twoje zastosowanie wymaga ograniczeń związanych z lokalizacją, 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 tworzy się i zarządza nimi w konsoli Firebase.

1. W konsoli Firebase otwórz Usługi AI > AI Logic > karta Szablony promptów.

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

   • Te szablony początkowe zawierają format i składnię dla niektórych typowych przypadków użycia. Niezależnie od wybranej opcji możesz 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 wyświetlana nazwa 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ę odwoływać do tego identyfikatora 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 zmodyfikuj sekcję Konfiguracja (sekcja z metadanymi) szablonu.

   • Ta sekcja musi zawierać co najmniej nazwę modelu, na przykład:

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

   • Możesz też opcjonalnie określić konfigurację modelu oraz 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 and (as applicable) system instructions (Prompt i instrukcje systemowe, jeśli dotyczy) szablonu.

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

     Write a story about a magic backpack.
     

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

     • (Opcjonalnie i w odpowiednich przypadkach) Podaj instrukcje systemowe, używając składni {{role "system"}}, a prompt tekstowy, używając składni {{role "user"}}.

     • (Opcjonalnie) Określ zmienne wejściowe za pomocą składni Handlebars (np. {{customerName}}). Możesz podać wartość domyślną w szablonie, 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 umożliwia testowanie szablonu. Dzięki temu możesz zobaczyć, co się stanie, gdy użyjesz szablonu – zarówno format żądania, jak i wynik rzeczywistego żądania.

1. Kliknij Zapisz szablon, aby przetestować szablon.

   Zawsze możesz później edytować lub 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, wpisz wartości testowe w polu Dane wejściowe testu. 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ć do żądania testowego. Jeśli ta opcja jest wyświetlana w konsoli, wybierz Gemini Developer API lub Agent Platform Gemini API (dawniej Vertex AI).

   Pamiętaj, że ten wybór dotyczy tylko żądań przesłanych za pomocą konsoli Firebase. W rzeczywistym żądaniu z aplikacji określasz wybranego dostawcę Gemini API tak samo jak w przypadku każdego innego żądania.

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

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

   Rozwiń, aby wyświetlić przykładowe sformatowane żądanie testowe

   {
     "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 prompta.

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

   Rozwiń, aby wyświetlić przykładową odpowiedź testową

   {
     "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 poziomu kodu aplikacji, zablokuj szablon, klikając ikonę lock blokady w prawym górnym rogu szablonu.

7. Kliknij Zamknij, aby wyjść z trybu edycji.

Krok 3. Uzyskaj dostęp do szablonu z poziomu kodu

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

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

Pamiętaj, że po utworzeniu lub zaktualizowaniu szablonu może być konieczne odczekanie kilku minut, aż szablon zostanie rozpowszechniony na serwerach Firebase, zanim 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.
  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}");
}

Co dalej?

• Dowiedz się więcej o sprawdzonych metodach i kwestiach do rozważenia podczas korzystania z szablonów promptów serwera.

• Dowiedz się więcej o formacie i składni szablonu oraz zapoznaj się z przykładami.

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

• Dowiedz się więcej o zaawansowanych przepływach pracy, takich jak automatyczna praca z szablonami przy użyciu interfejsu API typu REST lub wdrażanie szablonów w określonych lokalizacjach.