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

בכל בקשה למודל, אתם שולחים הנחיה, ואם רוצים, גם סכימה והגדרות כדי לשלוט בתשובה של המודל. כשמשתמשים ב-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.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    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, להפעיל את שירות הקצה העורפי של ספק ה-Gemini API שבחרתם וליצור מכונה של GenerativeModel.

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

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

  • 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 Logic ‏ > תבניות לפרומפט.

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. משנים את הקטע Prompt and (as applicable) system instructions בתבנית לפי הצורך.

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

     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. כשהבקשה לבדיקה בפורמט הרצוי, לוחצים על הכפתור Run prompt test.

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

   הרחבה כדי לראות את התשובה לדוגמה לבדיקה

   {
     "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.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    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 או פריסת התבניות במיקומים ספציפיים.