Gemini 2.5 Flash Image (diğer adıyla Nano Banana) artık Gemini API'de kullanılabiliyor. Daha fazla bilgi

Bu sayfa, Cloud Translation API ile çevrilmiştir.

Yapılandırılmış çıkış

Gemini'ı yapılandırılmamış metin yerine yapılandırılmış çıkış için yapılandırabilirsiniz. Bu sayede, bilgilerin daha fazla işlenmesi için hassas bir şekilde ayıklanıp standartlaştırılması sağlanır. Örneğin, yapılandırılmış çıkışı kullanarak öz geçmişlerden bilgi ayıklayabilir ve yapılandırılmış bir veritabanı oluşturmak için bu bilgileri standartlaştırabilirsiniz.

Gemini, yapılandırılmış çıkış olarak JSON veya enum değerleri oluşturabilir.

JSON oluşturma

Modelin JSON oluşturmasını kısıtlamak için responseSchema yapılandırın. Model, daha sonra tüm istemlere JSON biçimli çıkışla yanıt verir.

Python

from google import genai
from pydantic import BaseModel

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="List a few popular cookie recipes, and include the amounts of ingredients.",
    config={
        "response_mime_type": "application/json",
        "response_schema": list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents:
      "List a few popular cookie recipes, and include the amounts of ingredients.",
    config: {
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            recipeName: {
              type: Type.STRING,
            },
            ingredients: {
              type: Type.ARRAY,
              items: {
                type: Type.STRING,
              },
            },
          },
          propertyOrdering: ["recipeName", "ingredients"],
        },
      },
    },
  });

  console.log(response.text);
}

