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

في كل طلب ترسله إلى أحد النماذج، يمكنك إرسال طلب ونموذج بيانات اختياريًا وإعدادات للتحكّم في ردّ النموذج. عند استخدام 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-2.5-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.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 = response.result;
const text = response.text();

تعليمات مفصّلة

يقدّم هذا القسم تعليمات مفصّلة حول إنشاء نماذج طلبات من الخادم واختبارها واستخدامها.

قبل البدء

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

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

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

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

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

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

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

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

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

4. عدِّل قسم الإعدادات (frontmatter) في النموذج، حسب الحاجة.

   • يجب أن يتضمّن هذا القسم اسم طراز على الأقل، مثل ما يلي:

     ---
     model: 'gemini-2.5-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 أو Vertex AI Gemini API.

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

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

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

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

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-2.5-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-2.5-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.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 = response.result;
const text = response.text();

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

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

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

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