Cara Menggunakan Output Terstruktur OpenAI

Pada akhir panduan ini, Anda akan dapat memanggil keluaran terstruktur OpenAI dari kode Anda sendiri: berikan Skema JSON ke model, atur strict: true, dan dapatkan kembali respons yang dijamin sesuai dengan bentuk yang Anda minta. Anda akan mengirimkan permintaan pertama, membaca respons, menangani kasus-kasus khusus, dan menghasilkan koleksi pengujian API di Apidog yang menegaskan bahwa muatan benar-benar sesuai.

button

Apa yang Anda perlukan sebelum memulai

Keluaran terstruktur membatasi generasi model sehingga keluaran sesuai dengan Skema JSON yang Anda berikan. Ketika Anda meneruskan skema dengan strict: true, model tidak dapat mengeluarkan bidang yang melanggarnya. Setiap kunci yang diperlukan ada, setiap tipe cocok, dan setiap nilai enum adalah salah satu yang Anda cantumkan. Anda berhenti menulis kode parsing defensif dan mulai mempercayai muatan.

Itu adalah peningkatan nyata dibandingkan alternatifnya. Perintah teks bebas seperti “respons hanya dengan JSON” berfungsi sampai tidak berfungsi. Satu penyimpangan penalaran dan Anda mendapatkan prosa yang membungkus objek Anda, atau tanggal di mana Anda mengharapkan bilangan bulat. Keluaran terstruktur memindahkan kontrak dari instruksi yang penuh harapan menjadi batasan yang ditegakkan pada waktu dekode.

Untuk mengikuti, Anda memerlukan:

Kunci API OpenAI yang diatur sebagai OPENAI_API_KEY.
Model yang mendukung penegakan skema ketat (lebih lanjut tentang model mana di bawah).
Skema JSON yang menjelaskan bentuk yang Anda inginkan kembali.

Pilih model yang tepat

Keluaran terstruktur tersedia pada model terbaru OpenAI, dimulai dengan keluarga GPT-4o dan berlanjut hingga seri GPT-5. Dokumentasi OpenAI saat ini merekomendasikan untuk memulai proyek baru dengan model unggulan terbaru mereka (gpt-5.5 pada saat penulisan). Model yang lebih lama, dan model era gpt-3.5, mendukung mode JSON tetapi tidak penegakan skema ketat. Jika Anda bergantung pada strict: true, konfirmasikan bahwa ID model spesifik mendukungnya sebelum Anda mengirimkan, karena dukungan terkait dengan versi model dan OpenAI terus memperbaruinya.

Sangat membantu untuk mengetahui fitur mana yang sebenarnya Anda inginkan, karena OpenAI menyediakan dua fitur terkait yang mudah membingungkan.

Mode JSON (response_format: { "type": "json_object" }) menjamin bahwa keluarannya adalah *JSON yang secara sintaksis valid*. Hanya itu saja. Ia tidak mengetahui bidang, tipe, atau kunci yang Anda perlukan. Anda masih harus memvalidasi bentuknya sendiri.

Keluaran terstruktur (response_format dengan type: "json_schema" dan strict: true) menjamin bahwa keluarannya adalah JSON yang valid *dan* sesuai dengan skema Anda. OpenAI menggambarkan keluaran terstruktur sebagai evolusi mode JSON: keduanya menghasilkan JSON yang valid, tetapi hanya keluaran terstruktur yang menegakkan kepatuhan skema. Untuk pekerjaan baru, keluaran terstruktur adalah yang Anda inginkan.

	Mode JSON	Keluaran Terstruktur (ketat)
Parameter	`response_format: {"type":"json_object"}`	`response_format` dengan `type: "json_schema"`, `strict: true`
JSON Valid	Ya	Ya
Sesuai skema Anda	Tidak	Ya
Bidang wajib ditegakkan	Tidak	Ya
Tipe dan enum ditegakkan	Tidak	Ya
Anda masih memvalidasi di hilir	Selalu	Direkomendasikan (lihat di bawah)

Catatan tentang API: endpoint Chat Completions menggunakan response_format seperti yang ditunjukkan di atas. API Respons yang lebih baru menyatakan hal yang sama di bawah text.format dengan type: "json_schema". Aturan skemanya identik; hanya pembungkusnya yang berbeda. Periksa dokumentasi terbaru untuk jalur bidang yang tepat pada endpoint yang Anda panggil.

