איך מתחילים לעבוד עם תבניות להנחיות לשרת

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

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

• הגנה מפני חשיפת ההנחיה בצד הלקוח

• עדכון ההנחיה וההגדרה בלי לפרסם גרסה חדשה של האפליקציה

במדריך הזה מוסבר איך להתחיל להשתמש בתבניות של הנחיות לשרת.

arrow_downward מעבר לסקירה כללית arrow_downward מעבר להוראות מפורטות

מודלים ויכולות נתמכים

• אפשר להשתמש בתבניות הנחיות בשרת עם כל אחד מהמודלים של Gemini שFirebase AI Logic תומך בהם, חוץ ממודלים של Gemini Live API.

• מעיינים ברשימת התכונות שעדיין לא נתמכות.

סקירה כללית

זהו תהליך העבודה הבסיסי לשימוש בתבניות של פרומפטים לשרת:

1. יוצרים את התבנית באמצעות ממשק המשתמש המודרך במסוף Firebase.

2. בודקים את התבנית בבקשה אמיתית באמצעות חוויית הבדיקה בFirebase מסוף.

3. אפשר לגשת לתבנית מקוד האפליקציה באמצעות templateGenerativeModel.

פורמט בסיסי של תבנית לפרומפט לשרת

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

תבניות להנחיות בשרת משתמשות בתחביר ובפורמט שמבוססים על 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).

שימוש בתבנית בקוד

בדוגמה הבאה של קוד לקוח אפשר לראות איך להשתמש בתבנית בקוד:

// ...

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

// ...

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

// ...

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

// ...

// 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();

// ...

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

// ...

// 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, להוסיף את ה-SDK, לאתחל את שירות ה-Backend עבור Gemini APIהספקGenerativeModel שבחרתם וליצור מופע.

• חשוב לוודא שיש לכם את ההרשאות הנדרשות כדי ליצור ולנהל תבניות של הנחיות לשרת. כברירת מחדל, כל ההרשאות האלה כלולות בתפקיד Owner.

  הצגת ההרשאות הנדרשות

  • firebasevertexai.googleapis.com/promptTemplates.create
  • firebasevertexai.googleapis.com/promptTemplates.get
  • firebasevertexai.googleapis.com/promptTemplates.update
  • firebasevertexai.googleapis.com/promptTemplates.delete
  • firebasevertexai.googleapis.com/promptTemplates.list
  • firebasevertexai.googleapis.com/promptTemplates.updateLock

• אם אתם משתמשים ב-Agent Platform Gemini API (formerly Vertex AI) ואם תרחיש השימוש שלכם דורש הגבלות מבוססות-מיקום, אנחנו תומכים בתהליכי עבודה מתקדמים לתבניות.

שלב 1: יצירת תבנית לפרומפט של שרת

ברוב התרחישים לדוגמה, יוצרים ומנהלים תבניות של הנחיות לשרת במסוף Firebase.

1. במסוף Firebase, עוברים אל AI Services (שירותי AI) > AI Logic (לוגיקת AI) > הכרטיסייה Prompt templates (תבניות של הנחיות).

2. לוחצים על יצירת תבנית חדשה ובוחרים באפשרות של תבנית התחלתית.

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

   • במדריך הזה אנחנו יוצאים מנקודת הנחה שבחרתם באפשרות Input + System Instructions.

3. מזינים את המזהים של התבנית:

   • שם התבנית: זהו שם תצוגה לתבנית (לדוגמה, My First Template). הוא מוצג רק בממשקי Firebase, כמו מסוף Firebase.

   • מזהה התבנית: זה צריך להיות מזהה ייחודי של התבנית בפרויקט Firebase (לדוגמה, my-first-template-v1-0-0). תצטרכו להפנות למזהה הזה בבקשה מהאפליקציה.

     • מומלץ להשתמש במערכת ניהול גרסאות למזהי התבניות.

     • מזהי התבניות יכולים להכיל עד 63 תווים, והם יכולים לכלול אותיות קטנות, מספרים ומקפים.

4. משנים את הקטע Configuration (frontmatter) (הגדרה (מידע מקדים)) בתבנית, לפי הצורך.

   • הקטע הזה חייב לכלול לפחות שם של דגם, כמו בדוגמה הבאה:

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

שלב 2: בדיקת התבנית במסוף Firebase

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

1. לוחצים על שמירת תבנית כדי שתוכלו לבדוק את התבנית.

   תמיד אפשר לערוך או אפילו למחוק את התבנית בהמשך. הערך היחיד שאי אפשר לשנות בשלב מאוחר יותר הוא מזהה התבנית.

2. אם ההנחיה משתמשת במשתני קלט, צריך לכלול ערכי בדיקה בשדה Test input. בדוגמה הזו:

     {
       "customerName": "Jane"
     }
   

