Kako narediti strukturirane izhode LLM prenosljive v OpenAI, Anthropic in Gemini

Strukturirani rezultati LLM postanejo krhki, ko ekipe obravnavajo podporo ponudnika kot zamenljivo. OpenAI, Anthropic in Gemini lahko proizvajajo strukturirane podatke, vendar ne izpostavljajo iste pogodbe. Sintaksa sheme, ovojnice klicev orodij, jamstva za strogost, vedenje pri zavrnitvi, vedenje pretakanja in načini napak pri preverjanju se dovolj razlikujejo, da lahko razčlenjevalnik, ki deluje z enim modelom, tiho odpove drugemu.

Praktični popravek je prenehanje obravnavanja strukturiranih izhodnih funkcij, specifičnih za ponudnika, kot poslovne pogodbe. Definirajte eno kanonično izhodno pogodbo za vsak potek dela, jo prevedite v podprto obliko zahteve vsakega ponudnika, preverite vsak odgovor glede na kanonično shemo in preizkusite vsak model, preden mu je dovoljeno služiti produkcijskemu prometu.

Kaj je prenosni strukturirani izhod?

Prenosni strukturirani izhod pomeni, da se lahko aplikacija zanaša na isto obliko odziva na poslovni ravni, tudi če se spremeni osnovni ponudnik modela. To ne pomeni, da vsak ponudnik prejme povsem enako shemo JSON. Prav tako ne pomeni, da je preverjanje na strani ponudnika dovolj.

Prenosljiva pogodba ima pet ravni:

• Kanonična shema: oblika podatkov poteka dela, nevtralna glede ponudnika.
• Prenosljivost linting: preveri, ali se shema izogiba konstruktom, ki niso podprti, slabo uveljavljeni ali tvegani med ponudniki.
• Prevajanje ponudnika: prevod iz kanonične pogodbe v OpenAI, Anthropic, Gemini ali izvorno strukturirano izhodno površino drugega ponudnika.
• Preverjanje izvajalnega časa: preverjanje veljavnosti vrnjenega predmeta na strani aplikacije glede na kanonično shemo.
• Pogodbeni preizkusi: ponovljivi preizkusi, ki dokazujejo, da vsak model obravnava zahtevana polja, naštevanja, zavrnitve, obrezovanje, nepravilno oblikovane zahteve in semantične robne primere, preden se spremeni usmerjanje proizvodnje.

Ta vzorec je še posebej pomemben za podjetniški LLM API, kjer je več skupin, najemnikov ali delovnih tokov partnerjev odvisnih od predvidljivih izhodnih pogodb.

Dejstva: Strukturirani izhod ponudnika ni en standard

Pred načrtovanjem plasti prenosljivosti ločite dokumentirano vedenje ponudnika od predpostavk.

OpenAI

OpenAI dokumentira strukturirane izhode za razliko od načina JSON. Način JSON je namenjen zagotavljanju veljavnosti JSON, medtem ko so strukturirani izhodi namenjeni ujemanju s priloženo shemo JSON. OpenAI podpira strukturiran izhod prek oblikovanja odziva in klicanja funkcij s strogim upoštevanjem sheme, vendar dokumentirano vedenje vključuje omejitve modela in različice ter podmnožico podprte sheme. Nepodprte sheme v strogem načinu lahko povzročijo API napake, aplikacije pa morajo še vedno obravnavati robne primere.

Anthropic

Anthropic dokumenti Claude uporabljajo orodje kot strukturirane klice orodij, ki temeljijo na orodjih, ki jih nudijo razvijalci z input_schema. Model vrne blok tool_use in aplikacija izvede zahtevano orodje. To je podobno klicanju funkcije, vendar ni enaka pogodba kot odziv sheme OpenAI oblike odgovora JSON. Inženirska navodila Anthropic prav tako ugotavljajo, da JSON shema lahko definira strukturo, obvezna polja in enume, ne more pa izraziti vzorcev uporabe, na primer, kdaj je treba vključiti neobvezne parametre ali katere kombinacije polj so poslovno smiselne.

Gemini

Google Gemini API pravi, da je strukturiran izhod mogoče konfigurirati za JSON odgovore in da način Gemini strukturiranega izhoda podpira podmnožico specifikacije JSON sheme. To je pomembno, ker shema, ki je veljavna JSON Shema, morda še vedno ni primerna kot prenosna shema zahteve ponudnika.

Opazljivost

