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

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

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

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

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

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

يصف هذا الدليل كيفية البدء في استخدام نماذج الطلبات من الخادم.

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

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

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

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

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

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

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

   • رقم تعريف النموذج: يجب أن يكون رقم تعريف فريدًا للنموذج ضمن مشروع 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 ، يمكنك اختيار الموفّر الذي تريد استخدامه لطلب الاختبار. إذا ظهر هذا الخيار في وحدة التحكّم، اختَر Gemini Developer API أو Agent Platform Gemini API (المعروف سابقًا باسم Vertex AI).

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

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