تتيح لك ميزة "تخزين السياق مؤقتًا" حفظ رموز الإدخال المميزة التي تم احتسابها مسبقًا وإعادة استخدامها بشكل متكرر، مثلاً عند طرح أسئلة مختلفة حول ملف الوسائط نفسه. ويمكن أن يؤدي ذلك إلى توفير التكاليف والوقت، وذلك حسب الاستخدام. للحصول على مقدّمة تفصيلية، يُرجى الاطّلاع على دليل التخزين المؤقت للسياق.
الطريقة: cachedContents.create
تنشئ هذه الطريقة مورد CachedContent.
نقطة نهاية
posthttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
نص الطلب
يحتوي نص الطلب على مثال CachedContent
.
contents[]
object (Content
)
اختياريّ. الإدخال فقط غير قابل للتغيير المحتوى المطلوب تخزينه مؤقتًا.
tools[]
object (Tool
)
اختياريّ. الإدخال فقط غير قابل للتغيير قائمة Tools
قد يستخدمها النموذج لإنشاء الرد التالي
expiration
Union type
expiration
إحدى القيم التالية فقط:expireTime
string (Timestamp
format)
طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم توفير هذا الخيار دائمًا في الناتج، بغض النظر عن ما تم إرساله في الإدخال.
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
ttl
string (Duration
format)
الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.
مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s
". مثال: "3.5s"
displayName
string
اختياريّ. غير قابل للتغيير اسم العرض ذو الدلالة للمحتوى المخزّن مؤقتًا، وهو من إنشاء المستخدم. 128 حرف Unicode كحدّ أقصى
model
string
مطلوب. غير قابل للتغيير اسم Model
المطلوب استخدامه للمحتوى المخزّن مؤقتًا. التنسيق: models/{model}
systemInstruction
object (Content
)
اختياريّ. الإدخال فقط غير قابل للتغيير تعليمات النظام التي يحدّدها المطوّر تتوفّر الميزة حاليًا للنصوص فقط.
toolConfig
object (ToolConfig
)
اختياريّ. الإدخال فقط غير قابل للتغيير إعدادات الأداة تتم مشاركة هذا الإعداد مع جميع الأدوات.
مثال على الطلب
التذكرة الأساسية
Python
Node.js
Go
محارة
اسم المرسِل
Python
Node.js
Go
من محادثة
Python
Node.js
Go
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال تم إنشاؤه حديثًا CachedContent
.
الطريقة: cachedContents.list
تعرض هذه الطريقة محتوى القوائم المخزّن مؤقتًا.
نقطة نهاية
gethttps: / /generativelanguage.googleapis.com /v1beta /cachedContents
مَعلمات طلب البحث
pageSize
integer
اختياريّ. تعرض هذه المَعلمة أكبر عدد ممكن من المحتوى المخزّن مؤقتًا. قد تعرض الخدمة عددًا أقل من هذه القيمة. في حال عدم تحديدها، سيتم عرض عدد تلقائي (أقل من الحد الأقصى) من العناصر. الحد الأقصى للقيمة هو 1000، وسيتم فرض القيمة 1000 على القيم الأكبر من 1000.
pageToken
string
اختياريّ. رمز مميز للصفحة تم تلقّيه من طلب cachedContents.list
سابق. قدِّم هذه السلسلة لاسترداد الصفحة التالية.
عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة إلى cachedContents.list
مع الطلب الذي قدّم رمز الصفحة المميز.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
الردّ باستخدام قائمة CachedContents
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
cachedContents[]
object (CachedContent
)
قائمة بالمحتوى المخزَّن مؤقتًا
nextPageToken
string
رمز مميز يمكن إرساله كـ pageToken
لاسترداد الصفحة التالية. في حال حذف هذا الحقل، لن تكون هناك صفحات لاحقة.
تمثيل JSON |
---|
{
"cachedContents": [
{
object ( |
الطريقة: cachedContents.get
قراءة مورد CachedContent
نقطة نهاية
gethttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
مَعلمات المسار
name
string
مطلوب. اسم المرجع الخاص بإدخال ذاكرة التخزين المؤقت للمحتوى التنسيق: cachedContents/{id}
يتّخذ الشكل cachedContents/{cachedcontent}
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
مثال على الطلب
Python
Node.js
Go
محارة
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال CachedContent
.
الطريقة: cachedContents.patch
تعديل مورد CachedContent (يمكن تعديل تاريخ انتهاء الصلاحية فقط)
نقطة نهاية
patchhttps: / /generativelanguage.googleapis.com /v1beta /{cachedContent.name=cachedContents /*}
PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
مَعلمات المسار
cachedContent.name
string
النتائج فقط. المعرّف اسم المرجع الذي يشير إلى المحتوى المخزّن مؤقتًا التنسيق: cachedContents/{id}
يتّخذ الشكل cachedContents/{cachedcontent}
.
مَعلمات طلب البحث
updateMask
string (FieldMask
format)
قائمة الحقول التي سيتم تعديلها
هذه قائمة مفصولة بفواصل تتضمّن الأسماء المؤهَّلة بالكامل للحقول. مثال: "user.displayName,photo"
نص الطلب
يحتوي نص الطلب على مثال CachedContent
.
expiration
Union type
expiration
إحدى القيم التالية فقط:expireTime
string (Timestamp
format)
طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم توفير هذا الخيار دائمًا في الناتج، بغض النظر عن ما تم إرساله في الإدخال.
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
ttl
string (Duration
format)
الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.
مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s
". مثال: "3.5s"
مثال على الطلب
Python
Node.js
Go
محارة
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال CachedContent
.
الطريقة: cachedContents.delete
تحذف هذه الطريقة مورد CachedContent.
نقطة نهاية
deletehttps: / /generativelanguage.googleapis.com /v1beta /{name=cachedContents /*}
مَعلمات المسار
name
string
مطلوب. اسم المرجع الذي يشير إلى إدخال ذاكرة التخزين المؤقت للمحتوى، التنسيق: cachedContents/{id}
يأخذ الشكل cachedContents/{cachedcontent}
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
مثال على الطلب
Python
Node.js
Go
محارة
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيكون نص الاستجابة عبارة عن كائن JSON فارغ.
مورد REST: cachedContents
- المورد: CachedContent
- المحتوى
- الجزء
- Blob
- FunctionCall
- FunctionResponse
- الجدولة
- FileData
- ExecutableCode
- اللغة
- CodeExecutionResult
- النتيجة
- VideoMetadata
- الأداة
- FunctionDeclaration
- المخطط
- النوع
- السلوك
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- الوضع
- CodeExecution
- GoogleSearch
- الفاصل الزمني
- UrlContext
- ToolConfig
- FunctionCallingConfig
- الوضع
- UsageMetadata
- الطُرق
المورد: CachedContent
المحتوى الذي تمت معالجته مسبقًا ويمكن استخدامه في طلب لاحق إلى GenerativeService
لا يمكن استخدام المحتوى المخزّن مؤقتًا إلا مع النموذج الذي تم إنشاؤه من أجله.
contents[]
object (Content
)
اختياريّ. الإدخال فقط غير قابل للتغيير المحتوى المطلوب تخزينه مؤقتًا.
tools[]
object (Tool
)
اختياريّ. الإدخال فقط غير قابل للتغيير قائمة Tools
قد يستخدمها النموذج لإنشاء الرد التالي
createTime
string (Timestamp
format)
النتائج فقط. وقت إنشاء إدخال ذاكرة التخزين المؤقت
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
updateTime
string (Timestamp
format)
النتائج فقط. وقت آخر تعديل لإدخال ذاكرة التخزين المؤقت بالتوقيت العالمي المنسّق
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
usageMetadata
object (UsageMetadata
)
النتائج فقط. البيانات الوصفية المتعلقة باستخدام المحتوى المخزّن مؤقتًا
expiration
Union type
expiration
إحدى القيم التالية فقط:expireTime
string (Timestamp
format)
طابع زمني بالتوقيت العالمي المتفق عليه يحدّد وقت انتهاء صلاحية هذا المرجع. يتم توفير هذا الخيار دائمًا في الناتج، بغض النظر عن ما تم إرساله في الإدخال.
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
ttl
string (Duration
format)
الإدخال فقط مدة البقاء الجديدة لهذا المورد، يجب إدخالها فقط.
مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s
". مثال: "3.5s"
name
string
النتائج فقط. المعرّف اسم المرجع الذي يشير إلى المحتوى المخزّن مؤقتًا التنسيق: cachedContents/{id}
displayName
string
اختياريّ. غير قابل للتغيير اسم العرض ذو الدلالة للمحتوى المخزّن مؤقتًا، وهو من إنشاء المستخدم. 128 حرف Unicode كحدّ أقصى
model
string
مطلوب. غير قابل للتغيير اسم Model
المطلوب استخدامه للمحتوى المخزّن مؤقتًا. التنسيق: models/{model}
systemInstruction
object (Content
)
اختياريّ. الإدخال فقط غير قابل للتغيير تعليمات النظام التي يحدّدها المطوّر تتوفّر الميزة حاليًا للنصوص فقط.
toolConfig
object (ToolConfig
)
اختياريّ. الإدخال فقط غير قابل للتغيير إعدادات الأداة تتم مشاركة هذا الإعداد مع جميع الأدوات.
تمثيل JSON |
---|
{ "contents": [ { object ( |
المحتوى
نوع البيانات المنظَّمة الأساسي الذي يحتوي على محتوى متعدد الأجزاء لرسالة
يتضمّن Content
حقل role
يحدّد منتج Content
وحقل parts
يحتوي على بيانات متعدّدة الأجزاء تتضمّن محتوى دورة الرسالة.
parts[]
object (Part
)
Parts
بالترتيب التي تشكّل رسالة واحدة قد تحتوي الأجزاء على أنواع MIME مختلفة.
role
string
اختياريّ. تمثّل هذه السمة منتج المحتوى. يجب أن تكون القيمة إما "user" أو "model".
يجب ضبط هذه السمة للمحادثات المتعددة الأدوار، وإلا يمكن تركها فارغة أو بدون ضبط.
تمثيل JSON |
---|
{
"parts": [
{
object ( |
الجزء
نوع بيانات يحتوي على وسائط تشكّل جزءًا من رسالة Content
متعددة الأجزاء.
يتألف Part
من بيانات لها نوع بيانات مرتبط بها. لا يمكن أن يحتوي Part
إلا على أحد الأنواع المقبولة في Part.data
.
يجب أن يحتوي Part
على نوع MIME ثابت من IANA يحدّد نوع الوسائط ونوعها الفرعي إذا تم ملء الحقل inlineData
ببايتات أولية.
thought
boolean
اختياريّ. تشير إلى ما إذا كان الجزء مستنتجًا من النموذج.
thoughtSignature
string (bytes format)
اختياريّ. توقيع غير شفاف للفكرة حتى يمكن إعادة استخدامه في الطلبات اللاحقة.
سلسلة مرمّزة باستخدام Base64
data
Union type
data
إحدى القيم التالية فقط:text
string
نص مضمّن
inlineData
object (Blob
)
وحدات بايت الوسائط المضمّنة
functionCall
object (FunctionCall
)
FunctionCall
متوقّع يتم عرضه من النموذج يحتوي على سلسلة تمثّل FunctionDeclaration.name
مع الوسيطات وقيمها
functionResponse
object (FunctionResponse
)
يتم استخدام نتيجة تنفيذ FunctionCall
التي تحتوي على سلسلة تمثّل FunctionDeclaration.name
وعنصر JSON منظَّم يحتوي على أي ناتج من الدالة كسياق للنموذج.
fileData
object (FileData
)
البيانات المستندة إلى معرّف الموارد المنتظم (URI)
executableCode
object (ExecutableCode
)
الرمز الذي أنشأه النموذج والمخصّص للتنفيذ
codeExecutionResult
object (CodeExecutionResult
)
نتيجة تنفيذ ExecutableCode
metadata
Union type
metadata
إحدى القيم التالية فقط:videoMetadata
object (VideoMetadata
)
اختياريّ. البيانات الوصفية للفيديو يجب تحديد البيانات الوصفية فقط أثناء عرض بيانات الفيديو في inlineData أو fileData.
تمثيل JSON |
---|
{ "thought": boolean, "thoughtSignature": string, // data "text": string, "inlineData": { object ( |
بلوب
وحدات بايت الوسائط الأولية
يجب عدم إرسال النص كبايتات أولية، بل استخدام الحقل "text".
mimeType
string
نوع MIME المتوافق مع معيار IANA لبيانات المصدر. أمثلة: - image/png - image/jpeg في حال تقديم نوع MIME غير متوافق، سيتم عرض رسالة خطأ. للحصول على قائمة كاملة بالأنواع المتوافقة، راجِع تنسيقات الملفات المتوافقة.
data
string (bytes format)
وحدات البايت الأولية لتنسيقات الوسائط
سلسلة مرمّزة باستخدام Base64
تمثيل JSON |
---|
{ "mimeType": string, "data": string } |
FunctionCall
FunctionCall
متوقّع يتم عرضه من النموذج يحتوي على سلسلة تمثّل FunctionDeclaration.name
مع الوسيطات وقيمها
id
string
اختياريّ. المعرّف الفريد لطلب تنفيذ الدالة. في حال توفُّرها، على العميل تنفيذ functionCall
وعرض الردّ مع id
المطابق.
name
string
مطلوب. تمثّل هذه السمة اسم الدالة المطلوب استدعاؤها. يجب أن يكون من a إلى z أو من A إلى Z أو من 0 إلى 9 أو يحتوي على شرطات سفلية وواصلات، وبحد أقصى 63 حرفًا.
args
object (Struct
format)
اختياريّ. مَعلمات الدالة وقيمها بتنسيق عنصر JSON.
تمثيل JSON |
---|
{ "id": string, "name": string, "args": { object } } |
FunctionResponse
يتم استخدام نتيجة الإخراج من FunctionCall
التي تحتوي على سلسلة تمثّل FunctionDeclaration.name
وعنصر JSON منظَّم يحتوي على أي إخراج من الدالة كسياق للنموذج. يجب أن يحتوي هذا الحقل على نتيجة FunctionCall
تم إجراؤها استنادًا إلى توقّع النموذج.
id
string
اختياريّ. معرّف استدعاء الدالة الذي يخصّه هذا الردّ. يتم ملء هذا الحقل من خلال العميل لمطابقة استدعاء الدالة id
المقابل.
name
string
مطلوب. تمثّل هذه السمة اسم الدالة المطلوب استدعاؤها. يجب أن يكون من a إلى z أو من A إلى Z أو من 0 إلى 9 أو يحتوي على شرطات سفلية وواصلات، وبحد أقصى 63 حرفًا.
response
object (Struct
format)
مطلوب. استجابة الدالة بتنسيق عنصر JSON.
willContinue
boolean
اختياريّ. إشارات إلى أنّ استدعاء الدالة مستمر، وسيتم عرض المزيد من الردود، ما يحوّل استدعاء الدالة إلى مولّد. لا ينطبق إلا على استدعاءات الدوال NON_BLOCKING، ويتم تجاهله في الحالات الأخرى. في حال ضبطها على "خطأ"، لن يتم النظر في الردود المستقبلية. يُسمح بعرض response
فارغ مع willContinue=False
للإشارة إلى انتهاء طلب الدالة. قد يؤدي ذلك إلى بدء عملية إنشاء النموذج. لتجنُّب بدء عملية الإنشاء وإنهاء استدعاء الدالة، اضبط scheduling
على SILENT
أيضًا.
scheduling
enum (Scheduling
)
اختياريّ. تحدّد هذه السمة كيفية جدولة الرد في المحادثة. لا ينطبق إلا على استدعاءات الدوال NON_BLOCKING، ويتم تجاهله في الحالات الأخرى. القيمة التلقائية هي WHEN_IDLE.
تمثيل JSON |
---|
{
"id": string,
"name": string,
"response": {
object
},
"willContinue": boolean,
"scheduling": enum ( |
الجدولة
تحدّد هذه السمة كيفية جدولة الرد في المحادثة.
عمليات التعداد | |
---|---|
SCHEDULING_UNSPECIFIED |
هذه القيمة غير مستخدَمة. |
SILENT |
يجب إضافة النتيجة إلى سياق المحادثة فقط، وعدم مقاطعة المحادثة أو بدء عملية إنشاء المحتوى. |
WHEN_IDLE |
أضِف النتيجة إلى سياق المحادثة، واطلب إنشاء الناتج بدون مقاطعة عملية الإنشاء الجارية. |
INTERRUPT |
إضافة النتيجة إلى سياق المحادثة وإيقاف عملية الإنشاء الجارية مؤقتًا وطلب إنشاء الناتج |
FileData
البيانات المستندة إلى معرّف الموارد المنتظم (URI)
mimeType
string
اختياريّ. نوع MIME المتوافق مع معيار IANA لبيانات المصدر.
fileUri
string
مطلوب. عنوان URI.
تمثيل JSON |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
التعليمات البرمجية التي ينشئها النموذج والمخصّصة للتنفيذ، والنتيجة التي يتم إرجاعها إلى النموذج
يتم إنشاؤه فقط عند استخدام أداة CodeExecution
، حيث سيتم تنفيذ الرمز تلقائيًا، وسيتم أيضًا إنشاء CodeExecutionResult
مطابق.
language
enum (Language
)
مطلوب. لغة البرمجة الخاصة بـ code
code
string
مطلوب. الرمز المطلوب تنفيذه
تمثيل JSON |
---|
{
"language": enum ( |
اللغة
لغات البرمجة المتوافقة مع الرمز البرمجي الذي تم إنشاؤه
عمليات التعداد | |
---|---|
LANGUAGE_UNSPECIFIED |
لغة غير محدّدة يجب عدم استخدام هذه القيمة. |
PYTHON |
الإصدار 3.10 من Python أو الإصدارات الأحدث، مع توفّر numpy وsimpy |
CodeExecutionResult
نتيجة تنفيذ ExecutableCode
يتم إنشاؤه فقط عند استخدام CodeExecution
، ويتبع دائمًا part
يحتوي على ExecutableCode
.
outcome
enum (Outcome
)
مطلوب. نتيجة تنفيذ الرمز البرمجي
output
string
اختياريّ. يحتوي على stdout عند تنفيذ الرمز البرمجي بنجاح، أو stderr أو وصف آخر في الحالات الأخرى.
تمثيل JSON |
---|
{
"outcome": enum ( |
النتيجة
تعداد النتائج المحتملة لتنفيذ الرمز البرمجي
عمليات التعداد | |
---|---|
OUTCOME_UNSPECIFIED |
حالة غير محدَّدة يجب عدم استخدام هذه القيمة. |
OUTCOME_OK |
اكتمل تنفيذ الرمز البرمجي بنجاح. |
OUTCOME_FAILED |
اكتمل تنفيذ الرمز البرمجي ولكن مع حدوث خطأ. يجب أن يتضمّن stderr السبب. |
OUTCOME_DEADLINE_EXCEEDED |
استغرق تنفيذ الرمز البرمجي وقتًا طويلاً جدًا وتم إلغاؤه. قد تكون هناك نتائج جزئية أو لا تكون. |
VideoMetadata
تصف البيانات الوصفية محتوى الفيديو الذي يتم إدخاله.
startOffset
string (Duration
format)
اختياريّ. إزاحة بدء الفيديو
مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s
". مثال: "3.5s"
endOffset
string (Duration
format)
اختياريّ. إزاحة نهاية الفيديو
مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s
". مثال: "3.5s"
fps
number
اختياريّ. تمثّل هذه السمة عدد اللقطات في الثانية للفيديو المُرسَل إلى النموذج. إذا لم يتم تحديدها، ستكون القيمة التلقائية 1.0. نطاق عدد اللقطات في الثانية هو (0.0, 24.0].
تمثيل JSON |
---|
{ "startOffset": string, "endOffset": string, "fps": number } |
الأداة
تفاصيل الأداة التي قد يستخدمها النموذج لإنشاء الردّ
Tool
هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع أنظمة خارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة النموذج.
functionDeclarations[]
object (FunctionDeclaration
)
اختياريّ. قائمة FunctionDeclarations
متاحة للنموذج ويمكن استخدامها لاستدعاء الدوال.
لا ينفّذ النموذج أو النظام الدالة. بدلاً من ذلك، قد يتم عرض الدالة المحدّدة كـ FunctionCall
مع وسيطات من جهة العميل لتنفيذها. قد يقرّر النموذج استدعاء مجموعة فرعية من هذه الدوال عن طريق ملء FunctionCall
في الردّ. قد تتضمّن نوبة المحادثة التالية FunctionResponse
مع سياق إنشاء Content.role
"الوظيفة" لنوبة النموذج التالية.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
اختياريّ. أداة استرجاع مدعومة من "بحث Google"
codeExecution
object (CodeExecution
)
اختياريّ. تتيح هذه السمة للنموذج تنفيذ الرمز البرمجي كجزء من عملية الإنشاء.
googleSearch
object (GoogleSearch
)
اختياريّ. نوع أداة GoogleSearch أداة لدعم "بحث Google" في Model بواسطة Google.
urlContext
object (UrlContext
)
اختياريّ. أداة للمساعدة في استرداد سياق عنوان URL
تمثيل JSON |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
تمثيل منظَّم لتعريف دالة كما هو محدّد في مواصفات OpenAPI 3.03 يتضمّن هذا التعريف اسم الدالة ومعلَماتها. تمثّل FunctionDeclaration مجموعة من الرموز البرمجية التي يمكن استخدامها كـ Tool
من قِبل النموذج وتنفيذها من قِبل العميل.
name
string
مطلوب. اسم الدالة يجب أن يكون من a إلى z أو من A إلى Z أو من 0 إلى 9 أو يحتوي على شرطات سفلية وواصلات، وبحد أقصى 63 حرفًا.
description
string
مطلوب. وصف موجز للدالة
behavior
enum (Behavior
)
اختياريّ. تحدّد هذه السمة سلوك الدالة. لا تتوافق هذه السمة حاليًا إلا مع طريقة BidiGenerateContent.
parameters
object (Schema
)
اختياريّ. توضّح هذه السمة المَعلمات الخاصة بهذه الدالة. تعكس هذه السمة مفتاح سلسلة "عنصر المَعلمة" في Open API 3.03: اسم المَعلمة. أسماء المَعلمات حسّاسة لحالة الأحرف. قيمة المخطط: المخطط الذي يحدّد النوع المستخدَم للمَعلمة.
parametersJsonSchema
value (Value
format)
اختياريّ. تصف هذه السمة مَعلمات الدالة بتنسيق JSON Schema. يجب أن يصف المخطط كائنًا تكون خصائصه هي مَعلمات الدالة. على سبيل المثال:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"additionalProperties": false,
"required": ["name", "age"],
"propertyOrdering": ["name", "age"]
}
لا يمكن استخدام هذا الحقل مع parameters
.
response
object (Schema
)
اختياريّ. تصف هذه السمة الناتج من هذه الدالة بتنسيق JSON Schema. تعكس هذه السمة "عنصر الرد" في Open API 3.03. يحدّد المخطط نوع القيمة المستخدَمة في قيمة استجابة الدالة.
responseJsonSchema
value (Value
format)
اختياريّ. تصف هذه السمة الناتج من هذه الدالة بتنسيق JSON Schema. القيمة المحدّدة بواسطة المخطط هي قيمة الردّ للدالة.
لا يمكن استخدام هذا الحقل مع response
.
المخطط
يسمح العنصر Schema
بتحديد أنواع بيانات الإدخال والإخراج. يمكن أن تكون هذه الأنواع كائنات، ولكن أيضًا أنواعًا أولية ومصفوفات. يمثّل مجموعة فرعية محدّدة من كائن مخطط OpenAPI 3.0.
type
enum (Type
)
مطلوب. نوع البيانات
format
string
اختياريّ. تنسيق البيانات يُسمح بأي قيمة، ولكن معظم القيم لا تؤدي إلى تشغيل أي وظائف خاصة.
title
string
اختياريّ. تمثّل هذه السمة عنوان المخطط.
description
string
اختياريّ. وصف موجز للمَعلمة يمكن أن يحتوي ذلك على أمثلة على الاستخدام. قد يتم تنسيق وصف المَعلمة على شكل Markdown.
nullable
boolean
اختياريّ. تشير إلى ما إذا كان يمكن أن تكون القيمة فارغة.
enum[]
string
اختياريّ. القيم المحتملة لعنصر Type.STRING بتنسيق enum. على سبيل المثال، يمكننا تحديد تعداد Direction على النحو التالي : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
اختياريّ. الحدّ الأقصى لعدد العناصر في Type.ARRAY
minItems
string (int64 format)
اختياريّ. الحد الأدنى لعدد العناصر في Type.ARRAY
properties
map (key: string, value: object (Schema
))
اختياريّ. خصائص Type.OBJECT
عنصر يحتوي على قائمة بأزواج "key": value
مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }
required[]
string
اختياريّ. السمات المطلوبة من النوع Type.OBJECT
minProperties
string (int64 format)
اختياريّ. الحد الأدنى لعدد السمات الخاصة بـ Type.OBJECT
maxProperties
string (int64 format)
اختياريّ. الحدّ الأقصى لعدد السمات من النوع OBJECT
minLength
string (int64 format)
اختياريّ. حقول المخطط لنوع STRING الحدّ الأدنى لطول النوع STRING
maxLength
string (int64 format)
اختياريّ. الحد الأقصى لطول Type.STRING
pattern
string
اختياريّ. نمط Type.STRING لحصر سلسلة بتعبير عادي
example
value (Value
format)
اختياريّ. مثال على العنصر لن تتم تعبئة هذا الحقل إلا عندما يكون العنصر هو العنصر الجذر.
anyOf[]
object (Schema
)
اختياريّ. يجب التحقّق من صحة القيمة مقارنةً بأي من المخططات الفرعية (واحد أو أكثر) في القائمة.
propertyOrdering[]
string
اختياريّ. ترتيب السمات ليس حقلاً عاديًا في مواصفات Open API، ويُستخدم لتحديد ترتيب السمات في الاستجابة.
default
value (Value
format)
اختياريّ. القيمة التلقائية للحقل وفقًا لمخطط JSON، هذا الحقل مخصّص لأدوات إنشاء المستندات ولا يؤثر في عملية التحقّق من الصحة. لذلك، يتم تضمينه هنا وتجاهله حتى لا يتلقّى المطوّرون الذين يرسلون مخططات تتضمّن الحقل default
أخطاء حقل غير معروف.
items
object (Schema
)
اختياريّ. مخطط عناصر Type.ARRAY
minimum
number
اختياريّ. حقول المخطط لنوع العدد الصحيح والرقم، الحد الأدنى لقيمة النوع INTEGER والرقم
maximum
number
اختياريّ. الحدّ الأقصى لقيمة Type.INTEGER وType.NUMBER
تمثيل JSON |
---|
{ "type": enum ( |
النوع
يحتوي النوع على قائمة بأنواع بيانات OpenAPI كما هو محدّد في https://spec.openapis.org/oas/v3.0.3#data-types
عمليات التعداد | |
---|---|
TYPE_UNSPECIFIED |
لم يتم تحديدها، ويجب عدم استخدامها. |
STRING |
نوع السلسلة |
NUMBER |
نوع الرقم |
INTEGER |
نوع العدد الصحيح |
BOOLEAN |
النوع المنطقي |
ARRAY |
نوع المصفوفة |
OBJECT |
نوع العنصر |
NULL |
نوع القيمة الفارغة |
السلوك
تحدّد هذه السمة سلوك الدالة. القيمة التلقائية هي BLOCKING
.
عمليات التعداد | |
---|---|
UNSPECIFIED |
هذه القيمة غير مستخدَمة. |
BLOCKING |
في حال ضبط هذه السمة، سينتظر النظام تلقّي ردّ الدالة قبل مواصلة المحادثة. |
NON_BLOCKING |
في حال ضبطها، لن ينتظر النظام تلقّي استجابة الدالة. بدلاً من ذلك، سيحاول التعامل مع ردود الوظائف فور توفّرها مع الحفاظ على المحادثة بين المستخدم والنموذج. |
GoogleSearchRetrieval
أداة لاسترداد بيانات الويب المتاحة للجميع من أجل التأسيس، وهي من تطوير Google.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
تحدّد هذه السمة إعدادات الاسترجاع الديناميكي للمصدر المحدّد.
تمثيل JSON |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
توضّح هذه السمة خيارات تخصيص الاسترجاع الديناميكي.
mode
enum (Mode
)
وضع أداة التوقّع التي سيتم استخدامها في الاسترجاع الديناميكي.
dynamicThreshold
number
الحدّ الذي سيتم استخدامه في الاسترجاع الديناميكي. في حال عدم ضبط هذه السياسة، يتم استخدام قيمة تلقائية للنظام.
تمثيل JSON |
---|
{
"mode": enum ( |
الوضع
وضع أداة التوقّع التي سيتم استخدامها في الاسترجاع الديناميكي.
عمليات التعداد | |
---|---|
MODE_UNSPECIFIED |
تفعيل عملية الاسترداد دائمًا |
MODE_DYNAMIC |
إجراء عملية الاسترجاع فقط عندما يقرّر النظام أنّها ضرورية |
CodeExecution
لا يتضمّن هذا النوع أي حقول.
أداة تنفّذ الرمز الذي ينشئه النموذج وتعرض النتيجة تلقائيًا للنموذج
يمكنك الاطّلاع أيضًا على ExecutableCode
وCodeExecutionResult
اللذين يتم إنشاؤهما فقط عند استخدام هذه الأداة.
GoogleSearch
الفاصل الزمني
تمثّل هذه السمة فاصلًا زمنيًا، ويتم ترميزها كطابع زمني للبدء (شامل) وطابع زمني للانتهاء (غير شامل).
يجب أن تكون قيمة البداية أقل من أو تساوي قيمة النهاية. عندما يكون وقت البدء مساويًا لوقت الانتهاء، يكون الفاصل الزمني فارغًا (لا يتطابق مع أي وقت). عندما لا يتم تحديد كل من وقت البدء ووقت الانتهاء، يتطابق الفاصل الزمني مع أي وقت.
startTime
string (Timestamp
format)
اختياريّ. بداية الفاصل الزمني الشاملة
في حال تحديدها، يجب أن يكون الطابع الزمني الذي يتطابق مع هذا الفاصل الزمني هو نفسه وقت البدء أو بعده.
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
endTime
string (Timestamp
format)
اختياريّ. النهاية الحصرية للفاصل الزمني
في حال تحديد طابع زمني، يجب أن يكون الطابع الزمني الذي يتطابق مع هذا الفاصل الزمني قبل وقت الانتهاء.
يستخدم هذا النوع RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا عاديًا وموحّدًا حسب المنطقة الزمنية Z، وسيستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z"
أو "2014-10-02T15:01:23.045123456Z"
أو "2014-10-02T15:01:23+05:30"
تمثيل JSON |
---|
{ "startTime": string, "endTime": string } |
UrlContext
لا يتضمّن هذا النوع أي حقول.
أداة للمساعدة في استرداد سياق عنوان URL
ToolConfig
إعدادات الأداة التي تحتوي على مَعلمات لتحديد استخدام Tool
في الطلب
functionCallingConfig
object (FunctionCallingConfig
)
اختياريّ. إعدادات استدعاء الدالة
تمثيل JSON |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
إعدادات لتحديد سلوك استدعاء الدوال
mode
enum (Mode
)
اختياريّ. تحدّد هذه السمة الوضع الذي يجب أن يتم فيه تنفيذ ميزة "استدعاء الدوال". إذا لم يتم تحديدها، سيتم ضبط القيمة التلقائية على AUTO.
allowedFunctionNames[]
string
اختياريّ. مجموعة من أسماء الدوال التي تحدّ من الدوال التي سيستدعيها النموذج عند توفيرها.
يجب ضبط هذا الخيار فقط عندما يكون الوضع ANY أو VALIDATED. يجب أن تتطابق أسماء الدوال مع [FunctionDeclaration.name]. عند ضبط هذه السمة، سيتوقّع النموذج استدعاء دالة من أسماء الدوال المسموح بها فقط.
تمثيل JSON |
---|
{
"mode": enum ( |
الوضع
تحدّد هذه السمة سلوك التنفيذ الخاص بميزة "استدعاء الدوال" من خلال تحديد وضع التنفيذ.
عمليات التعداد | |
---|---|
MODE_UNSPECIFIED |
وضع غير محدّد لاستدعاء الدوال يجب عدم استخدام هذه القيمة. |
AUTO |
سلوك النموذج التلقائي، يقرّر النموذج التنبؤ إما باستدعاء دالة أو ردّ باللغة الطبيعية. |
ANY |
يقتصر النموذج على توقّع استدعاء دالة فقط. في حال ضبط "allowedFunctionNames"، سيقتصر استدعاء الدالة المتوقّعة على أيّ من "allowedFunctionNames"، وإلا سيكون استدعاء الدالة المتوقّعة أيًّا من "functionDeclarations" المقدَّمة. |
NONE |
لن يتوقّع النموذج أي استدعاء دالة. يكون سلوك النموذج هو نفسه عند عدم تمرير أي تعريفات للدوال. |
VALIDATED |
يقرّر النموذج توقّع إما طلب دالة أو ردّ باللغة الطبيعية، ولكنّه سيتحقّق من صحة طلبات الدوال باستخدام فك الترميز المقيد. في حال ضبط "allowedFunctionNames"، سيقتصر استدعاء الدالة المتوقّعة على أيّ من "allowedFunctionNames"، وإلا سيكون استدعاء الدالة المتوقّعة أيًّا من "functionDeclarations" المقدَّمة. |
UsageMetadata
البيانات الوصفية المتعلقة باستخدام المحتوى المخزّن مؤقتًا
totalTokenCount
integer
إجمالي عدد الرموز المميزة التي يستهلكها المحتوى المخزّن مؤقتًا
تمثيل JSON |
---|
{ "totalTokenCount": integer } |