Starting November 2, 2026, Firebase App Check enforcement will be required to use Firebase AI Logic. Learn more.

Model updates:

The latest Gemini models, like Gemini 3.6 Flash, are available to use with Firebase AI Logic! Learn more.
All Imagen models will shut down as early as August 17, 2026. Learn about migrating your apps to use Nano Banana.
Gemini 2.5 models will shut down in October 2026. To avoid service disruptions, update to a newer model (like gemini-3.6-flash or gemini-3.1-flash-image). Any stable Gemini Live API 2.5 models are not impacted. Learn more.

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

服务器提示模板使用入门

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

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

使用服务器提示模板时，您可以在服务器端存储提示和配置，然后在应用的代码库中仅提供一个密钥（模板 ID）。这种方法的一些好处包括：

防止在客户端泄露提示
无需发布新的应用版本即可更新提示和配置

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

跳转到简要概览跳转到详细说明

支持的模型和功能

使用服务器提示模板时，可搭配 Firebase AI Logic 支持的任何 Gemini 和 Imagen 模型，但 Gemini Live 模型除外。
查看尚未支持的功能列表。

简要概览

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

使用 Firebase 控制台中的引导式界面创建模板。
使用 Firebase 控制台中的测试体验，在真实请求中测试模板。
使用 templateGenerativeModel 从应用的代码中访问模板。

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

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

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

以下示例模板展示了向 Gemini 模型发送示例请求的模板的最重要组成部分：

---
model: 'gemini-3.6-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 语法）。

在代码中使用模板

点击您的 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 实例。
确保您拥有创建和管理服务器提示模板所需的权限。默认情况下，所有这些权限都包含在“所有者”角色中。
查看必需的权限
- 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
如果您使用 Agent Platform Gemini API (formerly Vertex AI) 和 如果您的使用情形需要基于位置的限制，我们支持模板的高级工作流。

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

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

在 Firebase 控制台中，依次前往 AI 服务 > AI 逻辑 > 提示模板标签页。
点击创建新模板，然后选择一个初始模板选项。
- 这些初始模板为一些常见用例提供了格式和语法。不过，无论您选择哪个选项，都可以完全更改模板以满足您的需求。
- 本入门指南假定您已选择 Input + System Instructions 选项。
输入模板的标识符：
- 模板名称：这是模板的显示名称（例如 My First Template）。它仅在 Firebase 界面（例如 Firebase 控制台）中可见。
- 模板 ID：这必须是 Firebase 项目中模板的唯一 ID（例如 my-first-template-v1-0-0）。您将在应用的请求中引用此 ID。
  - 我们建议您为模板 ID 使用版本控制系统。
  - 模板 ID 最多可包含 63 个字符，并且可以包含小写字母、数字和连字符。
根据需要修改模板的配置（前置元数据）部分。
- 此部分必须至少包含一个模型名称，如下所示：
```
---
model: 'gemini-3.6-flash'
---
```
- 您还可以根据需要指定模型的配置以及任何输入和输出控件等。如需了解更多详情和选项，请参阅模板格式、语法和示例。
根据需要修改模板的提示和（如适用）系统指令部分。
- 此部分必须至少包含要发送给模型的文本提示。
```
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 控制台可为您的模板提供测试体验。借助此体验，您可以了解使用模板时会发生什么情况，包括请求的格式以及实际请求的输出。

点击保存模板，以便测试模板。

您稍后可以随时修改甚至删除模板。您以后无法更改的唯一值是模板 ID。
如果提示使用输入变量，请在 Test input 字段中添加测试值。在此示例中：
```
  {
    "customerName": "Jane"
  }
```
如果您的 Firebase 项目中启用了多个 Gemini API 提供方，您可以选择要用于测试请求的提供方。如果控制台中显示此选项，请选择 Gemini Developer API 或 Agent Platform Gemini API（以前称为 Vertex AI）。

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

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

查看界面右侧生成的格式化测试请求，并根据需要迭代更新模板的任何字段。

展开即可查看已设置格式的测试请求示例

{
  "model": "projects/YOUR_PROJECT_ID/models/gemini-3.6-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."
    }]
  }
}

对格式化后的测试请求感到满意后，点击运行提示测试按钮。

查看界面右侧的测试回答，并根据需要迭代模板的任何字段。

展开可查看示例测试回答

{
  "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.6-flash",
  "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
  "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
}

如果您已准备好从应用的代码中访问模板，请点击模板右上角的锁定图标锁定模板。
点击关闭即可退出编辑体验。

第 3 步：通过代码访问模板

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

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

使用 templateGenerativeModel（或根据需要使用 templateImagenModel）。
提供模板 ID。
提供模板所需的任何变量输入的值。

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