بدء استخدام نماذج طلبات الخادم

في كل طلب ترسله إلى نموذج، يمكنك إرسال طلب، ويمكنك أيضًا إرسال مخطط وإعدادات للتحكّم في ردّ النموذج. عند استخدام Firebase AI Logic، يمكنك إرسال كل هذه المعلومات مباشرةً من رمز العميل، أو يمكنك تحديد هذه المعلومات من جهة الخادم باستخدام نماذج الطلبات من جهة الخادم.

عند استخدام نماذج الطلبات من جهة الخادم، يتم تخزين الطلب والمخطط والإعدادات من جهة الخادم، وتمرّر قاعدة الرموز البرمجية لتطبيقك من العميل إلى الخادم مفتاحًا فقط (معرّف النموذج) يشير إلى نموذج معيّن بالإضافة إلى المدخلات المطلوبة لهذا النموذج. في ما يلي بعض مزايا هذا النهج:

• الحماية من كشف طلبك من جهة العميل

• تعديل الطلب والإعدادات بدون طرح إصدار جديد من التطبيق

يوضّح هذا الدليل كيفية بدء استخدام نماذج الطلبات من الخادم.

arrow_downward الانتقال إلى النظرة العامة العالية المستوى arrow_downward الانتقال إلى التعليمات التفصيلية

النماذج والإمكانات المتوافقة

• يمكنك استخدام نماذج الطلبات من جهة الخادم مع أي من نماذج Gemini المتوافقة مع Firebase AI Logic، باستثناء نماذج Gemini Live API.

• راجِع قائمة الميزات غير المتوافقة بعد.

نظرة عامة شاملة

في ما يلي سير العمل الأساسي لاستخدام نماذج الطلبات من الخادم:

1. أنشِئ النموذج باستخدام واجهة المستخدم الإرشادية في وحدة تحكّم Firebase.

2. اختبِر النموذج في طلب حقيقي باستخدام تجربة الاختبار في وحدة تحكّم "Firebase".

3. يمكنك الوصول إلى النموذج من الرمز البرمجي لتطبيقك باستخدام templateGenerativeModel.

التنسيق الأساسي لنموذج طلب الخادم

بالنسبة إلى Firebase AI Logic، توفّر وحدة تحكّم "Firebase" واجهة مستخدم موجَّهة تتيح لك تحديد البيانات الوصفية للنموذج ومحتواه.

تستخدم نماذج الطلبات من الخادم بنية وتنسيقًا مستندَين إلى 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 Logic > علامة التبويب نماذج الطلبات.

2. انقر على إنشاء نموذج جديد، واختَر نموذجًا أوليًا.

   • توفّر هذه النماذج الأولية التنسيق والصيغة لبعض حالات الاستخدام الشائعة. بغض النظر عن الخيار الذي تحدده، يمكنك تغيير النموذج تمامًا لتلبية احتياجاتك.

   • يفترض دليل البدء هذا أنّك حدّدت الخيار "Input + System Instructions".

3. أدخِل معرّفات النموذج:

   • اسم النموذج: هو الاسم المعروض للنموذج (على سبيل المثال، My First Template). ولا يظهر إلا في واجهات Firebase، مثل وحدة تحكّم Firebase.

   • رقم تعريف النموذج: يجب أن يكون هذا رقم تعريف فريدًا للنموذج ضمن مشروعك على Firebase (على سبيل المثال، my-first-template-v1-0-0). ستشير إلى رقم التعريف هذا في الطلب من تطبيقك.

     • ننصحك باستخدام نظام تحديد الإصدارات لمعرّفات النماذج.

     • يمكن أن تتألف معرّفات النماذج من 63 حرفًا كحدّ أقصى، ويمكن أن تحتوي على أحرف صغيرة وأرقام وواصلات.

4. عدِّل قسم الإعدادات (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. إذا كان الطلب يستخدم متغيّرات إدخال، أدرِج قيمًا تجريبية في حقل إدخال تجريبي. في هذا المثال:

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

ما هي الخطوات التالية؟

• يمكنك الاطّلاع على أفضل الممارسات والاعتبارات لاستخدام نماذج الطلبات من الخادم.

• يمكنك الاطّلاع على تفاصيل حول تنسيق النموذج وبنيته، بالإضافة إلى أمثلة.

• مزيد من المعلومات حول إدارة النماذج، بما في ذلك تعديلها وقفلها والتحكّم في إصداراتها

• تعرَّف على مهام سير العمل المتقدّمة، مثل استخدام النماذج آليًا من خلال REST API أو نشر نماذجك في مواقع جغرافية محدّدة.