Output terstruktur

Anda dapat mengonfigurasi Gemini untuk output terstruktur, bukan teks tidak terstruktur, sehingga memungkinkan ekstraksi dan standarisasi informasi yang akurat untuk pemrosesan lebih lanjut. Misalnya, Anda dapat menggunakan output terstruktur untuk mengekstrak informasi dari resume, menstandarkannya untuk membuat database terstruktur.

Gemini dapat membuat JSON atau nilai enum sebagai output terstruktur.

Membuat JSON

Untuk membatasi model agar menghasilkan JSON, konfigurasikan responseSchema. Model kemudian akan merespons setiap perintah dengan output berformat JSON.

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

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();

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

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

Outputnya mungkin terlihat seperti ini:

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

Membuat nilai enum

Dalam beberapa kasus, Anda mungkin ingin model memilih satu opsi dari daftar opsi. Untuk menerapkan perilaku ini, Anda dapat meneruskan enum dalam skema. Anda dapat menggunakan opsi enum di mana pun Anda dapat menggunakan string di responseSchema, karena enum adalah array string. Seperti skema JSON, enum memungkinkan Anda membatasi output model untuk memenuhi persyaratan aplikasi Anda.

Misalnya, anggaplah Anda sedang mengembangkan aplikasi untuk mengklasifikasikan alat musik ke dalam salah satu dari lima kategori: "Percussion", "String", "Woodwind", "Brass", atau ""Keyboard"". Anda dapat membuat enum untuk membantu tugas ini.

Dalam contoh berikut, Anda meneruskan enum sebagai responseSchema, yang membatasi model untuk memilih opsi yang paling sesuai.

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

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

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

Library Python akan menerjemahkan deklarasi jenis untuk API. Namun, API menerima subset skema OpenAPI 3.0 (Schema).

