Sunucu istemi şablonlarını kullanmaya başlama

Bir modele gönderdiğiniz her istekte, istem ve isteğe bağlı olarak şema ve yapılandırmalar göndererek modelin yanıtını kontrol edersiniz. Firebase AI Logic kullanırken tüm bu bilgileri doğrudan istemci kodunuzdan gönderebilir veya sunucu istemi şablonlarını kullanarak sunucu tarafında belirtebilirsiniz.

Sunucu istemi şablonlarını kullanırken isteminizi, şemanızı ve yapılandırmalarınızı sunucu tarafında saklarsınız. Uygulamanız ise istemciden sunucuya yalnızca belirli bir şablona referans veren anahtarı (şablon kimliği) ve bu şablon için gerekli girişleri iletir.

Sunucu istemi şablonlarını kullanırken isteminizi ve yapılandırmalarınızı sunucu tarafında saklar ve uygulamanızın kod tabanında yalnızca bir anahtar (şablon kimliği) sağlarsınız. Bu yaklaşımın bazı avantajları şunlardır:

• İsteminizin istemci tarafında açığa çıkmasını önleme

• Yeni bir uygulama sürümü yayınlamadan isteminizi ve yapılandırmanızı güncelleme

Bu kılavuzda, sunucu istemi şablonlarını kullanmaya nasıl başlayacağınız açıklanmaktadır.

arrow_downward Üst düzey genel bakışa git arrow_downward Ayrıntılı talimatlara git

Desteklenen modeller ve özellikler

• Firebase AI Logic tarafından desteklenen Gemini ve Imagen modellerinin herhangi biriyle Gemini Live modelleri hariç sunucu istemi şablonlarını kullanın.

• Henüz desteklenmeyen özelliklerin listesini inceleyin.

Üst düzey genel bakış

Sunucu istemi şablonlarını kullanmayla ilgili temel iş akışı şöyledir:

1. Firebase konsolundaki rehberli kullanıcı arayüzünü kullanarak şablonu oluşturun.

2. FirebaseKonsolun test deneyimini kullanarak şablonu gerçek bir istekte test edin.

3. Uygulamanızdan şablona erişin.

Sunucu istemi şablonlarının temel biçimi

Firebase AI Logic için Firebase konsolu, şablonun içeriğini belirtmeniz için size rehberli bir kullanıcı arayüzü sunar.

Sunucu istemi şablonları, Dotprompt tabanlı bir sözdizimi ve biçim kullanır. Daha fazla bilgi için Şablon biçimi, söz dizimi ve örnekler başlıklı makaleye bakın.

Gemini modeline gönderilen örnek bir istek için en önemli bileşenler şunlardır:

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

• Üçlü tireler arasındaki üst bölümde model adı ve isteğe bağlı olarak, istekte göndermek istediğiniz model yapılandırması, giriş doğrulama veya şema yer alır. Anahtar/değer çiftleri olarak yazılır ve genellikle YAML frontmatter olarak adlandırılır.

• Şablonun gövdesinde istem bulunur. Ayrıca isteğe bağlı olarak sistem talimatları ve giriş değerleri de içerebilir (Handlebars söz dizimi kullanılarak).

Şablonunuzu kodda kullanma

Şablonu kodunuzda nasıl kullanacağınız aşağıda açıklanmıştır:

// ...

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

// ...

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

// ...

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

// ...

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

Ayrıntılı talimatlar

Bu bölümde, sunucu istemi şablonları oluşturma, test etme ve kullanmayla ilgili ayrıntılı talimatlar verilmektedir.

Başlamadan önce

• Henüz yapmadıysanız Firebase projenizi ayarlama, uygulamanızı Firebase'e bağlama, SDK'yı ekleme, seçtiğiniz Gemini API sağlayıcısı için arka uç hizmetini başlatma ve GenerativeModel örneği oluşturma işlemlerinin nasıl yapılacağını açıklayan başlangıç kılavuzunu tamamlayın.

• Sunucu istemi şablonları oluşturmak ve yönetmek için gerekli izinlere sahip olduğunuzdan emin olun. Varsayılan olarak bu izinlerin tümü sahip rolüne dahildir.

  Gerekli izinleri göster

  • 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

• Vertex AI Gemini API kullanıyorsanız ve kullanım alanınız konum tabanlı kısıtlamalar gerektiriyorsa şablonlar için gelişmiş iş akışlarını destekliyoruz.

1. adım: Sunucu istemi şablonu oluşturun

Çoğu kullanım alanında, sunucu istemi şablonlarını Firebase konsolunda oluşturup yönetirsiniz.

1. Firebase konsolunda Firebase AI Logic İstem şablonları sekmesine gidin.

2. Yeni şablon oluştur'u tıklayın ve bir başlangıç şablonu seçeneği belirleyin.

   • Bu başlangıç şablonları, bazı yaygın kullanım alanları için biçim ve söz dizimi sağlar. Hangi seçeneği belirlerseniz belirleyin, şablonu ihtiyaçlarınıza göre tamamen değiştirebilirsiniz.

   • Bu başlangıç kılavuzunda, Input + System Instructions seçeneğini belirlediğiniz varsayılmaktadır.

