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

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

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

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

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

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

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

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

خيارات أخرى للعمل مع Gemini API

• يمكنك تجربة إصدار "Google AI" بديل من Gemini API
  الحصول على إذن وصول مجاني (ضمن الحدود المتاحة) باستخدام Google AI Studio و Google AI حِزم تطوير برامج (SDK) للعملاء. يجب استخدام حِزم تطوير البرامج (SDK) هذه لإنشاء النماذج الأولية فقط في تطبيقات الويب والتطبيقات المتوافقة مع الأجهزة الجوّالة.

  بعد التعرّف على طريقة عمل Gemini API، يمكنك نقل بياناتك إلى حِزم Vertex AI in Firebase SDK (هذه المستندات)، التي تتضمّن العديد من الميزات الإضافية المهمة للتطبيقات المتوافقة مع الأجهزة الجوّالة والويب، مثل حماية واجهة برمجة التطبيقات من إساءة الاستخدام باستخدام Firebase App Check ودعم ملفات الوسائط الكبيرة في الطلبات.

• يمكنك اختياريًا استدعاء Vertex AI Gemini API من جهة الخادم (مثل استخدام Python أو Node.js أو Go)
  استخدِم حِزم تطوير البرامج (SDK) من جهة الخادم لVertex AI أو Firebase Genkit أو Firebase Extensions لGemini API.

قبل البدء

يُرجى إكمال دليل بدء استخدام حِزم تطوير البرامج (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