Kako napraviti strukturirane LLM izlaze prenosivim na OpenAI, Anthropic i Gemini

Strukturirani rezultati LLM-a postaju osjetljivi kada timovi tretiraju podršku pružatelja kao zamjenjivu. OpenAI, Anthropic i Gemini svi mogu proizvesti strukturirane podatke, ali ne izlažu isti ugovor. Sintaksa sheme, omotnice poziva alata, jamstva strogosti, ponašanje odbijanja, ponašanje strujanja i načini neuspjeha provjere valjanosti razlikuju se dovoljno da parser koji radi s jednim modelom može tiho pogriješiti s drugim.

Praktično rješenje je prestati tretirati strukturirane izlazne značajke specifične za pružatelja usluga kao poslovni ugovor. Definirajte jedan kanonski izlazni ugovor za svaki tijek rada, kompajlirajte ga u podržani format zahtjeva svakog pružatelja, potvrdite svaki odgovor u odnosu na kanonsku shemu i testirajte svaki model prije nego što mu se dopusti posluživanje proizvodnog prometa.

Što je prijenosni strukturirani izlaz?

Prijenosni strukturirani izlaz znači da se aplikacija može osloniti na isti oblik odgovora na poslovnoj razini čak i kada se promijeni pružatelj temeljnog modela. To ne znači da svaki davatelj usluga dobiva potpuno istu JSON shemu. To također ne znači da je provjera valjanosti na strani pružatelja dovoljna.

Prijenosni ugovor ima pet slojeva:

• Kanonička shema: oblik podataka tijeka rada neutralan prema pružatelju usluga.
• Portability linting: provjerava izbjegava li shema konstrukcije koje nisu podržane, slabo se provode ili su rizične među pružateljima usluga.
• Kompilacija pružatelja: prijevod iz kanonskog ugovora u OpenAI, Anthropic, Gemini ili izvornu površinu strukturiranog izlaza drugog pružatelja.
• Provjera valjanosti izvođenja: provjera valjanosti vraćenog objekta na strani aplikacije prema kanonskoj shemi.
• Ugovorni testovi: ponovljivi testovi koji dokazuju da svaki model obrađuje obavezna polja, popise, odbijanja, skraćivanje, neispravno oblikovane zahtjeve i semantičke rubne slučajeve prije nego što se promijeni usmjeravanje proizvodnje.

Ovaj je obrazac posebno važan za poduzeće LLM API gdje nekoliko timova, stanara ili tijekovi rada partnera ovise o predvidljivim ugovorima o rezultatima.

Činjenice: Strukturirani izlaz pružatelja usluga nije jedan standard

Prije dizajniranja sloja prenosivosti, odvojite dokumentirano ponašanje pružatelja usluga od pretpostavki.

OpenAI

OpenAI dokumentira strukturirane izlaze za razliku od JSON načina. Način rada JSON namijenjen je osiguravanju valjanosti JSON, dok su strukturirani izlazi namijenjeni usklađivanju s priloženom shemom JSON. OpenAI podržava strukturirani izlaz kroz oblikovanje odgovora i kroz pozivanje funkcije uz strogo pridržavanje sheme, ali dokumentirano ponašanje uključuje ograničenja modela i verzije i podržani podskup sheme. Nepodržane sheme u strogom načinu rada mogu proizvesti API pogreške, a aplikacije i dalje moraju obrađivati rubne slučajeve.

Anthropic

Anthropic dokumenti Claude korištenje alata kao strukturiranih poziva alata na temelju alata koje pruža razvojni programer s input_schema. Model vraća blok tool_use, a aplikacija izvršava traženi alat. Ovo sliči pozivu funkcije, ali nije isti ugovor kao OpenAI odgovor-format JSON odgovor sheme. Inženjerske smjernice Anthropic također napominju da JSON shema može definirati strukturu, obavezna polja i enumove, ali ne može izraziti obrasce upotrebe kao što je kada bi izborni parametri trebali biti uključeni ili koje kombinacije polja imaju poslovnog smisla.

Gemini

Google Gemini API dokumentacija kaže da se strukturirani izlaz može konfigurirati za JSON odgovore i da Gemini način strukturiranog izlaza podržava podskup JSON specifikacije sheme. To je važno jer shema koja je važeća JSON Shema još uvijek može biti neprikladna kao prijenosna shema zahtjeva davatelja usluga.

Uočljivost

OpenTelemetry GenAI semantičke konvencije uključuju atribute za pružatelja, traženi model, model odgovora, vrstu izlaza, razloge završetka, upotrebu tokena, definicije alata, argumente poziva alata i povezana polja GenAI zahtjeva i odgovora. Ova polja mogu podržati otklanjanje pogrešaka između pružatelja usluga kada je kvarove strukturiranog izlaza teško razlikovati od upita, sheme, modela ili problema s pružateljem usluga.

