פלט מובנה

אתם יכולים להבטיח שהפלט שנוצר על ידי המודל תמיד יתאים לסכימה ספציפית, כדי שתקבלו תשובות בפורמט עקבי. לדוגמה, יכול להיות שיש לכם סכימת נתונים קיימת שאתם משתמשים בה למשימות אחרות. אם המודל פועל לפי אותה סכימה, אתם יכולים לחלץ נתונים ישירות מהפלט של המודל בלי עיבוד נוסף.

כדי לציין את המבנה של פלט המודל, מגדירים סכֵימת תשובה, שפועלת כמו תוכנית לתשובות של המודל. כששולחים הנחיה וכוללים את סכמת התשובה, התשובה של המודל תמיד תואמת לסכמה שהגדרתם.

אתם יכולים לשלוט בפלט שנוצר כשאתם משתמשים במודלים הבאים:

  • מודלים של Gemini:

לחצו כדי להרחיב את רשימת המודלים הנתמכים

במודלים פתוחים, פועלים לפי המדריך למשתמש הזה.

תרחישים לדוגמה

תרחיש לדוגמה שבו כדאי להחיל סכֵימת תשובה הוא כשרוצים לוודא שהתשובה של המודל יוצרת קובץ JSON תקין ותואמת לסכימה. הפלט מהמודל הגנרטיבי יכול להשתנות במידה מסוימת, ולכן הכללת סכֵימת תשובה מבטיחה שתמיד תקבלו קובץ JSON תקין. כתוצאה מכך, המשימות הבאות בתהליך יכולות לצפות לקבל קלט JSON תקין מהתשובות שנוצרו.

דוגמה נוספת היא הגבלת האופן שבו המודל יכול להגיב. לדוגמה, אפשר להשתמש במודל כדי להוסיף הערות לטקסט עם תוויות שהמשתמש מגדיר, ולא עם תוויות שהמודל מייצר. האילוץ הזה שימושי כשמצפים לקבל קבוצה ספציפית של תוויות, כמו positive או negative, ולא רוצים לקבל שילוב של תוויות אחרות שהמודל עשוי ליצור, כמו good, positive, negative או bad.

לתשומת ליבכם

אם אתם מתכננים להשתמש בסכמת תשובה, כדאי להביא בחשבון את המגבלות הפוטנציאליות הבאות:

  • כדי להגדיר סכֵימת תשובה ולהשתמש בה, צריך להשתמש ב-API. אין תמיכה בקונסולות.
  • הגודל של סכמת התשובה נכלל במגבלת הטוקנים של הקלט.

  • יש תמיכה רק בפורמטים מסוימים של פלט, כמו application/json או text/x.enum. לגבי פלט JSON:

    • אם מגדירים את response_mime_type ל-application/json בלי לציין response_schema, זה משמש רק כרמז חזק ויש סיכון קטן ליצירת JSON בפורמט שגוי.
    • כדי לוודא שאובייקטים של JSON תקינים ב-100%, הבקשות חייבות לכלול גם response_schema וגם response_mime_type שמוגדרים ל-application/json.
    • כשיטה מומלצת, אם תרחיש השימוש שלכם מונע מכם להגדיר מראש סכימה, כדאי להטמיע מאמת JSON בצד הלקוח עם מנגנון ניסיון חוזר.

  • פלט מובנה תומך בקבוצת משנה של הסכימה של Agent Platform. מידע נוסף זמין במאמר שדות סכימה נתמכים.

  • סכימה מורכבת עלולה לגרום לשגיאת InvalidArgument: 400. המורכבות יכולה לנבוע משמות ארוכים של מאפיינים, מגבלות ארוכות על אורך המערך, ערכים מספריים עם הרבה ערכים, אובייקטים עם הרבה מאפיינים אופציונליים או שילוב של הגורמים האלה.

    אם קיבלתם את השגיאה הזו עם סכימה תקינה, נסו לבצע אחד או יותר מהשינויים הבאים כדי לפתור את השגיאה:

    • מקצרים את שמות המאפיינים או שמות ה-enum.
    • השטחת מערכים בתוך מערכים.
    • צמצמו את מספר המאפיינים עם מגבלות, כמו מספרים עם מגבלות מינימום ומקסימום.
    • צמצמו את מספר המאפיינים עם אילוצים מורכבים, כמו מאפיינים עם פורמטים מורכבים כמו date-time.
    • צמצמו את מספר המאפיינים האופציונליים.
    • צריך לצמצם את מספר הערכים התקינים של מאפייני enum.

