Luotettava JSON mistä tahansa LLM:stä: Pydantic + Zod -mallit vuodelle 2026

LLM:n jäsennelty tuloste on mekanismi, joka takaa kielen mallin vastauksen noudattavan ennalta määriteltyä skeemaa – ei vain kelvollista JSONia, vaan skeemavalidointia läpäissyttä JSONia täsmälleen määrittämilläsi kentillä, tyypeillä ja rajoituksilla. Jokainen merkittävä palveluntarjoaja tukee sitä nyt natiivisti, ja se on muuttanut tapaa, jolla tuotannossa olevia LLM-sovelluksia rakennetaan.

Pika yhteenveto: Jäsennellyt tulosteet silmäyksen alta

Jos sinulla on kiire, tässä on tilanne vuonna 2026:

Puretaan nyt kukin osa erikseen.

Mitä ovat LLM:n jäsennellyt tulosteet?

Jäsennelty tuloste on ero siinä, toivoo LLM:n palauttavan kelvollista JSONia ja takaa sen. Kun otat jäsennellyn tulosteen käyttöön, malli ei fyysisesti pysty tuottamaan tokeneita, jotka rikkoisivat skeemaasi. Määrittelet JSON-skeeman (tai Pydantic-mallin tai Zod-skeeman), välität sen API:lle ja saat takaisin vastauksen, joka vastaa sitä joka kerta.

Miksi tämä on tärkeää? Ennen jäsenneltyjä tulosteita kehittäjät kirjoittivat hauraita regex-parserit, kietovat jokaisen LLM-kutsun try/catch JSON.parse -lohkoihin ja kamppailivat silti "lähes oikeiden" vastausten kanssa – kelvollisen JSONin, josta puuttui kenttä tai jossa oli väärä tyyppi. Koko tämä bugiluokka on poistunut.

Rakenteen valvonnassa on kolme tasoa, ja ne edustavat selkeää evoluutiota:

1. Prompt-engineering, "Palauta JSON näillä kentillä." Epäluotettava. Malli saattaa totella 80–90 %:n todennäköisyydellä.
2. JSON-tila, Takaa syntaktisesti kelvollisen JSONin, mutta ei valvo skeemaasi. Voit saada {"foo": "bar"}, kun odotit {"name": string, "age": number}.
3. Tiukka tila / Rajoitettu dekoodaus, Takaa 100-prosenttisen skeeman noudattamisen. Malli ei kirjaimellisesti voi tuottaa virheellisiä tokeneita. Tämä on se, mitä "jäsennelty tuloste" tarkoittaa vuonna 2026.

Vuoden 2026 alkuun mennessä OpenAI, Anthropic ja Google Gemini tukevat kaikki natiivia jäsenneltyä tulostetta. Ekosysteemi on konvergoitunut.

Tuomio: Jos jäsentää LLM-vastauksia regexillä tai JSON.parsella tuotannossa, teet sen vaikealla tavalla. Natiivi jäsennelty tuloste poistaa koko tämän vikatilan.

JSON-tila vs. Tiukka tila: Mikä todella muuttui?

Tämä ero saa monet kehittäjät hämilleen, koska nimet kuulostavat samankaltaisilta. Ne eivät ole.

Aikajana: OpenAI esitteli JSON-tilan vuoden 2023 lopulla. Se oli askel eteenpäin, mutta kehittäjät huomasivat nopeasti, että "kelvollinen JSON" ei riittänyt, he tarvitsivat skeemavalidia JSONia. Elokuussa 2024 OpenAI lanseerasi Jäsennellyt tulosteet Tiukalla tilalla, joka käyttää rajoitettua dekoodausta taatakseen skeeman noudattamisen. Vuoteen 2025–2026 mennessä jokainen merkittävä palveluntarjoaja oli omaksunut saman lähestymistavan.

JSON-tilalla on edelleen kapea käyttötarkoitus: kun et todellakaan tiedä vastauksen muotoa etukäteen ja haluat vain jonkin kelvollisen JSONin rakenteettomaan tutkimiseen. Mutta tämä on harvinaista tuotannossa.

Tuomio: Käytä Tiukkaa tilaa kaikkeen tuotannossa. JSON-tila on käytännössä vanhentunut skeemasidonnaisiin käyttötarkoituksiin. Jos sinulla on skeema (ja sellainen pitäisi olla), käytä type: "json_schema" asetuksella strict: true.

