شروع به کار با الگوهای پیام‌واره سرور


در هر درخواست به مدل، یک پیام‌واره و به‌صورت اختیاری طرح‌واره و پیکربندی‌هایی برای کنترل پاسخ مدل ارسال می‌کنید. هنگام استفاده از Firebase AI Logic، می‌توانید همه این اطلاعات را مستقیماً از کد کارخواه ارسال کنید، یا می‌توانید این اطلاعات را در سمت سرور بااستفاده از الگوهای پیام‌واره سرور مشخص کنید.

هنگام استفاده از الگوهای پیام‌واره سرور، پیام‌واره، طرح‌واره، و پیکربندی‌هایتان را در سمت سرور ذخیره می‌کنید و پایگاه کد برنامه‌تان فقط یک کلید (شناسه الگو) را که به الگوی خاصی ارجاع می‌دهد و همچنین ورودی‌های لازم برای آن الگو را از کارخواه به سرور ارسال می‌کند. در اینجا برخی‌از مزایای این رویکرد آورده شده است:

  • محافظت دربرابر افشای پیام‌واره در سمت کارخواه

  • پیام‌واره و پیکربندی‌تان را بدون انتشار نسخه جدید برنامه به‌روز کنید

این راهنما نحوه شروع استفاده از الگوهای پیام‌واره سرور را شرح می‌دهد.

پرش به نمای کلی سطح بالا پرش به دستورالعمل‌های دقیق

مدل‌ها و قابلیت‌های پشتیبانی‌شده


نمای کلی سطح بالا

در اینجا گردش کار اصلی برای استفاده از الگوهای پیام‌واره سرور آورده شده است:

  1. الگو را بااستفاده از واسط کاربر راهنمایی‌شده در کنسول Firebase ایجاد کنید.

  2. الگو را در درخواست واقعی بااستفاده از تجربه آزمایشی در کنسول Firebase آزمایش کنید.

  3. بااستفاده از templateGenerativeModel، از کد برنامه‌تان به الگو دسترسی پیدا کنید.

قالب اصلی الگوی پیام‌واره سرور

برای Firebase AI Logic، کنسول Firebase واسط کاربر راهنمایی‌شده‌ای برای شما فراهم می‌کند تا بتوانید فراداده و محتوای الگو را مشخص کنید.

