Output Berstruktur LLM yang Rosak: Cara Sebenar Menulis Schema untuk Mod strict
Inti pati: Mengaktifkan strict pada JSON Schema rawak hampir sentiasa mengembalikan 400: semua medan required, additionalProperties:false pada setiap objek, $ref dan allOf ditolak serta-merta. Panduan ini menunjukkan cara menulis semula schema longgar kepada versi serasi strict — dengan union nullable, had ketat dan senarai semak refusal.

Intipati: strict: true bukan suis "jadi lebih serius" — ia adalah kontrak yang hanya menerima sebahagian kecil daripada JSON Schema. Semua medan required, additionalProperties: false pada setiap objek, $ref dan allOf dilarang serta-merta. Hantar schema dalam mod strict tanpa menulis semula, jawapannya ialah 400, bukan output yang boleh dipercayai.
Dalam amalan harian, situasi ini berulang dengan sama: pasukan mempunyai schema yang direka dengan baik, dengan medan pilihan, $defs yang boleh diguna semula dan additionalProperties yang terbuka untuk keserasian. Kemudian seseorang menambah "strict": true pada panggilan API, yakin bahawa model kini "akan menghormati" schema. Hasil segera ialah ralat 400 dengan mesej panjang, atau lebih teruk — schema diterima tetapi menghasilkan output yang tidak dijangka. Mod strict tidak mentafsir schema dengan bertolak ansur: ia menulis semula schema dari awal menjadi tatabahasa yang boleh diikuti enjin penjanaan secara literal, dan segala-galanya yang tidak muat dalam tatabahasa itu ditolak atau diabaikan secara senyap. Memahami peraturan yang benar-benar berkuat kuasa, sebelum menghantar permintaan, adalah perbezaan antara pipeline yang stabil dan seminggu debug.
Mod strict = JSON Schema anda dikompil menjadi tatabahasa yang mesti diikuti model perkata demi perkata. Segala-galanya yang tidak dapat dinyatakan oleh tatabahasa ditolak semasa penghantaran atau diabaikan secara senyap — dan dalam kedua-dua kes, masalah muncul selepas pengguna telah melihatnya.
Cara enjin mod strict sebenarnya berfungsi
Model tidak membaca JSON Schema anda seperti validator biasa. Apabila strict: true diaktifkan, schema ditukar menjadi tatabahasa terhad — automaton keadaan terhingga yang memutuskan token demi token susunan mana yang sah. Model hanya menjana peralihan yang dibenarkan oleh automaton; tiada kawalan selepas penjanaan yang membetulkan output — ketepatan adalah struktur.
Senibina ini menjelaskan semua gelagat yang kelihatan misteri. Jika medan tidak dimasukkan dalam required, automaton mesti memutuskan bila berhenti: satu-satunya penyelesaian selamat ialah memberi model kebebasan mengeluarkan null, jadi schema berkesan yang diterima enjin akan sentiasa mempunyai medan itu. Jika objek membenarkan sifat tambahan, automaton tidak boleh menjangka kunci apa yang akan muncul, jadi setiap objek mesti ditutup secara ketat. Setiap "dilarang" dalam dokumentasi lahir daripada had konkrit automaton ini, bukan pilihan gaya OpenAI.
Akibat kedua lebih licik: beberapa kata kunci JSON Schema (seperti pattern, minLength, maximum) adalah sah untuk schema tetapi tidak dikuatkuasakan oleh tatabahasa. Schema diterima, respons tiba bersih, tetapi kekangan tidak pernah dipatuhi. Ini cara paling senyap untuk merosakkan pipeline: pengesahan berikutnya gagal dalam produksi dan tiada log menunjukkan ralat schema.
Tiga peraturan yang tidak boleh dirunding
Jika anda hanya ada masa untuk membetulkan satu perkara, betulkan tiga ini. Ia menyelesaikan sebahagian besar kes 400.
1. Semua medan dalam required, sentiasa. Dalam mod strict, setiap kunci yang diisytiharkan dalam properties mesti muncul dalam required — termasuk yang pilihan. Trik rasmi untuk menyatakan "pilihan" ialah union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Dengan begitu automaton tahu tepat bila kunci itu sah, dan model menyatakan "tiada kupon" dengan null alih-alih menghilangkan kunci.
2. additionalProperties: false pada setiap objek. Bukan hanya pada objek akar: setiap objek bersarang, tanpa pengecualian. Satu tahap sahaja yang terbuka menjadikan keseluruhan schema tidak mematuhi.
3. $ref dan allOf dilarang. Tiada rujukan, tiada $defs, tiada komposisi. Schema mesti dikembangkan sepenuhnya — satu pokok tunggal yang berdiri sendiri. if/then/else dan oneOf di akar mengalami nasib yang sama.
Jadual istilah dilarang dan tidak berkesan
| Kata kunci | Hasil dalam mod strict | Pengganti disyorkan |
|---|---|---|
$ref, $defs |
Ditolak dengan 400 | Pengembangan penuh schema |
allOf |
Ditolak dengan 400 | Penggabungan sifat secara manual |
if/then/else |
Ditolak dengan 400 | enum + pengendalian di sisi klien |
oneOf di akar |
Masalah / respons tidak mematuhi | Satu objek akar sahaja |
Medan di luar required |
Ditukar kepada sentiasa diperlukan | Union nullable ["string", "null"] |
pattern, minLength |
Schema diterima tetapi kekangan diabaikan | Pengesahan eksplisit selepas respons |
maximum, format |
Schema diterima tetapi kekangan diabaikan | Semakan di sisi aplikasi |
Baris paling berbahaya ialah pasangan terakhir: schema lulus pengesahan tetapi kekangan tidak wujud. Jika logik anda mempercayai pattern, anda membina di atas pasir.
Had ketat yang tiada siapa baca
Sebelum menulis schema, pastikan anda berada dalam sempadan ini — melebihinya menghasilkan ralat umum yang sukar didiagnosis:
| Kekangan | Maksimum |
|---|---|
| Jumlah sifat bagi setiap schema | 5000 |
| Kedalaman bersarang | 10 tahap |
| Saiz rentetan schema | 120,000 aksara |
| Jumlah nilai enum | 1000 |
Schema yang dijana secara automatik daripada framework atau definisi OpenAPI sering melebihi had ini tanpa disedari: 6000 sifat keseluruhan, 12 tahap bersarang, 1500 nilai enum bertaburan. Mesej ralat API jarang menunjukkan ambang mana dilampaui, jadi lebih baik semak sendiri sebelum penghantaran.
Penulisan semula automatik: skrip make_strict
Untuk schema besar, penulisan semula manual tidak praktikal. Skrip Python ini menelusuri pokok dan menggunakan tiga peraturan secara rekursif:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# setiap sifat menjadi required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# medan "pilihan" mesti anda tandakan nullable dahulu
# buang perkara yang tidak diterima strict
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Dua amaran. Pertama: skrip tidak meneka medan mana yang pilihan — anda perlu menandakan union nullable sendiri, sebaiknya di sumber schema, bukan pada hasilnya. Kedua: selepas transformasi, sentiasa jalankan permintaan ujian: pengembangan boleh melebihi had saiz atau bilangan sifat yang sebelum ini dipatuhi.
Laluan setara dalam Anthropic
Anthropic tidak menawarkan bendera strict, tetapi mencapai hasil yang sama melalui mekanisme tool: definisi alat bertindak sebagai schema, dan model terikat pada bentuknya. Pendekatannya hampir identik:
const tool = {
name: "extract_invoice",
description: "Mengekstrak data invois daripada teks",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// model membalas dengan panggilan tool yang mematuhi
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
Peraturan praktikalnya sama: di Anthropic juga, setiap objek memerlukan required penuh dan additionalProperties: false. Perbezaannya pada saluran respons — tool_use selain kandungan teks — dan bahawa medan refusal adalah khusus OpenAI.
Refusal, pemotongan dan bentuk rosak: tiga kerosakan, tiga penawar
Walaupun dengan schema sempurna, output boleh gagal atas tiga sebab berbeza, dan mengelirukannya ialah cara terpantas untuk kehilangan sehari:
1. refusal tidak kosong. OpenAI dalam mod strict boleh memulangkan medan refusal dengan sebab permintaan ditolak. Ini bukan ralat schema — model menolak tugasan secara semantik. Penawarnya ialah menyemak semula prompt atau dasar, bukan schema.
2. Pemotongan disebabkan max_tokens. Penjanaan terputus di tengah rentetan dan JSON tidak tertutup. Dalam mod strict, respons yang tiba adalah mematuhi — tetapi jika belanjawan token habis, ia tiba terpotong. Naikkan max_tokens atau kurangkan saiz output yang dijangka. Untuk senario berulang, pembaikan automatik JSON terpotong mempunyai corak sedia guna.
3. Bentuk rosak tidak mematuhi. Schema terbuka (sifat tambahan dibenarkan, medan di luar required) dan strict tidak diaktifkan: model menghasilkan JSON sah yang tidak mematuhi kontrak. Penawarnya ialah menulis semula schema seperti dalam panduan ini, bukan menambah kawalan selepas penjanaan.
Diagnosis yang betul sentiasa bermula dengan membezakan tiga kes ini: lihat medan finish_reason, kewujudan refusal, dan bandingkan respons dengan schema yang benar-benar dihantar.
Senarai semak akhir sebelum ke produksi
| Titik semakan | Apa yang perlu disemak |
|---|---|
required lengkap |
Setiap sifat diisytiharkan wujud dalam required |
| Nullable eksplisit | Medan pilihan ialah union ["...", "null"] |
additionalProperties: false |
Pada setiap objek, bukan hanya akar |
Sifar $ref / allOf / if-then-else |
Schema dikembangkan sepenuhnya |
| Had dipatuhi | ≤ 5000 sifat, ≤ 10 tahap, ≤ 120k aksara |
| Kekangan tidak berkesan dipindahkan | pattern/format disemak di sisi aplikasi |
Pengendalian refusal |
Kod membezakan penolakan daripada ralat schema |
| Ujian dengan permintaan sebenar | Respons ujian disahkan sebelum deploy |
Jika anda ingin memahami mengapa additionalProperties: false begitu utama, analisis mendalam tentang kata kunci additionalProperties menunjukkan bagaimana setiap objek terbuka mengembangkan ruang penjanaan. Untuk memasukkan schema ke pipeline CI dengan ujian kontrak automatik, aliran yang diterangkan dalam JSON Schema contract testing menutup regresi senyap. Dan jika anda perlu membina schema daripada contoh JSON sedia ada, alat penukaran ke JSON Schema pada platform membolehkan anda bermula daripada data sebenar — namun untuk mod strict, anda tetap perlu menulis semula seperti dalam panduan ini.
FAQ
Mengapa dokumentasi mensyaratkan semua medan required, termasuk yang pilihan?
Kerana automaton keadaan terhingga mesti memutuskan lebih awal bila setiap kunci sah. "Kepilihan" dinyatakan dengan null, bukan dengan ketiadaan kunci: union nullable ialah cara rasmi untuk menyatakannya.
Schema diterima tetapi pattern tidak berfungsi. Adakah ini bug?
Bukan. Dalam mod strict, pattern, minLength, maximum dan format tidak dikuatkuasakan oleh tatabahasa penjanaan. Schema sah dari segi sintaks tetapi kekangan tidak wujud: semak di sisi aplikasi.
Bolehkah saya guna $ref jika saya isytihar $defs juga?
Tidak, kedua-duanya dilarang. Schema mesti satu pokok tunggal, dikembangkan sepenuhnya. Skrip penulisan semula automatik menguruskan pengembangan.
Apakah perbezaan antara refusal dan ralat schema? Refusal ialah respons yang mematuhi di mana model menyatakan secara semantik bahawa ia tidak mahu melaksanakan tugasan. Ralat schema ialah 400 semasa penghantaran atau output yang tidak mematuhi. Dua masalah berbeza dengan dua penawar berbeza.
Sedalam mana saya boleh bersarang objek? Maksimum 10 tahap bersarang dan 5000 sifat keseluruhan bagi setiap schema. Schema yang dijana automatik sering melebihi had ini: semak sebelum penghantaran.
Kesimpulan
Mod strict bukan pilihan kosmetik: ia adalah peralihan daripada "berharap model menghormati schema" kepada "tatabahasa secara fizikal menghalang output yang tidak mematuhi". Harganya ialah sebahagian kecil JSON Schema yang ketat — required penuh, objek tertutup, tiada rujukan — dan beberapa kekangan yang lalu tanpa diberi perhatian tetapi tidak dikuatkuasakan. Luangkan setengah jam untuk menulis semula dengan skrip make_strict, tandakan union nullable dengan berhemah, dan sentiasa uji dengan permintaan sebenar sebelum deploy: pipeline yang terhasil berbeza kualitinya daripada pipeline yang dibina atas retry dan pembetulan selepas kejadian.