Miten rajoitettu dekoodaus todella toimii?

Tässä on mekanismi, joka mahdollistaa 100-prosenttisen skeeman noudattamisen – ei 99,9 %, vaan kirjaimellisesti 100 %.

Kun lähetät JSON-skeeman palveluntarjoajalle Tiukka tila käytössä, skeema käännetään äärelliseksi automaatiksi (FSM). Tämä FSM edustaa jokaista kelvollista polkua skeemassasi. Jokaisessa tokenin generointivaiheessa päättelymoottori tarkistaa, mitkä tokenit pitävät tulosteen kelvollisella polulla ja mitkä eivät. Virheellisten tokenien logitit asetetaan negatiiviseen äärettömyyteen ennen otantaa, mikä tarkoittaa, että niiden todennäköisyys valikoitua on nolla.

Ajattele sitä kuin autocompletea steroideilla. Jos malli on juuri tuottanut {"rating": ja skeemasi sanoo, että rating on kokonaisluku, ainoat sallitut seuraavat tokenit ovat numerotokeneita. Lainausmerkit, kirjaimet, sulut, kaikki maskataan pois. Malli ei voi tuottaa "five", vaikka se "haluaisi".

Tämä on sama ydinmekanismi, jota käyttävät XGrammar (vLLM:n, SGLangin ja useimpien paikallisten päättelypalvelimien moottori) ja Outlines (avoin lähdekoodi -Python-kirjasto rajoitettua generointia varten). API-palveluntarjoajat ovat vain rakentaneet sen osaksi päättelyinfrastruktuuriaan.

On yksi kompromissi, joka kannattaa tietää: ensimmäinen pyyntö uudella skeemalla aiheuttaa käännösviiveen (tyypillisesti 50–200 ms), kun FSM rakennetaan. Myöhemmät pyynnöt samalla skeemalla käyttävät välimuistissa olevaa FSM:ää ja lisäävät lähes olemattoman kuorman. On myös hienovarainen laadullinen näkökohta: tokenisanaston rajoittaminen voi joskus heikentää tulosteen laatua luovissa tai vapaamuotoisissa kentissä, joten pidä skeemasi keskittyneenä aidosti jäsenneltyyn dataan.

Tuomio: Rajoitettu dekoodaus on se, mikä erottaa "yleensä toimii" ja "aina toimii". Se on insinööritaito, joka tekee jäsennellystä tulosteesta tuotantovalmiin.

Monen palveluntarjoajan toteutus: OpenAI, Anthropic ja Gemini

Tässä on jotain, mitä muut oppaat eivät näytä sinulle: sama purkutehtävä toteutettuna kaikilla kolmella suurella palveluntarjoajalla. Puramme jäsennellyn tuotearvion jäsentämättömästä tekstistä.

Pydantic-skeema (jaettu kaikkien palveluntarjoajien kesken):

from pydantic import BaseModel, Field
from typing import Literal

class ProductReview(BaseModel):
    reasoning: str = Field(description="Think through the review before scoring")
    rating: int = Field(description="Rating from 1-5", ge=1, le=5)
    sentiment: Literal["positive", "negative", "neutral"]
    pros: list[str] = Field(description="Key positive points")
    cons: list[str] = Field(description="Key negative points")
    summary: str = Field(description="One-sentence summary")

OpenAI-toteutus

from openai import OpenAI

client = OpenAI()

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract a structured review from the text."},
        {"role": "user", "content": review_text}
    ],
    response_format=ProductReview,  # Pydantic model directly
)

review = response.choices[0].message.parsed  # Typed ProductReview object

OpenAI:n toteutus on kypsynein. parse()-metodi hyväksyy Pydantic-mallin suoraan ja palauttaa tyypitetyn objektin. Yksi rajoitus: OpenAI:n Tiukka tila tukee osajoukkoa JSON-skeemasta, ei $ref:iä, rajoitettu anyOf, ja kaikkien kenttien on oltava pakollisia asetuksella additionalProperties: false.

Anthropic-toteutus

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": f"Extract a structured review:\n\n{review_text}"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "json_schema": ProductReview.model_json_schema()
        }
    }
)

import json
review_data = json.loads(response.content[0].text)
review = ProductReview(**review_data)

