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

בכל בקשה למודל, שולחים הנחיה ואפשר גם סכימה והגדרות כדי לשלוט בתשובה של המודל. כשמשתמשים ב-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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
const ai = getAI(app, { backend: new AgentPlatformBackend() });

// 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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.agentPlatform().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 Agent Platform Gemini API backend service (formerly Vertex AI).
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform());

// 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, לאתחל את שירות לקצה העורפי עבור 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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform()).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 Agent Platform Gemini API backend service (formerly Vertex AI).
const ai = getAI(app, { backend: new AgentPlatformBackend() });

// 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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.agentPlatform().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 Agent Platform Gemini API backend service (formerly Vertex AI).
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform());

// 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 או פריסת תבניות במיקומים ספציפיים.