1. korak: Definirajte kanonsku poslovnu shemu

Počnite od poslovnog tijeka rada, a ne od pružatelja API. Tijek rada trijaže podrške, tijek rada izvlačenja faktura, preporuka za odobrenje ili krajnja točka automatizacije usmjerena prema partnerima trebaju imati kanonsku shemu koja predstavlja ono što aplikacija treba nizvodno.

Na primjer, radni tijek trijaže podrške može koristiti ovaj kanonski oblik:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "requires_human_review"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "security", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "requires_human_review": {
      "type": "boolean"
    },
    "customer_risk_signals": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Ova je shema ugovor kojem ostatak aplikacije vjeruje. Formati zahtjeva specifični za pružatelja usluga generiraju se iz njega; oni nisu izvor istine.

Koristite eksplicitna obavezna polja, ograničene nizove, ograničene nizove, zatvorene enume i additionalProperties: false tamo gdje vaš validator to podržava. Izbjegavajte prihvaćanje proizvoljnih ugniježđenih objekata osim ako je nizvodni sustav dizajniran za rukovanje proizvoljnim ključevima.

Korak 2: Dodajte traku za prijenos sheme Korak

Linter prenosivosti trebao bi odbaciti sheme koje su tehnički valjane JSON Shema, ali rizične za korištenje s više modela. Cilj nije puna izražajnost JSON sheme. Cilj je stabilan izlazni ugovor koji se može kompajlirati u nekoliko površina pružatelja bez slabljenja jamstva aplikacije.

Korisne provjere dlačica uključuju:

• Odbijte nepodržane ključne riječi za sastav osim ako vaš kompajler nema eksplicitna preslikavanja pružatelja za njih.
• Odbacite neograničena object polja koja dopuštaju proizvoljna svojstva.
• Zahtijevaj popise za klasifikacijska polja koja upravljaju usmjeravanjem, naplatom, odobrenjima ili statusom vidljivim partnerima.
• Zahtijevajte maxItems za nizove koji se koriste u automatizaciji ili prikazu korisničkog sučelja.
• Zahtijevajte maxLength za tekstualna polja koja ulaze u baze podataka, redove ili partnerske API-je.
• Označite neobavezna polja čiji nedostatak mijenja poslovno značenje.
• Odbijte sheme čije ugniježđenje ili veličina premašuju poznata ograničenja pružatelja u vašoj matrici mogućnosti.

Linter bi trebao raditi u CI-ju i prije postavljanja sheme. Nemojte čekati dok proizvodni zahtjev ne naiđe na pogrešku pružatelja jer ključna riječ sheme nije podržana.

Korak 3: Kompajlirajte u formate zahtjeva specifične za pružatelja usluga

Kompilacija dobavljača prevodi kanonsku shemu u API površinu koju svaki model zapravo podržava. Prevodilac bi trebao biti deterministički i verzioniran. Također bi trebao ostaviti revizijski trag koji pokazuje koja je verzija kanonske sheme proizvela koji sadržaj zahtjeva davatelja.

OpenAI kompilacija

Za OpenAI, kompajler može ciljati strukturirane izlaze putem oblikovanja odgovora za zadatke ekstrakcije i klasifikacije, ili striktno pozivanje funkcija za tijekove rada usmjerene na akciju. Prevedeni korisni sadržaj trebao bi uključivati podržani podskup sheme i postavke strogosti specifične za pružatelja usluga ako su dostupne.

Anthropic kompilacija

Za Anthropic, prevodilac će često predstavljati željeni izlaz kao alat s input_schema. Aplikacija tada očekuje blok upotrebe alata i provjerava valjanost unosa alata prema kanonskoj shemi. To znači da adapter mora normalizirati omotnicu odgovora, a ne samo analizirati JSON.

Gemini kompilacija

Za Gemini, prevodilac bi trebao ciljati svoju strukturiranu konfiguraciju odgovora JSON koristeći samo podržani podskup sheme. Ako kanonska shema koristi ograničenja koja se Gemini ne provode izvorno, prevodilac bi trebao zabilježiti ta ograničenja kao da zahtijevaju provjeru valjanosti na strani aplikacije.

Izlaz adaptera trebao bi biti normaliziran u jednu internu vrstu rezultata:

type StructuredResult = {
  provider: "openai" | "anthropic" | "gemini";
  model: string;
  schema_version: string;
  status: "ok" | "refusal" | "truncated" | "provider_error" | "invalid";
  raw_response: unknown;
  parsed_output?: unknown;
  finish_reason?: string;
};

Ova normalizacija sprječava ovisnost nizvodnog koda tijeka rada o ovojnicama pružatelja usluga.

Korak 4: Potvrdite svaki odgovor u odnosu na kanonsku shemu