Anthropicin natiivi jäsennelty tuloste käyttää output_config.format-asetusta JSON-skeeman kanssa. Se saavutti GA-statukseen (General Availability) vuoden 2026 alussa. Anthropic tukee myös vanhempaa mallia määritellä "vale"-työkalu ja purkaa sen kautta tool_use, joka toimii edelleen, mutta natiivi jäsennelty tuloste on siistimpi puhtaaseen purkamiseen.

Gemini-toteutus

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=f"Extract a structured review:\n\n{review_text}",
    config={
        "response_mime_type": "application/json",
        "response_schema": ProductReview,  # Pydantic model directly
    }
)

import json
review = ProductReview(**json.loads(response.text))

Gemini tukee Pydantic-malleja suoraan Python SDK:ssa response_schema-parametrin kautta. Ainutlaatuinen ominaisuus: Gemini kunnioittaa skeeman propertyOrdering-asetusta, joten voit ohjata kenttien tulostejärjestystä (hyödyllinen päättely-ensin-mallille).

Palveluntarjoajien vertailu

Tuomio: OpenAI:ssa on hiotuin DX sen parse()-metodin ansiosta. Anthropic tarjoaa kyvykkäimmät perusmallit. Geminin ominaisuuksien järjestys on ainutlaatuisen hyödyllinen. Kaikki kolme hoitavat homman, valitse olemassa olevan palveluntarjoajasuhteesi perusteella.

Pydantic-mallit Python-kehittäjille

Pydantic on de facto -standardi jäsenneltyjen tulosteskeemojen määrittelyyn Pythonissa. Tässä ovat merkittävimmät mallit.

Perusskeema kuvauksilla

from pydantic import BaseModel, Field
from typing import Literal, Optional

class ExtractedEntity(BaseModel):
    reasoning: str = Field(description="Think step by step about the entity")
    name: str = Field(description="Full name of the entity")
    entity_type: Literal["person", "company", "location"]
    confidence: float = Field(description="Confidence score 0.0-1.0", ge=0.0, le=1.0)
    context: Optional[str] = Field(description="Surrounding context, if relevant")

Nuo description-merkkijonot eivät ole vain dokumentaatiota varten, ne tulevat osaksi mallille lähetettävää JSON-skeemaa ja vaikuttavat suoraan siihen, mitä malli tuottaa. Ajattele niitä prompt-engineeringinä skeeman sisällä.

Sisäkkäiset mallit

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: Optional[str] = None

class Company(BaseModel):
    reasoning: str = Field(description="Analysis of the company details")
    name: str
    industry: Literal["tech", "finance", "healthcare", "retail", "other"]
    headquarters: Address  # Nested model
    key_products: list[str] = Field(description="Top 3 products or services")

Pidä sisäkkäisyys maksimissaan 2–3 tasolla. Syvästi sisäkkäiset skeemat lisäävät virheriskiä ja hidastavat skeeman kääntämistä.

Päättely-ensin-malli

Tämä on yksittäisin vaikutuksiltaan suurin skeeman suunnittelumalli. Laita reasoning-kenttä ennen vastauskenttiäsi:

# Reliable JSON from Any LLM: Pydantic + Zod Patterns for 2026
class ClassificationBad(BaseModel):
    category: Literal["spam", "ham"]
    confidence: float

# Good -- model reasons through the problem first
class ClassificationGood(BaseModel):
    reasoning: str = Field(description="Analyze the text before classifying")
    category: Literal["spam", "ham"]
    confidence: float = Field(ge=0.0, le=1.0)

LLM-mallit tuottavat tokeneita vasemmalta oikealle. Jos category tulee ensin, malli valitsee kategorian ja rationalisoi sen jälkikäteen. Jos reasoning tulee ensin, malli käy läpi ongelman ja sitten sitoutuu kategoriaan. Se on ketjuajatteluun upotettuna skeemaan.

JSON-skeeman vienti

# Generate the JSON Schema for any Pydantic model
schema = ProductReview.model_json_schema()
# Pass this to any provider that accepts raw JSON Schema

Tuomio: Pydantic + kuvailevat kentät + päättely-ensin-järjestys on Pythonin jäsennellyn tulosteen kolminaisuus. Hallitse nämä kolme mallia, ja hoidat 90 % käyttötarkoituksista.