3. אם הפעלתם כמה ספקי Gemini API בפרויקט Firebase, אתם יכולים לבחור באיזה ספק להשתמש לבקשת הבדיקה. אם האפשרות הזו מוצגת במסוף, בוחרים באפשרות Gemini Developer API או Agent Platform Gemini API (לשעבר Vertex AI).

   שימו לב: הבחירה הזו רלוונטית רק לבקשות שנשלחות דרך Firebase ממשק הבדיקה של המסוף. בבקשה בפועל מהאפליקציה, מציינים את ספק Gemini API שבחרתם, בדיוק כמו בכל בקשה אחרת.

4. לוחצים על הלחצן יצירת בקשת בדיקה מעוצבת.

   בודקים את בקשת הבדיקה המעוצבת שמופיעה בצד שמאל של המסך, ומשנים את השדות בתבנית לפי הצורך.

   הרחבה לצפייה בדוגמה לבקשת בדיקה מעוצבת

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3.8-flash",
     "contents": [{
       "parts": [{
         "text": "Create an example customer invoice for a customer named Jane"
       }],
       "role": "user"
     }],
     "systemInstruction": {
       "parts": [{
         "text": "All output must be a clearly structured invoice document.\nUse a tabular or clearly delineated list format for line items."
       }]
     }
   }
   

5. אם מרוצים מהבקשה המעוצבת לבדיקה, לוחצים על הלחצן הפעלת בדיקת הנחיה.

   בודקים את תשובת הבדיקה שמתקבלת בצד שמאל של המסך, ומשנים את השדות בתבנית לפי הצורך.

   הרחבה לצפייה בתשובה לדוגמה לבדיקה

   {
     "candidates": [{
       "content": {
         "parts": [{
           "text": "```\n--------------------------------------------------------------------------------\n                         **INVOICE**\n--------------------------------------------------------------------------------\n\n**Creative Solutions Inc.**\n123 Business Lane, Suite 100\nAnytown, USA 12345\nPhone: (555) 123-4567\nEmail: info@creativesolutions.com\n\n**INVOICE NO:** INV-2023-001\n**INVOICE DATE:** October 26, 2023\n**DUE DATE:** November 25, 2023\n\n**BILL TO:**\nJane\n456 Client Street, Apt 2B\nAnytown, USA 12346\nPhone: (555) 987-6543\nEmail: jane@example.com\n\n--------------------------------------------------------------------------------\n**ITEM DESCRIPTION**               **QTY**   **UNIT PRICE**   **AMOUNT**\n--------------------------------------------------------------------------------\nWebsite Design Services            1         $800.00          $800.00\nContent Creation (Blog Posts)      4         $120.00          $480.00\nMonthly Hosting \u0026 Maintenance      1         $50.00           $50.00\nConsultation Fee                   2         $75.00           $150.00\n--------------------------------------------------------------------------------\n\n**SUMMARY:**\nSubtotal:                                                     $1,480.00\nSales Tax (8%):                                               $118.40\n--------------------------------------------------------------------------------\n**TOTAL DUE:**                                                **$1,598.40**\n--------------------------------------------------------------------------------\n\n**PAYMENT TERMS:**\nPayment is due within 30 days of the invoice date. Please make checks payable to Creative Solutions Inc. For electronic payments, please contact us for details.\n\nThank you for your business!\n```"
         }],
         "role": "model"
       },
       "finishReason": "STOP",
       "index": 0
     }],
     "usageMetadata": {
       "promptTokenCount": 34,
       "candidatesTokenCount": 418,
       "totalTokenCount": 890,
       "promptTokensDetails": [{
         "modality": "TEXT",
         "tokenCount": 34
       }],
       "thoughtsTokenCount": 438
     },
     "modelVersion": "gemini-3.8-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

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

7. לוחצים על סגירה כדי לצאת מממשק העריכה.

שלב 3: גישה לתבנית מהקוד

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

• שימוש ב-templateGenerativeModel.
• צריך לציין את מזהה התבנית.
• מזינים את הערכים של כל קלט משתנה שנדרש בתבנית.

שימו לב: אחרי שיוצרים או מעדכנים תבנית, יכול להיות שצריך לחכות כמה דקות עד שהתבנית תתעדכן בשרתי Firebase, לפני שאפשר לגשת אליה מהקוד.

// ...

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

// ...

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

// ...

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

// ...

// 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();

// ...

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

// ...

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

מה השלב הבא?

• שיטות מומלצות ושיקולים לשימוש בתבניות של הנחיות לשרת

• מידע נוסף על הפורמט והתחביר של התבנית, כולל דוגמאות

• מידע נוסף על ניהול תבניות, כולל עריכה, נעילה וניהול גרסאות.

• מידע נוסף על תהליכי עבודה מתקדמים, כמו עבודה עם תבניות באופן פרוגרמטי באמצעות API בארכיטקטורת REST או פריסת תבניות במיקומים ספציפיים.