إنشاء نتائج منظَّمة باستخدام 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 مناسبًا.

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 cups chocolate chips"
    ]
  },
  ...
]

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

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

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

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

from google import genai
from pydantic import BaseModel


class Recipe(BaseModel):
  recipe_name: str
  ingredients: list[str]


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to include the amounts of ingredients.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

بنية تعريف المخطط

حدِّد مخطّط استجابة JSON في السمة response_schema من إعدادات النموذج. يجب أن تكون قيمة response_schema أيًّا مما يلي:

• نوع، كما تستخدمه في تعليق توضيحي للنوع. اطّلِع على وحدة typing في Python.
• مثيل genai.types.Schema
• dict المكافئ لـ genai.types.Schema

تحديد مخطّط باستخدام نوع

إنّ أسهل طريقة لتحديد مخطّط هي باستخدام نوع مباشر. في ما يلي المنهج الذي تم استخدامه في المثال السابق:

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

تتوافق مكتبة عملاء Gemini API Python مع المخططات المحدّدة باستخدام الأنواع التالية (حيث يكون AllowedType أي نوع مسموح به):

• int
• float
• bool
• str
• list[AllowedType]
• بالنسبة إلى الأنواع من النوع "مُهيَّكل":
  • dict[str, AllowedType]. يُفصح هذا التعليق التوضيحي عن أنّ جميع قيم القاموس من النوع نفسه، ولكنّه لا يحدّد المفاتيح التي يجب تضمينها.
  • نماذج Pydantic التي يحدّدها المستخدم يتيح لك هذا النهج تحديد أسماء المفاتيح وتحديد أنواع مختلفة للقيم المرتبطة بكل مفتاح، بما في ذلك الهياكل المُدمجة.

استخدام مصنّف للحد من المخرجات

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

على سبيل المثال، لنفترض أنّك تُطوّر تطبيقًا لتصنيف الآلات الموسيقية إلى إحدى الفئات الخمس التالية: "Percussion" أو "String" أو "Woodwind" أو "Brass" أو ""Keyboard"". يمكنك إنشاء مصنّف للمساعدة في هذه المهمة.

في المثال التالي، يتم تمرير فئة enum Instrument على أنّه response_schema، ومن المفترض أن يختار النموذج خيار enum الأنسب.

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

ستُترجم حزمة تطوير البرامج (SDK) لـ Python بيانات أنواع واجهة برمجة التطبيقات. ومع ذلك، تقبل واجهة برمجة التطبيقات مجموعة فرعية من مخطّط OpenAPI 3.0 (المخطّط). يمكنك أيضًا تمرير المخطّط بتنسيق JSON:

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

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

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip 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 -> التنسيق
• bool
• 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": "bool" }

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