Semantične konvencije OpenTelemetry GenAI vključujejo atribute za ponudnika, zahtevani model, model odziva, vrsto izhoda, razloge za dokončanje, uporabo žetonov, definicije orodij, argumente klica orodij ter povezana polja zahteve in odgovora GenAI. Ta polja lahko podpirajo razhroščevanje med ponudniki, kadar je napake strukturiranih izhodnih podatkov težko razlikovati od težav s pozivom, shemo, modelom ali ponudnikom.

1. korak: Definirajte kanonično poslovno shemo

Začnite s poslovnim potekom dela, ne s ponudnikom API. Delovni tok triaže podpore, delovni tok ekstrakcije računov, priporočilo za odobritev ali končna točka avtomatizacije, obrnjena k partnerju, bi morala imeti kanonično shemo, ki predstavlja, kaj aplikacija potrebuje na nižji stopnji.

Na primer, delovni tok podpore-triaže lahko uporablja to kanonično obliko:

{
  "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
    }
  }
}

Ta shema je pogodba, ki ji zaupa preostali del aplikacije. Iz tega se ustvarijo posebni formati zahtev ponudnika; niso vir resnice.

Uporabite eksplicitna zahtevana polja, omejene nize, omejene nize, zaprte enume in additionalProperties: false, kjer vaš validator to podpira. Izogibajte se sprejemanju poljubnih ugnezdenih objektov, razen če je nadaljnji sistem zasnovan za obdelavo poljubnih ključev.

2. korak: dodajte lint za prenosljivost sheme. Korak

Linter prenosljivosti bi moral zavrniti sheme, ki so tehnično veljavne JSON Shema, vendar tvegane za uporabo z več modeli. Cilj ni popolna JSON izraznost sheme. Cilj je stabilna izhodna pogodba, ki jo je mogoče prevesti v več površin ponudnika, ne da bi oslabili garancijo aplikacije.

Uporabni pregledi vlaken vključujejo:

• Zavrni nepodprte ključne besede za sestavo, razen če ima prevajalnik zanje eksplicitne preslikave ponudnika.
• Zavrni neomejena object polja, ki dovoljujejo poljubne lastnosti.
• Zahtevaj naštevanja za klasifikacijska polja, ki vodijo usmerjanje, zaračunavanje, odobritve ali stanje, ki ga vidi partner.
• Zahtevaj maxItems za nize, ki se uporabljajo pri avtomatizaciji ali prikazu uporabniškega vmesnika.
• Zahtevaj maxLength za besedilna polja, ki vnašajo baze podatkov, čakalne vrste ali partnerske API-je.
• Označite izbirna polja, katerih odsotnost spremeni poslovni pomen.
• Zavrnite sheme, katerih gnezdenje ali velikost presega znane omejitve ponudnika v vaši matriki zmogljivosti.

Linter mora delovati v CI in pred uvedbo sheme. Ne čakajte, da produkcijska zahteva naleti na napako ponudnika, ker ključna beseda sheme ni bila podprta.

3. korak: Prevedi v oblike zahtev, specifične za ponudnika

Prevajanje ponudnika prevede kanonično shemo v API površino, ki jo vsak model dejansko podpira. Prevajalnik mora biti determinističen in imeti različice. Puščati mora tudi revizijsko sled, ki prikazuje, katera kanonična različica sheme je ustvarila koristno obremenitev zahteve ponudnika.

OpenAI kompilacija

Za OpenAI lahko prevajalnik cilja na strukturirane izhode prek oblikovanja odziva za naloge ekstrakcije in klasifikacije ali strogega klicanja funkcij za poteke dela, usmerjene v dejanja. Prevedeni koristni tovor mora vključevati podprto podmnožico sheme in nastavitve strogosti, specifične za ponudnika, če so na voljo.

Anthropic compilation

Za Anthropic bo prevajalnik pogosto predstavil želeni rezultat kot orodje z input_schema. Aplikacija nato pričakuje blok uporabe orodja in preveri vnos orodja glede na kanonično shemo. To pomeni, da mora adapter normalizirati ovojnico odgovora, ne le razčleniti JSON.

Gemini compilation

Za Gemini mora prevajalnik ciljati na strukturirano konfiguracijo odziva JSON z uporabo samo podmnožice podprte sheme. Če kanonična shema uporablja omejitve, ki jih Gemini ne uveljavlja izvorno, mora prevajalnik zabeležiti te omejitve, kot da zahtevajo preverjanje na strani aplikacije.

Izhod adapterja je treba normalizirati v en notranji tip 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;
};

Ta normalizacija preprečuje, da bi bila koda poteka dela odvisna od ponudnikovih ovojnic.

