إنشاء مخرجات منظَّمة (مثل JSON) باستخدام Gemini API


يعرض الرمز Gemini API الردود كنص غير منظَّم تلقائيًا. ومع ذلك، تتطلّب بعض حالات الاستخدام نصًا منظَّمًا، مثل JSON. على سبيل المثال، قد يتم استخدام الردّ في مهام أخرى لاحقة تتطلّب ملفًا تعريفيًا محددًا للبيانات.

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

وإليك بعض الأمثلة:

  • تأكَّد من أنّ استجابة النموذج تُنشئ ملف JSON صالحًا وأنّها تمتثل للمخطّط المقدَّم.
    على سبيل المثال، يمكن للنموذج إنشاء إدخالات منظَّمة للوصفات التي تشمل دائمًا اسم الوصفة وقائمة المكونات والخطوات. يمكنك بعد ذلك تحليل هذه المعلومات وعرضها في واجهة مستخدم تطبيقك بسهولة أكبر.

  • فرض قيود على كيفية استجابة النموذج أثناء مهام التصنيف
    على سبيل المثال، يمكنك أن تطلب من النموذج إضافة تعليقات توضيحية إلى النص باستخدام مجموعة محدّدة من التصنيفات (مثل مجموعة محدّدة من التصنيفات المحدّدة مسبقًا مثل positive وnegative)، بدلاً من التصنيفات التي ينشئها النموذج (التي قد تتضمّن درجة من التفاوت مثل good أو positive أو negative أو bad).

يوضّح لك هذا الدليل كيفية إنشاء إخراج بتنسيق JSON من خلال تقديم responseSchema في طلب إلى generateContent. ويركز هذا التطبيق على الإدخال النصي فقط، ولكن يمكنه أيضًا تقديم ردود منظَّمة على الطلبات التي تتضمّن عدة وسائط، مثل الصور والفيديوهات والمحتوى الصوتي.

في أسفل هذه الصفحة، يمكنك الاطّلاع على المزيد من الأمثلة، مثل كيفية إنشاء قيم مصنّفة كإخراج. للاطّلاع على مثالين إضافيين على كيفية إنشاء مخرجات منظَّمة، يمكنك الاطّلاع على قائمة أمثلة على المخططات والردود النموذجية في مستندات Google Cloud.

قبل البدء

إذا لم يسبق لك ذلك، أكمِل قراءة دليل البدء الذي يوضّح كيفية إعداد مشروعك على Firebase وربط تطبيقك بـ Firebase وإضافة حزمة تطوير البرامج (SDK) وبدء خدمة Vertex AI وإنشاء مثيل GenerativeModel.

الخطوة 1: تحديد مخطّط استجابة

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

عندما ينشئ النموذج رده، يستخدم اسم الحقل والسياق من طلبك. لكي يكون هدفك واضحًا، ننصحك باستخدام بنية واضحة وأسماء حقول لا لبس فيها، وحتى أوصافًا حسب الحاجة.

اعتبارات حول مخطّطات الاستجابة

يُرجى مراعاة ما يلي عند كتابة مخطّط الردّ:

  • يتم احتساب حجم مخطّط الاستجابة ضمن الحد الأقصى لرمز المرور المُدخل.

  • تتيح ميزة مخطّط الاستجابة أنواع MIME التالية للإجابات:

    • ‫application/json: إخراج JSON كما هو محدّد في مخطّط الاستجابة (مفيد لمتطلبات الإخراج المنظّم)

    • ‫text/x.enum: عرض قيمة إحصائية كما هو محدّد في مخطّط الاستجابة (مفيد لمهام التصنيف)

  • تتيح ميزة مخطّط الاستجابة حقول المخطّط التالية:

    enum
    items
    		 maxItems
    nullable
    		 properties
    required

    في حال استخدام حقل غير متوافق، سيظل بإمكان النموذج معالجة طلبك، ولكن سيتجاهل الحقل. يُرجى العِلم أنّ القائمة أعلاه هي مجموعة فرعية من عنصر مخطّط OpenAPI 3.0 (اطّلِع على مرجع مخطّط Vertex AI).

  • بالنسبة إلى Vertex AI in Firebase حِزم تطوير البرامج (SDK)، يتم اعتبار جميع الحقول تلقائيًا مطلوبة ما لم تحدّدها كحقول اختيارية في صفيف optionalProperties. بالنسبة إلى هذه الحقول الاختيارية، يمكن للنموذج تعبئة الحقول أو تخطّيها.

    يُرجى العلم أنّ هذا السلوك هو عكس السلوك التلقائي لعنصر Vertex AI Gemini API.

الخطوة 2: إرسال طلب يتضمّن مخطّط استجابة لإنشاء ملف JSON

يوضّح المثال التالي كيفية إنشاء إخراج JSON منظَّم.

لإنشاء إخراج منظَّم، عليك تحديد responseMimeType المناسب (application/json في هذا المثال) أثناء بدء تشغيل النموذج، بالإضافة إلى responseSchema الذي تريد أن يستخدمه النموذج.

يمكن استخدام responseSchema في جميع طُرز Gemini (باستثناء طُرز Gemini 1.0).

تعرَّف على كيفية اختيار نموذج وموقع جغرافي اختياريًا مناسبَين لحالة الاستخدام والتطبيق.

أمثلة إضافية

للاطّلاع على أمثلة إضافية حول كيفية استخدام النتائج المنظَّمة وإنشائها، اطّلِع على قائمة أمثلة على المخططات والردود النموذجية في مستندات Google Cloud.

إنشاء قيم enum كإخراج

يوضّح المثال التالي كيفية استخدام مخطّط استجابة لمهمّة تصنيف. يُطلب من النموذج تحديد نوع الفيلم استنادًا إلى وصفه. الناتج هو قيمة واحدة من القيم المحدّدة في النصوص العادية التي يختارها النموذج من قائمة القيم المحدّدة في مخطّط الاستجابة المقدَّم.

لتنفيذ مهمة التصنيف المنظَّم هذه، عليك تحديد responseMimeType المناسب (في هذا المثال، text/x.enum) بالإضافة إلى responseSchema الذي تريد أن يستخدمه النموذج أثناء بدء تشغيله.

تعرَّف على كيفية اختيار نموذج وموقع جغرافي اختياريًا مناسبَين لحالة الاستخدام والتطبيق.

خيارات أخرى للتحكّم في إنشاء المحتوى

  • اطّلِع على مزيد من المعلومات عن تصميم الطلب حتى تتمكّن من التأثير في النموذج لإنشاء نتائج خاصة باحتياجاتك.
  • يمكنك ضبط مَعلمات النموذج للتحكّم في كيفية إنشاء النموذج لردّ. بالنسبة إلى نماذج Gemini، تتضمّن هذه المَعلمات الحد الأقصى لرموز الإخراج ودرجة الحرارة وtopK وtopP. بالنسبة إلى نماذج Imagen، تشمل هذه الإعدادات نسبة العرض إلى الارتفاع وإنشاء الأشخاص ووضع العلامة المائية وما إلى ذلك.
  • استخدِم إعدادات الأمان لضبط احتمالية تلقّي ردود قد تُعتبر ضارة، بما في ذلك خطاب الكراهية والمحتوى الجنسي الفاضح.
  • اضبط تعليمات النظام لتوجيه سلوك النموذج. هذه الميزة تشبه "مقدّمة" تضعها قبل عرض النموذج على أي تعليمات أخرى من المستخدم النهائي.


تقديم ملاحظات حول تجربتك مع Vertex AI in Firebase