Yapılandırılmış Çıkışlar

Gemini modellerini, sağlanan bir JSON şemasına uygun yanıtlar oluşturacak şekilde yapılandırabilirsiniz. Bu özellik, tahmin edilebilir ve ayrıştırılabilir sonuçlar sunar, biçim ve tür güvenliğini sağlar, retlerin programatik olarak tespit edilmesini sağlar ve istem oluşturmayı kolaylaştırır.

Yapılandırılmış çıkışlar, çok çeşitli uygulamalar için idealdir:

  • Veri ayıklama: Yapılandırılmamış metinlerden belirli bilgileri çekme (ör. bir faturadan adları, tarihleri ve tutarları ayıklama).
  • Yapılandırılmış sınıflandırma: Metni önceden tanımlanmış kategorilere göre sınıflandırın ve yapılandırılmış etiketler atayın (ör. müşteri geri bildirimlerini duygu ve konuya göre kategorize edin).
  • Ajanlı iş akışları: Bir oyun için karakter sayfası oluşturma veya form doldurma gibi diğer araçları ya da API'leri çağırmak için kullanılabilecek yapılandırılmış veriler oluşturun.

REST API'de JSON şemasını desteklemenin yanı sıra Python ve JavaScript için Google GenAI SDK'ları, sırasıyla Pydantic ve Zod kullanarak nesne şemalarını tanımlamayı da kolaylaştırır. Aşağıdaki örnekte, kodda tanımlanan bir şemaya uygun yapılandırılmamış metinden bilgilerin nasıl ayıklanacağı gösterilmektedir.

Bu örnekte, object, array, string ve integer gibi temel JSON şema türlerini kullanarak metinden yapılandırılmış verilerin nasıl ayıklanacağı gösterilmektedir.

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"]
        }
      }
    }'

Örnek Yanıt:

{
  "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."
  ]
}

Canlı Yayın

Yapılandırılmış çıktıları yayınlayabilirsiniz. Bu sayede, yanıtın tamamlanmasını beklemeden oluşturulma sürecinde işlemeye başlayabilirsiniz. Bu, uygulamanızın algılanan performansını artırabilir.

Yayınlanan parçalar, son ve eksiksiz JSON nesnesini oluşturmak için birleştirilebilen geçerli kısmi JSON dizeleri olur.

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 şema desteği

JSON nesnesi oluşturmak için oluşturma yapılandırmasında response_mime_type değerini application/json olarak ayarlayın ve response_json_schema sağlayın. Şema, istenen çıkış biçimini açıklayan geçerli bir JSON şeması olmalıdır.

Ardından model, sağlanan şemayla eşleşen ve söz dizimi açısından geçerli bir JSON dizesi olan bir yanıt oluşturur. Yapılandırılmış çıkışlar kullanılırken model, çıkışları şemadaki anahtarlarla aynı sırada üretir.

Gemini'ın yapılandırılmış çıkış modu, JSON şeması spesifikasyonunun bir alt kümesini destekler.

type için aşağıdaki değerler desteklenir:

  • string: Metin için.
  • number: Kayan noktalı sayılar için.
  • integer: Tam sayılar için.
  • boolean: Doğru/yanlış değerleri için.
  • object: Anahtar/değer çiftleri içeren yapılandırılmış veriler için.
  • array: Öğe listeleri için.
  • null: Bir özelliğin null olmasına izin vermek için tür dizisine "null" ekleyin (ör. {"type": ["string", "null"]}).

Bu açıklayıcı özellikler, modele yol göstermeye yardımcı olur:

  • title: Bir mülkün kısa açıklaması.
  • description: Bir mülkün daha uzun ve ayrıntılı açıklaması.

Türe özel özellikler

object değerleri için:

  • properties: Her anahtarın bir özellik adı, her değerin ise söz konusu özelliğin şeması olduğu bir nesne.
  • required: Hangi özelliklerin zorunlu olduğunu listeleyen bir dize dizisi.
  • additionalProperties: properties içinde listelenmeyen özelliklere izin verilip verilmeyeceğini kontrol eder. Boole veya şema olabilir.

string değerleri için:

  • enum: Sınıflandırma görevleri için olası dizelerin belirli bir kümesini listeler.
  • format: Dize için date-time, date, time gibi bir söz dizimi belirtir.

number ve integer değerleri için:

  • enum: Olası sayısal değerlerden oluşan belirli bir grubu listeler.
  • minimum: Minimum dahil edilen değer.
  • maximum: Maksimum dahil değer.

array değerleri için:

  • items: Dizideki tüm öğelerin şemasını tanımlar.
  • prefixItems: İlk N öğe için bir şema listesi tanımlar ve demet benzeri yapılara izin verir.
  • minItems: Dizideki minimum öğe sayısı.
  • maxItems: Dizideki maksimum öğe sayısı.

Model desteği

Aşağıdaki modeller yapılandırılmış çıkışı destekler:

Model Yapılandırılmış Çıkışlar
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'ın, tercih edilen yapıyı tanımlamak için JSON girişinde açık bir propertyOrdering listesi gerektirdiğini unutmayın. Örneği bu çözüm kitabında bulabilirsiniz.

Yapılandırılmış çıkışlar ve işlev çağırma

Hem yapılandırılmış çıkışlar hem de işlev çağrıları JSON şemalarını kullanır ancak farklı amaçlara hizmet eder:

Özellik Birincil Kullanım Alanı
Yapılandırılmış Çıkışlar Kullanıcıya verilen son yanıtı biçimlendirme. Modelin yanıtının belirli bir biçimde olmasını istediğinizde (ör. bir belgeden veri ayıklayıp veritabanına kaydetme) bu işlevi kullanın.
İşlev Çağırma Sohbet sırasında işlem yapma Modelin bir görevi gerçekleştirmenizi istediği durumlarda (ör. "get current weather") komutunu çalıştırması gerekir.

En iyi uygulamalar

  • Net açıklamalar: Her özelliğin neyi temsil ettiği konusunda modele net talimatlar vermek için şemanızdaki description alanını kullanın. Bu, modelin çıkışını yönlendirmek için çok önemlidir.
  • Güçlü tür belirleme: Mümkün olduğunda belirli türleri (integer, string, enum) kullanın. Bir parametrenin geçerli değerleri sınırlıysa enum kullanın.
  • İstem mühendisliği: İsteminizde modelin ne yapmasını istediğinizi net bir şekilde belirtin. Örneğin, "Metinden aşağıdaki bilgileri ayıkla..." veya "Bu geri bildirimi sağlanan şemaya göre sınıflandır...".
  • Doğrulama: Yapılandırılmış çıkış, söz dizimi açısından doğru JSON'u garanti etse de değerlerin anlamsal olarak doğru olduğunu garanti etmez. Son çıktıyı kullanmadan önce her zaman uygulama kodunuzda doğrulayın.
  • Hata işleme: Modelin çıkışı şemaya uygun olsa da iş mantığı gereksinimlerinizi karşılamayabileceği durumları sorunsuz bir şekilde yönetmek için uygulamanızda güçlü bir hata işleme yöntemi uygulayın.

Sınırlamalar

  • Şema alt kümesi: JSON şema spesifikasyonunun tüm özellikleri desteklenmez. Model, desteklenmeyen özellikleri yoksayar.
  • Şema karmaşıklığı: API, çok büyük veya derinlemesine yerleştirilmiş şemaları reddedebilir. Hatayla karşılaşırsanız şema adlarını kısaltarak, iç içe yerleştirmeyi azaltarak veya kısıtlama sayısını sınırlayarak şemanızı basitleştirmeyi deneyin.