Zod-mallit TypeScript-kehittäjille

Zod on TypeScriptin vastine Pydanticille, ja se on yhtä keskeinen osa jäsenneltyjä tulostetyönkulkuja.

Perusskeema kuvauksilla

import { z } from "zod";

const ProductReview = z.object({
  reasoning: z.string().describe("Think through the review before scoring"),
  rating: z.number().int().min(1).max(5),
  sentiment: z.enum(["positive", "negative", "neutral"]),
  pros: z.array(z.string()).describe("Key positive points"),
  cons: z.array(z.string()).describe("Key negative points"),
  summary: z.string().describe("One-sentence summary"),
});

// Infer the TypeScript type automatically
type ProductReview = z.infer<typeof ProductReview>;

Kuten Pydanticin Field(description=...), Zodin .describe() tulee osaksi JSON-skeemaa ja ohjaa mallin tulostetta.

Integrointi OpenAI Node SDK:hon

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";

const client = new OpenAI();

const response = await client.beta.chat.completions.parse({
  model: "gpt-4o-2024-08-06",
  messages: [
    { role: "system", content: "Extract a structured review." },
    { role: "user", content: reviewText },
  ],
  response_format: zodResponseFormat(ProductReview, "product_review"),
});

const review = response.choices[0].message.parsed; // Typed!

Integrointi Vercel AI SDK:hon

import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";

const { object: review } = await generateObject({
  model: openai("gpt-4o"),
  schema: ProductReview,
  prompt: `Extract a structured review:\n\n${reviewText}`,
});
// review is fully typed as ProductReview

Vercel AI SDK käyttää Zodia natiivisti generateObject()-funktion kanssa, mikä tekee siitä siisteimmän TypeScript-integraation. Se toimii OpenAI:n, Anthropicin, Geminin ja muiden palveluntarjoajien kanssa yhdistetyn API:n kautta.

JSON-skeeman muunnos

import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(ProductReview);
// Use with any provider that accepts raw JSON Schema

Tuomio: Zod + .describe() + Vercel AI SDK on TypeScriptin jäsennellyn tulosteen pino. Jos olet Node/Next.js-ekosysteemissä, tämä on vähimmän vastuksen tie.

Jäsennelty tuloste vs. Funktion kutsu: Milloin käytät kumpaa?

Tämä on yksi yleisimmistä hämmennyksen aiheista. Molemmat sisältävät skeemoja, molemmat palauttavat jäsenneltyä dataa, mutta ne ratkaisevat eri ongelmia.

Jäsennelty tuloste sanoo: "Anna minulle dataa tässä tarkassa muodossa." Se on tarkoitettu purkamiseen, luokitteluun ja muotoiluun. Vedät jäsenneltyä tietoa jäsentämättömästä tekstistä.

Funktion kutsu (työkalunkäyttö) sanoo: "Tässä ovat toiminnot, joita voit suorittaa, päätä mikä niistä ajetaan ja anna argumentit." Se on tarkoitettu agenttityönkulkuihin, joissa malli valitsee useista työkaluista ja laukaisee toimintoja.

Hämmennys on historiallisesti ymmärrettävää. Anthropicin alkuperäinen "jäsennelty tuloste" oli kirjaimellisesti funktion kutsu, määrittelisit vale-työkalun nimeltä extract_review ja napaisit argumentit. Se toimii edelleen, mutta natiivi jäsennelty tuloste on yksinkertaisempi puhtaaseen purkamiseen.

Jäsennelty tuloste voimistaa tekoälyagenttijärjestelmien työkalukutsuputkia. Katso oppaamme tekoälyagenteista liiketoiminnalle nähdäksesi, miten nämä sopivat tuotantotyönkulkuihin.

Tuomio: Käytä jäsenneltyä tulostetta, kun tiedät, minkä muotoisen datan pitäisi olla. Käytä funktion kutsua, kun mallin tarvitsee valita toiminto. Käytännössä useimmat sovellukset käyttävät molempia: jäsenneltyä tulostetta datan purkamiseen ja funktion kutsua agenttien orkestrointiin.

Tuotantomallit: Virheet, uudelleenyritykset ja suoratoisto

Jäsennellyn tulosteen toimiminen demossa on helppoa. Sen luotettavana pitäminen tuotannossa vaatii kolmen asian käsittelyä: kieltäytymiset, validointivirheet ja suoratoisto.

