قالب الگو، نحو، و نمونه‌ها


برای 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-3.8-flash استفاده می‌کنند، اما می‌توانید از هر مدل Gemini که توسط Firebase AI Logic پشتیبانی می‌شود (به‌جز مدل‌های Gemini Live API) استفاده کنید.

سلام به همه

در اینجا نمونه‌ای حداقلی از الگوی پیام‌واره سرور آورده شده است:

پیکربندی (frontmatter)

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

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Write a story about a magic backpack.



کنترل کردن تولید پاسخ‌ها

می‌توانید تولید پاسخ‌ها را به روش‌های مختلفی بسته به مورد استفاده و سطح کنترلی که نیاز دارید کنترل کنید.

پیکربندی مدل

پیکربندی مدل را تنظیم کنید تا نحوه تولید پاسخ توسط مدل را کنترل کنید، مانند حداکثر داده‌واحدهای خروجی، توالی‌های توقف، و غیره.

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
config:
  maxOutputTokens: 200
  stopSequences: ["red"]
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Write a story about a magic backpack.


پیکربندی اندیشیدن

پیکربندی مرتبط با تفکر را برای مدل‌هایی که از تفکر پشتیبانی می‌کنند مشخص کنید.

پیکربندی (frontmatter)

  • ‫Gemini 3.x و مدل‌های جدیدتر (سطوح اندیشیدن)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • ‫Gemini 2.5 مدل (بودجه‌های تفکر)

    ---
    model: 'gemini-2.5-flash'
    config:
      thinkingConfig:
        thinkingBudget: 1024
        includeThoughts: true
    ---
    

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Solve x^2 + 4x + 4 = 0


تنظیمات ایمنی

از تنظیمات ایمنی برای تنظیم احتمال دریافت پاسخ‌هایی که ممکن است مضر تلقی شوند استفاده کنید.

پیکربندی (frontmatter)

مثال با یک تنظیم ایمنی:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
---

نمونه‌ای با چند تنظیم ایمنی:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
    - category: HARM_CATEGORY_HATE_SPEECH
      threshold: BLOCK_MEDIUM_AND_ABOVE
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Write a story about a magic backpack.


دستورالعمل‌های سیستم

دستورالعمل‌های سیستم را برای هدایت رفتار مدل تنظیم کنید. آن‌ها را به‌عنوان بخشی از پیام‌واره اضافه کنید:

  • دستورالعمل‌های سیستم را بااستفاده از نحو {{role "system"}} مشخص کنید.

  • پیام‌واره نوشتاری را بااستفاده از نحو {{role "user"}} مشخص کنید.

پیکربندی (frontmatter)

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



متغیرهای ورودی

برخی‌از پیام‌واره‌ها ثابت هستند، اما اغلب لازم است برخی‌از داده‌های کاربر را به‌عنوان بخشی از پیام‌واره اضافه کنید.

می‌توانید متغیرهای ورودی پویا را بااستفاده از عبارت‌های Handlebars در پیام‌واره بگنجانید. این عبارت‌ها در برچسب‌های {{ }} با قالب {{variableName}} یا {{object.propertyName}} (برای مثال، Hello, {{name}} from {{address.city}}) قرار می‌گیرند.

پیکربندی (frontmatter)

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

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Create an example customer invoice for a customer named {{customerName}}.

می‌توانید مقدار پیش‌فرضی در الگو ارائه دهید، اما مقدار متغیر ورودی معمولاً توسط کارخواه به‌عنوان بخشی از درخواست ارائه می‌شود.



جریان‌های کنترل (حلقه‌ها و شرطی‌ها)

