Format, składnia i przykłady szablonów


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

Szablony promptów serwera korzystają ze składni i formatu opartego na Dotprompt. Na tej stronie znajdziesz szczegółowe opisy formatu i składni szablonu oraz przykłady.

Oto najważniejsze komponenty 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).


Na tej stronie znajdziesz szczegółowe opisy formatu i składni szablonu oraz przykłady dotyczące tych elementów:

Wszystkie przykłady na tej stronie pokazują szablony, które używają modelu gemini-3.8-flash, ale możesz użyć dowolnego modelu Gemini obsługiwanego przez Firebase AI Logic (z wyjątkiem modeli Gemini Live).

Hello world

Oto minimalny przykład szablonu prompta serwera:

Konfiguracja (frontmatter)

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

Prompt i (w stosownych przypadkach) instrukcje systemowe

Write a story about a magic backpack.



Kontrolowanie generowania odpowiedzi

Możesz kontrolować generowanie odpowiedzi na różne sposoby w zależności od zastosowania i wymaganego poziomu kontroli.

Konfiguracja modelu

Ustaw konfigurację modelu, aby określić sposób generowania odpowiedzi przez model, np. liczbę wariantów odpowiedzi (candidateCount), maksymalną liczbę tokenów wyjściowych itp.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
config:
  candidateCount: 1
  maxOutputTokens: 200
  stopSequences: ["red"]
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Write a story about a magic backpack.


Konfiguracja myślenia

Określ konfigurację związaną z myśleniem w przypadku modeli, które obsługują myślenie.

Konfiguracja (frontmatter)

  • Gemini 3.x i nowsze modele (poziomy myślenia)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • Gemini 2.5 modeli (budżetów na myślenie)

    ---
    model: 'gemini-2.5-flash'
    config:
      thinkingConfig:
        thinkingBudget: 1024
        includeThoughts: true
    ---
    

Prompt i (w stosownych przypadkach) instrukcje systemowe

Solve x^2 + 4x + 4 = 0


Ustawienia bezpieczeństwa

Użyj ustawień bezpieczeństwa, aby dostosować prawdopodobieństwo otrzymania odpowiedzi, które mogą być uznane za szkodliwe.

Konfiguracja (frontmatter)

Przykład z 1 ustawieniem bezpieczeństwa:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
---

Przykład z wieloma ustawieniami bezpieczeństwa:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
    - category: HARM_CATEGORY_HATE_SPEECH
      threshold: BLOCK_MEDIUM_AND_ABOVE
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Write a story about a magic backpack.


Instrukcje systemowe

Ustaw instrukcje systemowe, aby sterować działaniem modelu. Dodajesz je do promptu:

  • Określ instrukcje systemowe, używając składni {{role "system"}}.

  • Określ prompt tekstowy, używając składni {{role "user"}}.

Konfiguracja (frontmatter)

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

Prompt i (w stosownych przypadkach) instrukcje systemowe

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



Zmienne wejściowe

Niektóre prompty są statyczne, ale często musisz uwzględnić w nich dane użytkownika.

W prompcie możesz uwzględnić dynamiczne zmienne wejściowe za pomocą wyrażeń Handlebars, które są zawarte w tagach {{ }} w formacie {{variableName}} lub {{object.propertyName}} (np. Hello, {{name}} from {{address.city}}).

Konfiguracja (frontmatter)

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

Prompt i (w stosownych przypadkach) instrukcje systemowe

Create an example customer invoice for a customer named {{customerName}}.

W szablonie możesz podać wartość domyślną, ale wartość zmiennej wejściowej jest zwykle podawana przez klienta w ramach żądania.



Przepływy sterujące (pętle i warunki)

