תבנית, תחביר ודוגמאות


ב-Firebase AI Logic, מסוף Firebase מספק ממשק משתמש מודרך שבו אפשר לציין את התוכן של תבנית.

תבניות הנחיות לשרת משתמשות בתחביר ובפורמט שמבוססים על Dotprompt. בדף הזה מופיעים תיאורים מפורטים של הפורמט והתחביר של התבנית, וגם דוגמאות ל-Gemini ול-Imagen.

אלה הרכיבים הכי חשובים בדוגמה לבקשה למודל Gemini:

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

  • החלק העליון בין שלושת המקפים מכיל את שם המודל, וגם את ההגדרות של המודל, אימות הקלט או הסכימה שרוצים לשלוח בבקשה. הוא נכתב בתור צמדי מפתח-ערך, ובדרך כלל נקרא frontmatter של YAML.

  • גוף התבנית מכיל את ההנחיה. הוא יכול לכלול גם הוראות למערכת וערכי קלט (באמצעות תחביר Handlebars).


בדף הזה מופיעים תיאורים מפורטים של פורמט התבנית והתחביר, וגם דוגמאות, ל:


Gemini

כל הדוגמאות בקטע הזה מראות תבניות שמשתמשות ב-gemini-2.5-flash, אבל אתם יכולים להשתמש בכל מודל Gemini שנתמך על ידי Firebase AI Logic (חוץ ממודלים של Gemini Live).

Hello world

דוגמה מינימלית לתבנית הנחיה לשרת:

הגדרה (frontmatter)

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

הנחיה והוראות מערכת (אם רלוונטי)

Write a story about a magic backpack.


הגדרת המודל

הגדרת תצורת מודל כדי לשלוט באופן שבו המודל יוצר תגובה, כמו מספר מקסימלי של טוקנים של פלט, טמפרטורה, top-K ו-top-P.

הגדרה (frontmatter)

---
model: 'gemini-2.5-flash'
config:
  candidateCount: 1
  temperature: 0.9
  topP: 0.1
  topK: 16
  maxOutputTokens: 200
  stopSequences: ["red"]
---

הנחיה והוראות מערכת (אם רלוונטי)

Write a story about a magic backpack.


הוראות מערכת

הגדרת הוראות למערכת כדי לכוון את התנהגות המודל. אתם כוללים אותם כחלק מההנחיה:

  • מגדירים את הוראות המערכת באמצעות התחביר {{role "system"}}.

  • מגדירים את הנחיית הטקסט באמצעות התחביר {{role "user"}}.

הגדרה (frontmatter)

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


משתני קלט

חלק מההנחיות הן סטטיות, אבל לעיתים קרובות צריך לכלול בהנחיה נתונים מהמשתמש.

אפשר לכלול במנחה משתני קלט דינמיים באמצעות ביטויי Handlebars, שנמצאים בתוך תגי {{ }} בפורמט {{variableName}} או {{object.propertyName}} (לדוגמה, Hello, {{name}} from {{address.city}}).

הגדרה (frontmatter)

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

הנחיה והוראות מערכת (אם רלוונטי)

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

אפשר לספק ערך ברירת מחדל בתבנית, אבל בדרך כלל הלקוח מספק את הערך של משתנה קלט כחלק מהבקשה.


תהליכי יצירת קשר (לולאות ותנאים)

