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

В каждом запросе к модели вы отправляете подсказку и, при необходимости, схему и конфигурации для управления ответом модели. При использовании 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}}.

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

// ...

// 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, подключить приложение к 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 перейдите в раздел AI Services (Сервисы ИИ) > AI Logic (Логика ИИ) > Prompt templates (Шаблоны запросов).

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

// ...

// 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 или развертывании шаблонов в определенных местоположениях.