All Gemini 1.0 and Gemini 1.5 models are now retired.
To avoid service disruption, update to a newer model (for example, gemini-2.5-flash-lite). Learn more.

Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai menggunakan template perintah server

Dalam setiap permintaan ke model, Anda mengirimkan perintah dan secara opsional skema dan konfigurasi untuk mengontrol respons model. Saat menggunakan Firebase AI Logic, Anda dapat mengirim semua informasi ini langsung dari kode klien, atau Anda dapat menentukan informasi ini di sisi server menggunakan template perintah server.

Saat menggunakan template perintah server, Anda menyimpan perintah, skema, dan konfigurasi di sisi server, dan aplikasi Anda meneruskan hanya kunci (ID template) dari klien ke server yang mereferensikan template tertentu serta input yang diperlukan untuk template tersebut.

Saat menggunakan template perintah server, Anda menyimpan perintah dan konfigurasi di sisi server dan hanya memberikan kunci (ID template) di codebase aplikasi Anda. Berikut beberapa manfaat dari pendekatan ini:

Melindungi agar perintah Anda tidak terekspos di sisi klien
Memperbarui perintah dan konfigurasi tanpa merilis versi aplikasi baru

Panduan ini menjelaskan cara mulai menggunakan template perintah server.

Langsung ke ringkasan umum Langsung ke petunjuk mendetail

Model dan kemampuan yang didukung

Gunakan template perintah server dengan salah satu model Gemini dan Imagen yang didukung Firebase AI Logic, kecuali model Gemini Live.
Tinjau daftar fitur yang belum didukung.

Ringkasan umum

Berikut adalah alur kerja dasar untuk menggunakan template perintah server:

Buat template menggunakan UI terpandu di konsol Firebase.
Uji template dalam permintaan nyata menggunakan pengalaman pengujian Firebase console.
Akses template dari aplikasi Anda.

Format dasar template perintah server

Untuk Firebase AI Logic, konsol Firebase menyediakan UI terpandu bagi Anda untuk menentukan konten template.

Template perintah server menggunakan sintaksis dan format berbasis Dotprompt. Untuk mengetahui detail selengkapnya, lihat Format, sintaksis, dan contoh template.

Berikut adalah komponen terpenting untuk contoh permintaan ke model Gemini:

---
model: 'gemini-2.5-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}}.

Bagian atas dalam tiga tanda hubung berisi nama model serta konfigurasi model, validasi input, atau skema yang ingin Anda kirim dalam permintaan. Bagian ini ditulis sebagai pasangan nilai kunci dan biasanya disebut frontmatter YAML.
Isi template berisi perintah. Respons juga dapat secara opsional menyertakan petunjuk sistem dan nilai input (menggunakan sintaksis Handlebars).

Menggunakan template dalam kode

Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini.

Berikut cara menggunakan template dalam kode Anda:

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.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 = response.result;
const text = response.text();

Dart

Plugin Flutter akan segera mendukung template perintah server.

Unity

Paket Unity akan segera mendukung template perintah server.

Petunjuk mendetail

Bagian ini memberikan petunjuk mendetail untuk membuat, menguji, dan menggunakan template perintah server.

Sebelum memulai

Jika belum melakukannya, selesaikan panduan memulai, yang menjelaskan cara menyiapkan project Firebase, menghubungkan aplikasi ke Firebase, menambahkan SDK, menginisialisasi layanan backend untuk penyedia Gemini API yang Anda pilih, dan membuat instance GenerativeModel.
Pastikan Anda memiliki izin yang diperlukan untuk membuat dan mengelola template perintah server. Secara default, semua izin ini disertakan dalam peran Pemilik.
Lihat izin yang diperlukan
- 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
Jika Anda menggunakan Vertex AI Gemini API dan jika kasus penggunaan Anda memerlukan pembatasan berbasis lokasi, kami mendukung alur kerja lanjutan untuk template.

Langkah 1: Buat template perintah server

Untuk sebagian besar kasus penggunaan, Anda membuat dan mengelola template perintah server di konsol Firebase.

Di konsol Firebase, buka tab Firebase AI Logic Prompt templates.
Klik Buat template baru, lalu pilih opsi template awal.
- Template awal ini menyediakan format dan sintaksis untuk beberapa kasus penggunaan umum. Namun, apa pun opsi yang Anda pilih, Anda dapat mengubah template sepenuhnya agar sesuai dengan kebutuhan Anda.
- Panduan memulai ini mengasumsikan bahwa Anda telah memilih opsi Input + System Instructions.
Masukkan ID template:
- Nama template: Ini adalah nama tampilan untuk template (misalnya, My First Template). Nama ini hanya terlihat dalam antarmuka Firebase, seperti konsol Firebase.
- ID template: Ini harus berupa ID unik untuk template dalam project Firebase Anda (misalnya, my-first-template-v1-0-0). Anda akan mereferensikan ID ini dalam permintaan dari aplikasi Anda.
  - Sebaiknya gunakan sistem pembuatan versi untuk ID template Anda.
  - ID template dapat berisi maksimal 63 karakter dan dapat berisi huruf kecil, angka, dan tanda hubung.
