Sunucu istemi şablonlarını kullanmaya başlama


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

Sunucu istem şablonlarını kullanırken isteminizi, şemanızı ve yapılandırmalarınızı sunucu tarafında depolarsınız. Uygulamanızın kod tabanı, istemciden sunucuya yalnızca belirli bir şablona referans veren bir anahtar (şablon kimliği) ve bu şablon için gerekli girişleri iletir. Bu yaklaşımın bazı avantajları şunlardır:

  • İstemci tarafında isteminizin açığa çıkmasını önleme

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

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

Genel bakışa atla Ayrıntılı talimatlara atla

Desteklenen modeller ve özellikler


Üst düzey genel bakış

Sunucu istem şablonlarını kullanmayla ilgili temel iş akışı şu şekildedir:

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

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

  3. templateGenerativeModel kullanarak uygulamanızın kodundan şablona erişin.

Sunucu istem şablonunun temel biçimi

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

Sunucu istem şablonları, Dotprompt tabanlı bir söz dizimi ve biçim kullanır. Daha fazla bilgi için Şablon biçimi, söz dizimi ve örnekler başlıklı makaleyi inceleyin.

Aşağıdaki örnek şablonda, bir Gemini modeline gönderilen örnek istek için şablonun en önemli bileşenleri gösterilmektedir:

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

  • Üç tirenin içindeki üst bölümde model adı ve isteğe bağlı olarak istekte göndermek istediğiniz model yapılandırması, giriş doğrulaması 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 yer alır. İsteğe bağlı olarak sistem talimatları ve giriş değerleri de (Handlebars söz dizimi kullanılarak) içerebilir.

Şablonunuzu kodda kullanma

Bu sayfada sağlayıcıya özel içerikleri ve kodları görüntülemek için Gemini API sağlayıcınızı tıklayın.

Aşağıdaki örnek istemci kodu, şablonun kodunuzda nasıl kullanılacağını gösterir:

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


Ayrıntılı talimatlar

Bu bölümde, sunucu istem şablonları oluşturma, test etme ve kullanma ile ilgili ayrıntılı talimatlar verilmiştir.

Başlamadan önce

  • Henüz yapmadıysanız Firebase projenizi nasıl oluşturacağınızı, uygulamanızı Firebase'e nasıl bağlayacağınızı, SDK'yı nasıl ekleyeceğinizi, seçtiğiniz Gemini API sağlayıcı için arka uç hizmetini nasıl başlatacağınızı ve bir GenerativeModel örneği nasıl oluşturacağınızı açıklayan başlangıç kılavuzunu tamamlayın.

  • Sunucu istem ş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.

  • Agent Platform Gemini API (formerly Vertex AI) kullanıyorsanız ve kullanım alanınız konuma dayalı kısıtlamalar gerektiriyorsa şablonlar için gelişmiş iş akışlarını destekleriz.

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

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

  1. Firebase konsolunda AI Services (Yapay Zeka Hizmetleri) > AI Logic (Yapay Zeka Mantığı) > Prompt templates (İ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. Ancak 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 (ör. My First Template). Yalnızca Firebase konsolu gibi Firebase arayüzlerinde görünür.

    • Şablon kimliği: Bu, Firebase projenizdeki şablon için benzersiz bir kimlik olmalıdır (örneğin, my-first-template-v1-0-0). Uygulamanızdan gelen istekte bu kimliğe referans verirsiniz.

  4. Şablonun Configuration (frontmatter) [Yapılandırma (ön bilgi)] bölümünü gerektiği gibi değiştirin.

    • Bu bölümde en azından bir model adı bulunmalıdır. Örneğin:

      ---
model: 'gemini-3.8-flash'
---

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

  5. Şablonun İstem ve (varsa) sistem talimatları bölümünü gerektiği gibi değiştirin.

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

      Write a story about a magic backpack.

    • Aşağıdaki seçenekler gibi daha karmaşık istemler de oluşturabilirsiniz. Daha fazla bilgi ve seçenek için Şablon biçimi, söz dizimi ve örnekler 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 ({{customerName}} gibi) 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ı (hem isteğin biçimini hem de gerçek bir isteğin çıkışını) görmenizi sağlar.

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

    Şablonu daha sonra istediğiniz zaman düzenleyebilir, hatta 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 giriş alanına test değerlerini ekleyin. Bu örnekte:

      {
    "customerName": "Jane"
  }

  3. Firebase projenizde birden fazla Gemini API sağlayıcı etkinleştirilmişse test isteği için hangisinin kullanılacağını seçebilirsiniz. Bu seçenek konsolda gösteriliyorsa Gemini Developer API veya Agent Platform Gemini API'ı (eski adıyla Vertex AI) seçin.

    Bu seçimin yalnızca Firebase Console test deneyimi aracılığıyla 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ısını herhangi bir istekte yaptığınız gibi belirtirsiniz.

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

    Ekranın sağ tarafında gösterilen Biçimlendirilmiş test isteği'ni inceleyin ve şablonunuzun alanlarından herhangi birini yineleyin.

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

    Ekranın sağ tarafında gösterilen Test response (Test yanıtı) bölümünü inceleyin ve şablonunuzun alanlarından herhangi birini yineleyin.

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

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

3. adım: Kodunuzdan şablonunuza erişin

Bu sayfada sağlayıcıya özel içerikleri ve kodları görüntülemek için Gemini API sağlayıcınızı tıklayın.

Sunucu istem şablonu kullanan bir istek, diğer isteklere benzer ancak aşağıdaki düzenlemeler yapılır:

  • templateGenerativeModel kullanın.
  • Şablon kimliğini girin.
  • Şablonunuzun gerektirdiği değişken girişlerinin değerlerini girin.

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

Swift

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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

İsteğinizde şablon kullanmak için bir templateGenerativeModel örneği oluşturun.


// ...

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


Sırada ne var?