Kieltäytymisen käsittely

Joskus malli kieltäytyy tuottamasta pyytämääsi tulostetta, tyypillisesti siksi, että turvallisuussuodattimet merkitsivät syötteen. Kun näin tapahtuu, jäsennellyn tulosteen API:t eivät palauta skeemaasi. Ne palauttavat kieltäytymisen.

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=messages,
    response_format=ProductReview,
)

# ALWAYS check for refusal before accessing parsed content
if response.choices[0].message.refusal:
    print(f"Model refused: {response.choices[0].message.refusal}")
else:
    review = response.choices[0].message.parsed

Jos ohitat kieltäytymistarkistuksen ja yrität käyttää .parsed kieltäytymisessä, saat None ja hämmentävän downstream-virheen. Tarkista aina ensin.

Uudelleenyritysmallit validointipalautteella

Skeeman noudattaminen taataan rajoitetulla dekoodauksella, mutta semanttinen oikeellisuus ei. Malli voi palauttaa {"rating": 1, "sentiment": "positive"}, kelvollinen skeema, ristiriitainen sisältö. Tässä tulevat validointi ja uudelleenyritykset kuvaan.

import instructor

client = instructor.from_openai(OpenAI())

# Instructor handles retries automatically
review = client.chat.completions.create(
    model="gpt-4o",
    response_model=ProductReview,
    max_retries=3,  # Retries with validation error feedback
    messages=[
        {"role": "user", "content": review_text}
    ],
)

Instructor syöttää validointivirheen takaisin mallille uudelleenyrityksen yhteydessä, jotta se voi korjata itseään. Manuaalisia uudelleenyritysmalleja ilman Instructoria varten:

from pydantic import ValidationError

for attempt in range(3):
    try:
        response = client.beta.chat.completions.parse(
            model="gpt-4o-2024-08-06",
            messages=messages,
            response_format=ProductReview,
        )
        review = response.choices[0].message.parsed
        # Run additional semantic validation here
        break
    except ValidationError as e:
        messages.append({"role": "assistant", "content": str(response)})
        messages.append({"role": "user", "content": f"Validation error: {e}. Fix it."})

Jäsennellyn tulosteen suoratoisto

Suurten jäsenneltyjen vastausten, pitkien taulukoiden, monien kenttien tai monimutkaisten sisäkkäisten objektien kohdalla suoratoisto mahdollistaa osittaisten tulosten progressiivisen renderöinnin.

import instructor

client = instructor.from_openai(OpenAI())

# Stream partial results as fields populate
review_stream = client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=ProductReview,
    messages=[{"role": "user", "content": review_text}],
)

for partial_review in review_stream:
    # Fields populate one by one as tokens stream in
    if partial_review.summary:
        print(f"Summary so far: {partial_review.summary}")

Yksi sudenkuoppa: yksittäiset suoratoistokatkelmat eivät itsessään ole skeemavalideja. reasoning-kenttä voi olla täytetty, kun rating on vielä None. Suunnittele käyttöliittymäsi sen mukaisesti, näytä lataustila täyttämättömillä kentillä.

Tuomio: Kieltäytymistarkistukset ovat ehdottomia. Uudelleenyritykset validointipalautteella vangitsevat semanttiset virheet. Suoratoisto kannattaa mille tahansa vastaukselle, joka kestää enemmän kuin pari sekuntia.

Jäsennellyn tulosteen kirjastojen vertailu

Voit käyttää jäsenneltyä tulostetta natiivien API:den kautta, mutta kirjastot lisäävät validoinnin, uudelleenyritykset, suoratoiston ja monen palveluntarjoajan tuen. Tässä on maisema.

Instructor on suosituin vaihtoehto yli 11 000 GitHub-tähdellä ja yli 3 miljoonalla kuukausittaisella latauksella. Se kietoo OpenAI:n, Anthropicin, Geminin, Coheren, Ollaman ja muita yhdistetyllä Pydantic-pohjaisella rajapinnalla. Keskeiset ominaisuudet: automaattiset uudelleenyritykset validointipalautteella, suoratoisto create_partial()-funktiolla ja äärimmäisen yksinkertainen asennus (instructor.from_openai(client)). Jos olet Python-tiimi, aloita tästä.