الگوهای پیام‌واره سرور از نحو و قالب مبتنی بر 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}}.

  • بخش بالایی در داخل خط تیره‌های سه‌گانه حاوی نام مدل و همچنین به‌صورت اختیاری هرگونه پیکربندی مدل، اعتبارسنجی ورودی، یا طرح‌واره‌ای است که می‌خواهید در درخواست ارسال کنید. این فراداده به‌صورت جفت‌های کلید-مقدار نوشته می‌شود و معمولاً frontmatter YAML نامیده می‌شود.

  • بدنه الگو حاوی پیام‌واره است. همچنین می‌تواند به‌صورت اختیاری شامل دستورالعمل‌های سیستم و مقادیر ورودی (بااستفاده از نحو 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، افزودن کیت توسعه نرم‌افزار، مقداردهی اولیه سرویس پس‌بست برای ارائه‌دهنده Gemini API انتخابی، و ایجاد نمونه GenerativeModel را شرح می‌دهد.

  • مطمئن شوید که اجازه‌های لازم را برای ایجاد و مدیریت الگوهای پیام‌واره سرور دارید. به‌طور پیش‌فرض، همه این اجازه‌ها در نقش «مالک» گنجانده شده است.

  • اگر از Agent Platform Gemini API (formerly Vertex AI) استفاده می‌کنید و اگر مورد استفاده شما به محدودیت‌های مبتنی بر مکان نیاز دارد، ما از گردش کارهای پیشرفته برای الگوها پشتیبانی می‌کنیم.

مرحله ۱: ایجاد الگوی پیام‌واره سرور

برای اکثر موارد استفاده، الگوهای پیام‌واره سرور را در کنسول Firebase ایجاد و مدیریت می‌کنید.

  1. در کنسول Firebase، به برگه سرویس‌های هوش مصنوعی > منطق هوش مصنوعی > الگوهای پیام‌واره بروید.

  2. روی ایجاد الگوی جدید کلیک کنید و یکی از گزینه‌های الگوی شروع را انتخاب کنید.

    • این الگوهای آغازین قالب و نحو را برای برخی‌از موارد استفاده رایج ارائه می‌دهند. بااین‌حال، صرف‌نظر از اینکه کدام گزینه را انتخاب می‌کنید، می‌توانید الگو را کاملاً تغییر دهید تا با نیازهایتان مطابقت داشته باشد.

    • این راهنمای شروع به کار فرض می‌کند که گزینه Input + System Instructions را انتخاب کرده‌اید.

  3. شناسه‌های الگو را وارد کنید:

    • نام الگو: این نام نمایشی الگو است (برای مثال، My First Template). این نام فقط در واسط‌های Firebase، مانند کنسول Firebase، قابل‌مشاهده است.

    • شناسه الگو: این شناسه باید برای الگو در پروژه Firebase شما یکتا باشد (برای مثال، my-first-template-v1-0-0). در درخواست از برنامه‌تان به این شناسه ارجاع خواهید داد.

      • توصیه می‌کنیم از سیستم نسخه‌بندی برای شناسه‌های الگوی خود استفاده کنید.

      • شناسه الگو می‌تواند حداکثر ۶۳ نویسه داشته باشد و می‌تواند حاوی حروف کوچک، عدد، و خط تیره باشد.

  4. درصورت نیاز، بخش پیکربندی (مقدمه) الگو را اصلاح کنید.

    • این بخش باید حداقل شامل نام مدل باشد، مانند این:

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

    • همچنین می‌توانید به‌صورت اختیاری پیکربندی مدل و هرگونه کنترل ورودی و خروجی و غیره را مشخص کنید. برای جزئیات و گزینه‌های بیشتر، به قالب، نحو، و نمونه‌های الگو مراجعه کنید.

  5. درصورت نیاز، بخش دستورالعمل‌های سیستم و پیام‌واره (درصورت وجود) الگو را اصلاح کنید.

    • ‫This section must include at minimum the text prompt to send to the model.

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

مرحله ۲: الگوی خود را در کنسول Firebase آزمایش کنید

کنسول Firebase تجربه آزمایشی برای الگوی شما ارائه می‌دهد. این تجربه به شما امکان می‌دهد ببینید وقتی از الگوی شما استفاده می‌شود چه اتفاقی می‌افتد – هم قالب درخواست و هم خروجی درخواست واقعی.

  1. روی ذخیره الگو کلیک کنید تا بتوانید الگوتان را آزمایش کنید.

    همیشه می‌توانید بعداً الگو را ویرایش یا حتی حذف کنید. تنها مقداری که بعداً نمی‌توانید تغییر دهید شناسه الگو است.

  2. اگر پیام‌واره‌تان از متغیرهای ورودی استفاده می‌کند، مقادیر آزمایشی را در فیلد ورودی آزمایشی وارد کنید. برای این مثال:

      {
    "customerName": "Jane"
  }

  3. اگر چند ارائه‌دهنده Gemini API در پروژه Firebase شما فعال باشد، می‌توانید انتخاب کنید که از کدام‌یک برای درخواست آزمایش استفاده شود. اگر این گزینه در کنسول نمایش داده می‌شود، Gemini Developer API یا Agent Platform Gemini API (Vertex AI سابق) را انتخاب کنید.

    توجه داشته باشید که این انتخاب فقط برای درخواست‌های ارسال‌شده ازطریق Firebase تجربه آزمایش کنسول اعمال می‌شود. در درخواست واقعی از برنامه‌تان، ارائه‌دهنده Gemini API انتخابی‌تان را درست مثل هر درخواست دیگری مشخص می‌کنید.

  4. روی دکمه ایجاد درخواست آزمایشی قالب‌بندی‌شده کلیک کنید.

    درخواست آزمایشی قالب‌بندی‌شده حاصل را در سمت راست صفحه مرور کنید و هرکدام از فیلدهای الگو را تکرار کنید.

  5. وقتی از درخواست آزمایشی قالب‌بندی‌شده راضی بودید، روی دکمه اجرای آزمایش پیام‌واره کلیک کنید.

    پاسخ آزمایشی حاصل را در سمت چپ صفحه مرور کنید و هرکدام از فیلدهای الگو را تکرار کنید.

  6. اگر آماده‌اید از کد برنامه‌تان به الگو دسترسی پیدا کنید، با کلیک کردن روی نماد قفل در گوشه بالای الگو، الگو را قفل کنید.

  7. برای خروج از تجربه ویرایش، روی بستن کلیک کنید.

مرحله ۳: دسترسی به الگو از کد

روی ارائه‌دهنده Gemini API کلیک کنید تا محتوا و کد مختص ارائه‌دهنده را در این صفحه ببینید.

درخواست بااستفاده از الگوی پیام‌واره سرور مشابه درخواست‌های دیگر است، با اصلاحات زیر:

  • از templateGenerativeModel استفاده کنید.
  • شناسه الگو را ارائه دهید.
  • مقادیر هر ورودی متغیری را که الگوی شما نیاز دارد ارائه دهید.

توجه داشته باشید که پس‌از ایجاد یا به‌روزرسانی الگو، ممکن است لازم باشد چند دقیقه صبر کنید تا الگو در سرورهای Firebase منتشر شود و سپس از کدتان به آن دسترسی پیدا کنید.

Swift

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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

نمونه templateGenerativeModel ایجاد کنید تا از الگو در درخواستتان استفاده کنید.


// ...

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


قدم بعدی چیست؟