إنشاء نتائج منظَّمة باستخدام Gemini API


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

في ما يلي بعض حالات الاستخدام التي قد تتطلّب إخراجًا منظّمًا من النموذج:

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

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

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

مزيد من المعلومات عن مخطّطات JSON

عند ضبط النموذج لعرض استجابة JSON، يمكنك استخدام Schema كائن لتحديد شكل بيانات JSON. يمثّل العنصر Schema مجموعة فرعية محدّدة من عنصر مخطّط OpenAPI 3.0.

في ما يلي تمثيل اصطناعي لتنسيق JSON لجميع حقول Schema:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

يجب أن يكون Type للمخطّط أحد أنواع البيانات في OpenAPI. تكون مجموعة فرعية فقط من الحقول صالحة لكل Type. تربط القائمة التالية كل Type بحقول صالحة لهذا النوع:

  • string -> enum, format
  • integer -> التنسيق
  • number -> التنسيق
  • boolean
  • array -> minItems وmaxItems وitems
  • object -> properties, required, propertyOrdering, nullable

في ما يلي بعض الأمثلة على المخططات التي تعرض مجموعات صالحة من النوع والحقل:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

للحصول على مستندات كاملة لحقول المخطط كما يتم استخدامها في واجهة برمجة التطبيقات Gemini API، يُرجى الاطّلاع على مرجع المخطط.

ترتيب المواقع

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

لضمان ترتيب ثابت ومتوقّع للخصائص، يمكنك استخدام الحقل propertyOrdering[] الاختياري.

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[] – ليس حقلًا عاديًا في مواصفات OpenAPI – هو مصفوفة من السلاسل المستخدَمة لتحديد ترتيب السمات في الاستجابة. من خلال تحديد ترتيب المواقع، ثم تقديم أمثلة باستخدام المواقع بالترتيب نفسه، يمكنك تحسين جودة النتائج.