3. Şablonun tanımlayıcılarını girin:

   • Şablon adı: Bu, şablonun görünen adıdır (örneğin, My First Template). Yalnızca Firebase konsolu gibi Firebase arayüzlerinde görünür.

   • Şablon kimliği: Bu, Firebase projenizdeki şablonun benzersiz kimliği olmalıdır (örneğin, my-first-template-v1-0-0). Bu kimliğe uygulamanızdan gelen istekte referans vereceksiniz.

     • Şablon kimlikleriniz için sürüm oluşturma sistemi kullanmanızı öneririz.

     • Şablon kimlikleri en fazla 63 karakter olabilir ve küçük harf, rakam ve kısa çizgi içerebilir.

4. Gerekirse şablonun Configuration (frontmatter) (Yapılandırma) bölümünü değiştirin.

   • Bu bölümde en azından şu şekilde bir model adı yer almalıdır:

     ---
     model: 'gemini-2.5-flash'
     ---
     

   • İsteğe bağlı olarak modelin yapılandırmasını ve giriş/çıkış kontrollerini de belirtebilirsiniz. Daha fazla ayrıntı ve seçenek için Şablon biçimi, söz dizimi ve örnekler başlıklı makaleyi inceleyin.

5. Şablondaki İstem ve (geçerli olduğu durumlarda) sistem talimatları bölümünü gerektiği şekilde değiştirin.

   • Bu bölümde, modele gönderilecek metin istemi en azından yer almalıdır.

     Write a story about a magic backpack.
     

   • Aşağıdaki seçenekler gibi daha karmaşık istemler de oluşturabilirsiniz. Daha fazla ayrıntı ve seçenek için Şablon biçimi, söz dizimi ve örnekleri başlıklı makaleyi inceleyin.

     • (İsteğe bağlı ve geçerli olduğu durumlarda) {{role "system"}} söz dizimini kullanarak sistem talimatlarını, {{role "user"}} söz dizimini kullanarak da metin istemini belirtin.

     • (İsteğe bağlı) Handlebars söz dizimini (ör. {{customerName}}) kullanarak giriş değişkenlerini belirtin. Şablonda varsayılan bir değer sağlayabilirsiniz ancak bu giriş değişkeninin değeri genellikle istekte iletilir.

     {{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. adım: Şablonunuzu Firebase konsolunda test edin

Firebase konsolu, şablonunuz için bir test deneyimi sunar. Bu deneyim, şablonunuz kullanıldığında ne olacağını görmenizi sağlar. Hem isteğin biçimini hem de gerçek bir isteğin çıktısını görebilirsiniz.

1. Şablonunuzu test edebilmek için Şablonu kaydet'i tıklayın.

   Şablonu daha sonra istediğiniz zaman düzenleyebilir veya silebilirsiniz. Daha sonra değiştiremeyeceğiniz tek değer şablon kimliğidir.

2. İsteminizde giriş değişkenleri kullanılıyorsa Test girişi alanına test değerleri ekleyin. Bu örnekte:

     {
       "customerName": "Jane"
     }
   

3. Firebase projenizde birden fazla Gemini API sağlayıcı etkinse test isteği için hangisini kullanacağınızı seçebilirsiniz. Bu seçenek konsolda gösteriliyorsa Gemini Developer API veya Vertex AI Gemini API simgesini seçin.

   Bu seçimin yalnızca Firebase konsol test deneyimi üzerinden gönderilen istekler için geçerli olduğunu unutmayın. Uygulamanızdan gelen gerçek istekte, seçtiğiniz Gemini API sağlayıcıyı diğer isteklerde olduğu gibi belirtirsiniz.

4. Biçimlendirilmiş test isteği oluştur düğmesini tıklayın.

   Ekranın sağ tarafındaki sonuç Biçimlendirilmiş test isteği'ni inceleyin ve şablonunuzun alanlarında yineleme yapın.

   Biçimlendirilmiş örnek test isteğini görüntülemek için genişletin.

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

5. Biçimlendirilmiş test isteğinden memnun olduğunuzda İstem testini çalıştır düğmesini tıklayın.

   Ekranın sağ tarafındaki Test yanıtı'nı inceleyin ve şablonunuzun alanlarında yineleme yapın.

   Örnek test yanıtını görüntülemek için genişletin

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

6. Şablona uygulamanızın kodundan erişmeye hazırsanız şablonun sağ üst köşesindeki lock kilit simgesini tıklayarak şablonu kilitleyin.

7. Düzenleme deneyiminden çıkmak için Kapat'ı tıklayın.

3. adım: Şablonunuza kodunuzdan erişin

Bir sunucu istemi şablonu kullanan istek, aşağıdaki ayarlamalarla diğer isteklere benzer:

• templateGenerativeModel (veya gerekirse templateImagenModel) kullanın.
• Şablon kimliğini sağlayın.
• Şablonunuzun gerektirdiği tüm değişken girişlerinin değerlerini sağlayın.

Şablonunuzu oluşturduktan veya güncelledikten sonra, kodunuzdan erişmeden önce şablonun Firebase sunucularına yayılması için birkaç dakika beklemeniz gerekebilir.

// ...

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

// ...

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

// ...

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

// ...

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

Sırada ne var?

• Sunucu istemi şablonlarını kullanmayla ilgili en iyi uygulamalar ve dikkat edilmesi gereken noktalar hakkında bilgi edinin.

• Şablon biçimi ve söz dizimi ile ilgili ayrıntıları ve örnekleri öğrenin.

• Düzenleme, kilitleme ve sürüm kontrolü dahil şablonları yönetme