פלט מובנה

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

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

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

  • מודלים של 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. מורכבות יכולה לנבוע משמות מאפיינים ארוכים, ממגבלות אורך ארוכות של מערכים, מ-enums עם הרבה ערכים, מאובייקטים עם הרבה מאפיינים אופציונליים או משילוב של הגורמים האלה.

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

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

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

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

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

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

  • 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 Agent Platform תומך בערכים הבאים: date,‏ date-time,‏ duration ו-time. התיאור והפורמט של כל ערך מפורטים במאגר של Open API Initiative

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

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

צריך לכלול את סכימת התגובה רק כחלק מהשדה 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();
    }
  }
}