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

في كل طلب ترسله إلى نموذج، يمكنك إرسال طلب، بالإضافة إلى مخطط وإعدادات اختيارية للتحكّم في استجابة النموذج. عند استخدام 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.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 Vertex AI Gemini API backend service.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "global")).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.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "global")).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.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.vertexAI("global")).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.
// Specify `global` as the location to access the model.
const ai = getAI(app, { backend: new VertexAIBackend('global') });

// 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.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.vertexAI(location: 'global').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.
// Specify `global` as the location to access the model.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "global"));

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

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

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-3.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-3.5-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

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

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

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

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

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

يُرجى العِلم أنّه بعد إنشاء النموذج أو تعديله، قد تحتاج إلى الانتظار بضع دقائق حتى يتم نشره على خوادم Firebase قبل الوصول إليه من الرمز.

// ...

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

// 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.
// Specify `global` as the location to access the model.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.vertexAI(location: 'global').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.
// Specify `global` as the location to access the model.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "global"));

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