4. korak: preverite vsak odziv glede na kanonično shemo

Struktura na strani ponudnika je prva obrambna linija in ne končno preverjanje pravilnosti. Ko se model odzove, vedno preverite razčlenjeni izhod glede na kanonično shemo.

Preverjanje med izvajanjem mora povzročiti strukturirane napake, kot so:

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

Strukturno validacijo hranite ločeno od semantične validacije. JSON Shema lahko preveri obliko, zahtevane lastnosti, enume in osnovne omejitve tipa. Ne more v celoti izraziti poslovnih pravil, kot so veljavni prehodi stanj, pragovi odobritve, pravilnik za posamezne stranke ali medsebojno odvisne kombinacije polj.

To je na primer semantični validator, ne pravilo sheme:

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

Vstavite ta preverjanja v kodo aplikacije, kjer lahko uporabljajo konfiguracijo stranke, stanje delovnega toka, avtorizacijski kontekst in različice pravilnika.

5. korak: Uporabite omejeno popravilo, nato neuspešno zaprto

Pot popravila lahko obnovi majhne izhodne napake, lahko pa tudi skrije sistematično shemo in takojšnje težave. Uporabite en ciljni poskus popravila z vključeno napako pri preverjanju. Če popravljen odgovor še vedno ne prestane preverjanja, neuspešno zaprite ali usmerite na pregled.

Praktični pravilnik o popravilu izgleda takole:

• Poskusite popraviti samo primerne vrste napak, kot so manjkajoča zahtevana polja, neveljavna enume ali nepravilno oblikovana JSON.
• Ne popravljajte ponudnikovih zavrnitev, varnostnih blokad, napak avtorizacije ali izhodov, ki so občutljivi na pravilnike.
• V poziv za popravilo vključite različico kanonične sheme in napako pri preverjanju.
• Dovoli največ en poskus popravila za poteke dela, ki so vidni stranki ali sprožijo dejanja.
• Število popravil dnevnika, uspeh popravila, uporaba žetona in končno stanje.

Za opravila notranje ekstrakcije z nizkim tveganjem je sprejemljiv drugi poskus popravila, če zakasnitev ni pomembna. Za poteke dela, ki sprožijo plačila, spremembe dostopa, odzive partnerja API ali dejanja skladnosti, je pravilnik o zaprtju zaradi napake običajno varnejši.

6. korak: Izdelajte pogodbene preizkuse za vsak proizvodni model

Pogodbeni testi odločajo, ali je model primeren za potek dela. Zagnati jih je treba pred začetnim zagonom, pred nadgradnjami modela in pred spremembami pravilnika o usmerjanju.

Preizkusite vsak model in adapter ponudnika vsaj za:

• Veljaven rezultat srečne poti.
• Manjkajoča obvezna polja.
• Neveljavne enum vrednosti.
• Dodatne lastnosti, ko je shema zaprta.
• Preveč elementov polja.
• Predolgi nizi.
• Zavrnitev ali nezmožnost izpolnjevanja.
• Skrajšan izpis.
• Neujemanje priklica orodja ali manjkajoči klic orodja.
• Strukturno veljaven, vendar pomensko napačen izpis.

Uporabi kontradiktorne pozive, ki pritiskajo na model, da krši pogodbo. Prosite ga na primer, naj doda dodatno razlagalno polje, vrne prednost zunaj enum ali izpusti zahtevano logično vrednost. Preizkus je uspešen le, če ponudnik, adapter in validator ustvarijo pričakovano stanje aplikacije.

Za vsak potek dela vzdržujte preprost zapis združljivosti:

{
  "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"]
}

Ta matrika zmogljivosti sodi v nadzorno ravnino, ne v razpršene konstante aplikacije.

7. korak: Zanesljivost strukturiranega izhoda instrumenta

Brez telemetrije ekipe ne morejo ugotoviti, ali napake izvirajo iz nezdružljivosti ponudnika, zamika modela, napak v shemi, napak v pozivu, okrnitve ali spodnjih validatorjev.

Zabeležite ta polja za vsako zahtevo strukturiranega izhoda:

• Ime delovnega toka in različica sheme.
• Ponudnik, zahtevani model in model odziva.
• Izhodni način, kot je odzivna shema, klic orodja ali JSON način.
• Status preverjanja in vrsta napake.
• Število popravil in rezultat popravila.
• Dokončaj razlog in stanje zavrnitve.
• Žetoni poziva, žetoni dokončanja, skupni stroški in zakasnitev.
• Različica adapterja in različica prevajalnika.

