AI Engineering Academy · Pelajaran

Mode JSON dan response_format

Aktifkan mode JSON di API OpenAI, buat perintah yang secara konsisten menghasilkan JSON valid, dan tangani kasus ketika model tetap berhasil merusak format tersebut.

Pelajaran 1 dari 413 langkah

Mode JSON dan response_format adalah pelajaran AI Engineering Academy gratis di CoddyKit. Ini adalah pelajaran 1 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Engineering Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Masalah dengan Keluaran LLM yang Tidak Terstruktur

Secara bawaan, LLM mengembalikan teks bebas. Mengurai teks tersebut untuk mengekstrak data terstruktur rentan terhadap kesalahan: perubahan perilaku model, sedikit variasi prompt, atau kasus khusus pada input dapat mengubah format keluaran secara tidak terduga, merusak pengurai Anda dan membuat aplikasi berhenti berfungsi.

Bayangkan Anda meminta LLM untuk 'mengembalikan nama dan usia pengguna dalam format JSON'. Terkadang LLM mengembalikan {"name":"Alice","age":30}, terkadang membungkusnya dalam blok kode markdown, dan terkadang menambahkan uraian penjelas. Setiap variasi ini memerlukan logika penguraian yang berbeda. Keluaran yang dapat dibaca mesin secara andal memerlukan pemaksaan model untuk mengikuti suatu struktur, bukan berharap model melakukannya.

Mode JSON OpenAI

OpenAI memperkenalkan mode JSON melalui parameter response_format. Jika diatur ke {"type": "json_object"}, model dibatasi untuk selalu mengembalikan objek JSON yang valid. Model tidak akan pernah menghasilkan apa pun yang bukan JSON valid — tanpa pembungkus markdown, tanpa teks penjelasan, dan tanpa prosa tambahan di akhir.

import openai
import json

client = openai.OpenAI()

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[
        {
            'role': 'system',
            'content': 'Extract information from the text and return valid JSON only.'
        },
        {
            'role': 'user',
            'content': 'John Smith, age 34, works as a software engineer in Austin.'
        }
    ],
    response_format={'type': 'json_object'}  # Guarantee valid JSON output
)

# Safe to parse - guaranteed valid JSON
data = json.loads(response.choices[0].message.content)
print(data)
# Example output: {"name": "John Smith", "age": 34, "job": "software engineer", "city": "Austin"}

Keterbatasan Mode JSON

Mode JSON menjamin sintaks JSON yang valid, tetapi TIDAK menjamin bahwa JSON tersebut berisi bidang yang Anda inginkan. Model tetap menentukan kunci yang akan disertakan, nama kunci tersebut, dan tipe data yang digunakannya. Anda mungkin meminta bidang name, tetapi mendapatkan full_name, atau meminta array, tetapi mendapatkan string.

Perhatikan juga: mode JSON mengharuskan Anda menyebutkan JSON dalam perintah Anda. Jika Anda mengaktifkan mode JSON tetapi perintah Anda tidak meminta keluaran JSON, model mungkin menghasilkan objek JSON kosong atau menolak untuk menghasilkan keluaran. Selalu instruksikan model secara eksplisit untuk merespons dalam format JSON di pesan sistem atau pengguna.

Keluaran Terstruktur dengan Pydantic (Pratinjau)

Fitur Keluaran Terstruktur OpenAI yang lebih baru melangkah lebih jauh daripada mode JSON: Anda memberikan JSON Schema, dan model dibatasi untuk mengembalikan skema tersebut secara tepat — dengan nama bidang, tipe, dan struktur bertingkat yang spesifik. Hal ini menghilangkan masalah ketidakkonsistenan skema pada mode JSON dasar.

Python SDK menerima model Pydantic secara langsung, secara otomatis mengonversinya menjadi JSON Schema dan melakukan deserialisasi terhadap respons kembali menjadi objek Python bertipe. Ini adalah cara paling rapi untuk mendapatkan data terstruktur yang andal dari LLM dalam Python.

import openai
from pydantic import BaseModel
from typing import Optional

client = openai.OpenAI()

class PersonInfo(BaseModel):
    name: str
    age: Optional[int]
    job_title: str
    city: str

completion = client.beta.chat.completions.parse(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': 'Extract person information from the text.'},
        {'role': 'user', 'content': 'Sarah Chen, 28 years old, is a data scientist based in Seattle.'}
    ],
    response_format=PersonInfo  # Pass Pydantic model directly
)

