Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

JSON taattu skeeman mukaiseksi

Oppitunti 1 / 12 Päivitetty 28. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi jäsennellyt tulostukset muuttavat kaiken
  2. Miten se toimii
  3. Saatavuus
  4. Ilman jäsenneltyjä tulostuksia vs. niiden kanssa
  5. Kaksi käytettävissä olevaa lähestymistapaa
  6. Keskeiset asiat

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.

100%
Taattu validi JSON
7
Tuetut tyypit
Kaikki
xAI-mallit
2
Kutsutavat

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) ja response_format (manuaalinen)
  • Tämä on minkä tahansa luotettavan tuotantoputken perusta Grok API:a käytettäessä