JSON z zagotovljeno shemo
Na tej strani
Zakaj strukturirani izhodi spremenijo vse
Ko jezični model uporabljaš v produkcijskem okolju, potrebuješ odzive, ki jih koda lahko neposredno uporabi. Ne prostega besedila, ne približnega JSON-a – temveč JSON, ki je zagotovljeno skladen s shemo, ki jo določiš. Točno to ti ponujajo strukturirani izhodi API-ja Grok.
Načelo je preprosto: modelu predložiš shemo JSON, API pa zagotavlja, da bo odgovor točno sledil tej strukturi. Brez naključnega razčlenjevanja, brez krhkih regularnih izrazov, brez blokov try/catch za obravnavo primerov, ko model izumi svojo obliko.
Kako deluje
Strukturirani izhodi temeljijo na mehanizmu omejitev, ki se uporabi med generiranjem besedila. Ob vsakem ustvarjenem žetonu je model omejen tako, da generira le žetone, združljive z dano shemo. Rezultat? JSON, ki je vedno veljaven in vedno skladen.
Poglejmo konkreten primer. Iz e-poštnega sporočila želiš izvleči kontaktne podatke:
from pydantic import BaseModel
class Contact(BaseModel):
nom: str
email: str
entreprise: str
telephone: str | None
# Odziv bo VEDNO veljaven objekt Contact
Brez strukturiranih izhodov bi model lahko vrnil telefonsko številko pod ključem "tel", "phone" ali "numéro". S shemo bo polje vedno imenovano telephone, njegova vrednost pa bo vedno niz ali null.
Razpoložljivost
Strukturirani izhodi so podprti na vseh jezičnih modelih xAI: Grok 4.5, Grok 4.3, različicah grok-4.20 in novejših. Ne glede na to, kateri model uporabljaš, je funkcija na voljo brez dodatnih stroškov ali dodatne konfiguracije.
Brez strukturiranih izhodov v primerjavi z njimi
Tukaj je pregled razlik med uporabo te funkcije in brez nje:
Brez strukturiranih izhodov:
- Model lahko vrne prosto besedilo, delni JSON ali nepričakovano obliko
- Ročno moraš razčleniti odgovor in obravnavati napake
- Imena polj se lahko od zahteve do zahteve spreminjajo
- Tvoj cevovod se poruši takoj, ko model spremeni obliko
S strukturiranimi izhodi:
- JSON je vedno sintaktično veljaven
- Struktura točno ustreza predloženi shemi
- Tipi so spoštovani (niz, število, boolean itd.)
- Tvoja koda lahko odgovor neposredno porabi
Dva razpoložljiva pristopa
API Grok ponuja dva načina uporabe strukturiranih izhodov:
parse(): Samodejna metoda, ki neposredno vrne tipiziran objekt. Idealna za večino primerov uporabe.response_format: Ročna metoda, ki vrne niz JSON. Omogoča več nadzora, vendar moraš razčlenjevanje opraviti sam.
Ti dve metodi boš podrobneje spoznal v naslednjih lekcijah.
Ključne ugotovitve
- Strukturirani izhodi zagotavljajo JSON, skladen s tvojo shemo, pri vsakem klicu
- Omejitev se uporabi med generiranjem, ne po njem
- To funkcijo podpirajo vsi jezični modeli xAI
- Na voljo sta dve metodi:
parse()(samodejna) inresponse_format(ročna) - To je temelj vsakega zanesljivega produkcijskega cevovoda z API-jem Grok