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

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

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

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

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

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

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

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

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

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

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

סקירה כללית

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

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

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

3. ניגשים לתבנית מהאפליקציה.

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

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

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

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

---
model: 'gemini-3-flash-preview'
---

{{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 Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .vertexAI()).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 Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.vertexAI()).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 Vertex AI Gemini 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 Vertex AI Gemini API backend service
const ai = getAI(app, { backend: new VertexAIBackend() });

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

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

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

שלב 1: יוצרים תבנית של הנחיה לשרת

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

1. במסוף Firebase, עוברים לכרטיסייה Firebase AI Logic 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-flash-preview'
     ---
     

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

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 או באפשרות Vertex AI Gemini API.

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

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

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

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

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3-flash-preview",
     "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-flash-preview",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

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

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

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

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

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

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

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
let model = FirebaseAI.firebaseAI(backend: .vertexAI()).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 Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
val model = Firebase.ai(backend = GenerativeBackend.vertexAI()).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 Vertex AI Gemini 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 Vertex AI Gemini API backend service
const ai = getAI(app, { backend: new VertexAIBackend() });

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

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

מה השלב הבא?

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

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

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