Kod anda memerlukan data, dan model menulis teks. Output berstruktur merapatkan jurang itu, tetapi “model memulangkan JSON” membawa tiga maksud berbeza bergantung pada cara anda meminta. Artikel ini membandingkan pilihan pada model terbuka yang serasi OpenAI, menunjukkan cara meminta setiap satu, dan memberi gelung sahkan-dan-baiki yang boleh terus dimasukkan ke pengeluaran.
Apakah perbezaan antara JSON mode dan json_schema?
| Kaedah | Permintaan | Apa yang dijanjikan |
|---|---|---|
| Prompt sahaja | “Balas dalam JSON dengan medan…” | Tiada; biasanya JSON, kadangkala dengan teks tambahan |
| JSON mode | response_format: {"type": "json_object"} |
JSON yang sah, apa-apa bentuk |
| Output berstruktur | response_format: {"type": "json_schema", ...} |
JSON yang sepadan dengan skema anda, jika dikuatkuasakan |
Panduan Structured Outputs OpenAI menyatakannya dengan terus: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (Terjemahan: Walaupun kedua-duanya memastikan JSON yang sah dihasilkan, hanya Structured Outputs yang memastikan pematuhan skema.) Ia mengesyorkan output berstruktur berbanding JSON mode bila-bila masa yang boleh.
Pada penyedia model terbuka, jaminannya bergantung pada cara pelayan melaksanakannya. Banyak yang menggunakan penyahkodan terkekang, yang menyekat token yang akan melanggar skema. Sesetengahnya menerima medan itu tetapi tidak menguatkuasakannya. Itulah sebabnya kod di bawah tetap mengesahkan.
Bagaimanakah 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 menjana JSON Schema daripada kelas anda, jadi skema dan pengesah tidak akan pernah tersasar. Jika anda tidak menggunakan Pydantic, penjana skema JSON membina skema strict mode daripada objek sampel. Untuk strict mode, OpenAI memerlukan additionalProperties: false dan setiap sifat disenaraikan sebagai wajib.
Mod manakah yang disokong oleh penyedia anda?
Jalankan ujian ini sekali bagi setiap model sebelum membina di atasnya:
- Hantar
json_schemadengan prompt yang mengundang medan tambahan (“tambahkan juga komen ringkas”). - Jika permintaan menghasilkan ralat, penyedia tidak menerima
json_schema. Cubajson_object. - Jika jawapan mengandungi medan tambahan itu, skema tidak dikuatkuasakan. Anggap ia sebagai JSON mode.
- Jika
json_objectjuga menghasilkan ralat, gunakan prompt sahaja dengan pengesahan.
Di BroadNet Inference, dokumentasi menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B (dibandingkan bersebelahan), tetapi tidak menamakan parameter permintaan. Jalankan ujian di atas pada model yang anda gunakan dalam produk.
Bagaimanakah mengesahkan dan membaiki output yang rosak?
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")
Apa yang membuat gelung ini berfungsi:
- Semak
finish_reasondahulu. Jawapan yang mencapaimax_tokensialah JSON yang terpotong. Mencuba semula dengan had yang sama gagal dengan cara yang sama. Kedua-dua model di atas membuat penaakulan sebelum menjawab, dan penaakulan dikira dalam had, jadi beri ruang. - Kendalikan penolakan secara berasingan. Panduan OpenAI menyatakan penolakan “does not necessarily follow the schema you have supplied” (Terjemahan: tidak semestinya mengikut skema yang anda berikan).
- Hantar semula ralat yang tepat. Cuba semula secara membuta tuli sering memulangkan kesilapan yang sama. “line_items: field required” memberi model sesuatu untuk dibetulkan.
- Semak peraturan perniagaan dalam kod. Skema tidak boleh menyatakan bahawa jumlah mesti sama dengan item barisnya. Semakan di atas boleh.
- Hadkan cubaan. Setiap cubaan menghantar semula keseluruhan prompt sebagai token input.
Ciri skema manakah yang menimbulkan masalah?
Pastikan skema ringkas dan membosankan:
- Rata lebih baik daripada bersarang. Dua tahap sudah memadai untuk kebanyakan pengekstrakan.
- Enum dan bukannya rentetan bebas untuk kategori.
- Tiada objek terbuka. Medan
dictbentuk bebas mematahkan tujuannya. - Nama medan pendek dengan penerangan. Penerangan dalam skema membimbing model.
- Medan pilihan sebagai nullable. Dalam strict mode, senaraikan setiap medan sebagai wajib dan benarkan
null.
Panduan OpenAI menyatakan sesetengah ciri JSON Schema tidak disokong dalam strict mode. Pelayan model terbuka mempunyai had mereka sendiri. Jika skema ditolak, permudahkannya sebelum menukar mod.
Bagaimanakah memantau output berstruktur dalam pengeluaran?
Gelung yang membaiki secara senyap boleh menyembunyikan masalah yang membazirkan token setiap hari. Log tiga angka bagi setiap tempat panggilan:
| Metrik | Apa yang diberitahunya |
|---|---|
| Kadar kejayaan cubaan pertama | Sejauh mana model dan skema sepadan; penurunan sering berlaku selepas perubahan prompt atau model |
| Purata cubaan bagi setiap kejayaan | Kos token untuk pembaikan |
| Kegagalan akhir | Input yang tidak dapat dikendalikan pipeline anda; semaknya secara manual |
Jika kejayaan cubaan pertama jatuh di bawah tahap biasa, permudahkan skema atau cuba model lain sebelum menambah lebih banyak cuba semula. Simpan sampel jawapan mentah yang gagal, supaya anda boleh menguji pembetulan terhadap kes sebenar.
Bilakah anda patut menggunakan tool sebaliknya?
Gunakan output berstruktur untuk jawapan akhir: pengekstrakan, klasifikasi, pelan. Gunakan panggilan tools apabila model memerlukan kod anda untuk melakukan sesuatu dan meneruskan. Banyak ejen menggunakan kedua-duanya: tools semasa gelung, skema untuk langkah terakhir. Untuk contoh imej ke JSON, lihat membaca invois bahasa Arab dengan model visi.
Di manakah BroadNet Inference sesuai
BroadNet Inference menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B, di sebalik format chat-completions standard, jadi kod di atas berjalan dengan SDK Python OpenAI tanpa perubahan. Qwen3.8 27B juga menerima imej, yang sesuai untuk pengekstrakan dokumen. Dokumentasi BroadNet tidak menyatakan output berstruktur untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi gunakan laluan prompt sahaja dengan pengesahan di sana. Bandingkan harga setiap token di halaman harga.