Buat permintaan pertama Anda

Misalnya Anda mengekstrak tiket dukungan ke dalam rekaman bertipe. Berikut adalah permintaan Chat Completions dengan skema ketat.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "system", "content": "Extract the ticket into the schema." },
      { "role": "user", "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary":  { "type": "string" },
            "category": { "type": "string", "enum": ["billing", "bug", "account", "other"] },
            "severity": { "type": "integer" },
            "account_id": {
              "anyOf": [ { "type": "string" }, { "type": "null" } ]
            }
          },
          "required": ["summary", "category", "severity", "account_id"],
          "additionalProperties": false
        }
      }
    }
  }'

Baca responsnya

Model mengembalikan pesan yang content-nya adalah string JSON yang cocok dengan skema tersebut, misalnya:

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}

Perhatikan account_id menggunakan anyOf dengan null. Begitulah cara Anda memodelkan bidang opsional, yang mengarah langsung ke aturan yang harus Anda ikuti saat menulis skema Anda sendiri.

Tetap dalam subset skema

Keluaran terstruktur menerima subset dari Skema JSON. Subset tersebut ada agar OpenAI dapat menegakkan batasan dengan andal dan menyimpan skema yang dikompilasi. Aturan yang perlu diingat:

Akar harus berupa objek. Anda tidak dapat menjadikan level teratas sebagai array atau string kosong. Bungkus daftar dalam properti objek.
Setiap properti harus tercantum dalam required. Tidak ada “opsional” dalam arti biasa. Untuk membuat bidang dapat bernilai null, berikan anyOf dengan tipe null, seperti pada contoh di atas.
additionalProperties harus false pada setiap objek. Ini menghalangi model untuk menciptakan kunci tambahan.
Berlaku batas ukuran. Sebuah skema dapat menampung sekitar 100 properti objek dengan hingga 5 tingkat bersarang. Skema yang sangat bersarang atau menyebar akan ditolak, jadi ratakan jika memungkinkan.
Beberapa kata kunci tidak ditegakkan. Kata kunci hanya validasi seperti pattern, format, minLength, dan minimum tidak dijamin oleh model. Jika Anda memerlukan regex atau rentang numerik yang dihormati, Anda tetap harus memeriksanya sendiri setelah respons diterima.
Latensi panggilan pertama. Permintaan pertama dengan skema baru membutuhkan waktu untuk mengompilasinya (biasanya beberapa detik, terkadang hingga satu menit untuk skema yang kompleks). Setelah itu, ia di-cache dan cepat.

Karena kata kunci validasi tidak ditegakkan, “JSON yang dijamin” tidak berarti “valid secara bisnis yang dijamin.” Strukturnya terkunci. Nilai-nilai di dalamnya masih memerlukan pengujian. Jika Anda pernah memodelkan bidang opsional atau union dengan oneOf/anyOf/allOf, model mentalnya familiar: skema membatasi bentuk, tetapi Anda menegaskan nilai riil secara terpisah.

Tangani penolakan dan pemotongan

Ada satu kasus di mana keluaran tidak akan sesuai dengan skema Anda secara sengaja. Jika model menolak permintaan yang tidak aman, ia mengembalikan bidang refusal pada pesan alih-alih konten berbentuk skema. Kode Anda harus bercabang pada itu sebelum parsing:

msg = response.choices[0].message
if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)

Penolakan sekarang dapat dideteksi secara terprogram, yang lebih bersih daripada memindai teks untuk permintaan maaf. Dua cara lain respons bisa tidak memenuhi skema: mencapai max_tokens di tengah objek (JSON terpotong), atau menggunakan panggilan alat paralel, yang tidak didukung oleh keluaran terstruktur. Atur parallel_tool_calls ke false saat Anda menggabungkan keduanya.

Cara mengujinya di Apidog

Mode ketat menegakkan skema pada waktu generasi. Ini tidak membebaskan Anda dari pengujian. Model ditukar, skema bergeser, rekan tim mengedit array required, atau jalur penolakan berubah. Anda menginginkan pengujian yang gagal dengan keras ketika respons berhenti cocok dengan kontrak. Di situlah Apidog berperan.

Agar lebih presisi tentang pembagian kerja: mode ketat OpenAI adalah yang menghasilkan JSON yang valid skema. Apidog tidak menegakkan skema pada model. Apa yang dilakukan Apidog adalah memvalidasi *respons yang Anda terima* terhadap skema yang Anda harapkan, sehingga Anda dapat menangkap penyimpangan dalam CI alih-alih dalam produksi.