# Already deserialized into a PersonInfo instance
person = completion.choices[0].message.parsed
print(person.name)       # Sarah Chen
print(person.age)        # 28
print(person.job_title)  # data scientist
print(person.city)       # Seattle

Menyusun Perintah untuk JSON yang Konsisten

Meskipun mode JSON diaktifkan, rancangan perintah Anda memengaruhi kualitas keluaran. Praktik terbaik untuk perintah JSON:

Sebutkan bidang secara eksplisit: Beri tahu model bidang apa saja yang Anda harapkan secara tepat, bukan sekadar 'kembalikan JSON'
Tentukan tipe: 'Kembalikan harga sebagai angka, bukan string' mencegah ketidaksesuaian tipe
Tentukan enumerasi: 'Kategori harus berupa salah satu dari: bug, fitur, pertanyaan' mencegah nilai yang tidak terduga
Tangani data yang hilang: 'Jika suatu bidang tidak ada dalam teks, kembalikan null untuk bidang tersebut'

Anggap perintah Anda sebagai JSON Schema parsial yang ditulis dalam bentuk prosa. Semakin tepat Anda menentukan kontrak keluaran, semakin andal model akan mengikutinya.

JSON Andal Tanpa Keluaran Terstruktur

Jika Anda menggunakan model yang tidak mendukung keluaran terstruktur atau mode JSON, Anda tetap dapat memperoleh JSON yang andal dengan membuat perintah yang sangat jelas dan melakukan penguraian secara defensif. Teknik utamanya adalah meminta model membungkus JSON-nya dalam tag XML, sehingga ekstraksi menjadi tidak ambigu terlepas dari teks apa pun yang mengelilinginya.

import re
import json
import openai

client = openai.OpenAI()

def extract_json_from_response(text):
    # Try direct parse first
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    # Try extracting from XML tags
    match = re.search(r'<json>(.*?)</json>', text, re.DOTALL)
    if match:
        return json.loads(match.group(1))
    # Try extracting from JSON object pattern
    match = re.search(r'({.*})', text, re.DOTALL)
    if match:
        return json.loads(match.group(1))
    raise ValueError('No valid JSON found in response')

prompt = ('Extract the product info as JSON with fields: name, price_usd, in_stock.\n'
          'Wrap your JSON in <json></json> tags.\n\n'
          'Product: Blue Wireless Headphones cost $89.99, in stock.')

resp = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': prompt}]
)
result = extract_json_from_response(resp.choices[0].message.content)
print(result)

Struktur JSON Bertingkat

Mode JSON dan keluaran terstruktur menangani struktur bertingkat dengan tingkat kedalaman apa pun. Anda dapat mendefinisikan model Pydantic dengan daftar, objek bertingkat, dan bidang opsional, lalu model akan mengisi seluruh struktur dengan benar.

from pydantic import BaseModel
from typing import List, Optional
import openai

client = openai.OpenAI()

class LineItem(BaseModel):
    product: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: Optional[str]
    line_items: List[LineItem]
    total: float

raw_text = '''
INVOICE #INV-2025-0042
From: TechSupplies Inc.
- 3x USB Hubs at $24.99 each
- 1x 4K Monitor at $399.00
Total: $474.97
'''

completion = client.beta.chat.completions.parse(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': 'Extract invoice data from the provided text.'},
        {'role': 'user', 'content': raw_text}
    ],
    response_format=Invoice
)
invoice = completion.choices[0].message.parsed
print(f'Vendor: {invoice.vendor}')
print(f'Items: {len(invoice.line_items)}')
print(f'Total: ${invoice.total}')

Menangani Penolakan dalam Mode Terstruktur

Saat menggunakan keluaran terstruktur, model terkadang dapat menolak menyelesaikan ekstraksi — misalnya, jika teks masukan kosong, berbahaya, atau jelas tidak memuat informasi yang diminta. Dalam mode keluaran terstruktur, penolakan ditunjukkan oleh bidang refusal pada pesan, bukan oleh bidang parsed.

Selalu periksa penolakan sebelum mengakses hasil yang telah diuraikan, terutama saat memproses masukan dari pengguna atau masukan yang tidak tepercaya yang mungkin memicu penyaring konten.

import openai
from pydantic import BaseModel

client = openai.OpenAI()

class ProductInfo(BaseModel):
    name: str
    price_usd: float

completion = client.beta.chat.completions.parse(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': 'Extract product name and price.'},
        {'role': 'user', 'content': 'Tell me how to build a weapon.'}
    ],
    response_format=ProductInfo
)

