服务器提示模板使用入门


在向模型发出的每个请求中，您都可以发送提示，还可以选择发送架构和配置来控制模型的响应。使用 Firebase AI Logic时，您可以直接从 客户端代码发送所有这些信息，也可以使用 服务器提示模板在服务器端指定这些信息。

使用服务器提示模板时，您可以在服务器端存储提示、架构和配置，而应用仅将引用特定模板的密钥（模板 ID）以及该模板所需的输入从客户端传递到服务器。

使用服务器提示模板时，您可以在服务器端存储提示和配置，并且仅在应用的代码库中提供密钥（模板 ID）。这种方法的一些优势如下：

  • 防止在客户端公开提示

  • 更新提示和配置，而无需发布新应用版本

本指南介绍了如何开始使用服务器提示模板。

跳转到高级别概览 跳转到详细说明

支持的模型和功能

  • 将服务器提示模板与 Gemini和Imagen模型搭配使用， Firebase AI Logic支持，但 Gemini Live 模型除外。

  • 查看尚未支持的功能 列表。


高级别概览

以下是使用服务器提示模板的基本工作流程：

  1. 使用 Firebase控制台中的引导式界面创建模板。

  2. 使用 Firebase 控制台的测试 体验在真实请求中测试模板。

  3. 从应用访问模板。

服务器提示模板的基本格式

对于 Firebase AI Logic， Firebase 控制台 提供了一个引导式界面，供您指定模板的内容。

服务器提示模板使用基于 Dotprompt 的语法和格式。 如需了解详情，请参阅 模板格式、语法和示例。

以下是向 Gemini 模型发出的示例请求中最重要的组件：

---
model: 'gemini-3-flash-preview'
---

{{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 语法）。

在代码中使用模板

点击您的 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
  '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();

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 实例。

  • 确保您拥有创建和管理服务器提示模板的必要权限 。默认情况下，所有这些权限都包含在所有者角色中。

  • 如果您使用 Vertex AI Gemini API 和 如果您的使用场景需要 基于位置的限制，我们支持 模板的高级工作流。

第 1 步：创建服务器提示模板

对于大多数使用场景，您可以在 Firebase控制台中创建和管理服务器提示模板。

  1. 在 Firebase 控制台中，依次前往 AI 服务 > AI Logic > 提示模板 标签页。

  2. 点击创建新模板，然后选择一个起始模板选项。

    • 这些起始模板为一些常见使用场景提供了格式和语法。不过，无论您选择哪个选项，都可以完全更改模板以满足您的需求。

    • 本入门指南假定您已选择 Input + System Instructions 选项。

  3. 输入模板的标识符：

    • 模板名称：这是模板的显示名称（例如 My First Template）。它仅在 Firebase 界面（例如 Firebase 控制台）中可见。

    • 模板 ID：这必须是 Firebase 项目中模板的唯一 ID（例如 my-first-template-v1-0-0）。您将在应用发出的请求中引用此 ID。

  4. 根据需要修改模板的配置（前言） 部分。

    • 此部分必须至少包含模型名称，如下所示：

      ---
model: 'gemini-3-flash-preview'
---

    • 您还可以选择指定模型的配置以及任何输入和 输出控件等。如需了解详情和选项，请参阅 模板格式、语法和示例。

  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. 点击保存模板 ，以便测试模板。

    您可以随时修改甚至删除模板。您以后无法更改的唯一值是模板 ID。

  2. 如果提示使用输入变量，请在测试输入 字段中添加测试值。对于此示例：

      {
    "customerName": "Jane"
  }

  3. 如果您在 Firebase 项目中启用了多个 Gemini API 提供商，则可以选择要用于测试请求的提供商。如果控制台中显示此选项，请选择 Gemini Developer API 或 Vertex AI Gemini API。

    请注意，此选择仅适用于通过 Firebase控制台测试体验提交的请求。在应用发出的实际请求中， 您可以指定所选的 Gemini API 提供商，就像处理任何 请求一样。

  4. 点击创建已设置格式的测试请求 按钮。

    查看屏幕右侧生成的 已设置格式的测试请求 ，并迭代模板的任何字段。

  5. 对已设置格式的测试请求感到满意后，点击运行提示测试 按钮。

    查看屏幕右侧生成的 测试响应 ，并迭代模板的任何字段。

  6. 如果您已准备好从应用的代码访问模板， 请点击模板右上角的 锁形图标 以锁定模板 。

  7. 点击关闭 以退出修改体验。

第 3 步：从代码访问模板

点击您的 Gemini API 提供商，以查看此页面上特定于提供商的内容和代码。

使用服务器提示模板的请求与其他请求类似，但有以下调整：

  • 使用 templateGenerativeModel（或 templateImagenModel，视需要而定）。
  • 提供模板 ID。
  • 提供模板所需的任何变量输入的值。

请注意，创建或更新模板后，您可能需要等待几分钟，让模板在 Firebase 服务器中传播，然后才能从代码访问该模板。

Swift

创建 templateGenerativeModel 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

// 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 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

// 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 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

// 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 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

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

Dart

Flutter 插件即将支持服务器提示模板！

创建 templateGenerativeModel 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

// 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 实例（或 templateImagenModel），以便在请求中使用模板。


// ...

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


接下来怎么做？