שדות סכימה נתמכים

אפשר לציין response_schema שמתאר את פורמט הפלט.

המודל ייצור תשובה שתואמת לסכימה שצוינה. כשמשתמשים בפלט מובנה, המודל יוצר פלט באותו סדר כמו המפתחות בסכימה.

  • השדות הבאים מסכימת Agent Platform נתמכים. אם תשתמשו בשדה לא נתמך, פלטפורמת Gemini Enterprise Agent עדיין תוכל לטפל בבקשה, אבל תתעלם מהשדה.

  • anyOf

  • ‫enum: רק ערכי enum מסוג string נתמכים

  • format

  • items

  • maximum

  • maxItems

  • minimum

  • minItems

  • nullable

  • properties

  • description

  • propertyOrdering*

  • required

* propertyOrdering מיועד ספציפית לפלט מובנה, והוא לא חלק מהסכימה של Agent Platform. השדה הזה מגדיר את הסדר שבו הנכסים נוצרים. המאפיינים שברשימה חייבים להיות ייחודיים וחייבים להיות מפתחות חוקיים במילון properties.

כשמגדירים סכימה, המודל לא פועל בדיוק לפי סדר המאפיינים שמוגדר בשדה properties. כדי לאכוף סדר ספציפי ליצירת נכסים, משתמשים בשדה propertyOrdering. המאפיינים שמופיעים ב-propertyOrdering נוצרים קודם, בסדר שצוין, ואחריהם נוצרים כל המאפיינים האחרים.

אם אתם משתמשים ב-Python SDK, סדר ברירת המחדל של המאפיינים הוא לפי הסדר שמוגדר בסכימה. בכל שאר המקרים, המאפיינים נוצרים בסדר אלפביתי, כשהמאפיינים הנדרשים מקובצים קודם ואחריהם המאפיינים האופציונליים.

בשדה format, פלטפורמת הסוכנים של Gemini Enterprise תומכת בערכים הבאים: date,‏ date-time,‏ duration ו-time. התיאור והפורמט של כל ערך מתוארים ב-OpenAPI Initiative Registry

לפני שמתחילים

מגדירים סכֵימת תשובה כדי לציין את מבנה הפלט של המודל, את שמות השדות ואת סוג הנתונים הצפוי בכל שדה. השתמשו רק בשדות הנתמכים שמפורטים בקטע שיקולים. המערכת תתעלם מכל שאר השדות.

כוללים את סכמת התשובה רק כחלק מהשדה responseSchema. אל תשכפלו את הסכימה בהנחיית הקלט. אם תעשו את זה, יכול להיות שהפלט שייווצר יהיה באיכות נמוכה יותר.

בקטע סכמות לדוגמה ותשובות של מודלים יש דוגמאות לסכמות.

התנהגות המודל וסכֵימת התשובה

כשהמודל יוצר תשובה, הוא משתמש בשם השדה ובתיאור מהסכימה שסופקה. לכן, מומלץ להשתמש במבנה ברור ובשמות שדות חד-משמעיים כדי שהכוונה שלכם תהיה ברורה. מומלץ להשתמש בשדה description בתוך מאפייני הסכימה כדי להגדיר את המטרה של כל שדה.

כברירת מחדל, השדות הם אופציונליים, כלומר המודל יכול לאכלס את השדות או לדלג עליהם. אתם יכולים להגדיר שדות כחובה כדי לאלץ את המודל לספק ערך. אם אין מספיק הקשר בהנחיית הקלט המשויכת, המודל יוצר תשובות שמבוססות בעיקר על הנתונים ששימשו לאימון שלו.

אם אתם לא רואים את התוצאות שאתם מצפים להן, התחילו בשינוי התיאורים בסכימה. אם אתם מרגישים שאתם לא יכולים לתאר את כל הניואנסים של הסכימה בתיאור הסכימה, אתם יכולים לדון בסכימה בהנחיה, אבל חשוב:

  1. צריך לציין את הסכימה רק באובייקט הסכימה. אל תציינו את הסכימה גם בהנחיה. אם תפעילו את שתי האפשרויות, הביצועים עלולים להיפגע.

  2. אל תתייחסו לסכימה בהנחיה (מעבר ל "פעלו לפי הסכימה שסופקה" או משהו דומה), אלא אם זה הכרחי. כך קל יותר לתחזק את הקוד. אם תצטרכו לשנות את הסכימה, תוכלו פשוט לשנות אותה במקום לוודא שגם ההנחיה וגם הסכימה מעודכנות כמו שצריך.

  3. אם אתם חייבים לדון בסכימה בהנחיה (כדי לספק דוגמאות או הוראות מפורטות במיוחד, שאחרת יובילו לערכי description מבלבלים בסכימה), הקפידו לפעול לפי סדר השדות exact שמופיע בסכימה שסופקה. אם סדר השדות בסכימה שסופקה שונה מהסדר בהנחיה, עלולות להתרחש שגיאות בפלט.