Uporabite te podatke za primerjavo modelov pred spremembo poti. Cenejši model ni cenejši, če poveča število poskusov popravila, ročni pregled, napake partnerja API ali nadaljnje obravnave incidentov.

Kompromisi za eksplicitno odločitev

Sheme najmanjšega skupnega imenovalca izboljšajo prenosljivost, vendar oslabijo omejitve. Če je treba shemo zahteve ponudnika poenostaviti, ohranite strožja preverjanja pri kanoničnem preverjanju in semantičnih validatorjih.

Prevajanje, specifično za ponudnika, ohranja izvorne prednosti, vendar dodaja vzdrževanje. To se običajno splača za produkcijske poteke dela, vendar le, če imajo prevajalniki različice in jih pokrivajo pogodbeni testi.

Stroge sheme zmanjšajo napake razčlenjevalnika, vendar zahtevajo boljšo zasnovo opravila. Če je opravilo premalo določeno, strogost prej razkrije dvoumnost. To je koristno, vendar lahko upočasni začetni razvoj.

Popravilo izboljša stopnje dokončanja, vendar doda stroške in zakasnitev. Omejeno popravilo je obnovitveni mehanizem in ne nadomestek za načrtovanje sheme.

Klicanje orodij in oblika odziva JSON služita različnim potekom dela. Klicanje orodij je pogosto bolj primerno za poteke dela, usmerjene v dejanja. Oblika odgovora JSON je enostavnejša za ekstrakcijo, klasifikacijo in povzemanje. Platforma z več modeli lahko podpira oboje, vendar mora biti politika poteka dela eksplicitna.

Napovedi: Kam gre prenosljivost strukturiranih izhodov

Podpora ponudnika za strukturiran izhod se bo verjetno še naprej izboljševala, vendar ne bi smeli domnevati popolne JSON prenosljivosti sheme med modeli. Ponudniki imajo različne arhitekture modelov, API zgodovine, vzorce uporabe orodij in varnostno vedenje. Tudi ko bo podpora shemi močnejša, bodo aplikacije še vedno potrebovale kanonično preverjanje, ker je pravilnost poslovanja odvisna od več kot JSON oblike.

Ekipe bi morale pričakovati, da bodo odločitve o usmerjanju strukturiranih izhodnih podatkov bolj temeljile na podatkih. Zanesljivost, stopnja popravil, obravnavanje zavrnitev, zakasnitev in stroški bodo pomembni poleg kakovosti modela. Operativno vprašanje se bo premaknilo z "ali ta model podpira JSON?" na "ali ta model izpolnjuje pogodbo tega poteka dela po sprejemljivi ceni in stopnji napak?"

Kontrolni seznam za implementacijo

• Določite eno kanonično shemo na potek dela.
• Različite sheme in ohranite koristne obremenitve zahtev ponudnika ponovljive.
• Dodajte CI linting za nepodprte ali tvegane funkcije sheme.
• Prevedite kanonične sheme v formate, specifične za ponudnika.
• Normalizirajte ovojnice ponudnika v eno interno vrsto rezultata.
• Preveri vsak razčlenjen odgovor glede na kanonično shemo.
• Dodajte semantične validatorje za poslovna pravila.
• Dovoli samo omejene poskuse popravljanja.
• Neuspešno zaprtje ali usmeritev na pregled zaradi potekov dela z visokim tveganjem.
• Izvedite pogodbene preizkuse, preden dodate ali nadgradite proizvodne modele.
• Vzdrževanje matrike zmogljivosti modela v nadzorni ravnini.
• Polja za preverjanje dnevnika, popravilo, stroške, zakasnitev, ponudnika in model za vsako zahtevo.

Uporabni sklep

Prenosljivost strukturiranega izhoda je API težava s pogodbo, ne težava s takojšnjim oblikovanjem. Zanesljiv vzorec je definirati kanonično poslovno shemo, jo prilagoditi za prenosljivost, prevesti v izvorno površino vsakega ponudnika, potrditi vsak odgovor, potem ko ga ponudnik vrne, in uporabiti pogodbene preizkuse za odločitev, kateri modeli so primerni za proizvodnjo.

Ta zasnova dodaja nekaj vnaprejšnjega inženirskega dela, vendar preprečuje dražji način odpovedi: sistemi na nižji stopnji prevzamejo stabilno pogodbo, medtem ko se usmerjanje modela, vedenje ponudnika ali uveljavljanje sheme tiho spreminjajo pod njimi.

Sorodno branje

• nadomestno usmerjanje, ki ščiti strukturiran izhod pogodbe