BAML ottaa erilaisen lähestymistavan: skeema-ensin räätälöidyn DSL:n kautta. Määrittelet skeemat .baml-tiedostoissa ja generoit automaattisesti asiakaskoodin Pythonille, TypeScriptille, Rubylle ja muille. Sen SAP-algoritmi (schema-aligned parsing) käsittelee epäjärjestelmällisiä mallitulosteita sulavasti. Paras cross-language-tiimeille tai kun haluat sopimuksia LLM-kerroksesi ja sovelluskerroksesi välille. Kompromissi: ylimääräinen käännösvaihe ja uusi syntaksi opittavaksi.

LangChain tarjoaa .with_structured_output(schema) palveluntarjoajariippumattomaan jäsenneltyyn tulosteeseen. Kätevää, jos olet jo LangChain-ekosysteemissä. Kompromissi: se on raskas riippuvuus, ja abstraktio voi piilottaa palveluntarjoajakohtaisia ominaisuuksia, joita saatat tarvita.

Natiivit API:t, suorat kutsut response_format / output_config -asetuksilla, vaativat nollariippuvuuksia palveluntarjoajan SDK:n lisäksi. Saat täyden kontrollin ja näkyvyyden. Paras yksinkertaisiin käyttötarkoituksiin tai tiimeille, jotka suosivat minimaalista abstraktiota.

Oikean jäsennellyn tulosteen kirjaston valinta on osa laajempaa tekoälypinon päätöstä. Puremme koko pinon Paras tekoälypino SaaS:lle -oppaassamme.

Katso Parhaat kirjastot LLM:n jäsennellyille tulosteille [tulossa pian] saadaksesi syvällisen vertailun Instructorista, BAMLista, Mirascopesta ja muista.

Tuomio: Aloita Instructorilla Pythonissa, natiiveilla API:illa TypeScriptissä. Siirry BAMLiin, jos tarvitset cross-language-skeemasopimuksia. Vältä LangChainia pelkästään jäsenneltyä tulostetta varten, se on liiallista.

Skeeman suunnittelun parhaat käytännöt (ja yleiset virheet)

Skeeman suunnittelu vaikuttaa suoraan tulosteen laatuun. Tässä ovat merkittävät mallit ja virheet, jotka maksavat tarkkuutesi.

Laita päättely ennen vastauksia

Käsittelimme tätä Pydantic-osiossa, mutta se kannattaa toistaa, koska se on vaikutuksiltaan suurin suunnittelupäätös:

# Before: model guesses the answer, then rationalizes
class Bad(BaseModel):
    answer: str
    reasoning: str

# After: model thinks first, then commits
class Good(BaseModel):
    reasoning: str = Field(description="Think step by step")
    answer: str

LLM-mallit tuottavat vasemmalta oikealle. Kenttien järjestys on promptin järjestys. Päättely ensin tarkoittaa, että mallin on käytävä läpi ongelma ennen kuin se sitoutuu vastaukseen.

Anti-mallitaulukko

Käsittele null-arvot eksplisiittisesti

Jos kentällä ei ehkä ole dataa lähdetekstissä, tee siitä valinnainen. Pakollisen kentän pakottaminen, kun dataa ei ole, johtaa hallusinaatioon:

class PersonInfo(BaseModel):
    name: str  # Always present
    email: Optional[str] = Field(None, description="Email if mentioned, null otherwise")
    phone: Optional[str] = Field(None, description="Phone if mentioned, null otherwise")

Pidä skeemat keskittyneinä

Yksi skeema per tehtävä. Älä yritä purkaa kaikkea yhdessä valtavassa skeemassa. Jos tarvitset 50+ kenttää, jaa useisiin purkukutsuihin. OpenAI:n Tiukalla tilalla on käytännön rajat skeeman monimutkaisuudelle, ja vaikka se toimisi, hyvin suuret skeemat heikentävät tulosteen laatua.

Tuomio: Päättely-ensin, kuvailevat kentät, eksplisiittiset nullit ja keskittyneet skeemat. Saat nämä neljä oikein, ja jäsennellyn tulosteen tarkkuus nousee mitattavasti.

Jäsennelty tuloste paikallisilla LLM-malleilla