Aby pisać bardziej złożone prompty, możesz używać bloków warunkowych (np. #if, else i #unless) oraz iteracji (#each).

Możesz podać dodatkowe informacje kontekstowe jako zmienne ze specjalnym prefiksem @:

  • @first: wartość true, gdy iterowany jest pierwszy element bloku #each.
  • @last: wartość „true” (prawda), gdy iterowany jest ostatni element bloku #each.
  • @index: podaje indeks (liczony od zera) bieżącego elementu.

Informacje o wszystkich wbudowanych pomocnikach logicznych znajdziesz w dokumentacji Handlebars.

Konfiguracja (frontmatter)

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

Prompt i (w stosownych przypadkach) instrukcje systemowe

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}

Pamiętaj, że warunki akceptują tylko odwołanie do zmiennej, a nie żaden typ wyrażenia, np.:

  • Działa to w przypadku: {{#if isVipCustomer}} ... {{/if}}
  • To nie działa: {{#if customer.type == 'vip'}} ... {{/if}}

Jeśli zmienna jest wartością logiczną, warunek działa zgodnie z oczekiwaniami. Jeśli zmienna nie jest wartością logiczną, warunek jest w praktyce sprawdzaniem, czy zmienna nie ma wartości null. Może to być przydatne w przypadku obsługi opcjonalnych danych wejściowych, na przykład:

{{#if customerName}}
Hello {{customerName}}
{{else}}
Hello Guest
{{/if}}



Weryfikacja danych wejściowych i schemat

Jeśli masz dane pochodzące od klienta, zdecydowanie zalecamy użycie input schema, aby chronić się przed atakami typu wstrzykiwanie promptów i mieć pewność, że dane przekazywane w żądaniu są zgodne z Twoimi oczekiwaniami.

  • Możesz podać wartości domyślne na wypadek, gdyby klient nie podał żadnej wartości.

  • Schemat obsługuje typy skalarne string, integer, number, boolean i object. Obiekty, tablice i wyliczenia są oznaczane nawiasem po nazwie pola.

  • Wszystkie właściwości są uważane za wymagane, chyba że oznaczysz je jako opcjonalne za pomocą symbolu ?. Gdy właściwość jest oznaczona jako opcjonalna, staje się też dopuszczająca wartość null, co daje modelom LLM większą swobodę w zwracaniu wartości null zamiast pomijania pola.

Oto podstawowy przykład schematu danych wejściowych. Bardziej zaawansowany schemat znajdziesz poniżej.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  default:
    isVipCustomer: false
  schema:
    customerName: string, the customers name  # string, number, and boolean types are defined like this
    productNames?(array, list of products to include in the invoice): string  # optional fields are marked with a ?
    isVipCustomer?: boolean, whether or not the customer is a VIP
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}



Schemat wyjściowy

Jeśli chcesz, aby model generował uporządkowane dane wyjściowe JSON, możesz określić schemat wyjściowy. Określając format: json, ograniczasz model, aby zawsze zwracał odpowiedź w formacie JSON zgodną z określonym schematem.

  • Schemat obsługuje typy skalarne string, integer, number, boolean i object. Obiekty, tablice i wyliczenia są oznaczane nawiasem po nazwie pola.

  • Wszystkie właściwości są uważane za wymagane, chyba że oznaczysz je jako opcjonalne za pomocą symbolu ?. Gdy właściwość jest oznaczona jako opcjonalna, staje się też dopuszczająca wartość null, co daje modelom LLM większą swobodę w zwracaniu wartości null zamiast pomijania pola.

Oto podstawowy przykład generowania uporządkowanych danych wyjściowych JSON. Bardziej zaawansowany schemat znajdziesz poniżej.

Konfiguracja (frontmatter)

---
model: gemini-3.8-flash
output:
  format: json
  schema:
    invoiceId: string
    invoiceFile(object, an invoice file):
      url?: string
      contents: string
      mimeType: string
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Create an example customer invoice.



Dane wejściowe multimodalne

Prompty multimodalne wysyłane do modelu Gemini mogą zawierać różne typy danych wejściowych, w tym pliki (np. tekst wraz z obrazami, plikami PDF, plikami tekstowymi, dźwiękiem i filmem).

  • Podaj plik, używając jego adresu URL w składni {{media url}}.

  • Podaj plik wbudowany ze składnią {{media type="mime_type" data="contents"}}.

Podstawowy przykład (dane wejściowe multimodalne)

Oto podstawowy przykład podawania danych wejściowych w różnych formatach. Bardziej złożony przykład znajdziesz poniżej.

Konfiguracja (frontmatter)

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

Prompt i (w stosownych przypadkach) instrukcje systemowe

Describe this image

{{media type="mimeType" data="imageData"}}

Złożony przykład (dane wejściowe multimodalne)

Oto bardziej złożony przykład podawania danych multimodalnych.

Konfiguracja (frontmatter)

---
model: gemini-3.8-flash
input:
  schema:
    image_urls?(array, urls of external images): string
    inline_images?(array, inline image data):
      type: object
      properties:
        mime_type: string
        contents: string  # inline data must be base64-encoded
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

{{role "system"}}
Use the following image as the basis for comparisons
{{media url="http://example.com/reference_img.bmp"}}

{{role "user"}}
What do the following images have in common?

{{#each image_urls}}
  {{media url="this"}}
{{/each}}

{{#each inline_images}}
  {{media type="mime_type" data="contents"}}
{{/each}}



Korzystanie z narzędzi

Szablony promptów serwera obsługują te narzędzia:

Jeśli chcesz, aby użytkownicy podawali dodatkowe informacje w prośbie do modelu, użyj zmiennych wejściowych w szablonie prompta serwera wraz z weryfikacją danych wejściowych.

Wywoływanie funkcji

Pełny przewodnik po wywoływaniu funkcji za pomocą szablonów promptów serwera.

Wykonanie kodu

Narzędzie wykonywanie kodu umożliwia modelowi generowanie i uruchamianie kodu w Pythonie.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - codeExecution
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

What is the sum of the first 50 prime numbers?
Generate and run code for the calculation, and make sure you get all 50.

Kontekst adresu URL

Narzędzie URL context umożliwia przekazywanie do modelu dodatkowych informacji w postaci adresów URL. Ten przykład pokazuje też, jak określić weryfikację danych wejściowych w przypadku adresów URL podanych przez użytkownika.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  schema:
    url1:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
    url2:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
tools:
  - urlContext
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Compare the ingredients and cooking times from the recipes at {{url1}} and {{url2}}

Narzędzie Powiązanie ze źródłami informacji przy użyciu Google Search łączy model z treściami z internetu dostępnymi publicznie w czasie rzeczywistym.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleSearch
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

Who won the Euro 2024?

Powiązanie ze źródłami informacji przy użyciu Google Maps

Powiązanie ze źródłem informacji z użyciem Google Maps zapewnia modelowi dane geoprzestrzenne na potrzeby funkcji opartych na lokalizacji.

Aby użyć narzędzia googleMaps, umieść je na liście w obiekcie tools w sekcji z metadanymi szablonu. Poniższy przykład pokazuje dodatkowe opcjonalne konfiguracje:

  • Zezwól na zmienne wejściowe z kodu po stronie klienta i przeprowadź weryfikację danych wejściowych i schematu tych danych (w tym przykładzie jest to question).

  • Skonfiguruj narzędzie googleMaps, podając w kodzie po stronie klienta współrzędne lokalizacji lub kod języka za pomocą elementu TemplateToolConfig.

Pod przykładowym szablonem znajdziesz rozwijaną sekcję z przykładowymi fragmentami kodu po stronie klienta, które umożliwiają korzystanie z tych opcjonalnych konfiguracji.

Konfiguracja (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleMaps
input:
  schema:
    question: string
---

Prompt i (w stosownych przypadkach) instrukcje systemowe

{{role "system"}}
You are a helpful tour guide. Use the Google Maps tool with the provided coordinates to answer the user's question based on their location.

{{role "user"}}
{{question}}