Ubah bagian Configuration (frontmatter) template, sesuai kebutuhan.
- Bagian ini setidaknya harus menyertakan nama model, seperti ini:
```
---
model: 'gemini-2.5-flash'
---
```
- Anda juga dapat secara opsional menentukan konfigurasi model dan kontrol input & output, dll. Untuk mengetahui detail dan opsi selengkapnya, lihat Format, sintaksis, dan contoh template.
Ubah bagian Perintah dan (jika berlaku) petunjuk sistem pada template sesuai kebutuhan.
- Bagian ini setidaknya harus menyertakan perintah teks yang akan dikirim ke model.
```
Write a story about a magic backpack.
```
- Anda juga dapat membuat perintah yang lebih kompleks, seperti opsi berikut. Untuk mengetahui detail dan opsi selengkapnya, lihat Format, sintaksis, dan contoh template.
  - (Opsional dan jika berlaku) Tentukan petunjuk sistem menggunakan sintaksis {{role "system"}}, dan perintah teks menggunakan sintaksis {{role "user"}}.
  - (Opsional) Tentukan variabel input menggunakan sintaksis Handlebars (seperti {{customerName}}). Anda dapat memberikan nilai default dalam template, tetapi nilai variabel input ini biasanya diteruskan dalam permintaan.
```
{{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}}.
```

Langkah 2: Uji template Anda di konsol Firebase

Konsol Firebase memberikan pengalaman pengujian untuk template Anda. Pengalaman ini memungkinkan Anda melihat apa yang akan terjadi saat template Anda digunakan – baik format permintaan maupun output permintaan sebenarnya.

Klik Simpan template agar Anda dapat menguji template.

Anda dapat mengedit atau bahkan menghapus template tersebut nanti. Satu-satunya nilai yang tidak dapat Anda ubah nanti adalah ID template.
Jika perintah Anda menggunakan variabel input, sertakan nilai pengujian di kolom Input pengujian. Untuk contoh ini:
```
  {
    "customerName": "Jane"
  }
```
Jika Anda mengaktifkan beberapa penyedia Gemini API di project Firebase, Anda dapat memilih penyedia yang akan digunakan untuk permintaan pengujian. Jika opsi ini ditampilkan di konsol, pilih Gemini Developer API atau Vertex AI Gemini API.

Perhatikan bahwa pilihan ini hanya berlaku untuk permintaan yang dikirimkan melalui pengalaman pengujian konsol Firebase. Dalam permintaan sebenarnya dari aplikasi Anda, Anda menentukan penyedia Gemini API yang dipilih seperti yang Anda lakukan untuk permintaan apa pun.

Klik tombol Create formatted test request.

Tinjau Permintaan pengujian yang diformat di sisi kanan layar, dan lakukan iterasi pada kolom template Anda.

Luaskan untuk melihat contoh permintaan pengujian yang diformat

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

Jika Anda sudah puas dengan permintaan pengujian yang diformat, klik tombol Jalankan pengujian perintah.

Tinjau Respons pengujian yang dihasilkan di sisi kanan layar, dan lakukan iterasi pada kolom template Anda.

Luaskan untuk melihat contoh respons pengujian

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

Jika Anda siap mengakses template dari kode aplikasi, kunci template dengan mengklik ikon kunci di pojok kanan atas template.
Klik Tutup untuk keluar dari pengalaman pengeditan.

Langkah 3: Akses template dari kode Anda

Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini.

Permintaan yang menggunakan template perintah server terlihat mirip dengan permintaan lainnya, dengan penyesuaian berikut:

Gunakan templateGenerativeModel (atau templateImagenModel, sesuai kebutuhan).
Berikan ID template.
Berikan nilai input variabel yang diperlukan oleh template Anda.

Perhatikan bahwa setelah membuat atau memperbarui template, Anda mungkin perlu menunggu beberapa menit agar template disebarkan di server Firebase sebelum mengaksesnya dari kode Anda.

Swift

Buat instance templateGenerativeModel (atau templateImagenModel) untuk menggunakan template dalam permintaan Anda.


// ...

// 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

Buat instance templateGenerativeModel (atau templateImagenModel) untuk menggunakan template dalam permintaan Anda.


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.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

Buat instance templateGenerativeModel (atau templateImagenModel) untuk menggunakan template dalam permintaan Anda.


// ...

// 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

Buat instance templateGenerativeModel (atau templateImagenModel) untuk menggunakan template dalam permintaan Anda.


// ...

// 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 = response.result;
const text = response.text();

Dart

Plugin Flutter akan segera mendukung template perintah server.

Unity

Paket Unity akan segera mendukung template perintah server.

Apa langkah selanjutnya?

Pelajari praktik terbaik dan pertimbangan untuk menggunakan template perintah server.
Pelajari detail tentang format dan sintaksis template, beserta contohnya.
Mengelola template, termasuk mengedit, mengunci, dan kontrol versi.

Mulai menggunakan template perintah server Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Model dan kemampuan yang didukung

Ringkasan umum

Format dasar template perintah server

Menggunakan template dalam kode

Swift

Kotlin

Java

Web

Dart

Unity

Petunjuk mendetail

Sebelum memulai

Langkah 1: Buat template perintah server

Langkah 2: Uji template Anda di konsol Firebase

Langkah 3: Akses template dari kode Anda

Swift

Kotlin

Java

Web

Dart

Unity

Apa langkah selanjutnya?

Mulai menggunakan template perintah server