כדי לכתוב הנחיות מורכבות יותר, אפשר להשתמש בבלוקים מותנים (כמו #if , else ו-#unless) ובאיטרציה (#each).

אפשר לספק מידע נוסף על ההקשר כמשתנים עם הקידומת המיוחדת @:

  • ‫@first: הערך הוא true כשמבצעים איטרציה על הפריט הראשון בבלוק #each.
  • ‫@last: הערך הוא true כשמבצעים איטרציה על הפריט האחרון בבלוק #each.
  • ‫@index: מחזיר את מיקום האינדקס (מבוסס-אפס) של הרכיב הנוכחי.

במסמכי התיעוד של Handlebars מופיע מידע על כל העוזרים הלוגיים המובנים.

הגדרה (frontmatter)

---
model: 'gemini-2.5-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}}

אם המשתנה הוא בוליאני, התנאי פועל כצפוי. אם המשתנה לא בוליאני, התנאי הוא למעשה בדיקה של 'לא אפס'. האפשרות הזו יכולה להיות שימושית לטיפול בקלטים אופציונליים, לדוגמה:

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


אימות קלט וסכימה

אם יש לכם נתונים שמגיעים מהלקוח, מומלץ מאוד להשתמש בסכימת קלט כדי להגן מפני הזרקת הנחיות וגם כדי לוודא שהנתונים שמועברים בבקשה תואמים לציפיות שלכם.

  • אתם יכולים לספק ערכי ברירת מחדל למקרה שהלקוח לא יספק ערך.

  • הסכימה תומכת בסוגים סקלריים string, integer, number, boolean ו-object. אובייקטים, מערכים וסוגי enum מסומנים בסוגריים אחרי שם השדה.

  • כל המאפיינים נחשבים לחובה, אלא אם מציינים שהם אופציונליים באמצעות ?. כשמאפיין מסומן כאופציונלי, הוא גם מוגדר כמאפשר ערך null כדי לספק למודלים של שפה גדולה (LLM) יותר גמישות להחזרת ערך null במקום השמטת שדה.

דוגמה בסיסית לאספקת סכימת קלט בהמשך מופיעה סכימה מתקדמת יותר.

הגדרה (frontmatter)

---
model: 'gemini-2.5-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. אובייקטים, מערכים וסוגי enum מסומנים בסוגריים אחרי שם השדה.

  • כל המאפיינים נחשבים לחובה, אלא אם מציינים שהם אופציונליים באמצעות ?. כשמאפיין מסומן כאופציונלי, הוא גם מוגדר כמאפשר ערך null כדי לספק למודלים של שפה גדולה (LLM) יותר גמישות להחזרת ערך null במקום השמטת שדה.

דוגמה בסיסית ליצירת פלט JSON מובנה. בהמשך מופיעה סכימה מתקדמת יותר.

הגדרה (frontmatter)

---
model: gemini-2.5-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, קובצי טקסט רגיל, אודיו ווידאו).

  • מציינים קובץ באמצעות כתובת ה-URL שלו עם התחביר {{media url}}.

  • צריך לספק קובץ מוטבע עם התחביר {{media type="mime_type" data="contents"}}.

דוגמה בסיסית להזנת קלט מולטימודאלי. בהמשך מופיעה דוגמה מורכבת יותר.

הגדרה (frontmatter)

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

הנחיה והוראות מערכת (אם רלוונטי)

Describe this image

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


‫Imagen (יצירת תמונות)

בגרסה הראשונית, תבניות של הנחיות לשרת תומכות ביצירת תמונות באמצעות מודלים של Imagen והנחיה שמבוססת על טקסט בלבד. אפשר לחזור לכאן מאוחר יותר כדי לקבל תמיכה נוספת, כולל עריכת תמונות באמצעות Imagen (כשמשתמשים ב-Vertex AI Gemini API).

בסיסי

בדוגמה הזו מוצגת תבנית בסיסית ליצירת תמונות באמצעות Imagen, עם משתני קלט ואימות קלט בדומה ל Gemini.

הגדרה (frontmatter)

---
model: 'imagen-4.0-generate-001'
input:
  schema:
    prompt: 'string'
---

הנחיה והוראות מערכת (אם רלוונטי)

Create an image containing {{prompt}}

מתקדם

בדוגמה הזו מוצגות דרכים להוסיף הגדרת מודל ולהשתמש בתכונות מתקדמות יותר בהנחיה, כמו משתני קלט, אימות קלט וזרימות בקרה, בדומה ל-Gemini.

הגדרה (frontmatter)

---
model: 'imagen-4.0-fast-generate-001'
config:
  sampleCount: 1
  aspectRatio: "16:9"
  personGeneration: dont_allow
  includeRaiReason: true
input:
  schema:
    style(enum, The style of image): [photo, sketch, painting]
    subject: string, The object or animal or scenery to generate.
    context?: string, Optional background or context description.
  default:
    style: photo
---

הנחיה והוראות מערכת (אם רלוונטי)

A {{style}} of {{subject}}{{#if context}}{{context}}{{/if}}.