إنشاء مخرجات منظَّمة (مثل 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).

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

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

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

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

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

يتوفّر استخدام responseSchema في Gemini 1.5 Pro وGemini 1.5 Flash.

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

أمثلة إضافية

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

إنشاء قيم تعداد كإخراج

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

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

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

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

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


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