Как начать работу с шаблонами запросов на сервере


В каждом запросе к модели вы отправляете запрос и, при необходимости, схему и конфигурации, чтобы управлять ответом модели. При использовании Firebase AI Logic вы можете отправлять всю эту информацию непосредственно из клиентского кода или указывать ее на стороне сервера с помощью шаблонов запросов на сервере.

При использовании шаблонов запросов на сервере вы храните запрос, схему и конфигурации на стороне сервера, а база кода вашего приложения передает от клиента серверу только ключ (идентификатор шаблона), ссылающийся на определенный шаблон, а также необходимые входные данные для этого шаблона. Вот некоторые преимущества такого подхода:

  • Защита от раскрытия запроса на стороне клиента

  • Обновляйте подсказку и конфигурацию без выпуска новой версии приложения

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

Перейти к общему обзору Перейти к подробным инструкциям

Поддерживаемые модели и функции


Общие сведения

Вот как это работает:

  1. Создайте шаблон с помощью пошагового интерфейса в консоли Firebase.

  2. Проверьте шаблон в реальном запросе, используя функцию тестирования в консоли Firebase.

  3. Получите доступ к шаблону из кода приложения с помощью templateGenerativeModel.

Базовый формат шаблона запроса к серверу

Для 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 API, чтобы посмотреть контент и код, относящиеся к нему.

В приведенном ниже примере клиентского кода показано, как использовать шаблон в коде:

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

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}");
}


Подробные инструкции

В этом разделе приведены подробные инструкции по созданию, тестированию и использованию шаблонов запросов на сервере.

Подготовка

  • Если вы ещё этого не сделали, ознакомьтесь с кратким руководством, в котором описано, как настроить проект Firebase, подключить приложение к Firebase, добавить SDK, инициализировать бэкенд-службу для выбранного поставщика Gemini API и создать экземпляр GenerativeModel.

  • Убедитесь, что у вас есть необходимые разрешения для создания шаблонов запросов к серверу и управления ими. По умолчанию все эти разрешения включены в роль владельца.

  • Если вы используете Agent Platform Gemini API (formerly Vertex AI) и если вам нужны ограничения на основе местоположения, мы поддерживаем расширенные рабочие процессы для шаблонов.

Шаг 1. Создайте шаблон запроса к серверу

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

  1. В консоли Firebase перейдите в раздел AI Services (Сервисы ИИ) > AI Logic (Логика ИИ) > Prompt templates (Шаблоны запросов).

  2. Нажмите Создать шаблон и выберите стартовый шаблон.

    • Эти шаблоны содержат формат и синтаксис для некоторых распространенных вариантов использования. Однако независимо от выбранного варианта вы можете полностью изменить шаблон в соответствии со своими потребностями.

    • В этом кратком руководстве предполагается, что вы выбрали вариант Input + System Instructions.

  3. Укажите идентификаторы шаблона:

    • Название шаблона. Отображаемое название шаблона (например, My First Template). Оно видно только в интерфейсах Firebase, например в консоли Firebase.

    • Идентификатор шаблона. Это должен быть уникальный идентификатор шаблона в вашем проекте Firebase (например, my-first-template-v1-0-0). Вы будете ссылаться на этот идентификатор в запросе из своего приложения.

  4. При необходимости измените раздел Configuration (frontmatter) шаблона.

    • В этом разделе должно быть указано хотя бы название модели, например:

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

    • Вы также можете указать конфигурацию модели, элементы управления вводом и выводом и т. д. Подробнее о формате, синтаксисе и примерах шаблонов…

  5. При необходимости измените раздел Запрос и (если применимо) системные инструкции шаблона.

    • Этот раздел должен содержать как минимум текстовый запрос, который будет отправлен модели.

      Write a story about a magic backpack.

    • Вы также можете создавать более сложные запросы, например такие: Подробную информацию и варианты вы найдете в статье Формат, синтаксис и примеры шаблонов.

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

      • (Необязательно.) Укажите входные переменные, используя синтаксис Handlebars (например, {{customerName}}). Вы можете указать в шаблоне значение по умолчанию, но обычно значение этой входной переменной передается в запросе.

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

Шаг 2. Протестируйте шаблон в консоли Firebase

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

  1. Нажмите Сохранить шаблон, чтобы протестировать его.

    Вы всегда можете изменить или удалить шаблон. Единственное значение, которое нельзя изменить, – это идентификатор шаблона.

  2. Если в запросе используются входные переменные, укажите тестовые значения в поле Тестовый ввод. В этом примере:

      {
    "customerName": "Jane"
  }

  3. Если в проекте Firebase включено несколько поставщиков Gemini API, вы можете выбрать, какой из них использовать для тестового запроса. Если этот вариант отображается в консоли, выберите Gemini Developer API или Agent Platform Gemini API (ранее Vertex AI).

    Обратите внимание, что этот выбор применяется только к запросам, отправленным через интерфейс тестирования консоли Firebase. В запросе из приложения вы указываете выбранного поставщика Gemini API так же, как и для любого другого запроса.

  4. Нажмите кнопку Создать отформатированный тестовый запрос.

    Проверьте отформатированный тестовый запрос в правой части экрана и при необходимости измените поля шаблона.

  5. Если вы довольны форматированием запроса, нажмите кнопку Запустить тестирование запроса.

    Проверьте тестовый ответ в правой части экрана и при необходимости измените поля шаблона.

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

  7. Нажмите Закрыть, чтобы выйти из режима редактирования.

Шаг 3. Получите доступ к шаблону из кода

Нажмите на название своего поставщика Gemini API, чтобы посмотреть контент и код, относящиеся к нему.

Запрос с шаблоном запроса к серверу выглядит так же, как и другие запросы, но с некоторыми изменениями:

  • Используйте templateGenerativeModel.
  • Укажите идентификатор шаблона.
  • Укажите значения всех переменных, необходимых для вашего шаблона.

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

Swift

Чтобы использовать шаблон в запросе, создайте экземпляр templateGenerativeModel.


// ...

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

Чтобы использовать шаблон в запросе, создайте экземпляр templateGenerativeModel.


// ...

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

Чтобы использовать шаблон в запросе, создайте экземпляр templateGenerativeModel.


// ...

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

Создайте экземпляр templateGenerativeModel, чтобы использовать шаблон в запросе.


// ...

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

Dart

Скоро в плагине Flutter появится поддержка шаблонов запросов к серверу.

Создайте экземпляр templateGenerativeModel, чтобы использовать шаблон в запросе.


// ...

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

Создайте экземпляр templateGenerativeModel, чтобы использовать шаблон в запросе.


// ...

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


Что дальше?