Mulai menggunakan template perintah server

Dalam setiap permintaan ke model, Anda mengirim 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 hanya meneruskan 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) dalam codebase aplikasi. Berikut beberapa manfaat pendekatan ini:

• Melindungi dari pemaparan perintah di sisi klien

• Memperbarui perintah dan konfigurasi tanpa merilis versi aplikasi baru

Panduan ini menjelaskan cara memulai penggunaan template perintah server.

arrow_downward Lompat ke ringkasan tingkat tinggi arrow_downward Lompat 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 tingkat tinggi

Berikut alur kerja dasar untuk menggunakan template perintah server:

1. Buat template menggunakan UI terpandu di Firebase konsol.

2. Uji template dalam permintaan sebenarnya menggunakan pengalaman pengujian di Firebase console.

3. Akses template dari kode aplikasi menggunakan templateGenerativeModel.

Format dasar template perintah server

Untuk Firebase AI Logic, Firebase konsol menyediakan UI terpandu agar Anda dapat menentukan frontmatter dan konten template.

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

Contoh template di bawah menunjukkan komponen terpenting dari template untuk contoh permintaan ke model Gemini:

---
model: 'gemini-3.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 tanda hubung tiga 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 YAML frontmatter.

• Isi template berisi perintah. Secara opsional, bagian ini juga dapat menyertakan petunjuk sistem dan nilai input (menggunakan sintaksis Handlebars).

Menggunakan template dalam kode

Contoh kode klien di bawah menunjukkan cara menggunakan template dalam kode Anda:

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "global")).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")

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "global")).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)

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.vertexAI("global")).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);

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
const ai = getAI(app, { backend: new VertexAIBackend('global') });

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

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.vertexAI(location: 'global').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);

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "global"));

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

Petunjuk mendetail

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

Sebelum memulai

• Jika belum, selesaikan panduan memulai, yang menjelaskan cara menyiapkan project Firebase, menghubungkan aplikasi ke Firebase, menambahkan SDK, menginisialisasi layanan backend untuk penyedia yang Anda pilih, Gemini API 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 batasan berbasis lokasi, kami mendukung alur kerja lanjutan untuk template.

Langkah 1: Membuat template perintah server

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

1. Di Firebase console, buka tab AI Services > AI Logic > Prompt templates.

2. Klik Create new template, 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 sepenuhnya mengubah template untuk memenuhi kebutuhan Anda.

   • Panduan memulai ini mengasumsikan bahwa Anda telah memilih opsi Input + System Instructions.

3. 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.

   • Template ID: ID 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 memiliki maksimal 63 karakter dan dapat berisi huruf kecil, angka, dan tanda hubung.

4. Ubah bagian Configuration (frontmatter) template, jika diperlukan.

   • Bagian ini harus menyertakan minimal nama model, seperti ini:

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

5. Ubah bagian Prompt and (as applicable) system instructions template, jika diperlukan.

   • Bagian ini harus menyertakan minimal 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: Menguji template di Firebase console

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

1. Klik Save template agar Anda dapat menguji template.

   Anda selalu dapat mengedit atau bahkan menghapus template nanti. Satu-satunya nilai yang tidak dapat Anda ubah nanti adalah ID template.

2. Jika perintah Anda menggunakan variabel input, sertakan nilai pengujian di kolom Test input. Untuk contoh ini:

     {
       "customerName": "Jane"
     }
   

3. 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 dikirim 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.

4. Klik tombol Create formatted test request.

   Tinjau Formatted test request yang dihasilkan di sisi kanan layar, dan ulangi kolom template Anda.

   Luaskan untuk melihat contoh permintaan pengujian yang diformat

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

5. Jika Anda puas dengan permintaan pengujian yang diformat, klik tombol Run prompt test.

   Tinjau Test response yang dihasilkan di sisi kanan layar, dan ulangi 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-3.5-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Jika Anda siap mengakses template dari kode aplikasi, kunci template dengan mengklik ikon lock kunci di sudut kanan atas template.

7. Klik Close untuk keluar dari pengalaman pengeditan.

Langkah 3: Mengakses template dari kode

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

• Gunakan templateGenerativeModel (atau templateImagenModel, jika diperlukan).
• 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 diterapkan di seluruh server Firebase sebelum mengaksesnya dari kode Anda.

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "global")).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")

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "global")).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)

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.vertexAI("global")).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);

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
const ai = getAI(app, { backend: new VertexAIBackend('global') });

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

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.vertexAI(location: 'global').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);

// ...

// Initialize the Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "global"));

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

Apa langkah selanjutnya?

• Pelajari tentang praktik terbaik dan pertimbangan untuk menggunakan template perintah server.

• Pelajari detail tentang format dan sintaksis template, beserta contohnya.

• Pelajari cara mengelola template, termasuk mengedit, mengunci, dan kontrol versi.

• Pelajari tentang alur kerja lanjutan, seperti menggunakan template secara terprogram menggunakan REST API atau men-deploy template ke lokasi tertentu.