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

Model updates:

Gemini 4 Argon is now available to use with Firebase AI Logic! Learn more.
Gemini 2.5 models are limited to projects that actively used them in the past. For the Agent Platform Gemini API, these models will shut down for all projects in October 2026. To avoid service disruptions, update to a newer model (like gemini-4-argon, gemini-3.8-flash, or gemini-nano-banana-2.1). Any stable Gemini Live API 2.5 models are not impacted. Learn more.

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

開始使用伺服器提示詞範本

在向模型提出的每項要求中，您會傳送提示，並視需要傳送結構定義和設定，以控制模型的回覆。使用 Firebase AI Logic 時，您可以直接從用戶端程式碼傳送所有這類資訊，也可以使用伺服器提示詞範本在伺服器端指定這類資訊。

使用伺服器提示詞範本時，提示詞、結構定義和設定會儲存在伺服器端，而應用程式的程式碼集只會從用戶端傳遞至伺服器，其中包含參照特定範本的金鑰 (範本 ID)，以及該範本所需的輸入內容。這種做法有以下優點：

防止提示詞在用戶端公開
更新提示詞和設定，不必發布新的應用程式版本

本指南說明如何開始使用伺服器提示詞範本。

跳到高層級總覽跳到詳細操作說明

支援的模型和功能

伺服器提示詞範本可搭配 Firebase AI Logic 支援的任何 Gemini 模型，但不支援 Gemini Live API 模型。
請參閱尚未支援的功能清單。

高階總覽

以下是使用伺服器提示詞範本的基本工作流程：

在 Firebase 控制台中使用引導式 UI 建立範本。
在 Firebase 控制台中使用測試功能，在實際要求中測試範本。
使用 templateGenerativeModel 從應用程式的程式碼存取範本。

伺服器提示詞範本的基本格式

如果是 Firebase AI Logic，Firebase 控制台會提供引導式使用者介面，讓您指定範本的 frontmatter 和內容。

伺服器提示詞範本採用 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 frontmatter。
範本主體包含提示詞。也可以選擇加入系統指令和輸入值 (使用 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.
  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();

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
- firebasevertexai.googleapis.com/promptTemplates.updateLock
如果您使用 Agent Platform Gemini API (formerly Vertex AI)，且用途需要依據位置設定限制，我們支援範本進階工作流程。

步驟 1：建立伺服器提示詞範本

在多數用途中，您可以在 Firebase 控制台建立及管理伺服器提示詞範本。

在 Firebase 控制台，依序前往「AI Services」(AI 服務) >「AI Logic」 >「Prompt templates」(提示詞範本) 分頁標籤。
按一下「建立新範本」，然後選取範本選項。
- 這些入門範本提供一些常見用途的格式和語法。不過，無論您選取哪一個選項，都可以完全變更範本，以符合您的需求。
- 本入門指南假設您已選取 Input + System Instructions 選項。
輸入範本 ID：
- 範本名稱：範本的顯示名稱 (例如 My First Template)，只會顯示在 Firebase 介面 (例如 Firebase 控制台)。
- 範本 ID：這是範本的專屬 ID，在 Firebase 專案中不得重複 (例如 my-first-template-v1-0-0)。在應用程式中提出要求時，會參照這個 ID。
  - 建議您為範本 ID 使用版本管理系統。
  - 範本 ID 最多可包含 63 個字元，且可包含小寫英文字母、數字和連字號。
視需要修改範本的「Configuration (frontmatter)」(設定 (frontmatter)) 部分。
- 這個部分至少須包含模型名稱，如下所示：
```
---
model: 'gemini-3.8-flash'
---
```
- 您也可以視需要指定模型設定、輸入/輸出控管機制等。如要瞭解詳情和選項，請參閱「範本格式、語法和範例」。
視需要修改範本的「Prompt and (as applicable) system instructions」(提示詞和系統指令 (如適用)) 部分。
- 這個部分至少須包含要傳送至模型的文字提示詞。
```
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 供應商，就像處理任何要求一樣。

點選「Create formatted test request」按鈕。

查看畫面右側產生的「Formatted test request」(格式化測試要求)，並疊代範本的任何欄位。

展開即可查看已套用格式的測試要求範例

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

確認測試要求格式正確後，請按一下「Run prompt test」(執行提示測試) 按鈕。

查看畫面右側產生的「測試回應」，並視需要調整範本欄位。

展開即可查看測試回應範例

{
  "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 伺服器中傳播，然後才能從程式碼存取。