בכל בקשה למודל, שולחים הנחיה ואפשר גם סכימה והגדרות כדי לשלוט בתגובה של המודל. כשמשתמשים ב-Firebase AI Logic, אפשר לשלוח את כל המידע הזה ישירות מקוד הלקוח, או לציין את המידע הזה בצד השרת באמצעות תבניות של הנחיות לשרת.
כשמשתמשים בתבניות של הנחיות בצד השרת, מאחסנים את ההנחיה, הסכימה וההגדרות בצד השרת, והאפליקציה מעבירה מהלקוח לשרת רק את המפתח (מזהה התבנית) שמפנה לתבנית ספציפית, וגם את נתוני הקלט הנדרשים לתבנית הזו.
כשמשתמשים בתבניות של הנחיות בצד השרת, שומרים את ההנחיה וההגדרות בצד השרת ומספקים רק מפתח (מזהה התבנית) בבסיס הקוד של האפליקציה. הנה כמה יתרונות של הגישה הזו:
הגנה מפני חשיפת ההנחיה בצד הלקוח
עדכון ההנחיה וההגדרה בלי לפרסם גרסה חדשה של האפליקציה
במדריך הזה מוסבר איך להתחיל להשתמש בתבניות של הנחיות לשרת.
מעבר לסקירה כללית מעבר להוראות מפורטות
מודלים ויכולות נתמכים
אפשר להשתמש בתבניות של הנחיות לשרת עם כל אחד מהמודלים Gemini ו-Imagen ש-Firebase AI Logic תומך בהם, למעט מודלים של Gemini Live.
מעיינים ברשימת התכונות שעדיין לא נתמכות.
סקירה כללית
זהו תהליך העבודה הבסיסי לשימוש בתבניות של הנחיות לשרת:
יוצרים את התבנית באמצעות ממשק המשתמש המודרך במסוף Firebase.
בודקים את התבנית בבקשה אמיתית באמצעות חוויית הבדיקה של Firebase המסוף.
ניגשים לתבנית מהאפליקציה.
פורמט בסיסי של תבניות הנחיות לשרת
ב-Firebase AI Logic, מסוף Firebase מספק ממשק משתמש מודרך שבו אפשר לציין את התוכן של תבנית.
תבניות של הנחיות לשרת משתמשות בתחביר ובפורמט שמבוססים על Dotprompt. פרטים נוספים זמינים במאמר בנושא הפורמט, התחביר והדוגמאות של תבניות.
אלה הרכיבים הכי חשובים בדוגמה לבקשה למודל 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 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.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 = response.result;
const text = response.text();
Dart
בקרוב תהיה תמיכה בתבניות של הנחיות לשרת בפלאגין Flutter.
Unity
בקרוב תהיה תמיכה בתבניות של הנחיות לשרת בחבילת Unity.
הוראות מפורטות
בקטע הזה מפורטות הוראות ליצירה, לבדיקה ולשימוש בתבניות של הנחיות לשרת.
לפני שמתחילים
אם עדיין לא עשיתם את זה, אתם צריכים להשלים את המדריך לתחילת העבודה, שבו מוסבר איך להגדיר את פרויקט Firebase, לקשר את האפליקציה ל-Firebase, להוסיף את ה-SDK, לאתחל את שירות ה-Backend עבור ספק Gemini API שבחרתם וליצור מופע
GenerativeModel.חשוב לוודא שיש לכם את ההרשאות הנדרשות כדי ליצור ולנהל תבניות של הנחיות לשרת. כברירת מחדל, כל ההרשאות האלה כלולות בתפקיד 'בעלים'.
אם אתם משתמשים ב-Vertex AI Gemini API ואם תרחיש השימוש שלכם דורש הגבלות מבוססות-מיקום, אנחנו תומכים בתהליכי עבודה מתקדמים לתבניות.
שלב 1: יוצרים תבנית של הנחיה לשרת
ברוב התרחישים לדוגמה, יוצרים ומנהלים תבניות של הנחיות לשרת במסוף Firebase.
במסוף Firebase, עוברים לכרטיסייה Firebase AI Logic Prompt templates.
לוחצים על יצירת תבנית חדשה ובוחרים באפשרות של תבנית התחלתית.
תבניות ההתחלה האלה מספקות את הפורמט והתחביר לכמה תרחישי שימוש נפוצים. לא משנה איזו אפשרות תבחרו, תוכלו לשנות את התבנית לחלוטין בהתאם לצרכים שלכם.
במדריך הזה לתחילת העבודה אנחנו יוצאים מנקודת הנחה שבחרתם באפשרות
Input + System Instructions.
מזינים את מזהי התבנית:
שם התבנית: זהו שם תצוגה של התבנית (לדוגמה,
My First Template). הוא מוצג רק בממשקי Firebase, כמו מסוף Firebase.מזהה תבנית: צריך להיות מזהה ייחודי לתבנית בפרויקט Firebase (לדוגמה,
my-first-template-v1-0-0מומלץ להשתמש במערכת לניהול גרסאות למזהי התבניות.
מזהי התבניות יכולים להכיל עד 63 תווים, והם יכולים לכלול אותיות קטנות, ספרות ומקפים.
משנים את הקטע Configuration (frontmatter) (הגדרה (מידע מקדים)) בתבנית, לפי הצורך.
הקטע הזה חייב לכלול לפחות שם של מודל, כמו בדוגמה הבאה:
--- model: 'gemini-2.5-flash' ---אפשר גם לציין את ההגדרה של המודל, את אמצעי הבקרה של הקלט והפלט וכו'. פרטים נוספים ואפשרויות נוספות זמינים במאמר פורמט התבנית, התחביר ודוגמאות.
משנים את הקטע הנחיה ו (אם רלוונטי) הוראות מערכת בתבנית לפי הצורך.
הקטע הזה צריך לכלול לפחות את הנחיית הטקסט לשליחה למודל.
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}}.
שלב 2: בדיקת התבנית במסוף Firebase
במסוף Firebase יש אפשרות לבדוק את התבנית. החוויה הזו מאפשרת לכם לראות מה יקרה כשמשתמשים בתבנית שלכם – גם את הפורמט של הבקשה וגם את הפלט של בקשה בפועל.
לוחצים על שמירת התבנית כדי לבדוק את התבנית.
תמיד אפשר לערוך או אפילו למחוק את התבנית בהמשך. הערך היחיד שאי אפשר לשנות בשלב מאוחר יותר הוא מזהה התבנית.
אם ההנחיה משתמשת במשתני קלט, צריך לכלול ערכי בדיקה בשדה Test input. בדוגמה הזו:
{ "customerName": "Jane" }אם הפעלתם כמה ספקי Gemini API בפרויקט Firebase, תוכלו לבחור באיזה מהם להשתמש לבקשת הבדיקה. אם האפשרות הזו מוצגת במסוף, בוחרים באפשרות
Gemini Developer APIאוVertex AI Gemini API.שימו לב שהבחירה הזו חלה רק על בקשות שנשלחות דרך Firebase ממשק הבדיקה של המסוף. בבקשה בפועל מהאפליקציה, מציינים את ספק Gemini API שבחרתם, בדיוק כמו בכל בקשה אחרת.
לוחצים על הלחצן יצירת בקשת בדיקה מעוצבת.
בודקים את בקשת הבדיקה המעוצבת שמופיעה בצד שמאל של המסך, וחוזרים על הפעולה לגבי שדות אחרים בתבנית.
אם מרוצים מהבקשה המעוצבת לבדיקה, לוחצים על הלחצן הפעלת בדיקת ההנחיה.
בודקים את תשובת הבדיקה שמופיעה בצד שמאל של המסך, ומשנים את השדות בתבנית לפי הצורך.
אם אתם רוצים לגשת לתבנית מהקוד של האפליקציה, אתם צריכים לנעול את התבנית. כדי לעשות זאת, לוחצים על סמל הנעילה
בפינה השמאלית העליונה של התבנית. לוחצים על סגירה כדי לצאת מממשק העריכה.
שלב 3: ניגשים לתבנית מהקוד
|
לוחצים על הספק Gemini API כדי לראות בדף הזה תוכן וקוד שספציפיים לספק. |
בקשה שמשתמשת בתבנית של הנחיה לשרת דומה לבקשות אחרות, עם ההתאמות הבאות:
- משתמשים ב-
templateGenerativeModel(או ב-templateImagenModel, לפי הצורך). - צריך לציין את מזהה התבנית.
- מזינים את הערכים של כל משתני הקלט שנדרשים בתבנית.
שימו לב: אחרי שיוצרים או מעדכנים תבנית, יכול להיות שתצטרכו להמתין כמה דקות עד שהתבנית תתעדכן בשרתי Firebase, לפני שתוכלו לגשת אליה מהקוד.
Swift
יוצרים מופע templateGenerativeModel (או templateImagenModel) כדי להשתמש בתבנית בבקשה.
// ...
// 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 (או templateImagenModel) כדי להשתמש בתבנית בבקשה.
// ...
// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.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 (או templateImagenModel) כדי להשתמש בתבנית בבקשה.
// ...
// 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 (או templateImagenModel) כדי להשתמש בתבנית בבקשה.
// ...
// 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 = response.result;
const text = response.text();
Dart
בקרוב תהיה תמיכה בתבניות של הנחיות לשרת בפלאגין Flutter.
Unity
בקרוב תהיה תמיכה בתבניות של הנחיות לשרת בחבילת Unity.
מה השלב הבא?
שיטות מומלצות ושיקולים לשימוש בתבניות של הנחיות לשרת
ניהול תבניות, כולל עריכה, נעילה ובקרת גרסאות.