Output Terstruktur

Anda dapat mengonfigurasi model Gemini untuk menghasilkan respons yang sesuai dengan Skema JSON yang diberikan. Kemampuan ini menjamin hasil yang dapat diprediksi dan diuraikan, memastikan keamanan format dan jenis, memungkinkan deteksi penolakan secara terprogram, dan menyederhanakan perintah.

Penggunaan output terstruktur sangat ideal untuk berbagai aplikasi:

  • Ekstraksi data: Mengambil informasi tertentu dari teks tidak terstruktur, seperti mengekstrak nama, tanggal, dan jumlah dari invoice.
  • Klasifikasi terstruktur: Mengklasifikasikan teks ke dalam kategori yang telah ditentukan dan menetapkan label terstruktur, seperti mengategorikan masukan pelanggan berdasarkan sentimen dan topik.
  • Alur kerja agentik: Membuat data terstruktur yang dapat digunakan untuk memanggil alat atau API lain, seperti membuat lembar karakter untuk game atau mengisi formulir.

Selain mendukung Skema JSON di REST API, Google GenAI SDK untuk Python dan JavaScript juga memudahkan Anda menentukan skema objek menggunakan Pydantic dan Zod. Contoh di bawah menunjukkan cara mengekstrak informasi dari teks tidak terstruktur yang sesuai dengan skema yang ditentukan dalam kode.

Contoh ini menunjukkan cara mengekstrak data terstruktur dari teks menggunakan jenis Skema JSON dasar seperti object, array, string, dan integer.

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

Contoh Respons:

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

Streaming

Anda dapat melakukan streaming output terstruktur, yang memungkinkan Anda mulai memproses respons saat sedang dibuat, tanpa harus menunggu seluruh output selesai. Hal ini dapat meningkatkan performa yang dirasakan dari aplikasi Anda.

Chunk yang di-streaming akan berupa string JSON parsial yang valid, yang dapat digabungkan untuk membentuk objek JSON akhir yang lengkap.

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

Dukungan skema JSON

Untuk membuat objek JSON, tetapkan response_mime_type dalam konfigurasi pembuatan ke application/json dan berikan response_json_schema. Skema harus berupa JSON Schema yang valid dan mendeskripsikan format output yang diinginkan.

Kemudian, model akan menghasilkan respons berupa string JSON yang valid secara sintaksis dan cocok dengan skema yang diberikan. Saat menggunakan output terstruktur, model akan menghasilkan output dalam urutan yang sama dengan kunci dalam skema.

Mode output terstruktur Gemini mendukung subset spesifikasi JSON Schema.

Nilai type berikut didukung:

  • string: Untuk teks.
  • number: Untuk bilangan floating point.
  • integer: Untuk bilangan bulat.
  • boolean: Untuk nilai benar/salah.
  • object: Untuk data terstruktur dengan pasangan nilai kunci.
  • array: Untuk daftar item.
  • null: Untuk mengizinkan properti bernilai null, sertakan "null" dalam array jenis (misalnya, {"type": ["string", "null"]}).

Properti deskriptif ini membantu memandu model:

  • title: Deskripsi singkat properti.
  • description: Deskripsi properti yang lebih panjang dan mendetail.

Properti khusus jenis

Untuk nilai object:

  • properties: Objek dengan setiap kunci adalah nama properti dan setiap nilai adalah skema untuk properti tersebut.
  • required: Array string, yang mencantumkan properti mana yang wajib diisi.
  • additionalProperties: Mengontrol apakah properti yang tidak tercantum di properties diizinkan. Dapat berupa boolean atau skema.

Untuk nilai string:

  • enum: Mencantumkan kumpulan string tertentu yang mungkin untuk tugas klasifikasi.
  • format: Menentukan sintaksis untuk string, seperti date-time, date, time.

Untuk nilai number dan integer:

  • enum: Mencantumkan serangkaian nilai numerik tertentu yang mungkin.
  • minimum: Nilai inklusif minimum.
  • maximum: Nilai inklusif maksimum.

Untuk nilai array:

  • items: Menentukan skema untuk semua item dalam array.
  • prefixItems: Menentukan daftar skema untuk N item pertama, sehingga memungkinkan struktur seperti tuple.
  • minItems: Jumlah minimum item dalam array.
  • maxItems: Jumlah maksimum item dalam array.

Dukungan model

Model berikut mendukung output terstruktur:

Model Output Terstruktur
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Perhatikan bahwa Gemini 2.0 memerlukan daftar propertyOrdering eksplisit dalam input JSON untuk menentukan struktur yang diinginkan. Anda dapat menemukan contohnya di buku resep ini.

Output terstruktur vs. panggilan fungsi

Output terstruktur dan panggilan fungsi menggunakan skema JSON, tetapi keduanya memiliki tujuan yang berbeda:

Fitur Kasus Penggunaan Utama
Output Terstruktur Memformat respons akhir untuk pengguna. Gunakan ini jika Anda ingin jawaban model dalam format tertentu (misalnya, mengekstrak data dari dokumen untuk disimpan ke database).
Panggilan Fungsi Mengambil tindakan selama percakapan. Gunakan ini saat model perlu meminta Anda untuk melakukan tugas (misalnya, "get current weather") sebelum dapat memberikan jawaban akhir.

Praktik terbaik

  • Deskripsi yang jelas: Gunakan kolom description dalam skema Anda untuk memberikan petunjuk yang jelas kepada model tentang apa yang diwakili oleh setiap properti. Hal ini penting untuk memandu output model.
  • Pengetikan kuat: Gunakan jenis tertentu (integer, string, enum) jika memungkinkan. Jika parameter memiliki serangkaian nilai valid yang terbatas, gunakan enum.
  • Rekayasa perintah: Nyatakan dengan jelas dalam perintah Anda apa yang Anda inginkan dari model. Misalnya, "Ekstrak informasi berikut dari teks..." atau "Klasifikasikan masukan ini sesuai dengan skema yang diberikan...".
  • Validasi: Meskipun output terstruktur menjamin JSON yang benar secara sintaksis, output ini tidak menjamin nilai yang benar secara semantik. Selalu validasi output akhir dalam kode aplikasi Anda sebelum menggunakannya.
  • Penanganan error: Terapkan penanganan error yang andal di aplikasi Anda untuk mengelola kasus dengan baik saat output model, meskipun sesuai dengan skema, mungkin tidak memenuhi persyaratan logika bisnis Anda.

Batasan

  • Subkumpulan skema: Tidak semua fitur spesifikasi Skema JSON didukung. Model mengabaikan properti yang tidak didukung.
  • Kompleksitas skema: API dapat menolak skema yang sangat besar atau memiliki banyak tingkat. Jika Anda mengalami error, coba sederhanakan skema dengan mempersingkat nama properti, mengurangi penautan, atau membatasi jumlah batasan.