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


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

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

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

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

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

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

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

قبل البدء

أكمِل دليل البدء لحِزم تطوير البرامج (SDK) "Vertex AI in Firebase"، إذا لم يسبق لك إجراء ذلك. تأكّد من القيام بكل ما يلي:

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

  2. ربط تطبيقك بمنصّة Firebase، بما في ذلك تسجيل تطبيقك وإضافة إعدادات Firebase إلى تطبيقك

  3. أضِف حزمة تطوير البرامج (SDK) وابدأ إعداد خدمة Vertex AI والنموذج التوليدي في تطبيقك.

بعد ربط تطبيقك بمنصّة Firebase وإضافة حزمة تطوير البرامج (SDK) وإعداد خدمة Vertex AI والنموذج التوليدي، سيكون بإمكانك استدعاء Gemini API.

الخطوة 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 1.5 Pro وGemini 1.5 Flash.

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

أمثلة إضافية

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

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

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

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

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

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

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


تقديم ملاحظات حول تجربتك في استخدام "Vertex AI in Firebase"