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

في كل طلب ترسله إلى أحد النماذج، يمكنك إرسال طلب وإضافة مخطط وإعدادات بشكل اختياري للتحكّم في ردّ النموذج. عند استخدام 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. عدِّل قسم الإعدادات (البيانات الوصفية) في النموذج، حسب الحاجة.

   • يجب أن يتضمّن هذا القسم اسم النموذج على الأقل، على النحو التالي:

     ---
     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 أو نشر نماذجك في مواقع جغرافية معيّنة.