Struktura na strani pružatelja prva je linija obrane, a ne konačna provjera ispravnosti. Uvijek provjerite raščlanjeni izlaz u odnosu na kanonsku shemu nakon što model odgovori.

Provjera valjanosti izvođenja trebala bi proizvoditi strukturirane pogreške kao što su:

• missing_required_field
• invalid_enum
• unexpected_property
• type_mismatch
• array_too_long
• string_too_long
• semantic_rule_failed

Odvojite strukturnu validaciju od semantičke validacije. JSON Shema može provjeriti oblik, potrebna svojstva, popise i osnovna ograničenja tipa. Ne može u potpunosti izraziti poslovna pravila kao što su valjani prijelazi stanja, pragovi odobrenja, pravila specifična za klijenta ili međusobno ovisne kombinacije polja.

Na primjer, ovo je semantički validator, a ne pravilo sheme:

if (output.priority === "urgent" && output.requires_human_review !== true) {
  throw new SemanticValidationError(
    "urgent tickets must require human review"
  );
}

Stavite te provjere u kod aplikacije gdje mogu koristiti konfiguraciju korisnika, stanje tijeka rada, kontekst autorizacije i verziju pravila.

Korak 5: Koristite ograničeni popravak, a zatim neuspješno zatvoreno

Putanja popravka može se oporaviti od malih izlaznih grešaka, ali također može sakriti sustavnu shemu i brze probleme. Upotrijebite jedan ciljani pokušaj popravka s uključenom pogreškom provjere valjanosti. Ako popravljeni odgovor i dalje ne prođe provjeru valjanosti, neuspješno zatvorite ili usmjerite na pregled.

Praktična pravila popravka izgledaju ovako:

• Pokušajte popraviti samo prihvatljive vrste grešaka, kao što su nedostajuća obavezna polja, nevažeći enumeri ili neispravni JSON.
• Nemojte popravljati odbijanja pružatelja usluga, sigurnosne blokade, neuspješne autorizacije ili izlaze osjetljive na pravila.
• U upit za popravak uključite verziju kanonske sheme i pogrešku provjere valjanosti.
• Dopustite najviše jedan pokušaj popravka za tijekove rada koji su vidljivi korisniku ili koji pokreću radnju.
• Broj popravaka dnevnika, uspjeh popravka, korištenje tokena i konačni status.

Za poslove unutarnjeg izdvajanja niskog rizika, drugi pokušaj popravka može biti prihvatljiv ako kašnjenje nije važno. Za tijekove rada koji pokreću plaćanja, promjene pristupa, odgovore partnera API ili radnje usklađivanja, obično je sigurnije pravilo o zatvaranju kod pogreške.

Korak 6: Izradite ugovorne testove za svaki model proizvodnje

Ugovorni testovi odlučuju je li model prikladan za tijek rada. Trebali bi se pokrenuti prije početnog pokretanja, prije nadogradnje modela i prije promjena pravila usmjeravanja.

Testirajte svaki model i adapter davatelja barem na:

• Valjani izlaz sretnog puta.
• Nedostaju obavezna polja.
• Nevažeće enum vrijednosti.
• Dodatna svojstva kada je shema zatvorena.
• Previše stavki niza.
• Predugi nizovi.
• Odbijanje ili nemogućnost pridržavanja.
• Skraćeni izlaz.
• Neusklađenost poziva alata ili nedostajući poziv alata.
• Strukturalno valjan, ali semantički pogrešan izlaz.

Koristite kontradiktorne upute koje vrše pritisak na model da prekrši ugovor. Na primjer, zatražite od njega da doda dodatno polje za objašnjenje, vrati prioritet izvan enuma ili izostavi obaveznu booleovu vrijednost. Test prolazi samo ako pružatelj plus adapter plus validator proizvode očekivani status aplikacije.

Za svaki tijek rada vodite jednostavan zapis kompatibilnosti:

{
  "workflow": "support_triage",
  "schema_version": "2026-09-24",
  "model": "provider-model-name",
  "supports_strict_schema": true,
  "supports_tool_calling": true,
  "supports_streaming_structured_output": false,
  "refusal_signal_normalized": true,
  "contract_tests_passed": true,
  "known_limitations": ["max schema depth 4"]
}

Ova matrica sposobnosti pripada u kontrolnu ravninu, a ne u raspršene konstante aplikacije.

Korak 7: Pouzdanost strukturiranog izlaza instrumenta

Bez telemetrije timovi ne mogu znati dolaze li kvarovi od nekompatibilnosti pružatelja usluga, odstupanja modela, nedostataka sheme, brzih nedostataka, skraćivanja ili nizvodnih validatora.

Zabilježite ova polja za svaki zahtjev strukturiranog izlaza:

