BroadRouter
Mulai

JSON mode vs json_schema: output terstruktur yang andal

Oleh tim BroadNet Inference · 4 menit baca · Dipublikasikan

JSON mode (response_format json_object) hanya menjanjikan JSON yang valid. Output terstruktur (response_format json_schema) juga menjanjikan field dan tipe data Anda, sejauh penyedia menegakkannya. Apa pun pilihannya, cek finish_reason, parse hasilnya, lalu validasi terhadap skema seperti model Pydantic. Jika validasi gagal, kirim error-nya kembali dan minta ulang, dengan batas percobaan yang tegas.

Kode Anda butuh data, sedangkan model menulis teks. Output terstruktur menjembatani celah itu, tetapi “model mengembalikan JSON” bisa berarti tiga hal berbeda tergantung cara Anda memintanya. Artikel ini membandingkan opsinya di model open yang kompatibel OpenAI, menunjukkan cara meminta masing-masing, dan memberi loop validasi-dan-perbaikan yang bisa langsung Anda pasang di produksi.

Apa beda JSON mode dan json_schema?

Metode Permintaan Yang dijanjikan
Prompt saja “Balas dalam JSON dengan field…” Tidak ada; biasanya JSON, kadang dengan teks tambahan
JSON mode response_format: {"type": "json_object"} JSON valid, bentuk apa pun
Output terstruktur response_format: {"type": "json_schema", ...} JSON yang sesuai skema Anda, jika ditegakkan

Panduan Structured Outputs OpenAI mengatakannya terus terang: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (Terjemahan BroadRouter: “Meski keduanya memastikan JSON yang dihasilkan valid, hanya Structured Outputs yang menjamin kepatuhan pada skema.”) Panduan itu merekomendasikan output terstruktur dibanding JSON mode bila memungkinkan.

Di penyedia model open, jaminannya bergantung pada cara server mengimplementasikannya. Banyak yang memakai constrained decoding, yang memblokir token yang akan merusak skema. Ada juga yang menerima field-nya tetapi tidak menegakkannya. Itulah sebabnya kode di bawah tetap melakukan validasi.

Bagaimana cara meminta json_schema?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic menghasilkan JSON Schema dari class Anda, sehingga skema dan validatornya tidak pernah selisih. Jika Anda tidak memakai Pydantic, generator JSON schema membuat skema mode strict dari objek contoh. Untuk mode strict, OpenAI mewajibkan additionalProperties: false dan setiap properti dicantumkan sebagai required.

Mode mana yang didukung penyedia Anda?

Jalankan uji ini sekali per model sebelum membangun sesuatu di atasnya:

  1. Kirim json_schema dengan prompt yang memancing field ekstra (“tambahkan juga komentar singkat”).
  2. Jika permintaan error, penyedia tidak menerima json_schema. Coba json_object.
  3. Jika balasannya berisi field ekstra itu, skema tidak ditegakkan. Perlakukan sebagai JSON mode.
  4. Jika json_object juga error, pakai prompt saja dengan validasi.

Di BroadNet Inference, dokumentasinya mencantumkan output terstruktur untuk GLM 5.3 dan Qwen3.8 27B (perbandingan berdampingan), tetapi tidak menyebut nama parameter permintaannya. Jalankan uji di atas pada model yang akan Anda rilis.

Bagaimana memvalidasi dan memperbaiki output yang buruk?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

Yang membuat loop ini berhasil:

  • Cek finish_reason lebih dulu. Balasan yang menyentuh max_tokens adalah JSON yang terpotong. Mencoba ulang dengan batas yang sama akan gagal dengan cara yang sama. Kedua model di atas melakukan penalaran sebelum menjawab, dan penalaran ikut dihitung dalam batas itu, jadi sisakan ruang.
  • Tangani penolakan secara terpisah. Panduan OpenAI mencatat bahwa penolakan “does not necessarily follow the schema you have supplied” (Terjemahan BroadRouter: “belum tentu mengikuti skema yang Anda berikan”).
  • Kirim kembali error yang persis. Retry buta sering mengembalikan kesalahan yang sama. “line_items: field required” memberi model sesuatu yang konkret untuk diperbaiki.
  • Cek aturan bisnis di kode. Skema tidak bisa menyatakan bahwa total harus sama dengan jumlah rinciannya. Pengecekan di atas bisa.
  • Batasi percobaan. Setiap percobaan mengirim ulang seluruh prompt sebagai token input.

