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.8 Flash, are available to use with Firebase AI Logic! Learn more.
Gemini 2.5 models will shut down in October 2026 (and new projects cannot start using them). To avoid service disruptions, update to a newer model (like gemini-3.8-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）。这种方法的一些优势如下：

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

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

跳转到总体概览跳转到详细说明

支持的模型和功能

将服务器提示模板与 Gemini模型搭配使用，Firebase AI Logic 支持，但Gemini Live API模型除外。
查看尚未支持的功能列表。

总体概览

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

使用 Firebase控制台中的引导式界面创建模板。
使用 Firebase控制台中的测试体验在真实请求中测试模板。
使用 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 语法）。

在代码中使用模板

点击您的 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 Logic > 提示模板 标签页。
点击创建新模板，然后选择一个起始模板选项。
- 这些起始模板为一些常见使用场景提供了格式和语法。不过，无论您选择哪个选项，都可以完全更改模板以满足您的需求。
- 本入门指南假定您已选择 Input + System Instructions 选项。
输入模板的标识符：
- 模板名称：这是模板的显示名称（例如 My First Template）。它仅在 Firebase 界面（例如 Firebase 控制台）中可见。
- 模板 ID：这必须是 Firebase 项目中模板的唯一 ID（例如 my-first-template-v1-0-0）。您将在应用的请求中引用此 ID。
  - 我们建议您为模板 ID 使用版本控制系统。
  - 模板 ID 最多可以包含 63 个字符，并且可以包含小写字母、数字和连字符。
根据需要修改模板的配置（前置元数据） 部分。
- 此部分至少必须包含模型名称，如下所示：
```
---
model: 'gemini-3.8-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。
如果提示使用输入变量，请在测试输入 字段中添加测试值。对于此示例：
```
  {
    "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.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."
    }]
  }
}

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

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

展开以查看测试响应示例

{
  "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"
}

如果您已准备好从应用的代码访问模板，请点击模板右上角的锁形图标以锁定模板。
点击关闭以退出修改体验。

第 3 步：从代码访问模板

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

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

使用 templateGenerativeModel。
提供模板 ID。
提供模板所需的任何变量输入的值。

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