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


در هر درخواست به مدل، پیام‌واره و به‌صورت اختیاری طرحواره و پیکربندی‌هایی برای کنترل پاسخ مدل ارسال می‌کنید. هنگام استفاده از 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}}.

  • بخش بالایی در داخل خط‌چین سه‌تایی حاوی نام مدل و همچنین به‌صورت اختیاری هرگونه پیکربندی مدل، اعتبارسنجی ورودی، یا طرحواره‌ای است که می‌خواهید در درخواست ارسال کنید. به‌صورت جفت‌های کلید-مقدار نوشته می‌شود و معمولاً به آن پیش‌گفتار 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.
  '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();

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. بخش پیام‌واره و (درصورت لزوم) دستورالعمل‌های سیستم را در الگو، درصورت نیاز، اصلاح کنید.

    • این بخش باید حداقل پیام‌واره نوشتاری را برای ارسال به مدل داشته باشد.

      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.
  '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();

Dart

افزایه Flutter به‌زودی از الگوهای پیام‌واره سرور پشتیبانی خواهد کرد!

برای استفاده از الگو در درخواستتان، نمونه 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}");
}


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