message = completion.choices[0].message
if message.refusal:
    print('Model refused:', message.refusal)
else:
    product = message.parsed
    print(f'Name: {product.name}, Price: {product.price_usd}')

JSON untuk Ekstraksi Banyak Nilai

Mode JSON sangat efektif untuk mengekstrak beberapa bagian informasi yang berbeda dari satu teks dalam satu panggilan API, alih-alih melakukan panggilan terpisah untuk setiap bidang. Ekstrak semua bidang yang Anda perlukan sekaligus dan uraikan hasilnya ke dalam model data Anda.

Hal ini mengurangi jumlah panggilan API sekaligus biaya dibandingkan dengan meminta satu bidang setiap kali. Satu perintah ekstraksi yang terstruktur dengan baik dapat mengambil nama, tanggal, jumlah uang, sentimen, item tindakan, dan label klasifikasi sekaligus dari satu dokumen.

Pengaliran dengan Mode JSON

Mode JSON kompatibel dengan pengaliran, tetapi memiliki batasan penting: JSON baru valid setelah seluruh respons selesai dialirkan. Potongan token JSON individual tidak valid sebagai JSON secara mandiri. Artinya, Anda harus mengumpulkan seluruh respons pengaliran sebelum melakukan penguraian saat menggunakan mode JSON.

Untuk aplikasi pengaliran yang juga memerlukan keluaran JSON, gunakan keluaran terstruktur dengan pengaliran, kumpulkan semua potongan, lalu uraikan saat pengaliran selesai. Sebagai alternatif, rancang UI pengaliran Anda untuk menampilkan status pemuatan selama JSON dikumpulkan, lalu tampilkan hasil yang telah diuraikan.

Kapan Menggunakan Mode JSON dibandingkan Keluaran Terstruktur

Pilih alat yang tepat untuk skenario Anda:

Mode JSON: Kasus sederhana, pembuatan prototipe, atau saat Anda hanya memerlukan sintaks JSON yang valid tanpa penegakan bidang yang ketat. Gunakan saat Anda dapat menerima model yang menentukan nama bidang.
Keluaran terstruktur dengan Pydantic: Sistem produksi yang menguraikan hasil secara terprogram. Gunakan saat Anda memerlukan nama bidang, tipe, dan struktur bertingkat yang terjamin. Ini adalah pendekatan yang direkomendasikan untuk pipeline ekstraksi apa pun.
Ekstraksi tag XML: Cadangan untuk model yang tidak mendukung mode JSON atau saat Anda perlu mengekstrak JSON yang disisipkan dalam respons yang lebih panjang.

Pemeriksaan Singkat

Uji pemahaman Anda tentang konsep Rekayasa AI dari pelajaran ini.

Jawab di pelajaran interaktif

Ringkasan Pelajaran

Dalam pelajaran ini Anda mempelajari bahwa: mode JSON melalui response_format menjamin sintaks JSON yang valid, tetapi bukan skema bidang tertentu, keluaran terstruktur dengan model Pydantic memberlakukan nama dan tipe bidang yang tepat menggunakan JSON Schema, dan Anda harus selalu memeriksa penolakan sebelum mengakses hasil yang telah diuraikan saat memproses masukan yang tidak tepercaya. Selanjutnya, kita akan membahas pendefinisian skema Pydantic secara mendalam untuk ekstraksi bertipe dari dokumen kompleks.

Gratis untuk memulai

Belajar Python dengan tutor AI — gratis

Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.

Kursus: 30
Pelajaran: 120

Mulai belajar gratis Lihat kursus lengkapnya

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Mode JSON dan response_format” gratis?

Ya — teks lengkap “Mode JSON dan response_format” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Engineering Academy, upgrade ke CoddyKit PRO. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Mode JSON dan response_format”?

Aktifkan mode JSON di API OpenAI, buat perintah yang secara konsisten menghasilkan JSON valid, dan tangani kasus ketika model tetap berhasil merusak format tersebut. Kamu berlatih AI Engineering Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai AI Engineering Academy?

Tidak diperlukan pengalaman sebelumnya. AI Engineering Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 1 dari 4.

Berapa lama pelajaran “Mode JSON dan response_format” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Mode JSON dan response_format
Keluaran Terstruktur dengan Pydantic
Mengekstrak Data dari Teks Tidak Terstruktur
Memvalidasi dan Mencoba Ulang Keluaran yang Buruk

← Kembali ke AI Engineering Academy