يمكنك ضبط نماذج Gemini لإنشاء ردود تتوافق مع مخطط JSON المقدَّم. تضمن هذه الإمكانية الحصول على نتائج يمكن توقّعها وتحليلها، وتضمن أمان التنسيق والنوع، وتتيح رصد الرفض آليًا، وتسهّل عملية تقديم الطلبات.
يُعدّ استخدام المُخرجات المنظَّمة مثاليًا لمجموعة كبيرة من التطبيقات:
- استخراج البيانات: استخراج معلومات معيّنة من نص غير منظَّم، مثل استخراج الأسماء والتواريخ والمبالغ من فاتورة
- التصنيف المنظَّم: تصنيف النص ضِمن فئات محدَّدة مسبقًا وتعيين تصنيفات منظَّمة، مثل تصنيف ملاحظات العملاء حسب المشاعر والموضوع
- سير العمل المستند إلى الوكلاء: إنشاء بيانات منظَّمة يمكن استخدامها لاستدعاء أدوات أو واجهات برمجة تطبيقات أخرى، مثل إنشاء ورقة شخصية للعبة أو ملء نموذج
بالإضافة إلى إتاحة استخدام JSON Schema في REST API، تسهّل حِزم تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي في Python وJavaScript عملية تحديد مخططات العناصر باستخدام Pydantic وZod على التوالي. يوضّح المثال أدناه كيفية استخراج المعلومات من نص غير منظَّم يتوافق مع مخطط محدّد في الرمز.
يوضّح هذا المثال كيفية استخراج البيانات المنظَّمة من النص باستخدام أنواع مخطط JSON الأساسية، مثل object وarray وstring وinteger.
Python
from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional
class Ingredient(BaseModel):
name: str = Field(description="Name of the ingredient.")
quantity: str = Field(description="Quantity of the ingredient, including units.")
class Recipe(BaseModel):
recipe_name: str = Field(description="The name of the recipe.")
prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
ingredients: List[Ingredient]
instructions: List[str]
client = genai.Client()
prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=prompt,
config={
"response_mime_type": "application/json",
"response_json_schema": Recipe.model_json_schema(),
},
)
recipe = Recipe.model_validate_json(response.text)
print(recipe)
JavaScript
import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
const ingredientSchema = z.object({
name: z.string().describe("Name of the ingredient."),
quantity: z.string().describe("Quantity of the ingredient, including units."),
});
const recipeSchema = z.object({
recipe_name: z.string().describe("The name of the recipe."),
prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
ingredients: z.array(ingredientSchema),
instructions: z.array(z.string()),
});
const ai = new GoogleGenAI({});
const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: prompt,
config: {
responseMimeType: "application/json",
responseJsonSchema: zodToJsonSchema(recipeSchema),
},
});
const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
prompt := `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`
config := &genai.GenerateContentConfig{
ResponseMIMEType: "application/json",
ResponseJsonSchema: map[string]any{
"type": "object",
"properties": map[string]any{
"recipe_name": map[string]any{
"type": "string",
"description": "The name of the recipe.",
},
"prep_time_minutes": map[string]any{
"type": "integer",
"description": "Optional time in minutes to prepare the recipe.",
},
"ingredients": map[string]any{
"type": "array",
"items": map[string]any{
"type": "object",
"properties": map[string]any{
"name": map[string]any{
"type": "string",
"description": "Name of the ingredient.",
},
"quantity": map[string]any{
"type": "string",
"description": "Quantity of the ingredient, including units.",
},
},
"required": []string{"name", "quantity"},
},
},
"instructions": map[string]any{
"type": "array",
"items": map[string]any{"type": "string"},
},
},
"required": []string{"recipe_name", "ingredients", "instructions"},
},
}
result, err := client.Models.GenerateContent(
ctx,
"gemini-2.5-flash",
genai.Text(prompt),
config,
)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text())
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{ "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." }
]
}],
"generationConfig": {
"responseMimeType": "application/json",
"responseJsonSchema": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the recipe."
},
"prep_time_minutes": {
"type": "integer",
"description": "Optional time in minutes to prepare the recipe."
},
"ingredients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Name of the ingredient."},
"quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
},
"required": ["name", "quantity"]
}
},
"instructions": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["recipe_name", "ingredients", "instructions"]
}
}
}'
مثال على الرد:
{
"recipe_name": "Delicious Chocolate Chip Cookies",
"ingredients": [
{
"name": "all-purpose flour",
"quantity": "2 and 1/4 cups"
},
{
"name": "baking soda",
"quantity": "1 teaspoon"
},
{
"name": "salt",
"quantity": "1 teaspoon"
},
{
"name": "unsalted butter (softened)",
"quantity": "1 cup"
},
{
"name": "granulated sugar",
"quantity": "3/4 cup"
},
{
"name": "packed brown sugar",
"quantity": "3/4 cup"
},
{
"name": "vanilla extract",
"quantity": "1 teaspoon"
},
{
"name": "large eggs",
"quantity": "2"
},
{
"name": "semisweet chocolate chips",
"quantity": "2 cups"
}
],
"instructions": [
"Preheat the oven to 375°F (190°C).",
"In a small bowl, whisk together the flour, baking soda, and salt.",
"In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
"Beat in the vanilla and eggs, one at a time.",
"Gradually beat in the dry ingredients until just combined.",
"Stir in the chocolate chips.",
"Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
]
}
البث
يمكنك بث النتائج المنظَّمة، ما يتيح لك بدء معالجة الردّ أثناء إنشائه، بدون الحاجة إلى الانتظار حتى يكتمل الناتج بالكامل. ويمكن أن يؤدي ذلك إلى تحسين الأداء المُدرَك لتطبيقك.
ستكون الأجزاء التي يتم بثها سلاسل JSON جزئية صالحة، ويمكن ربطها لتكوين عنصر JSON النهائي الكامل.
Python
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)
JavaScript
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.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️* |
| Gemini 2.0 Flash-Lite | ✔️* |
* يُرجى العِلم أنّ Gemini 2.0 يتطلّب قائمة propertyOrdering صريحة ضمن إدخال JSON لتحديد البنية المفضّلة. يمكنك العثور على مثال في كتاب الطبخ هذا.
المُخرجات المنظَّمة مقارنةً باستدعاء الدالة
تستخدم كل من النتائج المنظَّمة واستدعاء الدوال مخططات JSON، ولكنها تخدم أغراضًا مختلفة:
| الميزة | حالة الاستخدام الأساسية |
|---|---|
| المخرجات المنظَّمة | تنسيق الرد النهائي للمستخدم: استخدِم هذه الأداة عندما تريد أن يكون ردّ النموذج بتنسيق معيّن (مثل استخراج البيانات من مستند لحفظها في قاعدة بيانات). |
| استدعاء الدوال | اتّخاذ إجراء أثناء المحادثة استخدِم هذه الحالة عندما يحتاج النموذج إلى أن يطلب منك تنفيذ مهمة (مثلاً، "get current weather") قبل أن تتمكّن من تقديم إجابة نهائية. |
أفضل الممارسات
- أوصاف واضحة: استخدِم الحقل
descriptionفي المخطط لتقديم تعليمات واضحة للنموذج حول ما تمثّله كل سمة. هذا أمر بالغ الأهمية لتوجيه ناتج النموذج. - الكتابة القوية: استخدِم أنواعًا محدّدة (
integerوstringوenum) كلما أمكن ذلك. إذا كانت إحدى المَعلمات تتضمّن مجموعة محدودة من القيم الصالحة، استخدِمenum. - هندسة الطلبات: حدِّد بوضوح في طلبك ما تريد أن يفعله النموذج، مثل "استخرِج المعلومات التالية من النص..." أو "صنِّف هذه الملاحظات وفقًا للمخطط المقدَّم...".
- التحقّق من الصحة: على الرغم من أنّ الناتج المنظَّم يضمن أن يكون ملف JSON صحيحًا من الناحية النحوية، إلا أنّه لا يضمن أن تكون القيم صحيحة من الناحية الدلالية. يجب دائمًا التحقّق من صحة الناتج النهائي في رمز تطبيقك قبل استخدامه.
- التعامل مع الأخطاء: نفِّذ عملية معالجة قوية للأخطاء في تطبيقك لإدارة الحالات التي قد لا يستوفي فيها ناتج النموذج متطلبات منطق نشاطك التجاري، على الرغم من توافقه مع المخطط.
القيود
- مجموعة فرعية من المخطط: لا تتوافق بعض ميزات مواصفات JSON Schema. يتجاهل النموذج الخصائص غير المتوافقة.
- تعقيد المخطط: قد ترفض واجهة برمجة التطبيقات المخططات الكبيرة جدًا أو المتداخلة بشكل كبير. في حال مواجهة أخطاء، جرِّب تبسيط المخطط عن طريق تقصير أسماء السمات أو تقليل التداخل أو الحدّ من عدد القيود.