שליחת הנחיה עם סכֵימת תשובה

כברירת מחדל, כל השדות הם אופציונליים, כלומר המודל יכול ליצור תשובה לשדה. כדי לאלץ את המודל ליצור תמיד תשובה לשדה, מגדירים את השדה כחובה.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import HttpOptions

response_schema = {
    "type": "ARRAY",
    "items": {
        "type": "OBJECT",
        "properties": {
            "recipe_name": {"type": "STRING"},
            "ingredients": {"type": "ARRAY", "items": {"type": "STRING"}},
        },
        "required": ["recipe_name", "ingredients"],
    },
}

prompt = """
    List a few popular cookie recipes.
"""

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_schema": response_schema,
    },
)

print(response.text)
# Example output:
# [
#     {
#         "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",
#         ],
#         "recipe_name": "Chocolate Chip Cookies",
#     }
# ]

Go

איך מתקינים או מעדכנים את Go

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithRespSchema shows how to use a response schema to generate output in a specific format.
func generateWithRespSchema(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "application/json",
		// See the OpenAPI specification for more details and examples:
		//   https://spec.openapis.org/oas/v3.0.3.html#schema-object
		ResponseSchema: &genai.Schema{
			Type: "array",
			Items: &genai.Schema{
				Type: "object",
				Properties: map[string]*genai.Schema{
					"recipe_name": {Type: "string"},
					"ingredients": {
						Type:  "array",
						Items: &genai.Schema{Type: "string"},
					},
				},
				Required: []string{"recipe_name", "ingredients"},
			},
		},
	}
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "List a few popular cookie recipes."},
		},
			Role: genai.RoleUser},
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// [
	//   {
	//     "ingredients": [
	//       "2 1/4 cups all-purpose flour",
	//       "1 teaspoon baking soda",
	//       ...
	//     ],
	//     "recipe_name": "Chocolate Chip Cookies"
	//   },
	//   {
	//     ...
	//   },
	//   ...
	// ]

	return nil
}

Node.js

התקנה

npm install @google/genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateResponseSchema(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const prompt = 'List a few popular cookie recipes.';

  const responseSchema = {
    type: 'ARRAY',
    items: {
      type: 'OBJECT',
      properties: {
        recipeName: {type: 'STRING'},
        ingredients: {
          type: 'ARRAY',
          items: {type: 'STRING'},
        },
      },
      required: ['recipeName', 'ingredients'],
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      responseMimeType: 'application/json',
      responseSchema: responseSchema,
    },
  });

  console.log(response.text);

  // Example output:
  // [
  //     {
  //         "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",
  //         ],
  //         "recipe_name": "Chocolate Chip Cookies",
  //     }
  // ]

  return response.text;
}

Java

איך מתקינים או מעדכנים את Java

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.List;
import java.util.Map;

public class ControlledGenerationWithResponseSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";

    String contents = "List a few popular cookie recipes.";

    generateContent(modelId, contents);
  }

  // Generates content with a response schema
  public static String generateContent(String modelId, String contents) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Schema for each item in array
      Schema recipeSchema =
          Schema.builder()
              .type(Type.Known.OBJECT)
              .properties(
                  Map.of(
                      "recipe_name", Schema.builder().type(Type.Known.STRING).build(),
                      "ingredients",
                          Schema.builder()
                              .type(Type.Known.ARRAY)
                              .items(Schema.builder().type(Type.Known.STRING).build())
                              .build()))
              .required(List.of("recipe_name", "ingredients"))
              .build();

      // Full root schema (array)
      Schema responseSchema = Schema.builder().type(Type.Known.ARRAY).items(recipeSchema).build();

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .responseMimeType("application/json")
              .responseSchema(responseSchema)
              .build();

      GenerateContentResponse response = client.models.generateContent(modelId, contents, config);

      System.out.println(response.text());
      // Example response:
      // [
      //    {
      //        "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",
      //        ],
      //        "recipe_name": "Chocolate Chip Cookies",
      //    }
      // ]
      return response.text();
    }
  }
}

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫GENERATE_RESPONSE_METHOD: סוג התשובה שרוצים שהמודל ייצור. בוחרים שיטה שקובעת איך התשובה של המודל תוחזר:
    • ‫streamGenerateContent: התשובה מועברת בסטרימינג בזמן שהיא נוצרת, כדי שהמשתמשים לא ירגישו את זמן האחזור.
    • ‫generateContent: התשובה מוחזרת אחרי שהיא נוצרת במלואה.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫PROJECT_ID: מזהה הפרויקט. .
  • ‫MODEL_ID: מזהה המודל של המודל המולטי-מודאלי שבו רוצים להשתמש.
  • ROLE: התפקיד בשיחה שמשויך לתוכן. חובה לציין תפקיד גם בתרחישי שימוש של פנייה אחת. הערכים הקבילים כוללים:
    • USER: מציין תוכן שאתם שלחתם.
  • TEXT: ההוראות בטקסט שצריך לכלול בהנחיה.
  • ‫RESPONSE_MIME_TYPE: סוג הפורמט של הטקסט שנוצר. רשימה של הערכים הנתמכים מופיעה בפרמטר responseMimeType ב-Gemini API.
  • ‫RESPONSE_SCHEMA: הסכימה שלפיה המודל צריך לפעול כשהוא יוצר תשובות. מומלץ להשתמש בשדה description כדי לתאר את מטרת הסכימה ואת המאפיינים שלה. מידע נוסף זמין במאמרי העזרה בנושא סכימה.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD

גוף בקשת JSON: 

{
  "contents": {
    "role": "ROLE",
    "parts": {
      "text": "TEXT"
    }
  },
  "generation_config": {
    "responseMimeType": "RESPONSE_MIME_TYPE",
    "responseSchema": RESPONSE_SCHEMA,
  }
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

דוגמה לפקודת curl

LOCATION="us-central1"
MODEL_ID="gemini-3.5-flash"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"

cat << EOF > request.json
{
  "contents": {
    "role": "user",
    "parts": {
      "text": "List a few popular cookie recipes."
    }
  },
  "generation_config": {
    "maxOutputTokens": 2048,
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "recipe_name": {
            "type": "string",
            "description": "The name of the cookie recipe."
          },
        },
        "required": ["recipe_name"],
      },
    }
  }
}
EOF

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} \
-d '@request.json'

סכימות לדוגמה לפלט JSON

בקטעים הבאים מוצגות מגוון דוגמאות להנחיות ולסכמות תשובה. אחרי כל דוגמת קוד יש גם דוגמה לתשובה מהמודל.

תחזית מזג האוויר לכל יום בשבוע

בדוגמה הבאה, הפלט הוא אובייקט forecast לכל יום בשבוע, שכולל מערך של מאפיינים כמו הטמפרטורה ורמת הלחות הצפויות לאותו יום. חלק מהמאפיינים מוגדרים כ-nullable, כדי שהמודל יוכל להחזיר ערך null כשאין לו מספיק הקשר ליצירת תשובה משמעותית. האסטרטגיה הזו עוזרת לצמצם הזיות.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

response_schema = {
    "type": "OBJECT",
    "properties": {
        "forecast": {
            "type": "ARRAY",
            "items": {
                "type": "OBJECT",
                "properties": {
                    "Day": {"type": "STRING", "nullable": True},
                    "Forecast": {"type": "STRING", "nullable": True},
                    "Temperature": {"type": "INTEGER", "nullable": True},
                    "Humidity": {"type": "STRING", "nullable": True},
                    "Wind Speed": {"type": "INTEGER", "nullable": True},
                },
                "required": ["Day", "Temperature", "Forecast", "Wind Speed"],
            },
        }
    },
}

prompt = """
    The week ahead brings a mix of weather conditions.
    Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
    Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
    Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
    Wednesday may see thunderstorms, with a temperature of 68°F.
    Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
    Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
    Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
"""

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config=GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=response_schema,
    ),
)

print(response.text)
# Example output:
# {"forecast": [{"Day": "Sunday", "Forecast": "sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
#   {"Day": "Monday", "Forecast": "partly cloudy", "Temperature": 72, "Wind Speed": 15},
#   {"Day": "Tuesday", "Forecast": "rain showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
#   {"Day": "Wednesday", "Forecast": "thunderstorms", "Temperature": 68, "Wind Speed": null},
#   {"Day": "Thursday", "Forecast": "cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
#   {"Day": "Friday", "Forecast": "partly cloudy", "Temperature": 73, "Wind Speed": 12},
#   {"Day": "Saturday", "Forecast": "sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}]}

