JSON taattu skeeman mukaiseksi
Tällä sivulla
Miksi jäsennellyt tulostukset muuttavat kaiken
Kun käytät kielimallia tuotantoympäristössä, tarvitset vastauksia, joita koodi voi hyödyntää. Et vapaata tekstiä tai likimääräistä JSONia, vaan JSONia, joka on taatusti skeemasi mukainen. Juuri tätä Grok API:n jäsennellyt tulostukset tarjoavat sinulle.
Periaate on yksinkertainen: syötät mallille JSON-skeeman, ja API takaa, että vastaus noudattaa tätä rakennetta täsmällisesti. Ei satunnaista jäsennystä, ei hauraita säännöllisiä lausekkeita eikä try/catch-lohkoja tilanteisiin, joissa malli keksii oman formaattinsa.
Miten se toimii
Jäsennellyt tulostukset perustuvat rajoitusmekanismiin, jota sovelletaan tekstin generoinnin aikana. Jokaista tuotettua tokenia kohden malli pakotetaan tuottamaan vain annettuun skeemaan yhteensopivia tokeneita. Tulos: JSON, joka on aina validi ja aina vaatimusten mukainen.
Tarkastellaan konkreettista esimerkkiä. Haluat poimia yhteystiedot sähköpostiviestistä:
from pydantic import BaseModel
class Contact(BaseModel):
nom: str
email: str
entreprise: str
telephone: str | None
# Vastaus on AINA validi Contact-objekti
Ilman jäsenneltyjä tulostuksia malli saattaa palauttaa puhelinnumeron avaimella "tel", "phone" tai "numéro". Skeeman avulla kentän nimi on aina telephone, ja sen arvo on aina merkkijono tai null.
Saatavuus
Jäsennellyt tulostukset tuetaan kaikilla xAI:n kielimalleilla: Grok 4.5, Grok 4.3, grok-4.20-muunnelmat ja myöhemmät versiot. Riippumatta siitä, mitä mallia käytät, ominaisuus on saatavilla ilman lisäkustannuksia tai erityistä konfigurointia.
Ilman jäsenneltyjä tulostuksia vs. niiden kanssa
Tässä vertailu siitä, mitä saat ilman tätä ominaisuutta ja sen kanssa:
Ilman jäsenneltyjä tulostuksia:
- Malli saattaa palauttaa vapaata tekstiä, osittaista JSONia tai odottamattoman formaatin
- Sinun on jäsennettävä vastaus manuaalisesti ja käsiteltävä virheet
- Kenttien nimet voivat vaihdella pyynnöstä toiseen
- Putkesi hajoaa heti, kun malli muuttaa formaattia
Jäsennellyillä tulostuksilla:
- JSON on aina syntaktisesti validi
- Rakenne vastaa annettua skeemaa täsmällisesti
- Tyypit noudatetaan (merkkijono, numero, totuusarvo jne.)
- Koodisi voi kuluttaa vastauksen suoraan
Kaksi käytettävissä olevaa lähestymistapaa
Grok API tarjoaa kaksi tapaa hyödyntää jäsenneltyjä tulostuksia:
parse(): Automaattinen metodi, joka palauttaa tyypitetyn objektin suoraan. Ihanteellinen useimpiin tapauksiin.response_format: Manuaalinen metodi, joka palauttaa JSON-merkkijonon. Tarjoaa enemmän hallintaa, mutta jäsennys on sinun vastuullasi.
Tutustut näihin kahteen metodiin yksityiskohtaisesti seuraavissa oppitunneissa.
Keskeiset asiat
- Jäsennellyt tulostukset takaavat skeemasi mukaisen JSONin joka kutsulla
- Rajoitus sovelletaan generoinnin aikana, ei sen jälkeen
- Kaikki xAI:n kielimallit tukevat tätä ominaisuutta
- Käytettävissä on kaksi metodia:
parse()(automaattinen) jaresponse_format(manuaalinen) - Tämä on minkä tahansa luotettavan tuotantoputken perusta Grok API:a käytettäessä