Et tarvitse API-palveluntarjoajaa jäsenneltyä tulostetta varten. Paikalliset päättelymoottorit tukevat sitä grammatiikkapohjaisella rajoitetulla dekoodauksella, samalla perusmekanismilla, omalla laitteistollasi ajettuna.

Ollama

Helpoin tie paikalliseen jäsenneltyyn tulosteeseen. Ollama hyväksyy JSON-skeeman format-parametrin kautta:

import ollama
from pydantic import BaseModel

class Country(BaseModel):
    name: str
    capital: str
    languages: list[str]

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Tell me about Japan."}],
    format=Country.model_json_schema(),
)

import json
country = Country(**json.loads(response.message.content))

Ollama käyttää XGrammar-kirjastoa kulissien takana rajoitettuun dekoodaukseen. Sama takuu kuin API-palveluntarjoajilla: 100-prosenttinen skeeman noudattaminen.

vLLM ja SGLang

Tuotantotason paikallista päättelyä varten vLLM ja SGLang tukevat jäsenneltyä tulostetta guided_json- ja guided_regex-parametrien kautta. XGrammar on oletusarvoinen backend, joka tarjoaa lähes olemattoman kuorman JSON-generoinnissa, jopa 3,5 kertaa nopeammin kuin vaihtoehtoiset grammatiikkamoottorit.

Outlines

Outlines on avoimen lähdekoodin Python-kirjasto, joka pioneeroi grammatiikkapohjaista rajoitettua generointia. Se toimii minkä tahansa Hugging Face -mallin kanssa ja tukee JSON-skeemaa, regexiä ja täysiä kontekstivapaita kielioppi (CFG/EBNF) -rajoituksia. Se on myös integroitu vLLM:ään ja SGLangiin grammatiikkabackend-vaihtoehtona.

Keskeinen ero API-palveluntarjoajiin verrattuna: paikallisessa jäsennellyssä tulosteessa ei ole skeeman osajoukkorajoituksia. Kontrolloit grammatiikkaa täysin. Mutta mallin laatu vaihtelee enemmän, 7 miljardin parametrin paikallinen malli ei vastaa GPT-4o:ta tai Claudea monimutkaisissa purkutehtävissä. Skeema on aina validi; sisällön laatu riippuu mallista.

Tuomio: Ollama kehitykseen, vLLM/SGLang XGrammarilla tuotantoon. Paikallinen jäsennelty tuloste on tarpeeksi kypsä useimpiin käyttötarkoituksiin, sillä varauksella, että pienemmät mallit tuottavat heikompilaatuista sisältöä skeeman sisällä.

UKK

Mikä on jäsennelty tuloste LLM-malleissa?

Jäsennelty tuloste on mekanismi, joka takaa LLM:n vastauksen noudattavan ennalta määriteltyä JSON-skeemaa. Toisin kuin pelkkä teksti tai jopa JSON-tila, jäsennelty tuloste käyttää rajoitettua dekoodausta varmistaakseen, että jokainen skeemasi kenttä, tyyppi ja rajoitus täyttyy – 100-prosenttisesti, ei "yleensä".

Mikä on ero JSON-tilan ja jäsenneltyjen tulosteiden välillä?

JSON-tila takaa syntaktisesti kelvollisen JSONin, mutta ei valvo skeemaasi, voit saada minkä tahansa kelvollisen JSON-objektin. Jäsennellyt tulosteet (Tiukka tila) takaavat täyden skeeman noudattamisen rajoitetun dekoodauksen kautta. Käytä Tiukkaa tilaa tuotannossa; JSON-tila on relevantti vain, kun sinulla ei ole skeemaa etukäteen.

Mitkä LLM-palveluntarjoajat tukevat jäsenneltyä tulostetta natiivisti?

OpenAI (elokuusta 2024 lähtien), Google Gemini (2024, laajennettu 2026), Anthropic (beta marraskuussa 2025, GA vuoden 2026 alussa), Cohere ja xAI (Grok) tukevat kaikki natiivia jäsenneltyä tulostetta. Paikallisella puolella Ollama, vLLM ja SGLang tukevat sitä grammatiikkapohjaisella rajoitetulla dekoodauksella.

Miten rajoitettu dekoodaus takaa skeeman noudattamisen?

