المُخرجات المنظَّمة

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

يُعدّ استخدام المُخرجات المنظَّمة مثاليًا لمجموعة كبيرة من التطبيقات:

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

بالإضافة إلى إتاحة استخدام JSON Schema في REST API، تسهّل حِزم تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي في Python وJavaScript عملية تحديد مخططات العناصر باستخدام Pydantic وZod على التوالي. يوضّح المثال أدناه كيفية استخراج المعلومات من نص غير منظَّم يتوافق مع مخطط محدّد في الرمز.

أداة استخراج الوصفات الإشراف على المحتوى البُنى المتكرّرة

البث

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

ستكون الأجزاء التي يتم بثها سلاسل JSON جزئية صالحة، ويمكن ربطها لتكوين عنصر JSON النهائي الكامل.

from google import genai
from pydantic import BaseModel, Field
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!"

response_stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Feedback.model_json_schema(),
    },
)

for chunk in response_stream:
    print(chunk.candidates[0].content.parts[0].text)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});
const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";

const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await ai.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(feedbackSchema),
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].text)
}

إتاحة مخطّط JSON

لإنشاء عنصر JSON، اضبط response_mime_type في إعدادات الإنشاء على application/json وقدِّم response_json_schema. يجب أن يكون المخطط مخطط JSON صالحًا يصف تنسيق الإخراج المطلوب.

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

يتوافق وضع الإخراج المنظَّم في Gemini مع مجموعة فرعية من مواصفات مخطط JSON.

يمكن استخدام القيم التالية لـ type:

• string: للنص
• number: للأرقام ذات الفاصلة العائمة
• integer: للأعداد الصحيحة
• ‫boolean: للقيم الصحيحة أو الخاطئة
• object: للبيانات المنظَّمة التي تتضمّن أزواجًا من المفاتيح والقيم
• array: لقوائم العناصر
• null: للسماح بأن تكون قيمة السمة فارغة، أدرِج "null" في مصفوفة النوع (مثلاً {"type": ["string", "null"]}).

تساعد هذه الخصائص الوصفية في توجيه النموذج:

• ‫title: وصف موجز للمكان المخصّص للاستئجار
• ‫description: وصف أطول وأكثر تفصيلاً للمكان المخصّص للاستئجار

السمات الخاصة بأنواع محدّدة

بالنسبة إلى قيم object:

• properties: عنصر يكون فيه كل مفتاح هو اسم خاصية وكل قيمة هي مخطط لتلك الخاصية.
• استبدِل بمصفوفة من السلاسل التي تسرد السمات الإلزامية.required
• ‫additionalProperties: يتحكّم هذا الإعداد في ما إذا كان مسموحًا باستخدام المواقع غير المدرَجة في properties. يمكن أن تكون قيمة منطقية أو مخططًا.

بالنسبة إلى قيم string:

• ‫enum: تعرض هذه السمة مجموعة محدّدة من السلاسل المحتملة لمهام التصنيف.
• format: تحدّد هذه السمة بنية السلسلة، مثل date-time أو date أو time.

بالنسبة إلى القيمتَين number وinteger:

• enum: تعرض مجموعة معيّنة من القيم الرقمية المحتملة.
• ‫minimum: تمثّل الحد الأدنى للقيمة الشاملة.
• ‫maximum: تمثّل الحدّ الأقصى للقيمة الشاملة.

بالنسبة إلى قيم array:

• ‫items: تحدّد هذه السمة المخطط لجميع العناصر في المصفوفة.
• prefixItems: تحدّد قائمة بمخططات أول N عناصر، ما يسمح بإنشاء بنى تشبه الصفوف.
• ‫minItems: الحد الأدنى لعدد العناصر في المصفوفة
• ‫maxItems: الحد الأقصى لعدد العناصر في المصفوفة

النماذج المتوافقة

تتيح النماذج التالية إخراج بيانات منظَّمة:

* يُرجى العِلم أنّ Gemini 2.0 يتطلّب قائمة propertyOrdering صريحة ضمن إدخال JSON لتحديد البنية المفضّلة. يمكنك العثور على مثال في كتاب الطبخ هذا.

المُخرجات المنظَّمة مقارنةً باستدعاء الدالة

تستخدم كل من النتائج المنظَّمة واستدعاء الدوال مخططات JSON، ولكنها تخدم أغراضًا مختلفة:

أفضل الممارسات

• أوصاف واضحة: استخدِم الحقل description في المخطط لتقديم تعليمات واضحة للنموذج حول ما تمثّله كل سمة. هذا أمر بالغ الأهمية لتوجيه ناتج النموذج.
• الكتابة القوية: استخدِم أنواعًا محدّدة (integer وstring وenum) كلما أمكن ذلك. إذا كانت إحدى المَعلمات تتضمّن مجموعة محدودة من القيم الصالحة، استخدِم enum.
• هندسة الطلبات: حدِّد بوضوح في طلبك ما تريد أن يفعله النموذج، مثل "استخرِج المعلومات التالية من النص..." أو "صنِّف هذه الملاحظات وفقًا للمخطط المقدَّم...".
• التحقّق من الصحة: على الرغم من أنّ الناتج المنظَّم يضمن أن يكون ملف JSON صحيحًا من الناحية النحوية، إلا أنّه لا يضمن أن تكون القيم صحيحة من الناحية الدلالية. يجب دائمًا التحقّق من صحة الناتج النهائي في رمز تطبيقك قبل استخدامه.
• التعامل مع الأخطاء: نفِّذ عملية معالجة قوية للأخطاء في تطبيقك لإدارة الحالات التي قد لا يستوفي فيها ناتج النموذج متطلبات منطق نشاطك التجاري، على الرغم من توافقه مع المخطط.

القيود

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