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

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

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

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

• الحماية من عرض الطلب من جهة العميل

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

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

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

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

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

• راجِع قائمة الميزات التي لم يتم إتاحتها بعد.

نظرة عامة على مستوى عالٍ

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

1. يمكنك إنشاء النموذج باستخدام واجهة المستخدم الإرشادية في الـ Firebase Console.

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

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

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

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

تستخدِم نماذج طلبات الخادم تنسيقًا وبنية مستندَين إلى Dotprompt. لمزيد من التفاصيل، يُرجى الاطّلاع على تنسيق النموذج وبنيته وأمثلة عليه.

يوضّح نموذج الطلب أدناه أهم مكوّنات نموذج لطلب مثال إلى نموذج Gemini:

---
model: 'gemini-3.7-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}}.

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

• إذا كنت تستخدم Agent Platform Gemini API (formerly Vertex AI) و كانت حالة الاستخدام تتطلب فرض قيود تستند إلى الموقع الجغرافي، فإنّنا نتيح سير عمل متقدّمًا للنماذج.

الخطوة 1: إنشاء نموذج طلب خادم

في معظم حالات الاستخدام، يمكنك إنشاء نماذج طلبات الخادم وإدارتها في الـ Firebase Console.

1. في Firebase Console، انتقِل إلى خدمات الذكاء الاصطناعي > 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.7-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 Console

يوفّر Firebase Console تجربة اختبار لنموذجك. تتيح لك هذه التجربة الاطّلاع على ما سيحدث عند استخدام النموذج، أي تنسيق الطلب ونتائج الطلب الفعلي.

1. انقر على حفظ النموذج لتتمكّن من اختباره.

   يمكنك تعديل النموذج أو حتى حذفه لاحقًا في أي وقت. القيمة الوحيدة التي لا يمكنك تغييرها لاحقًا هي رقم تعريف النموذج.

2. إذا كان طلبك يستخدم متغيّرات إدخال، أدرِج قيم الاختبار في حقل اختبار الإدخال. في هذا المثال:

     {
       "customerName": "Jane"
     }
   

3. إذا كان لديك عدة موفّري Gemini API مفعّلين في مشروعك على Firebase ، يمكنك اختيار الموفّر الذي تريد استخدامه لطلب الاختبار. إذا ظهر هذا الخيار في Firebase Console، اختَر Gemini Developer API أو Agent Platform Gemini API (المعروف سابقًا باسم Vertex AI).

   يُرجى العِلم أنّ هذا الاختيار لا ينطبق إلا على الطلبات المُرسَلة من خلال الـ Firebase تجربة الاختبار. في الطلب الفعلي من تطبيقك، يمكنك تحديد موفّر Gemini API الذي اخترته تمامًا كما تفعل مع أي طلب آخر.

4. انقر على الزر إنشاء طلب اختبار منسَّق.

   راجِع طلب الاختبار المنسَّق الناتج في الجانب الأيسر من الشاشة، وعدِّل أيًا من حقول النموذج.

   توسيع العرض للاطّلاع على مثال لطلب اختبار منسَّق

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

6. إذا كنت مستعدًا للوصول إلى النموذج من رمز تطبيقك، يمكنك قفله من خلال النقر على lock رمز القفل في أعلى يسار النموذج.

7. انقر على إغلاق للخروج من تجربة التعديل.

الخطوة 3: الوصول إلى النموذج من الرمز

يبدو الطلب الذي يستخدم نموذج طلب خادم مشابهًا للطلبات الأخرى، مع إجراء التعديلات التالية:

• استخدِم templateGenerativeModel (أو templateImagenModel حسب الحاجة).
• قدِّم رقم تعريف النموذج.
• قدِّم قيم أي إدخالات متغيّرة يتطلبها النموذج.

يُرجى العِلم أنّه بعد إنشاء النموذج أو تعديله، قد تحتاج إلى الانتظار بضع دقائق حتى يتم نشر النموذج على خوادم 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.
  '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 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 أو نشر النماذج في مواقع جغرافية معيّنة.