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:
- Kirim
json_schemadengan prompt yang memancing field ekstra (“tambahkan juga komentar singkat”). - Jika permintaan error, penyedia tidak menerima
json_schema. Cobajson_object. - Jika balasannya berisi field ekstra itu, skema tidak ditegakkan. Perlakukan sebagai JSON mode.
- Jika
json_objectjuga 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_reasonlebih dulu. Balasan yang menyentuhmax_tokensadalah 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:
- Datar lebih baik daripada bersarang. Dua level sudah lebih dari cukup untuk sebagian besar ekstraksi.
- Enum alih-alih string bebas untuk kategori.
- Hindari objek terbuka. Field
dictberbentuk bebas menghilangkan manfaatnya. - Nama field pendek dengan deskripsi. Deskripsi di skema memandu model.
- 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.