Ada dua cara lain untuk menentukan enumerasi. Anda dapat menggunakan Literal: ```

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

Anda juga dapat meneruskan skema sebagai JSON:

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

Selain masalah pilihan ganda dasar, Anda dapat menggunakan enum di mana saja dalam skema JSON. Misalnya, Anda dapat meminta model untuk membuat daftar judul resep dan menggunakan enum Grade untuk memberi setiap judul tingkat popularitas:

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)

Responsnya mungkin terlihat seperti ini:

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

Tentang skema JSON

Mengonfigurasi model untuk output JSON menggunakan parameter responseSchema bergantung pada objek Schema untuk menentukan strukturnya. Objek ini merepresentasikan subset terpilih dari objek Skema OpenAPI 3.0, dan juga menambahkan kolom propertyOrdering.

Berikut adalah representasi pseudo-JSON dari semua kolom Schema:

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

Type skema harus berupa salah satu Jenis Data OpenAPI, atau gabungan dari jenis tersebut (menggunakan anyOf). Hanya subset kolom yang valid untuk setiap Type. Daftar berikut memetakan setiap Type ke subset kolom yang valid untuk jenis tersebut:

• 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

Berikut beberapa contoh skema yang menunjukkan kombinasi jenis dan kolom yang valid:

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

Untuk dokumentasi lengkap kolom Skema sebagaimana digunakan dalam Gemini API, lihat Referensi skema.

Pengurutan properti

Saat Anda bekerja dengan skema JSON di Gemini API, urutan properti penting. Secara default, API mengurutkan properti menurut abjad dan tidak mempertahankan urutan properti ditentukan (meskipun SDK AI Generatif Google dapat mempertahankan urutan ini). Jika Anda memberikan contoh ke model dengan skema yang dikonfigurasi, dan urutan properti contoh tidak konsisten dengan urutan properti skema, outputnya bisa tidak jelas atau tidak terduga.

Untuk memastikan pengurutan properti yang konsisten dan dapat diprediksi, Anda dapat menggunakan kolom propertyOrdering[] opsional.

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

propertyOrdering[] – bukan kolom standar dalam spesifikasi OpenAPI – adalah array string yang digunakan untuk menentukan urutan properti dalam respons. Dengan menentukan urutan properti, lalu memberikan contoh dengan properti dalam urutan yang sama, Anda berpotensi meningkatkan kualitas hasil. propertyOrdering hanya didukung saat Anda membuat types.Schema secara manual.

Skema di Python

Saat Anda menggunakan library Python, nilai response_schema harus salah satu dari berikut ini:

• Jenis, seperti yang akan Anda gunakan dalam anotasi jenis (lihat modul typing Python)
• Instance genai.types.Schema
• dict yang setara dengan genai.types.Schema

Cara termudah untuk menentukan skema adalah dengan jenis Pydantic (seperti yang ditunjukkan pada contoh sebelumnya):

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

Saat Anda menggunakan jenis Pydantic, library Python akan membuat skema JSON untuk Anda dan mengirimkannya ke API. Untuk contoh tambahan, lihat Dokumen library Python.

Library Python mendukung skema yang ditentukan dengan jenis berikut (dengan AllowedType adalah jenis yang diizinkan):

• int
• float
• bool
• str
• list[AllowedType]
• AllowedType|AllowedType|...
• Untuk jenis terstruktur:
  • dict[str, AllowedType]. Anotasi ini mendeklarasikan semua nilai dict memiliki jenis yang sama, tetapi tidak menentukan kunci yang harus disertakan.
  • Model Pydantic yang ditentukan pengguna. Pendekatan ini memungkinkan Anda menentukan nama kunci dan menentukan berbagai jenis untuk nilai yang terkait dengan setiap kunci, termasuk struktur bertingkat.

Dukungan Skema JSON

JSON Schema adalah spesifikasi yang lebih baru daripada OpenAPI 3.0, yang menjadi dasar objek Schema. Dukungan untuk Skema JSON tersedia sebagai pratinjau menggunakan kolom responseJsonSchema yang menerima Skema JSON apa pun dengan batasan berikut:

• Fitur ini hanya berfungsi dengan Gemini 2.5.
• Meskipun semua properti Skema JSON dapat diteruskan, tidak semuanya didukung. Lihat dokumentasi untuk mengetahui detail selengkapnya tentang kolom.
• Referensi rekursif hanya dapat digunakan sebagai nilai properti objek yang tidak wajib.
• Referensi rekursif diuraikan hingga tingkat terbatas, berdasarkan ukuran skema.
• Skema yang berisi $ref tidak boleh berisi properti lain selain yang diawali dengan $.

Berikut adalah contoh pembuatan Skema JSON dengan Pydantic dan pengirimannya ke model:

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

Penerusan Skema JSON secara langsung belum didukung saat menggunakan SDK.

Praktik terbaik

Perhatikan pertimbangan dan praktik terbaik berikut saat Anda menggunakan skema respons:

• Ukuran skema respons Anda dihitung dalam batas token input.
• Secara default, kolom bersifat opsional, artinya model dapat mengisi kolom atau melewatkannya. Anda dapat menetapkan kolom sebagai wajib diisi untuk memaksa model memberikan nilai. Jika tidak ada konteks yang memadai dalam perintah input terkait, model akan menghasilkan respons terutama berdasarkan data yang digunakan untuk melatihnya.

• Skema yang kompleks dapat menyebabkan error InvalidArgument: 400. Kompleksitas dapat berasal dari nama properti yang panjang, batas panjang array yang panjang, enum dengan banyak nilai, objek dengan banyak properti opsional, atau kombinasi dari faktor-faktor ini.

  Jika Anda mendapatkan error ini dengan skema yang valid, lakukan satu atau beberapa perubahan berikut untuk mengatasi error:

  • Perpendek nama properti atau nama enum.
  • Meratakan array bertingkat.
  • Kurangi jumlah properti dengan batasan, seperti angka dengan batas minimum dan maksimum.
  • Kurangi jumlah properti dengan batasan yang rumit, seperti properti dengan format yang rumit seperti date-time.
  • Kurangi jumlah properti opsional.
  • Kurangi jumlah nilai valid untuk enum.

• Jika Anda tidak melihat hasil yang diharapkan, tambahkan lebih banyak konteks ke perintah input atau revisi skema respons Anda. Misalnya, tinjau respons model tanpa output terstruktur untuk melihat cara model merespons. Kemudian, Anda dapat memperbarui skema respons agar lebih sesuai dengan output model. Untuk tips pemecahan masalah tambahan terkait output terstruktur, lihat panduan pemecahan masalah.

Langkah berikutnya

Setelah mempelajari cara membuat output terstruktur, Anda dapat mencoba menggunakan alat Gemini API:

• Pemanggilan fungsi
• Eksekusi kode
• Grounding dengan Google Penelusuran