Формат шаблона, синтаксис и примеры


В Firebase AI Logic консоль Firebase предоставляет пошаговый интерфейс, в котором можно указать содержимое шаблона.

Шаблоны запросов сервера используют синтаксис и формат на основе Dotprompt. На этой странице вы найдете подробные описания формата и синтаксиса шаблонов, а также примеры.

Ниже перечислены основные компоненты примера запроса к модели 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}}.
  • В верхнем разделе, ограниченном тройными дефисами, указывается название модели, а также (необязательно) ее конфигурация, проверка входных данных или схема, которую вы хотите отправить в запросе. Они записываются в виде пар "ключ-значение" и обычно называются frontmatter YAML.

  • Тело шаблона содержит запрос. Он также может содержать системные инструкции и входные значения (с использованием синтаксиса Handlebars).


На этой странице приведены подробные описания формата и синтаксиса шаблонов, а также примеры для следующих элементов:

Во всех примерах на этой странице показаны шаблоны, в которых используется gemini-3.8-flash, но вы можете использовать любую модель Gemini, поддерживаемую Firebase AI Logic (кроме моделей Gemini Live API).

Здравствуй, мир!

Вот минимальный пример шаблона запроса к серверу:

Конфигурация (frontmatter)

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

Запрос и (если применимо) системные инструкции

Write a story about a magic backpack.



Управление генерацией ответов

Вы можете управлять генерацией ответов разными способами в зависимости от вашего варианта использования и необходимого уровня контроля.

Конфигурация модели

Задайте конфигурацию модели, чтобы управлять тем, как модель генерирует ответ, например максимальное количество выходных токенов, стоп-последовательности и т. д.

Конфигурация (заголовок)

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

Запрос и системные инструкции (если применимо)

Write a story about a magic backpack.


Настройка мышления

Укажите конфигурацию, связанную с мышлением, для моделей, которые поддерживают мышление.

Конфигурация (frontmatter)

  • Gemini 3.x и более поздние модели (уровни размышлений)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • Gemini 2.5 моделей (бюджеты на размышления)

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

Запрос и системные инструкции (если применимо)

Solve x^2 + 4x + 4 = 0


Настройки безопасности

Используйте настройки безопасности, чтобы снизить вероятность получения ответов, которые могут считаться вредоносными.

Конфигурация (frontmatter)

Пример с одной настройкой безопасности:

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

Пример с несколькими настройками безопасности:

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

Запрос и (если применимо) системные инструкции

Write a story about a magic backpack.


Системные инструкции

Задайте системные инструкции, чтобы управлять поведением модели. Вы включаете их в запрос:

  • Укажите системные инструкции, используя синтаксис {{role "system"}}.

  • Укажите текстовый запрос, используя синтаксис {{role "user"}}.

Конфигурация (заголовок)

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



Входные переменные

Некоторые запросы статичны, но часто вам нужно включить в запрос некоторые данные от пользователя.

В запрос можно включить динамические входные переменные, используя выражения Handlebars, которые содержатся в тегах {{ }} в формате {{variableName}} или {{object.propertyName}} (например, Hello, {{name}} from {{address.city}}).

Конфигурация (frontmatter)

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

Запрос и (если применимо) системные инструкции

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

В шаблоне можно указать значение по умолчанию, но обычно значение входной переменной предоставляется клиентом в составе запроса.



Управляющие конструкции (циклы и условные операторы)

Чтобы написать более сложный запрос, можно использовать условные блоки (например, #if, else и #unless) и итерацию (#each).

Вы можете добавить дополнительную контекстную информацию в виде переменных со специальным префиксом @:

  • @first: true, если итерация выполняется для первого элемента блока #each.
  • @last: true при итерации последнего элемента блока #each.
  • @index: возвращает индексную позицию текущего элемента (с точкой отсчета в нуле).

Информацию о встроенных логических помощниках можно найти в документации по Handlebars.

Конфигурация (заголовок)

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

Запрос и (если применимо) системные инструкции

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

Обратите внимание, что условные операторы принимают только ссылки на переменные, а не выражения, например:

  • Следующий запрос будет обработан: {{#if isVipCustomer}} ... {{/if}}
  • Следующий код не работает: {{#if customer.type == 'vip'}} ... {{/if}}

Если переменная является логическим значением, то условие работает так, как вы ожидаете. Если переменная не является логическим значением, то условие фактически представляет собой проверку "не равно нулю". Это может быть полезно для обработки необязательных входных данных, например:

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



Проверка входных данных и схема

Если вы получаете данные от клиента, мы настоятельно рекомендуем использовать входную схему, чтобы защититься от внедрения запроса, а также убедиться, что данные, переданные в запросе, соответствуют вашим ожиданиям.

  • Вы можете указать значения по умолчанию на случай, если клиент не предоставит значение.

  • Схема поддерживает скалярные типы string, integer, number, boolean и object. Объекты, массивы и перечисления указываются в скобках после названия поля.

  • Все свойства считаются обязательными, если вы не пометили их как необязательные с помощью ?. Когда свойство помечается как необязательное, оно также становится обнуляемым, чтобы LLM могли возвращать значение null вместо того, чтобы пропускать поле.

Ниже приведен простой пример схемы входных данных. Ниже приведена более сложная схема.

Конфигурация (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
---

Запрос и (если применимо) системные инструкции

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



Схема вывода

Если вы хотите, чтобы модель генерировала структурированный вывод в формате JSON, вы можете указать схему вывода. Если указать format: json, модель будет возвращать только ответы в формате JSON, соответствующие заданной схеме.

  • Схема поддерживает скалярные типы string, integer, number, boolean и object. Объекты, массивы и перечисления указываются в скобках после названия поля.

  • Все свойства считаются обязательными, если вы не пометили их как необязательные с помощью ?. Когда свойство помечается как необязательное, оно также становится nullable, чтобы LLM могли возвращать null вместо пропуска поля.

Ниже приведен простой пример для создания структурированного вывода в формате JSON. Более сложная схема приведена ниже.

Конфигурация (заголовок)

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

Запрос и системные инструкции (если применимо)

Create an example customer invoice.



Мультимодальный ввод

Мультимодальные запросы, отправляемые модели Gemini, могут включать несколько типов входных данных, в том числе файлы (например, текст вместе с изображениями, PDF-файлами, файлами обычного текста, аудио и видео).

  • Укажите файл, используя его URL с синтаксисом {{media url}}.

  • Укажите встроенный файл с синтаксисом {{media type="mime_type" data="contents"}}.

Простой пример (мультимодальный ввод)

Ниже приведен простой пример использования мультимодального ввода. Более сложный пример приведен ниже.

Конфигурация (заголовок)

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

Запрос и (если применимо) системные инструкции

Describe this image

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

Сложный пример (мультимодальный ввод)

Вот более сложный пример мультимодального запроса.

Конфигурация (заголовок)

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

Запрос и системные инструкции (если применимо)

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



Использование инструментов

Шаблоны запросов на сервере поддерживают следующие инструменты:

Если вы хотите, чтобы пользователи предоставляли дополнительную информацию для запроса к модели, используйте входные переменные в шаблоне запроса сервера, а также проверку входных данных.

Вызов функций

Ознакомьтесь с полным руководством по вызову функций с помощью шаблонов запросов сервера.

Выполнение кода

Инструмент выполнения кода позволяет модели генерировать и выполнять код на Python.

Конфигурация (заголовок)

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

Запрос и (если применимо) системные инструкции

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

URL-контекст

Инструмент URL-контекст позволяет предоставлять модели дополнительный контекст в виде URL. В этом примере также показано, как можно указать проверку входных данных для URL, если они предоставлены пользователем.

Конфигурация (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
---

Запрос и системные инструкции (если применимо)

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

Инструмент Обоснование с Google Search позволяет модели получать доступ к общедоступному веб-контенту в реальном времени.

Конфигурация (frontmatter)

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

Запрос и системные инструкции (если применимо)

Who won the Euro 2024?

Обоснование с помощью Google Maps

Инструмент Обоснование с помощью Google Maps предоставляет модели геопространственные данные для функций, связанных с местоположением.

Чтобы использовать инструмент googleMaps, укажите его в объекте tools в начале шаблона. В примере ниже показаны некоторые дополнительные конфигурации:

Под примером шаблона вы найдете раскрывающееся меню с примерами клиентского кода для работы с этими необязательными конфигурациями.

Конфигурация (заголовок)

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

Запрос и системные инструкции (если применимо)

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