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

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

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

• Как защитить клиентскую часть от раскрытия запроса

• Как изменить запрос и конфигурацию, не выпуская новую версию приложения

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

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

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

• Используйте шаблоны запросов на сервере с любыми моделями Gemini, которые поддерживает Firebase AI Logic, кроме моделей Gemini Live API.

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

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

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

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

• В верхней части между тремя дефисами указано название модели, а также, при необходимости, конфигурация модели, проверка входных данных или схема, которую вы хотите отправить в запросе. Они записываются в виде пар "ключ-значение" и обычно называются заголовком YAML.

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

Как использовать шаблон в коде

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

// ...

// 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.
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  {
    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}");
}

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

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

Подготовка

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

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

  Посмотреть требуемые права доступа

  • 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

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

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

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

1. В консоли Firebase перейдите на вкладку Сервисы ИИ > Логика ИИ > Шаблоны запросов.

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

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

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

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

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

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

     • Мы рекомендуем использовать систему управления версиями для идентификаторов шаблонов.

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

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. Нажмите кнопку Создать запрос на тестирование в формате.

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

   Развернуть, чтобы посмотреть пример запроса на тестирование с форматированием

   {
     "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. Если вы довольны форматированием запроса, нажмите кнопку Запустить тестирование запроса.

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

   Пример ответа на тест

   {
     "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. Если вы готовы получить доступ к шаблону из кода приложения, заблокируйте шаблон, нажав на значок lock блокировки в правом верхнем углу шаблона.

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

Шаг 3. Откройте шаблон с помощью кода

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

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

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

// ...

// 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.
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  {
    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}");
}

Что дальше?

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

• Подробнее о формате и синтаксисе шаблонов, а также о примерах…

• Узнайте, как управлять шаблонами, в том числе редактировать, блокировать и контролировать версии.

• Узнайте больше о расширенных рабочих процессах, например о том, как работать с шаблонами программно с помощью REST API или развертывать шаблоны в определенных местах.