Fitur skema apa yang sering bermasalah?

Buat skema sesederhana mungkin:

  1. Datar lebih baik daripada bersarang. Dua level sudah lebih dari cukup untuk sebagian besar ekstraksi.
  2. Enum alih-alih string bebas untuk kategori.
  3. Hindari objek terbuka. Field dict berbentuk bebas menghilangkan manfaatnya.
  4. Nama field pendek dengan deskripsi. Deskripsi di skema memandu model.
  5. Field opsional dibuat nullable. Di mode strict, cantumkan setiap field sebagai required dan izinkan null.

Panduan OpenAI mencatat beberapa fitur JSON Schema tidak didukung di mode strict. Server model open juga punya batasannya sendiri. Jika skema ditolak, sederhanakan dulu sebelum mengganti mode.

Bagaimana memantau output terstruktur di produksi?

Loop yang memperbaiki diam-diam bisa menyembunyikan masalah yang setiap hari menghabiskan token Anda. Catat tiga angka per titik pemanggilan:

Metrik Yang ditunjukkannya
Tingkat keberhasilan percobaan pertama Seberapa cocok model dan skema; penurunan sering terjadi setelah perubahan prompt atau model
Rata-rata percobaan per keberhasilan Biaya token dari perbaikan
Kegagalan akhir Input yang tidak bisa ditangani pipeline Anda; tinjau secara manual

Jika keberhasilan percobaan pertama turun di bawah biasanya, sederhanakan skema atau coba model lain sebelum menambah retry. Simpan sampel balasan mentah yang gagal agar Anda bisa menguji perbaikan pada kasus nyata.

Kapan sebaiknya memakai tool?

Pakai output terstruktur untuk jawaban akhir: ekstraksi, klasifikasi, rencana. Pakai tool calling saat model perlu kode Anda melakukan sesuatu lalu melanjutkan. Banyak agen memakai keduanya: tools selama loop, skema untuk langkah terakhir. Untuk contoh gambar-ke-JSON, lihat membaca faktur bahasa Arab dengan model vision.

Posisi BroadNet Inference

BroadNet Inference mencantumkan output terstruktur untuk GLM 5.3 dan Qwen3.8 27B, di balik format chat completions standar, sehingga kode di atas berjalan dengan SDK Python OpenAI tanpa perubahan. Qwen3.8 27B juga menerima gambar, cocok untuk ekstraksi dokumen. Dokumentasi BroadNet tidak menyebut output terstruktur untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi di sana pakai jalur prompt saja dengan validasi. Bandingkan harga per token di halaman harga.

Pertanyaan umum

Apa beda JSON mode dan output terstruktur?

JSON mode, response_format tipe json_object, hanya menjanjikan balasan bisa di-parse sebagai JSON. Output terstruktur, tipe json_schema, juga menjanjikan field dan tipe yang Anda definisikan, sejauh penyedia menegakkannya. OpenAI merekomendasikan output terstruktur dibanding JSON mode bila memungkinkan.

Apakah model open mendukung response_format json_schema?

Tergantung penyedianya. Ada yang menerima json_schema, ada yang hanya json_object, dan ada yang mengabaikan field itu. Kirim permintaan uji dengan skema dan prompt yang memancing model menambahkan field ekstra, lalu cek balasannya.

Apakah output terstruktur masih perlu divalidasi?

Ya. Balasan bisa terpotong oleh max_tokens, bisa berupa penolakan, dan bisa melanggar aturan bisnis yang tidak bisa diekspresikan skema, misalnya total yang harus pas dengan jumlah rinciannya.

Berapa kali JSON yang tidak valid sebaiknya dicoba ulang?

Dua atau tiga percobaan dengan menyertakan error validasinya biasanya cukup. Setelah itu, catat input-nya dan arahkan ke jalur cadangan, model yang lebih kuat, atau manusia. Loop tanpa batas membuang token.

Sebaiknya pakai output terstruktur atau tool calling?

Pakai output terstruktur jika Anda ingin jawaban akhir dalam bentuk yang tetap. Pakai tool calling jika model perlu kode Anda melakukan sesuatu lalu melanjutkan.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity