تنسيق النموذج وبنيته وأمثلة عليه


بالنسبة إلى 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).


تقدّم هذه الصفحة أوصافًا مفصّلة لتنسيق النموذج وبنيته، بالإضافة إلى أمثلة على ما يلي:

تعرض جميع الأمثلة في هذه الصفحة نماذج تستخدم gemini-3.8-flash، ولكن يمكنك استخدام أي نموذج Gemini متوافق مع Firebase AI Logic (باستثناء نماذج Gemini Live API).

Hello world

في ما يلي مثال بسيط على نموذج طلب من الخادم:

الإعداد (frontmatter)

---
model: 'gemini-3.8-flash'
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Write a story about a magic backpack.



التحكّم في إنشاء الردود

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

إعدادات النموذج

اضبط إعدادات النموذج للتحكّم في كيفية إنشاء النموذج للردود، مثل الحد الأقصى لعدد الرموز المميزة الناتجة وتسلسلات الإيقاف وما إلى ذلك.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
config:
  maxOutputTokens: 200
  stopSequences: ["red"]
---

الطلبات وتعليمات النظام (حسب الاقتضاء)

Write a story about a magic backpack.


إعدادات التفكير

حدِّد إعدادًا متعلقًا بالتفكير للنماذج التي تتيح التفكير.

الإعدادات (frontmatter)

  • ‫Gemini 3.x والنماذج الأحدث (مستويات التفكير)

    ---
    model: 'gemini-3.8-flash'
    config:
      thinkingConfig:
        thinkingLevel: medium
        includeThoughts: true
    ---
    
  • ‫Gemini 2.5 نموذج (ميزانيات التفكير)

    ---
    model: 'gemini-2.5-flash'
    config:
      thinkingConfig:
        thinkingBudget: 1024
        includeThoughts: true
    ---
    

الطلب وتعليمات النظام (حسب الاقتضاء)

Solve x^2 + 4x + 4 = 0


إعدادات الأمان

استخدِم إعدادات الأمان لتعديل احتمالية تلقّي ردود قد تُعتبر ضارة.

الإعدادات (frontmatter)

مثال على إعداد أمان واحد:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
---

مثال على إعدادات أمان متعدّدة:

---
model: 'gemini-3.8-flash'
config:
  safetySettings:
    - category: HARM_CATEGORY_HARASSMENT
      threshold: BLOCK_ONLY_HIGH
    - category: HARM_CATEGORY_HATE_SPEECH
      threshold: BLOCK_MEDIUM_AND_ABOVE
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Write a story about a magic backpack.


تعليمات النظام

يمكنك ضبط تعليمات النظام لتوجيه سلوك النموذج. يمكنك تضمينها كجزء من الطلب:

  • حدِّد تعليمات النظام باستخدام بنية {{role "system"}}.

  • حدِّد الطلب النصي باستخدام البنية {{role "user"}}.

الإعدادات (frontmatter)

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



متغيّرات الإدخال

بعض الطلبات ثابتة، ولكن غالبًا ما تحتاج إلى تضمين بعض البيانات من المستخدم كجزء من الطلب.

يمكنك تضمين متغيّرات إدخال ديناميكية في الطلب باستخدام تعبيرات Handlebars، والتي يتم تضمينها ضمن علامات {{ }} بالتنسيق {{variableName}} أو {{object.propertyName}} (على سبيل المثال، Hello, {{name}} from {{address.city}}).

الإعداد (frontmatter)

---
model: 'gemini-3.8-flash'
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Create an example customer invoice for a customer named {{customerName}}.

يمكنك تقديم قيمة تلقائية في النموذج، ولكن عادةً ما يقدّم العميل قيمة متغيّر الإدخال كجزء من الطلب.



التحكّم في التدفق (الحلقات والشروط)

لكتابة طلبات أكثر تعقيدًا، يمكنك استخدام كتل شرطية (مثل #if وelse و#unless) والتكرار (#each).

يمكنك تقديم معلومات سياقية إضافية كمتغيّرات باستخدام بادئة @ خاصة:

  • ‫@first: تكون القيمة "صحيح" عند تكرار العنصر الأول في مجموعة #each.
  • ‫@last: true عند تكرار العنصر الأخير في مجموعة #each.
  • ‫@index: تعرض موضع الفهرس (بدءًا من الصفر) للعنصر الحالي.

يُرجى الاطّلاع على مستندات Handlebars للحصول على معلومات عن جميع الدوال المساعدة المنطقية المضمّنة.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}