• Naziv tijeka rada i verzija sheme.
• Dobavljač, traženi model i model odgovora.
• Način izlaza, kao što je shema odgovora, poziv alata ili JSON način.
• Status provjere valjanosti i vrsta pogreške.
• Broj popravaka i rezultat popravka.
• Završi razlog i status odbijanja.
• Tokeni upita, tokeni završetka, ukupni trošak i kašnjenje.
• Verzija adaptera i verzija prevoditelja.

Upotrijebite ove podatke za usporedbu modela prije promjene rute. Jeftiniji model nije jeftiniji ako povećava broj pokušaja popravka, ručni pregled, kvarove partnera API ili daljnje rješavanje incidenata.

Kompromisi za eksplicitnu odluku

Sheme najmanjeg zajedničkog nazivnika poboljšavaju prenosivost, ali slabe ograničenja. Ako se shema zahtjeva pružatelja mora pojednostaviti, očuvajte strože provjere u kanonskoj provjeri valjanosti i semantičkim validatorima.

Kompilacija specifična za pružatelja čuva izvorne prednosti, ali dodaje održavanje. To se obično isplati za proizvodne tijekove rada, ali samo ako prevoditelji imaju verzije i pokriveni ugovornim testovima.

Stroge sheme smanjuju greške parsera, ali zahtijevaju bolji dizajn zadatka. Ako je zadatak nedovoljno određen, strogost prije razotkriva dvosmislenost. To je korisno, ali može usporiti početni razvoj.

Popravak poboljšava stope završetka, ali dodaje troškove i kašnjenje. Ograničeni popravak je mehanizam oporavka, a ne zamjena za dizajn sheme.

Pozivanje alata i format odgovora JSON služe različitim tijekovima rada. Pozivanje alata često bolje odgovara tijekovima rada usmjerenim na akciju. Format odgovora JSON jednostavniji je za izdvajanje, klasifikaciju i sažimanje. Platforma s više modela može podržavati oboje, ali pravila tijeka rada moraju biti eksplicitna.

Predviđanja: kamo ide prenosivost strukturiranog izlaza

Podrška pružatelja za strukturirani izlaz vjerojatno će se nastaviti poboljšavati, ali ne treba pretpostaviti potpunu JSON prenosivost sheme među modelima. Pružatelji usluga imaju različite arhitekture modela, API povijest, obrasce upotrebe alata i sigurnosno ponašanje. Čak i kada podrška sheme postane jača, aplikacije će i dalje trebati kanonsku provjeru jer poslovna ispravnost ovisi o više od JSON oblika.

Timovi bi trebali očekivati da će odluke o usmjeravanju strukturiranog izlaza postati više vođene podacima. Pouzdanost, stopa popravka, rješavanje odbijanja, latencija i cijena bit će važni uz kvalitetu modela. Operativno pitanje će se promijeniti s "podržava li ovaj model JSON?" na "zadovoljava li ovaj model ovaj ugovor tijeka rada uz prihvatljivu cijenu i stopu neuspjeha?"

Kontrolni popis za implementaciju

• Definirajte jednu kanoničku shemu po tijeku rada.
• Sheme verzija i održavanje korisnih opterećenja zahtjeva davatelja ponovljivim.
• Dodajte CI linting za nepodržane ili rizične značajke sheme.
• Kompilirajte kanonske sheme u formate specifične za pružatelja usluga.
• Normalizirajte omotnice pružatelja u jednu internu vrstu rezultata.
• Provjerite svaki raščlanjeni odgovor prema kanonskoj shemi.
• Dodajte semantičke validatore za poslovna pravila.
• Dopusti samo ograničene pokušaje popravka.
• Neuspješno zatvaranje ili usmjeravanje na pregled za visokorizične tijekove rada.
• Pokrenite ugovorne testove prije dodavanja ili nadogradnje proizvodnih modela.
• Održavajte matricu mogućnosti modela u kontrolnoj ravnini.
• Polja za provjeru valjanosti dnevnika, popravak, trošak, latencija, pružatelj usluga i model za svaki zahtjev.

Zaključak koji se može poduzeti

Prenosivost strukturiranog izlaza je API problem ugovora, a ne problem brzog oblikovanja. Pouzdan obrazac je definirati kanonsku poslovnu shemu, prilagoditi je radi prenosivosti, kompajlirati je u izvornu površinu svakog pružatelja, potvrditi svaki odgovor nakon što ga pružatelj vrati i koristiti ugovorne testove za odlučivanje koji su modeli prihvatljivi za proizvodnju.

Ovaj dizajn dodaje nešto prethodnog inženjerskog rada, ali sprječava skuplji način kvara: nizvodni sustavi koji preuzimaju stabilan ugovor dok se usmjeravanje modela, ponašanje pružatelja ili provedba sheme tiho mijenja ispod njih.

Povezano čitanje

• zamjensko usmjeravanje koje štiti strukturirani izlaz ugovori