Berikut alurnya:

Kirim permintaan. Buat panggilan Chat Completions di Apidog dengan blok response_format Anda. Simpan ke koleksi agar dapat diulang.
Tegaskan bentuknya. Tambahkan penegasan respons di Apidog. Periksa apakah category adalah salah satu nilai enum Anda, bahwa severity adalah bilangan bulat, bahwa account_id adalah string atau null. Apidog dapat memvalidasi respons terhadap Skema JSON sehingga Anda melampirkan skema yang tepat dan menggagalkan eksekusi ketika muatan menyimpang.
Jalankan di CI. Masukkan koleksi ke dalam pipeline Anda sehingga setiap perubahan model atau prompt memeriksa ulang kesesuaian. Pelanggaran skema yang senyap menjadi build yang merah.
Mock kontrak. Sebelum panggilan nyata ada, atau untuk menguji konsumen hilir tanpa menghabiskan token, siapkan API mock yang mengembalikan respons sampel yang valid skema. Frontend dan pengujian Anda berjalan terhadap bentuk yang stabil sementara integrasi menguat.

Poin terakhir itu adalah yang diremehkan. Anda dapat mengembangkan dan menguji segala sesuatu yang *mengonsumsi* keluaran terstruktur terhadap mock yang menghormati skema yang sama, lalu menukar dengan panggilan OpenAI langsung ketika Anda siap. Unduh Apidog dan Anda dapat membangun permintaan, penegasan, dan mock di satu tempat.

Pertanyaan yang sering diajukan

Apakah mode JSON sudah tidak digunakan lagi setelah adanya keluaran terstruktur? Mode JSON masih berfungsi dan masih menjamin JSON yang valid. Ia hanya tidak menegakkan skema. Untuk kode baru, keluaran terstruktur dengan strict: true adalah pilihan yang lebih kuat. Gunakan mode JSON biasa hanya pada model yang tidak mendukung skema ketat, atau ketika Anda benar-benar tidak memiliki bentuk tetap.

Bisakah akar skema saya berupa array? Tidak. Level teratas harus berupa objek. Bungkus daftar Anda dalam sebuah properti, seperti { "items": [...] }, dan masukkan items ke dalam required. Ini sering membingungkan banyak orang pada hari pertama.

Bagaimana cara membuat bidang opsional? Keluaran terstruktur mewajibkan setiap properti berada di required, jadi tidak ada bidang opsional klasik. Modelkan “hilang” sebagai nullable: gunakan anyOf dengan string (atau tipe apa pun) dan null. Kuncinya selalu ada; nilainya bisa null.

Apakah mode ketat berarti saya dapat sepenuhnya melewati validasi? Strukturnya dijamin, jadi Anda dapat melewati pemeriksaan bentuk. Namun, kata kunci seperti pattern, format, dan rentang numerik tidak ditegakkan oleh model, dan penolakan atau pemotongan masih dapat menghasilkan respons di luar spesifikasi. Uji kesesuaian masih memiliki nilai. Jika Anda baru mengenal format ini, panduan singkat Skema JSON ini mencakup blok bangunan dasar, dan Anda dapat menjalankan pemeriksaan pada setiap deployment.

Model mana yang harus saya gunakan? Keluaran terstruktur berfungsi pada GPT-4o dan yang lebih baru, termasuk seri GPT-5. Dokumentasi OpenAI mengarahkan proyek baru ke model unggulan mereka saat ini. Konfirmasikan bahwa ID model yang tepat mendukung mode ketat sebelum mengandalkannya, karena dukungan mengikuti versi model.

Ringkasan

Anda sekarang memiliki alur lengkapnya: pilih model yang mendukung mode ketat, kirim permintaan Chat Completions dengan json_schema dan strict: true, jaga skema Anda tetap dalam subset yang didukung, bercabang pada refusal, dan ingat bahwa aturan tingkat nilai masih perlu diperiksa. Kemudian buktikan dengan pengujian: bangun permintaan di Apidog, tegaskan respons terhadap skema Anda, dan tiru (mock) sehingga sisa tumpukan Anda dapat bergerak sementara integrasi stabil. Model menjanjikan bentuknya. Pengujian Anda membuktikan bahwa bentuk itu tetap terjaga.

button