بالنسبة إلى 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).
Hello world
في ما يلي مثال بسيط على نموذج طلب من الخادم:
الإعداد (frontmatter)
---
model: 'gemini-3.8-flash'
---
الطلب وتعليمات النظام (حسب الاقتضاء)
Write a story about a magic backpack.
التحكّم في إنشاء الردود
يمكنك التحكّم في إنشاء الردود بطرق متنوعة حسب حالة الاستخدام ومستوى التحكّم الذي تحتاجه.
إعدادات النموذج
اضبط إعدادات النموذج للتحكّم في طريقة إنشاء النموذج للردود، مثل عدد صيغ الردود (candidateCount) والحد الأقصى لعدد الرموز المميزة في الناتج وما إلى ذلك.
الإعداد (frontmatter)
---
model: 'gemini-3.8-flash'
config:
candidateCount: 1
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: تكون القيمة true عند تكرار العنصر الأول من مجموعة#each. -
@last: تكون القيمة صحيحة عند تكرار آخر عنصر في مجموعة#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. يُشار إلى العناصر والمصفوفات وقيم التعداد بقوسين بعد اسم الحقل.تُعتبر جميع السمات مطلوبة ما لم تحدّدها على أنّها اختيارية باستخدام
?. عندما يتم تصنيف سمة على أنّها اختيارية، يتم أيضًا السماح بقيم فارغة لها لتوفير مرونة أكبر لنماذج اللغات الكبيرة في عرض قيمة فارغة بدلاً من حذف حقل.
إليك مثالاً أساسيًا لتقديم مخطط الإدخال. يمكنك العثور على مخطط أكثر تقدّمًا أدناه مباشرةً.
الإعداد (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. يُشار إلى العناصر والمصفوفات وقيم التعداد بقوسين بعد اسم الحقل.تُعتبر جميع السمات مطلوبة ما لم تحدّدها على أنّها اختيارية باستخدام
?. عندما يتم تصنيف سمة على أنّها اختيارية، يتم أيضًا السماح بقيم فارغة لها لتوفير مرونة أكبر لنماذج اللغات الكبيرة في عرض قيمة فارغة بدلاً من حذف حقل.
إليك مثال أساسي لإنشاء ناتج 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 "
تزوّد أداة Grounding with
لاستخدام أداة 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}}