main();

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)
    }

    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseSchema: &genai.Schema{
            Type: genai.TypeArray,
            Items: &genai.Schema{
                Type: genai.TypeObject,
                Properties: map[string]*genai.Schema{
                    "recipeName": {Type: genai.TypeString},
                    "ingredients": {
                        Type:  genai.TypeArray,
                        Items: &genai.Schema{Type: genai.TypeString},
                    },
                },
                PropertyOrdering: []string{"recipeName", "ingredients"},
            },
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."),
        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' \
-d '{
      "contents": [{
        "parts":[
          { "text": "List a few popular cookie recipes, and include the amounts of ingredients." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipeName": { "type": "STRING" },
              "ingredients": {
                "type": "ARRAY",
                "items": { "type": "STRING" }
              }
            },
            "propertyOrdering": ["recipeName", "ingredients"]
          }
        }
      }
}' 2> /dev/null | head

Çıkış şu şekilde görünebilir:

[
  {
    "recipeName": "Chocolate Chip Cookies",
    "ingredients": [
      "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 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

Enum değerleri oluşturma

Bazı durumlarda modelin, seçenekler listesinden tek bir seçenek belirlemesini isteyebilirsiniz. Bu davranışı uygulamak için şemanızda bir enum iletebilirsiniz. Enum, bir dize dizisi olduğundan responseSchema içinde string kullanabileceğiniz her yerde enum seçeneğini kullanabilirsiniz. JSON şemasına benzer şekilde, enum, model çıkışını uygulamanızın gereksinimlerini karşılayacak şekilde kısıtlamanıza olanak tanır.

Örneğin, müzik aletlerini beş kategoriden birine ("Percussion", "String", "Woodwind", "Brass" veya ""Keyboard"") sınıflandırmak için bir uygulama geliştirdiğinizi varsayalım. Bu görevde yardımcı olması için bir enum oluşturabilirsiniz.

Aşağıdaki örnekte, modeli en uygun seçeneği belirlemeye zorlayarak responseSchema olarak bir enum geçiriyorsunuz.

Python

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "What type of instrument is an oboe?",
    config: {
      responseMimeType: "text/x.enum",
      responseSchema: {
        type: Type.STRING,
        enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
      },
    },
  });

console.log(response.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' \
    -d '{
          "contents": [{
            "parts":[
              { "text": "What type of instrument is an oboe?" }
            ]
          }],
          "generationConfig": {
            "responseMimeType": "text/x.enum",
            "responseSchema": {
              "type": "STRING",
              "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
            }
          }
    }'

Python kitaplığı, API'nin tür bildirimlerini çevirir. Ancak API, OpenAPI 3.0 şemasının bir alt kümesini (Şema) kabul eder.

Numaralandırma belirtmenin iki yolu daha vardır. Aşağıdaki Literal öğesini kullanabilirsiniz: ```

Python

Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]

Şemayı JSON olarak da iletebilirsiniz:

Python

from google import genai

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

print(response.text)
# Woodwind

Temel çoktan seçmeli soruların yanı sıra, JSON şemasında herhangi bir yerde enum kullanabilirsiniz. Örneğin, modelden yemek tarifi başlıklarının listesini isteyebilir ve her başlığa popülerlik derecesi vermek için Grade enum'ını kullanabilirsiniz:

Python

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='List 10 home-baked cookie recipes and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)

Yanıt aşağıdaki gibi görünebilir:

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "rating": "a+"
  },
  {
    "recipe_name": "Peanut Butter Cookies",
    "rating": "a"
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "rating": "b"
  },
  ...
]

JSON şemaları hakkında

responseSchema parametresini kullanarak modeli JSON çıkışı için yapılandırma, yapısını tanımlamak üzere Schema nesnesine dayanır. Bu nesne, OpenAPI 3.0 Şema nesnesinin belirli bir alt kümesini temsil eder ve propertyOrdering alanını da ekler.

Aşağıda, tüm Schema alanlarının sözde JSON gösterimi verilmiştir:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": integer,
  "minItems": integer,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Şemanın Type bölümü, OpenAPI Veri Türleri'nden biri veya bu türlerin birleşimi (anyOf kullanılarak) olmalıdır. Her Type için yalnızca bir alan alt kümesi geçerlidir. Aşağıdaki listede her Type, bu tür için geçerli olan alanların bir alt kümesiyle eşlenir:

string -> enum, format, nullable
integer -> format, minimum, maximum, enum, nullable
number -> format, minimum, maximum, enum, nullable
boolean -> nullable
array -> minItems, maxItems, items, nullable
object -> properties, required, propertyOrdering, nullable

Aşağıda, geçerli tür ve alan kombinasyonlarını gösteren bazı örnek şemalar verilmiştir:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

Gemini API'de kullanılan Şema alanlarının eksiksiz belgeleri için Şema referansı bölümüne bakın.

Mülk sıralaması

Gemini API'de JSON şemalarıyla çalışırken özelliklerin sırası önemlidir. API, varsayılan olarak özellikleri alfabetik sıraya göre sıralar ve özelliklerin tanımlandığı sırayı korumaz (ancak Google Gen AI SDK'ları bu sırayı koruyabilir). Modele, şeması yapılandırılmış örnekler sağlıyorsanız ve örneklerin özellik sıralaması şemanın özellik sıralamasıyla tutarlı değilse çıkış, tutarsız veya beklenmedik olabilir.

Özelliklerin tutarlı ve tahmin edilebilir bir şekilde sıralanmasını sağlamak için isteğe bağlı propertyOrdering[] alanını kullanabilirsiniz.

"propertyOrdering": ["recipeName", "ingredients"]

propertyOrdering[] – OpenAPI spesifikasyonunda standart bir alan değildir – yanıttaki özelliklerin sırasını belirlemek için kullanılan bir dize dizisidir. Mülklerin sırasını belirleyip ardından aynı sıradaki mülklerle örnekler sağlayarak sonuçların kalitesini artırabilirsiniz. propertyOrdering yalnızca types.Schema'yi manuel olarak oluşturduğunuzda desteklenir.

Python'da şemalar

Python kitaplığını kullanırken response_schema değeri aşağıdakilerden biri olmalıdır:

Tür ek açıklamasında kullanacağınız tür (Python typing modülüne bakın)
genai.types.Schema örneği
genai.types.Schema tutarının dict cinsinden karşılığı

Şema tanımlamanın en kolay yolu, Pydantic türü kullanmaktır (önceki örnekte gösterildiği gibi):

Python

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

Pydantic türü kullandığınızda Python kitaplığı sizin için bir JSON şeması oluşturur ve bunu API'ye gönderir. Ek örnekler için Python kitaplığı belgelerine bakın.

Python kitaplığı, aşağıdaki türlerle tanımlanan şemaları destekler (burada AllowedType, izin verilen herhangi bir türdür):

int
float
bool
str
list[AllowedType]
AllowedType|AllowedType|...
Yapılandırılmış türler için:
- dict[str, AllowedType]. Bu ek açıklama, tüm sözlük değerlerinin aynı türde olduğunu belirtir ancak hangi anahtarların dahil edilmesi gerektiğini belirtmez.
- Kullanıcı tanımlı Pydantic modelleri. Bu yaklaşım, anahtar adlarını belirtmenize ve iç içe yerleştirilmiş yapılar da dahil olmak üzere her anahtarla ilişkili değerler için farklı türler tanımlamanıza olanak tanır.

JSON şema desteği

JSON Şeması, Şema nesnesinin temel alındığı OpenAPI 3.0'dan daha yeni bir spesifikasyondur. JSON şeması desteği, aşağıdaki sınırlamalarla birlikte herhangi bir JSON şemasını kabul eden responseJsonSchema alanı kullanılarak önizleme olarak sunulmaktadır:

Yalnızca Gemini 2.5 ile çalışır.
Tüm JSON şema özellikleri iletilebilse de hepsi desteklenmez. Daha fazla ayrıntı için alanla ilgili belgeleri inceleyin.
Özyinelemeli referanslar yalnızca zorunlu olmayan bir nesne özelliğinin değeri olarak kullanılabilir.
Yinelemeli referanslar, şemanın boyutuna göre sınırlı bir dereceye kadar açılır.
$ref içeren şemalar, $ ile başlayanlar dışında özellik içeremez.

Pydantic ile JSON şeması oluşturma ve bunu modele gönderme örneğini burada bulabilirsiniz:

curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY"\
    -H 'Content-Type: application/json' \
    -d @- <<EOF
{
  "contents": [{
    "parts":[{
      "text": "Please give a random example following this schema"
    }]
  }],
  "generationConfig": {
    "response_mime_type": "application/json",
    "response_json_schema": $(python3 - << PYEOF
    from enum import Enum
    from typing import List, Optional, Union, Set
    from pydantic import BaseModel, Field, ConfigDict
    import json

    class UserRole(str, Enum):
        ADMIN = "admin"
        VIEWER = "viewer"

    class Address(BaseModel):
        street: str
        city: str

    class UserProfile(BaseModel):
        username: str = Field(description="User's unique name")
        age: Optional[int] = Field(ge=0, le=120)
        roles: Set[UserRole] = Field(min_items=1)
        contact: Union[Address, str]
        model_config = ConfigDict(title="User Schema")

    # Generate and print the JSON Schema
    print(json.dumps(UserProfile.model_json_schema(), indent=2))
    PYEOF
    )
  }
}
EOF

SDK kullanılırken JSON şemasının doğrudan iletilmesi henüz desteklenmemektedir.

En iyi uygulamalar

Yanıt şeması kullanırken aşağıdaki hususları ve en iyi uygulamaları göz önünde bulundurun:

Yanıt şemanızın boyutu, giriş jetonu sınırına dahil edilir.
Varsayılan olarak alanlar isteğe bağlıdır. Bu, modelin alanları doldurabileceği veya atlayabileceği anlamına gelir. Modelin değer sağlamasını zorlamak için alanları zorunlu olarak ayarlayabilirsiniz. İlişkili giriş isteminde yeterli bağlam yoksa model, yanıtları temel olarak üzerinde eğitildiği verilere göre oluşturur.
Karmaşık bir şema, InvalidArgument: 400 hatasına neden olabilir. Karmaşıklık; uzun özellik adlarından, uzun dizi uzunluğu sınırlarından, çok sayıda değer içeren numaralandırmalardan, çok sayıda isteğe bağlı özellik içeren nesnelerden veya bu faktörlerin bir kombinasyonundan kaynaklanabilir.

Geçerli bir şemayla bu hatayı alırsanız hatayı düzeltmek için aşağıdaki değişikliklerden birini veya birkaçını yapın:
- Mülk adlarını veya enum adlarını kısaltın.
- İç içe yerleştirilmiş dizileri düzleştirin.
- Minimum ve maksimum sınırlar gibi kısıtlamaları olan özelliklerin sayısını azaltın.
- Karmaşık biçimlere sahip özellikler (ör. date-time) gibi karmaşık kısıtlamaları olan özelliklerin sayısını azaltın.
- İsteğe bağlı özelliklerin sayısını azaltın.
- Numaralandırmalar için geçerli değerlerin sayısını azaltın.
Beklediğiniz sonuçları görmüyorsanız giriş istemlerinize daha fazla bağlam ekleyin veya yanıt şemanızı düzeltin. Örneğin, modelin nasıl yanıt verdiğini görmek için modelin yapılandırılmış çıkış içermeyen yanıtını inceleyin. Ardından, yanıt şemanızı modelin çıkışına daha iyi uyacak şekilde güncelleyebilirsiniz. Yapılandırılmış çıkışla ilgili ek sorun giderme ipuçları için sorun giderme kılavuzuna bakın.

Sırada ne var?

Yapılandırılmış çıkış oluşturmayı öğrendiğinize göre, Gemini API araçlarını kullanmayı deneyebilirsiniz: