В каждом запросе к модели вы отправляете запрос и, при необходимости, схему и конфигурации для управления ответом модели. При использовании Firebase AI Logic вы можете отправлять всю эту информацию непосредственно из клиентского кода или указать ее на стороне сервера с помощью шаблонов запросов на сервере.
При использовании шаблонов запросов на сервере вы храните запрос, схему и конфигурации на стороне сервера, а база кода вашего приложения передает от клиента серверу только ключ (идентификатор шаблона), ссылающийся на определенный шаблон, а также необходимые входные данные для этого шаблона. Вот некоторые преимущества такого подхода:
Защита от раскрытия клиентского запроса
Обновляйте подсказки и конфигурацию без выпуска новой версии приложения
В этом руководстве рассказывается, как начать работу с шаблонами запросов на сервере.
Перейти к общему обзору Перейти к подробным инструкциям
Поддерживаемые модели и возможности
Шаблоны запросов к серверу можно использовать с любыми моделями Gemini, которые поддерживает Firebase AI Logic, за исключением моделей Gemini Live API.
Ознакомьтесь со списком функций, которые пока не поддерживаются.
Общие сведения
Вот как это делается:
Создайте шаблон с помощью пошаговых инструкций в консоли Firebase.
Протестируйте шаблон в реальном запросе, используя тестовую среду в консоли Firebase.
Получите доступ к шаблону из кода приложения с помощью
templateGenerativeModel.
Базовый формат шаблона запроса к серверу
Для Firebase AI Logic в консоли Firebase есть интерфейс с подсказками, который позволяет указать метаданные и содержимое шаблона.
Шаблоны запросов на сервере используют синтаксис и формат на основе Dotprompt. Подробнее о формате, синтаксисе и примерах шаблонов…
В примере ниже показаны наиболее важные компоненты шаблона для запроса к модели Gemini.
---
model: 'gemini-4-hydrogen'
---
{{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.
В теле шаблона содержится запрос. Он также может включать системные инструкции и входные значения (с использованием синтаксиса Handlebars).
Как использовать шаблон в коде
|
Нажмите на название своего поставщика Gemini API, чтобы посмотреть контент и код, относящиеся к нему. |
В примере кода клиента ниже показано, как использовать шаблон в коде:
Swift
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
const ai = getAI(app, { backend: new AgentPlatformBackend() });
// 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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.agentPlatform().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 Agent Platform Gemini API backend service (formerly Vertex AI).
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform());
// 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.
В консоли Firebase перейдите в раздел AI Services (Сервисы ИИ) > AI Logic (Логика ИИ) > вкладка Prompt templates (Шаблоны запросов).
Нажмите Создать шаблон и выберите стартовый шаблон.
Эти шаблоны содержат формат и синтаксис для некоторых распространенных вариантов использования. Однако независимо от выбранного варианта вы можете полностью изменить шаблон в соответствии со своими потребностями.
В этом кратком руководстве предполагается, что вы выбрали вариант
Input + System Instructions.
Укажите идентификаторы шаблона:
Название шаблона. Отображаемое название шаблона (например,
My First Template). Оно видно только в интерфейсах Firebase, таких как консоль Firebase.Идентификатор шаблона. Это должен быть уникальный идентификатор шаблона в вашем проекте Firebase (например,
). Вы будете ссылаться на этот идентификатор в запросе из вашего приложения.my-first-template-v1-0-0Рекомендуем использовать систему версий для идентификаторов шаблонов.
Идентификатор шаблона может содержать до 63 символов, включая строчные буквы, цифры и дефисы.
При необходимости измените раздел Configuration (frontmatter).
В этом разделе должно быть указано как минимум название модели, например:
--- model: 'gemini-4-hydrogen' ---Вы также можете указать конфигурацию модели, элементы управления вводом и выводом и т. д. Подробную информацию и варианты вы найдете в разделе Формат, синтаксис и примеры шаблонов.
При необходимости измените раздел Prompt and (as applicable) system instructions (Запрос и системные инструкции (если применимо)).
Этот раздел должен содержать как минимум текстовый запрос, который будет отправлен модели.
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 можно протестировать шаблон. Вы увидите, что произойдет при использовании шаблона, в том числе формат запроса и результат его выполнения.
Нажмите Сохранить шаблон, чтобы протестировать его.
Вы всегда можете изменить или удалить шаблон. Единственное значение, которое нельзя изменить, – это идентификатор шаблона.
Если в запросе используются входные переменные, укажите тестовые значения в поле Тестовые входные данные. В этом примере:
{ "customerName": "Jane" }Если в проекте Firebase включено несколько поставщиков Gemini API, вы можете выбрать, какой из них использовать для тестового запроса. Если этот вариант доступен в консоли, выберите
Gemini Developer APIилиAgent Platform Gemini API(ранее – Vertex AI).Обратите внимание, что этот выбор применяется только к запросам, отправленным через консоль тестирования Firebase. В запросе из приложения вы указываете выбранного поставщика Gemini API так же, как и для любого другого запроса.
Нажмите кнопку Создать отформатированный тестовый запрос.
Проверьте отформатированный тестовый запрос в правой части экрана и при необходимости измените поля шаблона.
Когда вы будете удовлетворены отформатированным тестовым запросом, нажмите кнопку Запустить тестовый запрос.
Проверьте тестовый ответ в правой части экрана и при необходимости измените поля шаблона.
Если вы готовы использовать шаблон в коде приложения, заблокируйте его, нажав на значок
в правом верхнем углу шаблона. Нажмите Закрыть, чтобы выйти из режима редактирования.
Шаг 3. Получите доступ к шаблону из кода
|
Нажмите на название своего поставщика Gemini API, чтобы посмотреть контент и код, относящиеся к нему. |
Запрос с использованием шаблона подсказки сервера похож на другие запросы, но имеет следующие отличия:
- Используйте
templateGenerativeModel. - Укажите идентификатор шаблона.
- Укажите значения всех переменных, необходимых для вашего шаблона.
Обратите внимание, что после создания или обновления шаблона может потребоваться подождать несколько минут, пока он не распространится по серверам Firebase, прежде чем вы сможете получить к нему доступ из своего кода.
Swift
Чтобы использовать шаблон в запросе, создайте экземпляр templateGenerativeModel.
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
const ai = getAI(app, { backend: new AgentPlatformBackend() });
// 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
Чтобы использовать шаблон в запросе, создайте экземпляр templateGenerativeModel.
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.agentPlatform().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 Agent Platform Gemini API backend service (formerly Vertex AI).
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform());
// 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}");
}
Что дальше?
Ознакомьтесь с рекомендациями и примечаниями по использованию шаблонов запросов на сервере.
Подробнее о формате и синтаксисе шаблонов…
Подробнее об управлении шаблонами, в том числе об их редактировании, блокировке и управлении версиями…
Узнайте о расширенных рабочих процессах, например о программной работе с шаблонами с помощью REST API или развертывании шаблонов в определенных местоположениях.