JSON-skeema käännetään ärelliseksi automaatiksi (FSM). Jokaisessa tokenin generointivaiheessa sallitaan vain tokenit, jotka pitävät tulosteen kelvollisella polulla FSM:n läpi, virheellisten tokenien logitit asetetaan negatiiviseen äärettömyyteen. Tämä tarkoittaa, että virheellisillä tokeneilla on nolla todennäköisyys generoitua, mikä antaa matemaattisen takuun, ei tilastollisen.

Pitäisikö minun käyttää jäsenneltyä tulostetta vai funktion kutsua?

Käytä jäsenneltyä tulostetta purkamiseen ja luokitteluun, kun haluat dataa tietyssä muodossa. Käytä funktion kutsua agenttityönkulkuihin, kun mallin tarvitsee päättää, minkä toiminnon se suorittaa. Monet tuotantosovellukset käyttävät molempia: jäsenneltyä tulostetta datan purkamiseen ja funktion kutsua orkestrointiin.

Voinko suoratoistaa jäsenneltyä tulostetta?

Kyllä. OpenAI tukee suoratoistoa parse()-metodilla, ja Instructor tarjoaa create_partial()-funktion Pydantic-mallien suoratoistamiseen, jotka täyttyvät kenttä kerrallaan. Huomaa, että yksittäiset suoratoistokatkelmat eivät itsessään ole skeemavalideja, kentät täyttyvät asteittain.

Mikä on Instructor-kirjasto?

Instructor on suosituin jäsennellyn tulosteen kirjasto (yli 11 000 GitHub-tähteä, yli 3 miljoonaa kuukausittaista latausta). Se kietoo palveluntarjoajien SDK:t Pydantic-pohjaisella validoinnilla, automaattisilla uudelleenyrityksillä validointipalautteella ja suoratoistotuella. Se toimii OpenAI:n, Anthropicin, Geminin, Coheren, Ollaman ja yli 10 muun palveluntarjoajan kanssa.

Toimiiiko jäsennelty tuloste paikallisten LLM-mallien kanssa?

Kyllä. Ollama tukee jäsenneltyä tulostetta format-parametrin kautta JSON-skeemalla. vLLM ja SGLang tukevat sitä guided_json-parametrien kautta. Kaikki kolme käyttävät XGrammaria tai Outlinesia rajoitettuun dekoodaukseen. Skeeman noudattamisen takuu on sama kuin API-palveluntarjoajilla; sisällön laatu riippuu mallista.

Mitkä ovat yleisiä skeeman suunnitteluvirheitä?

Tärkeimmät virheet: päättelykentän sijoittaminen vastauskentän jälkeen (malli päättää ennen ajattelua), syvästi sisäkkäiset skeemat (4+ tasoa lisäävät virheitä), puuttuvat kenttäkuvaukset (malli arvoo aikomuksen), ei null-käsittelyä valinnaiselle datalle (pakottaa hallusinaation) ja liian suuret skeemat (50+ kenttää heikentävät laatua).

Lisääkö jäsennelty tuloste viivettä?

Ensimmäisessä pyynnössä on skeeman käännöskuorma, tyypillisesti 50–200 ms, kun FSM rakennetaan. Myöhemmät pyynnöt samalla skeemalla käyttävät välimuistissa olevaa FSM:ää ja lisäävät lähes olemattoman viiveen. Useimmille sovelluksille tämä on merkityksetöntä verrattuna kokonaispäättelyaikaan.

Voinko käyttää jäsenneltyä tulostetta kuvien tai multimodaalisten syötteiden kanssa?

Kyllä. Jäsennelty tuloste koskee vastauksen muotoa, ei syötettä. Voit lähettää kuvan GPT-4o:lle tai Geminalle jäsennellyn tulosteen skeeman kanssa ja saada takaisin skeemaa noudattavan analyysin kuvasta. Tämä on tehokasta visuaalisissa purkutyönkuluissa, kuten jäsennellyn datan purkaminen kuiteista, lomakkeista tai tuotekuvista.

Lähteet

• OpenAI Jäsennellyt tulosteet -opas
• Anthropic Työkalunkäytön dokumentaatio
• Google Gemini Jäsennelty tuloste
• Instructor-kirjaston dokumentaatio
• BAML-dokumentaatio
• Pydantic-dokumentaatio
• Zod-dokumentaatio
• Outlines-kirjasto
• XGrammar GitHub
• Ollama Jäsennellyt tulosteet
• Vercel AI SDK