برای نوشتن پیام‌واره‌های پیچیده‌تر، می‌توانید از بلوک‌های شرطی (مثل #if، else، و #unless) و تکرار (#each) استفاده کنید.

می‌توانید اطلاعات زمینه‌ای تکمیلی را به‌عنوان متغیرهایی با پیشوند ویژه @ ارائه دهید:

  • ‫@first: درست است وقتی‌که اولین مورد از بلوک #each تکرار می‌شود.
  • ‫@last: وقتی آخرین مورد از قطعه #each تکرار می‌شود، مقدار آن true است.
  • @index: موقعیت نمایه (مبتنی بر صفر) عنصر فعلی را ارائه می‌دهد.

برای اطلاعات درباره همه کمک‌کننده‌های منطقی داخلی، اسناد Handlebars را ببینید.

پیکربندی (frontmatter)

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

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}

توجه داشته باشید که شرطی‌ها فقط مرجع متغیر را می‌پذیرند، نه هیچ نوع عبارتی، برای مثال:

  • آثار زیر: {{#if isVipCustomer}} ... {{/if}}
  • موارد زیر کار نمی‌کند: {{#if customer.type == 'vip'}} ... {{/if}}

اگر متغیر بولی باشد، شرطی طبق انتظار شما کار می‌کند. اگر متغیر بولی نباشد، شرطی درواقع بررسی «is-not-null» است. این کار می‌تواند برای مدیریت ورودی‌های اختیاری مفید باشد، برای مثال:

{{#if customerName}}
Hello {{customerName}}
{{else}}
Hello Guest
{{/if}}



اعتبارسنجی ورودی و طرح‌واره

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

  • می‌توانید مقادیر پیش‌فرضی را برای مواردی که مشتری مقداری ارائه نمی‌کند ارائه دهید.

  • این طرح‌واره از انواع اسکالر string، integer، number، boolean، و object پشتیبانی می‌کند. اشیاء، آرایه‌ها، و شمارش‌ها با پرانتز بعداز نام فیلد نشان داده می‌شوند.

  • همه ویژگی‌ها الزامی درنظر گرفته می‌شوند مگراینکه آن را با ? به‌عنوان اختیاری مشخص کنید. وقتی ویژگی‌ای به‌عنوان اختیاری علامت‌گذاری می‌شود، همچنین قابل‌تهی می‌شود تا به مدل‌های زبانی بزرگ اجازه دهد به‌جای حذف فیلد، مقدار تهی برگردانند.

در اینجا نمونه‌ای ساده برای ارائه طرح‌واره ورودی آورده شده است. می‌توانید طرح‌واره پیشرفته‌تری را در زیر ببینید.

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  default:
    isVipCustomer: false
  schema:
    customerName: string, the customers name  # string, number, and boolean types are defined like this
    productNames?(array, list of products to include in the invoice): string  # optional fields are marked with a ?
    isVipCustomer?: boolean, whether or not the customer is a VIP
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}



طرح‌واره برونداد

اگر می‌خواهید مدل برونداد JSON ساختاریافته تولید کند، می‌توانید طرح‌واره برونداد را مشخص کنید. با مشخص کردن format: json، مدل را محدود می‌کنید تا همیشه پاسخی در قالب JSON برگرداند که از طرحواره مشخص‌شده پیروی می‌کند.

  • این طرح‌واره از انواع اسکالر string، integer، number، boolean، و object پشتیبانی می‌کند. اشیاء، آرایه‌ها، و شمارش‌ها با پرانتز بعداز نام فیلد نشان داده می‌شوند.

  • همه ویژگی‌ها الزامی درنظر گرفته می‌شوند مگراینکه آن را با ? به‌عنوان اختیاری مشخص کنید. وقتی ویژگی‌ای به‌عنوان اختیاری علامت‌گذاری می‌شود، همچنین قابل‌تهی می‌شود تا به مدل‌های زبانی بزرگ اجازه دهد به‌جای حذف فیلد، مقدار تهی برگردانند.

در اینجا نمونه‌ای ساده برای تولید خروجی JSON ساختاریافته آورده شده است. می‌توانید طرح‌واره پیشرفته‌تری را در زیر پیدا کنید.

پیکربندی (frontmatter)

---
model: gemini-3.8-flash
output:
  format: json
  schema:
    invoiceId: string
    invoiceFile(object, an invoice file):
      url?: string
      contents: string
      mimeType: string
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Create an example customer invoice.



ورودی چندحالته

پیام‌واره‌های چندحالته ارسال‌شده به مدل Gemini می‌تواند شامل انواع مختلفی از ورودی باشد، ازجمله فایل‌ها (مانند نوشتار همراه با تصاویر، فایل‌های PDF، فایل‌های نوشتار ساده، صدا، و ویدیو).

  • فایلی را بااستفاده از نشانی وب آن با نحو {{media url}} ارائه دهید.

  • فایل درون‌خطی با نحو {{media type="mime_type" data="contents"}} ارائه دهید.

مثال پایه (ورودی چندحالته)

در اینجا نمونه‌ای ساده برای ارائه ورودی چندحالته آورده شده است. در زیر می‌توانید نمونه پیچیده‌تری را ببینید.

پیکربندی (frontmatter)

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

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Describe this image

{{media type="mimeType" data="imageData"}}

مثال پیچیده (ورودی چندحالته)

در اینجا مثال پیچیده‌تری برای ارائه ورودی چندوجهی آورده شده است.

پیکربندی (frontmatter)

---
model: gemini-3.8-flash
input:
  schema:
    image_urls?(array, urls of external images): string
    inline_images?(array, inline image data):
      type: object
      properties:
        mime_type: string
        contents: string  # inline data must be base64-encoded
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

{{role "system"}}
Use the following image as the basis for comparisons
{{media url="http://example.com/reference_img.bmp"}}

{{role "user"}}
What do the following images have in common?

{{#each image_urls}}
  {{media url="this"}}
{{/each}}

{{#each inline_images}}
  {{media type="mime_type" data="contents"}}
{{/each}}



استفاده از ابزار

الگوهای پیام‌واره سرور از ابزارهای زیر پشتیبانی می‌کنند.

اگر می‌خواهید کاربرانتان اطلاعات بیشتری برای درخواست به مدل ارائه دهند، از متغیرهای ورودی در الگوی پیام‌واره سرور، همراه با اعتبارسنجی ورودی استفاده کنید.

فراخوانی تابع

راهنمای کامل فراخوانی تابع بااستفاده از الگوهای پیام‌واره سرور را ببینید.

اجرای کد

ابزار اجرای کد به مدل امکان می‌دهد کد Python تولید و اجرا کند.

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - codeExecution
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

What is the sum of the first 50 prime numbers?
Generate and run code for the calculation, and make sure you get all 50.

بافت نشانی وب

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

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  schema:
    url1:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
    url2:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
tools:
  - urlContext
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Compare the ingredients and cooking times from the recipes at {{url1}} and {{url2}}

ابزار پایه‌سازی با Google Search مدل را به محتوای وب هم‌زمان و دردسترس عموم متصل می‌کند.

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleSearch
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

Who won the Euro 2024?

پایه‌مندسازی با Google Maps

ابزار پایه‌سازی با Google Maps داده‌های زمین‌مکانی را برای عملکرد آگاه از مکان به مدل ارائه می‌دهد.

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

  • متغیرهای ورودی را از کد سمت کارخواه مجاز کنید و اعتبارسنجی ورودی و طرح‌واره آن ورودی را انجام دهید (در این مثال، question).

  • ابزار googleMaps را با ارائه مختصات مکان و/یا کد زبان در کد سمت کارخواه بااستفاده از TemplateToolConfig پیکربندی کنید.

در زیر الگوی نمونه، منوی گسترش‌پذیری را پیدا کنید که نمونه‌های کد سمت کارخواه را برای کار با این پیکربندی‌های اختیاری نشان می‌دهد.

پیکربندی (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleMaps
input:
  schema:
    question: string
---

پیام‌واره و (درصورت وجود) دستورالعمل‌های سیستم

{{role "system"}}
You are a helpful tour guide. Use the Google Maps tool with the provided coordinates to answer the user's question based on their location.

{{role "user"}}
{{question}}