Data ang kailangan ng code mo, at text ang isinusulat ng mga model. Pinagdudugtong ng structured output ang dalawa, pero tatlong magkakaibang bagay ang ibig sabihin ng “nagbabalik ng JSON ang model” depende sa kung paano ka humingi. Ikinukumpara ng post na ito ang mga opsyon sa mga OpenAI-compatible na open model, ipinapakita kung paano hingin ang bawat isa, at nagbibigay ng validate-and-repair loop na puwede mong ilagay agad sa production.
Ano ang pagkakaiba ng JSON mode at json_schema?
| Paraan | Request | Ano ang ipinapangako sa iyo |
|---|---|---|
| Prompt lang | “Sumagot sa JSON na may mga field na…” | Wala; kadalasan JSON, minsan may sobrang text |
| JSON mode | response_format: {"type": "json_object"} |
Valid na JSON, kahit anong hugis |
| Structured output | response_format: {"type": "json_schema", ...} |
JSON na tugma sa schema mo, kung ipinapatupad |
Diretsahan ito sa Structured Outputs guide ng OpenAI: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (salin: Bagama’t parehong tinitiyak na valid na JSON ang nagagawa, Structured Outputs lang ang tumitiyak na sinusunod ang schema.) Inirerekomenda nito ang structured output kaysa JSON mode kung posible.
Sa mga provider ng open model, nakadepende ang garantiya sa kung paano ito ipinatupad ng server. Marami ang gumagamit ng constrained decoding, na hinaharangan ang mga token na sisira sa schema. May iba na tumatanggap ng field pero hindi ito ipinapatupad. Kaya nagva-validate pa rin ang code sa ibaba, anuman ang mangyari.
Paano humingi ng 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}}
Ginagawa ng Pydantic ang JSON Schema mula sa class mo, kaya hindi kailanman magkakalayo ang schema at ang validator. Kung hindi ka gumagamit ng Pydantic, gumagawa ang JSON schema generator ng strict-mode na schema mula sa isang sample na object. Para sa strict mode, hinihingi ng OpenAI ang additionalProperties: false at na nakalistang required ang bawat property.
Aling mode ang sinusuportahan ng provider mo?
Patakbuhin ang test na ito nang isang beses kada model bago ka mag-build dito:
- Magpadala ng
json_schemana may prompt na nag-iimbita ng sobrang field (“magdagdag ka rin ng maikling komento”). - Kung nag-error ang request, hindi tumatanggap ng
json_schemaang provider. Subukan angjson_object. - Kung may sobrang field ang sagot, hindi ipinapatupad ang schema. Ituring itong JSON mode.
- Kung nag-error din ang
json_object, gumamit ng prompt lang na may validation.
Sa BroadNet Inference, nakalista sa docs ang structured output para sa GLM 5.3 at Qwen3.8 27B (magkatabing paghahambing), pero hindi nito pinapangalanan ang request parameter. Patakbuhin ang test sa itaas sa model na isi-ship mo.
Paano i-validate at ayusin ang maling output?
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")
Ito ang nagpapagana sa loop na ito:
- Unahing i-check ang
finish_reason. Putol na JSON ang sagot na tumama samax_tokens. Papalya rin sa parehong paraan ang retry na may parehong limit. Parehong nagre-reason ang dalawang model sa itaas bago sumagot, at binibilang ang reasoning sa limit, kaya mag-iwan ng puwang. - Hiwalay na hawakan ang refusal. Sinasabi ng guide ng OpenAI na ang refusal ay “does not necessarily follow the schema you have supplied” (salin: hindi kinakailangang sumusunod sa schema na ibinigay mo).
- Ibalik ang eksaktong error. Kadalasan, ibinabalik ng bulag na retry ang parehong mali. May maaayos ang model kapag binigyan mo ng “line_items: field required”.
- I-check sa code ang mga business rule. Hindi masasabi ng schema na dapat katumbas ng total ang kabuuan ng line items nito. Kaya iyon ng check sa itaas.
- Limitahan ang bilang ng subok. Ipinapadala ulit ng bawat subok ang buong prompt bilang input token.
Aling mga feature ng schema ang nagdudulot ng problema?
Panatilihing simple ang mga schema:
- Mas mabuti ang flat kaysa nested. Sapat na ang dalawang level para sa karamihan ng extraction.
- Enum imbes na malayang string para sa mga kategorya.
- Walang open-ended na object. Tinatalo ng mga free-form na
dictfield ang layunin. - Maiikling pangalan ng field na may description. Ginagabayan ng mga description sa schema ang model.
- Nullable ang mga optional na field. Sa strict mode, ilista ang bawat field bilang required at payagan ang
null.
Sinasabi ng guide ng OpenAI na may ilang feature ng JSON Schema na hindi suportado sa strict mode. May sarili ring limit ang mga server ng open model. Kung tinanggihan ang isang schema, pasimplehin muna ito bago magpalit ng mode.
Paano i-monitor ang structured output sa production?
Puwedeng itago ng loop na tahimik na nag-aayos ang isang problemang gumagastos sa iyo ng token araw-araw. Mag-log ng tatlong numero kada call site:
| Metric | Ano ang sinasabi nito sa iyo |
|---|---|
| Success rate sa unang subok | Gaano kabagay ang model at schema; madalas bumaba ito pagkatapos magbago ang prompt o model |
| Average na bilang ng subok kada tagumpay | Ang gastos sa token ng mga repair |
| Mga huling failure | Mga input na hindi kaya ng pipeline mo; suriin ang mga ito nang mano-mano |
Kung bumaba ang success sa unang subok kumpara sa nakasanayan mo, pasimplehin ang schema o sumubok ng ibang model bago ka magdagdag ng mas maraming retry. Magtabi ng sample ng mga raw na sagot na pumalya, para ma-test mo ang mga ayos laban sa totoong mga kaso.
Kailan mas mabuting gumamit ng tool?
Gamitin ang structured output para sa huling sagot: isang extraction, isang classification, isang plano. Gamitin ang tool calling kapag kailangan ng model na may gawin ang code mo at saka magpatuloy. Maraming agent ang gumagamit ng dalawa: tools habang nasa loop, schema para sa huling hakbang. Para sa halimbawa ng image-to-JSON, tingnan ang pagbasa ng mga Arabic invoice gamit ang vision model.
Saan pumapasok ang BroadNet Inference
Nakalista sa BroadNet Inference ang structured output para sa GLM 5.3 at Qwen3.8 27B, sa likod ng standard na chat-completions format, kaya tumatakbo ang code sa itaas gamit ang OpenAI Python SDK nang walang binabago. Tumatanggap din ng larawan ang Qwen3.8 27B, na bagay sa document extraction. Hindi sinasabi ng docs ng BroadNet na may structured output ang DeepSeek V4.1 Flash o Gemma 4 VL 26B, kaya gamitin doon ang prompt lang na may validation. Ikumpara ang presyo kada token sa pricing page.
