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

Python Node.js Go Dart (Flutter) Android Swift Web REST

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

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

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

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

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

قبل البدء: إعداد مشروعك ومفتاح واجهة برمجة التطبيقات

قبل طلب Gemini API، عليك إعداد مشروعك وضبط مفتاح واجهة برمجة التطبيقات.

إنشاء JSON

عند ضبط النموذج لإخراج تنسيق JSON، يستجيب لأي طلب باستخدام مخرج بتنسيق JSON.

يمكنك التحكّم في بنية استجابة JSON من خلال تقديم مخطّط. هناك طريقتان لتقديم مخطّط للنموذج:

• كنص في الطلب
• كمخطّط منظَّم يتم توفيره من خلال إعدادات النموذج

تقديم مخطّط كنص في الطلب

يطلب المثال التالي من النموذج عرض وصفات ملفات تعريف الارتباط بتنسيق JSON محدّد.

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

قد تبدو النتيجة على النحو التالي:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

تقديم مخطّط من خلال إعداد النموذج

ينفِّذ المثال التالي ما يلي:

1. تنشئ مثيلًا لنموذج تم ضبطه من خلال مخطّط للردّ باستخدام تنسيق JSON.
2. يطلب من النموذج عرض وصفات ملفات تعريف الارتباط.

تمنحك هذه الطريقة الأكثر رسمية لتعريف مخطّط JSON مزيدًا من التحكّم العميق مقارنةً بالاعتماد على النص في الطلب فقط.

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

قد تبدو النتيجة على النحو التالي:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

مزيد من المعلومات عن مخطّطات 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 – هو مصفوفة من السلاسل المستخدَمة لتحديد ترتيب السمات في الاستجابة. من خلال تحديد ترتيب المواقع، ثم تقديم أمثلة باستخدام المواقع بالترتيب نفسه، يمكنك تحسين جودة النتائج.