Go

איך מתקינים או מעדכנים את Go

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithNullables shows how to use the response schema with nullable values.
func generateWithNullables(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	prompt := `
The week ahead brings a mix of weather conditions.
Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
Wednesday may see thunderstorms, with a temperature of 68°F.
Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
`
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "application/json",
		// See the OpenAPI specification for more details and examples:
		//   https://spec.openapis.org/oas/v3.0.3.html#schema-object
		ResponseSchema: &genai.Schema{
			Type: "object",
			Properties: map[string]*genai.Schema{
				"forecast": {
					Type: "array",
					Items: &genai.Schema{
						Type: "object",
						Properties: map[string]*genai.Schema{
							"Day":         {Type: "string", Nullable: genai.Ptr(true)},
							"Forecast":    {Type: "string", Nullable: genai.Ptr(true)},
							"Temperature": {Type: "integer", Nullable: genai.Ptr(true)},
							"Humidity":    {Type: "string", Nullable: genai.Ptr(true)},
							"Wind Speed":  {Type: "integer", Nullable: genai.Ptr(true)},
						},
						Required: []string{"Day", "Temperature", "Forecast", "Wind Speed"},
					},
				},
			},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// {
	// 	"forecast": [
	// 		{"Day": "Sunday", "Forecast": "Sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
	// 		{"Day": "Monday", "Forecast": "Partly Cloudy", "Temperature": 72, "Wind Speed": 15},
	// 		{"Day": "Tuesday", "Forecast": "Rain Showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
	// 		{"Day": "Wednesday", "Forecast": "Thunderstorms", "Temperature": 68, "Wind Speed": null},
	// 		{"Day": "Thursday", "Forecast": "Cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
	// 		{"Day": "Friday", "Forecast": "Partly Cloudy", "Temperature": 73, "Wind Speed": 12},
	// 		{"Day": "Saturday", "Forecast": "Sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}
	// 	]
	// }

	return nil
}

Node.js

התקנה

npm install @google/genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateNullableSchema(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const prompt = `
  The week ahead brings a mix of weather conditions.
  Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
  Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
  Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
  Wednesday may see thunderstorms, with a temperature of 68°F.
  Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
  Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
  Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
`;

  const responseSchema = {
    type: 'object',
    properties: {
      forecast: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            Day: {type: 'string', nullable: true},
            Forecast: {type: 'string', nullable: true},
            Temperature: {type: 'integer', nullable: true},
            Humidity: {type: 'string', nullable: true},
            WindSpeed: {type: 'integer', nullable: true},
          },
          required: ['Day', 'Temperature', 'Forecast', 'WindSpeed'],
        },
      },
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      responseMimeType: 'application/json',
      responseSchema: responseSchema,
    },
  });
  console.log(response.text);

  // Example output:
  //  {"forecast": [{"Day": "Sunday", "Forecast": "sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
  //   {"Day": "Monday", "Forecast": "partly cloudy", "Temperature": 72, "Wind Speed": 15},
  //   {"Day": "Tuesday", "Forecast": "rain showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
  //   {"Day": "Wednesday", "Forecast": "thunderstorms", "Temperature": 68, "Wind Speed": null},
  //   {"Day": "Thursday", "Forecast": "cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
  //   {"Day": "Friday", "Forecast": "partly cloudy", "Temperature": 73, "Wind Speed": 12},
  //   {"Day": "Saturday", "Forecast": "sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}]}

  return response.text;
}

Java

איך מתקינים או מעדכנים את Java

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.List;
import java.util.Map;

public class ControlledGenerationWithNullableSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";

    String prompt =
        "The week ahead brings a mix of weather conditions.\n"
            + "Sunday is expected to be sunny with a temperature "
            + "of 77°F and a humidity level of 50%. "
            + "Winds will be light at around 10 km/h.\n"
            + "Monday will see partly cloudy skies with "
            + "a slightly cooler temperature of 72°F and the winds "
            + "will pick up slightly to around 15 km/h.\n"
            + "Tuesday brings rain showers, with temperatures dropping "
            + "to 64°F and humidity rising to 70%.\n"
            + "Wednesday may see thunderstorms, with a temperature of 68°F.\n"
            + "Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.\n"
            + "Friday returns to partly cloudy conditions, with "
            + "a temperature of 73°F and the Winds will be "
            + "light at 12 km/h.\n"
            + "Finally, Saturday rounds off the week with sunny skies, a "
            + "temperature of 80°F, and a humidity "
            + "level of 40%. Winds will be gentle at 8 km/h.\n";

    generateContent(modelId, prompt);
  }

  // Generates content with a nullable response schema
  public static String generateContent(String modelId, String contents) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Define schema for array items (each weather entry object)
      Schema dayForecastSchema =
          Schema.builder()
              .type(Type.Known.OBJECT)
              .properties(
                  Map.of(
                      "Day", Schema.builder().type(Type.Known.STRING).nullable(true).build(),
                      "Forecast", Schema.builder().type(Type.Known.STRING).nullable(true).build(),
                      "Temperature",
                          Schema.builder().type(Type.Known.INTEGER).nullable(true).build(),
                      "Humidity", Schema.builder().type(Type.Known.STRING).nullable(true).build(),
                      "Wind Speed",
                          Schema.builder().type(Type.Known.INTEGER).nullable(true).build()))
              .required(List.of("Day", "Temperature", "Forecast", "Wind Speed"))
              .build();

      // Full response schema
      Schema responseSchema =
          Schema.builder()
              .type(Type.Known.OBJECT)
              .properties(
                  Map.of(
                      "forecast",
                      Schema.builder().type(Type.Known.ARRAY).items(dayForecastSchema).build()))
              .build();

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .responseMimeType("application/json")
              .responseSchema(responseSchema)
              .build();

      GenerateContentResponse response = client.models.generateContent(modelId, contents, config);

      System.out.println(response.text());
      // Example response:
      // {"forecast": [{"Day": "Sunday", "Forecast": "sunny", "Temperature": 77, "Wind Speed": 10,
      // "Humidity": "50%"},
      //  {"Day": "Monday", "Forecast": "partly cloudy", "Temperature": 72, "Wind Speed": 15},
      //  {"Day": "Tuesday", "Forecast": "rain showers", "Temperature": 64, "Wind Speed": null,
      // "Humidity": "70%"},
      //  {"Day": "Wednesday", "Forecast": "thunderstorms", "Temperature": 68, "Wind Speed": null},
      //  {"Day": "Thursday", "Forecast": "cloudy", "Temperature": 66, "Wind Speed": null,
      // "Humidity": "60%"},
      //  {"Day": "Friday", "Forecast": "partly cloudy", "Temperature": 73, "Wind Speed": 12},
      //  {"Day": "Saturday", "Forecast": "sunny", "Temperature": 80, "Wind Speed": 8, "Humidity":
      // "40%"}]}
      return response.text();
    }
  }
}

סיווג מוצר

בדוגמה הבאה יש ערכים מסוג enum, שבהם המודל צריך לסווג את הסוג והמצב של אובייקט מתוך רשימה של ערכים נתונים.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

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

print(response.text)
# Example output:
# Woodwind

Go

איך מתקינים או מעדכנים את Go

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithEnumSchema shows how to use enum schema to generate output.
func generateWithEnumSchema(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What type of instrument is an oboe?"},
		}, Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "text/x.enum",
		ResponseSchema: &genai.Schema{
			Type: "STRING",
			Enum: []string{"Percussion", "String", "Woodwind", "Brass", "Keyboard"},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// Woodwind

	return nil
}

Node.js

התקנה

npm install @google/genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

const {GoogleGenAI, Type} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const responseSchema = {
    type: Type.STRING,
    enum: ['Percussion', 'String', 'Woodwind', 'Brass', 'Keyboard'],
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'What type of instrument is an oboe?',
    config: {
      responseMimeType: 'text/x.enum',
      responseSchema: responseSchema,
    },
  });

  console.log(response.text);
  // Example output:
  //  Woodwind
  return response.text;
}

Java

איך מתקינים או מעדכנים את Java

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.List;

public class ControlledGenerationWithEnumSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String contents = "What type of instrument is an oboe?";
    String modelId = "gemini-2.5-flash";
    generateContent(modelId, contents);
  }

  // Generates content with an enum response schema
  public static String generateContent(String modelId, String contents) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Define the response schema with an enum.
      Schema responseSchema =
          Schema.builder()
              .type(Type.Known.STRING)
              .enum_(List.of("Percussion", "String", "Woodwind", "Brass", "Keyboard"))
              .build();

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .responseMimeType("text/x.enum")
              .responseSchema(responseSchema)
              .build();

      GenerateContentResponse response = client.models.generateContent(modelId, contents, config);

      System.out.print(response.text());
      // Example response:
      // Woodwind
      return response.text();
    }
  }
}