يُرجى العِلم أنّ الشروط تقبل فقط مرجعًا لمتغيّر، وليس أي نوع من التعبيرات، على سبيل المثال:

  • الأعمال التالية: {{#if isVipCustomer}} ... {{/if}}
  • لا تعمل الطريقة التالية: {{#if customer.type == 'vip'}} ... {{/if}}

إذا كان المتغيّر قيمة منطقية، سيعمل الشرط على النحو المتوقّع. إذا لم يكن المتغيّر قيمة منطقية، يكون الشرط في الواقع عملية تحقّق من "القيمة غير فارغة". يمكن أن يكون ذلك مفيدًا للتعامل مع المدخلات الاختيارية، على سبيل المثال:

{{#if customerName}}
Hello {{customerName}}
{{else}}
Hello Guest
{{/if}}



التحقّق من صحة البيانات المُدخَلة والمخطط

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

  • يمكنك تقديم قيم تلقائية في حال لم يقدّم العميل قيمة.

  • يتيح المخطط استخدام الأنواع العددية string وinteger وnumber وboolean وobject. يُشار إلى العناصر والمصفوفات والتعدادات بين قوسين بعد اسم الحقل.

  • تُعتبر جميع السمات مطلوبة ما لم تحدّدها على أنّها اختيارية باستخدام ?. عند وضع علامة على سمة بأنّها اختيارية، يتم أيضًا جعلها قابلة للإلغاء لتوفير مزيد من المرونة لنماذج LLM لعرض قيمة فارغة بدلاً من حذف حقل.

إليك مثالاً أساسيًا لتقديم مخطط الإدخال. يمكنك العثور على مخطط أكثر تقدمًا أدناه مباشرة.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  default:
    isVipCustomer: false
  schema:
    customerName: string, the customers name  # string, number, and boolean types are defined like this
    productNames?(array, list of products to include in the invoice): string  # optional fields are marked with a ?
    isVipCustomer?: boolean, whether or not the customer is a VIP
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Create an example customer invoice for a customer named {{customerName}}.

Include entries for each of the following products

{{#each productNames}}
  {{#if @first}}
  Include line items for the following purchases
  {{/if}}
  - {{this}}
{{/each}}

{{#if isVipCustomer}}
Give the customer a 5% discount.
{{/if}}



المخطط الناتج

إذا أردت أن ينشئ النموذج إخراج JSON منظَّمًا، يمكنك تحديد مخطط إخراج. من خلال تحديد format: json، أنت تفرض على النموذج أن يعرض دائمًا استجابة بتنسيق JSON تتّبع المخطط المحدّد.

  • يتيح المخطط استخدام الأنواع العددية string وinteger وnumber وboolean وobject. يُشار إلى العناصر والمصفوفات وقيم التعداد بقوسين بعد اسم الحقل.

  • تُعتبر جميع السمات مطلوبة ما لم تحدّدها على أنّها اختيارية باستخدام ?. عند وضع علامة على سمة بأنّها اختيارية، يتم أيضًا جعلها قابلة للإلغاء لتوفير مزيد من المرونة لنماذج LLM لعرض قيمة فارغة بدلاً من حذف حقل.

إليك مثال أساسي لإنشاء ناتج JSON منظَّم. يمكنك العثور على مخطط أكثر تقدمًا أدناه.

الإعداد (frontmatter)

---
model: gemini-3.8-flash
output:
  format: json
  schema:
    invoiceId: string
    invoiceFile(object, an invoice file):
      url?: string
      contents: string
      mimeType: string
---

الطلبات وتعليمات النظام (حسب الاقتضاء)

Create an example customer invoice.



إدخال متعدد الوسائط

يمكن أن تتضمّن الطلبات المتعدّدة الوسائط المُرسَلة إلى نموذج Gemini أنواعًا متعدّدة من الإدخالات، بما في ذلك الملفات (مثل النصوص مع الصور وملفات PDF وملفات النص العادي والمحتوى الصوتي والفيديو).

  • قدِّم ملفًا باستخدام عنوان URL الخاص به مع بنية {{media url}}.

  • يُرجى تقديم ملف مضمّن باستخدام البنية {{media type="mime_type" data="contents"}}.

مثال أساسي (إدخال متعدد الوسائط)

في ما يلي مثال أساسي على تقديم إدخال متعدد الوسائط. يمكنك الاطّلاع على مثال أكثر تعقيدًا أدناه.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Describe this image

{{media type="mimeType" data="imageData"}}

مثال معقّد (إدخال متعدد الوسائط)

في ما يلي مثال أكثر تعقيدًا لتقديم إدخال متعدد الوسائط.

الإعداد (frontmatter)

---
model: gemini-3.8-flash
input:
  schema:
    image_urls?(array, urls of external images): string
    inline_images?(array, inline image data):
      type: object
      properties:
        mime_type: string
        contents: string  # inline data must be base64-encoded
---

الطلب وتعليمات النظام (حسب الاقتضاء)

{{role "system"}}
Use the following image as the basis for comparisons
{{media url="http://example.com/reference_img.bmp"}}

{{role "user"}}
What do the following images have in common?

{{#each image_urls}}
  {{media url="this"}}
{{/each}}

{{#each inline_images}}
  {{media type="mime_type" data="contents"}}
{{/each}}



استخدام الأدوات

تتيح نماذج الطلبات من الخادم استخدام الأدوات التالية.

إذا أردت أن يقدّم المستخدمون أي معلومات إضافية للنموذج، استخدِم متغيّرات الإدخال ضمن نموذج طلب الخادم، بالإضافة إلى التحقّق من صحة الإدخال.

استدعاء الدالة

اطّلِع على الدليل الكامل حول استخدام نماذج الطلبات من الخادم لاستدعاء الدوال.

تطبيق الرموز البرمجية

تتيح أداة تنفيذ الرموز البرمجية للنموذج إنشاء رموز Python البرمجية وتشغيلها.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - codeExecution
---

الطلب وتعليمات النظام (حسب الاقتضاء)

What is the sum of the first 50 prime numbers?
Generate and run code for the calculation, and make sure you get all 50.

سياق عناوين URL

تتيح لك أداة سياق عنوان URL تقديم سياق إضافي للنموذج في شكل عناوين URL. يوضّح هذا المثال أيضًا كيف يمكنك تحديد عملية التحقّق من صحة الإدخال لعناوين URL إذا كان المستخدم هو من يقدّمها.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
input:
  schema:
    url1:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
    url2:
      type: string
      pattern: '^https?://[\w.-]+\.[a-z]{2,}\S*$'
      maxLength: 100
tools:
  - urlContext
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Compare the ingredients and cooking times from the recipes at {{url1}} and {{url2}}

تتيح أداة تحديد المصدر من خلال Google Search ربط النموذج بمحتوى على الويب متاح للجميع في الوقت الفعلي.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleSearch
---

الطلب وتعليمات النظام (حسب الاقتضاء)

Who won the Euro 2024?

تحديد المصدر من خلال "Google Maps"

توفّر أداة التحقّق من المصادر باستخدام Google Maps للنموذج بيانات جغرافية مكانية تتيح له تقديم وظائف تستند إلى الموقع الجغرافي.

لاستخدام أداة googleMaps، أدرِجها في عنصر tools ضمن المقدمة في النموذج. يعرض المثال أدناه بعض الإعدادات الإضافية الاختيارية:

  • السماح بمتغيّرات الإدخال من الرمز البرمجي من جهة العميل، وإجراء التحقّق من صحة الإدخال والمخطط لهذا الإدخال (في هذا المثال، question).

  • اضبط أداة googleMaps من خلال تقديم إحداثيات الموقع الجغرافي و/أو رمز اللغة في الرمز البرمجي من جهة العميل باستخدام TemplateToolConfig.

أسفل نموذج المثال، يمكنك العثور على قسم قابل للتوسيع يعرض عينات تعليمات برمجية من جهة العميل للتعامل مع هذه الإعدادات الاختيارية.

الإعدادات (frontmatter)

---
model: 'gemini-3.8-flash'
tools:
  - googleMaps
input:
  schema:
    question: string
---

الطلب وتعليمات النظام (حسب الاقتضاء)

{{role "system"}}
You are a helpful tour guide. Use the Google Maps tool with the provided coordinates to answer the user's question based on their location.

{{role "user"}}
{{question}}