Strukturirani izhodi v prehodu API-ja z več modeli: shema JSON, klici orodij in semantične zaščitne ograje

Pozivanje modela, naj »vrne JSON«, ni produkcijska pogodba. Lahko ustvari veljaven JSON z napačnim enumom, izpusti zahtevano poslovno pravilo ali samozavestno zahteva dejanje, ki ga uporabnik ni nikoli odobril. V poteku dela z več ponudniki postane težava težja: vsak ponudnik izpostavi različne mehanizme strukturiranega izhoda in uporabe orodij in vsak podpira samo del vesolja sheme JSON.

Praktična rešitev ni en čarobni poziv. To je večplastni vzorec prehoda: normalizirajte razvijalčevo želeno shemo, jo prevedite v ponudnikove izvorne formate strukturiranih izhodnih podatkov ali orodnih klicev, kjer je to mogoče, potrdite vrnjeni objekt in uporabite semantične zaščitne ograje pred kakršnim koli stranskim učinkom.

Ta vodnik ločuje tri različne cilje, ki se pogosto mešajo:

• Veljavnost sintakse: odgovor je razčlenljiv JSON.
• Veljavnost sheme: JSON se ujema z zahtevanimi polji, vrstami, enumami in strukturnimi pravili.
• Poslovna pravilnost: predmet je varen, zvest uporabniškemu namenu in veljaven za nadaljnje dejanje.

Napaka v proizvodnji: veljaven JSON, napačno dejanje

Razmislite o avtomatizaciji podpore, ki usmerja dohodne prijave:

{
  "ticket_id": "t_481",
  "kategorija": "obračun",
  "priority": "nujno",
  "action": "refund_customer",
  "znesek_usd": 499
}

Ta objekt je sintaktično veljaven. Lahko celo prenese preprosto shemo, če je action niz in amount_usd številka. Ampak še vedno je lahko narobe. Mogoče je stranka zahtevala le kopijo računa. Morda je za vračila nad 100 USD potrebna odobritev upravitelja. Morda uporabnik sploh ni pooblaščen za sprožitev vračil.

Strukturirani izhodi zmanjšujejo napake pri razčlenjevanju. Ne nadomeščajo avtorizacije, preverjanj politik, preverjanj inventarja, preverjanj cen, idempotence ali človeške potrditve za tvegane operacije.

Dejstva: kaj načini strukturiranega izhoda ponudnika obljubljajo in kaj ne

Pokrajina ponudnikov se hitro spreminja, vendar je za arhitekturo pomembnih več stabilnih dejstev:

• Način JSON lahko pomaga ustvariti veljaven JSON, vendar veljaven JSON ni isto kot skladnost z določeno shemo.
• Načini strukturiranega izhoda, ki izvirajo iz ponudnika, so zasnovani za izboljšanje skladnosti s shemo, vendar običajno podpirajo samo podmnožico sheme JSON.
• Klicanje orodij je običajno bolj primerno za dejanja kot prosta oblika JSON, ker model izbere deklarirano orodje in vrne strukturirane argumente, medtem ko je aplikacija še naprej odgovorna za izvajanje.
• Različni ponudniki izpostavljajo različne pogodbe. Eden lahko uporablja strogo obliko odziva sheme JSON, drugi lahko uporablja sheme vnosa orodja, tretji pa lahko zahteva nadomestno preverjanje in ponovni poskus.
• Celo izhod, ki velja za shemo, je lahko semantično napačen, preden doseže zbirko podatkov, potek dela ali plačano dejanje.

Arhitekturna implikacija je preprosta: API, združljiv z OpenAI, lahko standardizira vmesnik odjemalca, vendar mora sloj zanesljivosti še vedno razumeti zmožnosti ponudnika in preverjati rezultate po ustvarjanju.

Priporočena arhitektura: vmesnik s strukturiranim izhodom

Uporabite vmesnik na strani prehoda med kodo aplikacije in API-ji ponudnika. Aplikacija pošlje en namen sheme. Prehod preslika to namero v najmočnejši podprti mehanizem ponudnika.

1. Sprejmi eno normalizirano zahtevo iz aplikacije

Odjemalec ne bi smel potrebujeti ločenih kodnih poti za vsakega ponudnika. Praktična ovojnica zahteve vključuje nastavitev modela, vnos naloge, shemo, metapodatke sheme in stopnjo tveganja:

{
  "model": "samodejno:natančno",
  "sporočila": [
    {"role": "system", "content": "Izvlecite polja računa. Ne sklepajte na manjkajoče vrednosti."},
    {"role": "user", "content": "Besedilo računa ..."}
  ],
  "strukturiran_izhod": {
    "schema_id": "ekstrakcija_računa",
    "schema_version": "2026-08-01",
    "način": "shema_json",
    "strogo": res,
    "shema": {
      "vrsta": "predmet",
      "additionalProperties": false,
      "required": ["invoice_number", "vendor_name", "total", "currency", "due_date"],
      "lastnosti": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "total": {"type": "number", "minimum": 0},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "string", "format": "date"},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1}
      }
    }
  },
  "metapodatki": {
    "workflow": "accounts_payable",
    "raven_tveganja": "srednja"
  }
}

Ta pogodba daje prehodu dovolj informacij za izbiro implementacije, ki je izvirna od ponudnika, zagon preverjanja in beleženje pomembnih podatkov o napakah.

2. Vzdržujte matriko zmogljivosti ponudnika

Prehod mora ohraniti strojno berljivo matriko zmogljivosti, ne pa se zanašati na predpostavke, kot je "vsi modeli, združljivi z OpenAI, podpirajo isto vedenje sheme." Uporabna matrika vključuje:

• Ime ponudnika in modela.
• Podpira način JSON.
• Podpira obliko odziva sheme JSON.
• Podpira klice orodij.
• Podpira način stroge sheme.
• Znane omejitve podnabora sheme JSON.
• Ali so vzporedni klici orodij združljivi z načinom stroge sheme.
• Nadomestno vedenje, ko zahtevani način ni podprt.

Primer zapisa zmogljivosti:

{
  "ponudnik": "ponudnik_a",
  "model": "model_x",
  "json_mode": drži,
  "json_schema_response": res,
  "tool_calls": drži,
  "strict_schema": res,
  "schema_limitations": ["no oneOf", "omejeno preverjanje formata"],
  "fallback": "zavrni_ali_usmeri_na_združljiv_model"
}

Ta matrika bi morala imeti različico in jo preizkusiti. Ko ponudnik spremeni vedenje ali je dodan nov model, je treba pred usmerjanjem proizvodnje preveriti združljivost strukturiranega izhoda.

3. Prevedite v najmočnejšo izvorno pogodbo ponudnika

Vmesnik mora slediti jasnemu prednostnemu vrstnemu redu:

1. Uporabite striktne izvorne strukturirane izhode ponudnika, če jih podpirata izbrani model in shema.
2. Uporabite izvorno orodje ponudnika, ki kliče za dejanja in opravila, podobna funkcijam.
3. Uporabite nestrogi strukturirani izpis ali način JSON s preverjanjem in ponovnimi poskusi, ko strogi način ni na voljo.
4. Zavrnite zahtevo, usmerite na združljiv nadomestni model ali vrnite odgovor brez ukrepanja za poteke dela z visokim tveganjem.

Ne znižajte na tihem visoko tvegane operacije iz načina stroge sheme v »po najboljših močeh JSON«. Če je aplikacija zahtevala strogo vedenje in izbrani ponudnik tega ne more podpreti, bi moral prehod to prikazati prek napake, odločitve o usmerjanju ali izrecne zastavice za znižanje.

Tri plasti preverjanja pred izvedbo

Prva plast: preverjanje razčlenitve

Najprej ugotovite, ali je odgovor mogoče razčleniti v pričakovano ovojnico. Hitra napaka zaradi napačno oblikovanega JSON-a, manjkajočih blokov klica orodij, okrnjenih odgovorov ali mešanice naravnega jezika in JSON-a, kadar to prepoveduje pogodba.

function parseStructuredResponse(raw) {
  poskusi {
    return { ok: res, vrednost: JSON.parse(raw) };
  } ulov (napaka) {
    return {ok: false, failure_type: "parse_failure", error: String(error) };
  }
}

Klici orodij, ki izvirajo iz ponudnika, morda ne bodo zahtevali razčlenjevanja grunde neobdelanega besedila, vendar še vedno zahtevajo preverjanje ovojnice: ali je model izbral znano orodje, ali je zagotovil argumente in ali se je ustavil za izvajanje orodja, kot je bilo pričakovano?

Sloj 2: Preverjanje sheme JSON

Nato preverite objekt glede na deklarirano shemo z uporabo validatorja na strani strežnika. To storite tudi, če ponudnik trdi, da podpira strogo shemo. Preverjanje na strani prehoda vam omogoča dosledno beleženje napak, ščiti pred napakami pri integraciji in ujame nezdružljivosti na nižji stopnji.

const validate = schemaValidator.compile(shema);
const valid = validate(object);
if (!valid) {
  return {
    v redu: napačno,
    error_type: "shema_failure",
    napake: potrdi.napake
  };
}

Za prenosljivost načrtujte sheme z upoštevanjem skupnega podnabora:

• Daj prednost eksplicitnemu type, required, properties, enum in additionalProperties: false.
• Izogibajte se kompleksnim kombinacijam, kot so globoko ugnezdene oneOf, anyOf in pogojne sheme, razen če veste, da jih ciljni ponudnik podpira.
• Argumenti o dejanjih naj bodo majhni in konkretni.
• Uporabite nize za ID-je, datume in kode, razen če nadaljnji sistemi zahtevajo drugo vrsto.
• Izrecno predstavite negotovost s polji, kot so confidence, missing_fields ali requires_human_review.

3. plast: semantična in poslovna validacija

Na koncu preverite, ali je strukturiran rezultat pravilen za nalogo. Ta plast je specifična za domeno in je ni mogoče prenesti samo na shemo JSON.

Za ekstrakcijo računa lahko semantična preverjanja vključujejo:

• Vsota je nenegativna in se ujema z vrstičnimi postavkami znotraj tolerance.
• Valuta je prikazana v izvornem dokumentu.
• Datum zapadlosti ni nemogoče daleč v preteklosti ali prihodnosti.
• Dobavitelj obstaja na odobrenem seznamu prodajalcev.
• Zaupanje je dovolj visoko za samodejni vnos.

Za kvalifikacijo vodilnega moža lahko preverjanja vključujejo:

• Izbrani segment je eden od aktivnih segmentov prodajne ekipe.
• Zahtevani proračun ni izmišljen, če ga uporabnik ni zagotovil.
• Dejanje »predstavitev knjige« se ne izvede, razen če uporabnik tega izrecno zahteva.

Za avtomatizacijo API-ja Partner lahko preverjanja vključujejo:

• Račun preprodajalca je pooblaščen za ustvarjanje zahtevane stranke ali ključa.
• Zahtevana omejitev porabe je v okviru partnerske politike.
• Operacija ima ključ za idempotenco.
• Dejanje se pred izvedbo zabeleži v revizijski dnevnik.

Klici orodja: obravnavajte izhod modela kot zahtevo, ne kot izvedbo

Klicanje orodij je pravi vzorec, ko mora model od aplikacije zahtevati nekaj: ustvariti vstopnico, poslati ukaz Telegram bot, poiskati cene, posodobiti zapis stranke ali začeti potek dela.

Varna zanka orodja izgleda takole:

1. Aplikacija navaja razpoložljiva orodja in njihove vnosne sheme.
2. Model vrne klic orodja s strukturiranimi argumenti.
3. Prehod preveri ime orodja in argumente.
4. Aplikacija preveri avtorizacijo, politiko, idempotenco in zahteve za potrditev uporabnika.
5. Šele nato aplikacija izvede orodje.
6. Če se mora pogovor nadaljevati, se rezultat orodja pošlje nazaj modelu.

Klica orodja nikoli ne obravnavajte kot dokaz, da se mora dejanje zgoditi. Obravnavajte ga kot strukturiran predlog. Aplikacija ostaja avtoriteta za stranske učinke.

Varna nadomestna lestvica za poteke dela z več modeli

Prehod mora definirati nadomestno vedenje, preden pride do incidentov. Praktična lestev je:

1. Primarni: strogo strukturiran izpis na želenem modelu.
2. Združljiva nadomestna različica: drug model, ki podpira enake stroge zahteve sheme.
3. Preverjanje in ponovni poskus: ponudnik brez stroge podpore, ki se uporablja samo, kadar tveganje to dopušča.
4. Ročni pregled: postavite strukturiran rezultat in izvorno vsebino v čakalno vrsto za odobritev.
5. Odziv na neukrepanje: pojasnite, da sistem ne more varno dokončati operacije.

Ponovni poskusi so uporabni za formatiranje ali manjše napake sheme, vendar niso varnostna strategija. Če objekt ni semantično varen, lahko ponavljajoče se pozivanje pravilno zavrnitev spremeni v nevaren izvedljiv objekt. Pri dejanjih z visokim tveganjem raje pregledajte ali zavrnite kot ponavljajoče se poskuse izsiljanja uspeha.

Opazljivost: zabeležite vsako odločitev o strukturiranem izhodu

Napake strukturiranih izhodov so signali delovanja. Zabeležite jih z dovolj podrobnostmi za izboljšanje usmerjanja, shem in pozivov brez izpostavljanja nepotrebne občutljive vsebine.

Priporočena polja:

• schema_id in schema_version.
• Ponudnik in model.
• Zahtevani in dejanski uporabljen način.
• Stanje napake pri razčlenjevanju.
• Stanje napake sheme in napake pri preverjanju.
• Razlog za napako semantičnega preverjanja.
• Število ponovnih poskusov.
• Zakasnitev.
• Uporaba žetona in stroški.
• Stanje končnega dejanja: izvedeno, v čakalni vrsti, zavrnjeno ali vrnjeno uporabniku.
• Ekipa, projekt, ključ API ali identifikator računa partnerja, kjer je to primerno.

Ti dnevniki podpirajo odpravljanje napak, analizo stroškov, primerjavo ponudnikov in upravljanje skupinskega API-ja. Pomagajo tudi odgovoriti na vprašanja, kot je: "Katera različica sheme povzroča največ ponovnih poskusov?" in »Kateri nadomestni model prenese sintakso, vendar ne uspe potrditve poslovanja?«

Pravila za različico sheme

Sheme so produkcijski vmesniki. Obravnavajte jih kot pogodbe API.

• Vključite schema_id in schema_version v metapodatke in dnevnike zahtev.
• Ne spreminjajte tiho zahtevanih polj za obstoječe avtomatizacije.
• Med selitvijo odjemalcev ohranite na voljo stare sheme.
• Dodajte nova neobvezna polja, preden postanejo obvezna.
• Preizkusite sheme glede na vsakega ponudnika in nadomestni model v usmerjevalni skupini.
• Zapišite, katera različica sheme je bila uporabljena za vsako dejanje s stranskim učinkom.

Različice postanejo še posebej pomembne za agencije, prodajne posrednike in avtomatizacijo API-jev partnerjev, kjer so lahko številne stranke na nižji stopnji odvisne od stabilne strukturirane pogodbe.

Kdaj ne izvesti strukturiranega rezultata

Uporabite močno zaustavitev, ko se pojavi kateri koli od naslednjih pogojev:

• Odgovora ni mogoče razčleniti.
• Objekt ne prestane preverjanja sheme JSON.
• Vrednost enum ni podprta ali izmišljena.
• Količina, cena, datum ali valuta ni mogoča.
• Rezultat je v nasprotju z uporabnikovim namenom.
• Model izraža nizko zaupanje ali manjkajoče dokaze.
• Uporabniška navodila so dvoumna.
• Dejanje ima stranske učinke in nima potrditve.
• Račun, ekipa ali ključ API ni pooblaščen.
• Odziv ponudnika vključuje zavrnitev ali neodgovor, povezan z varnostjo.

Priporočila v primerjavi z napovedmi

Priporočila: uporabite strukturirane izhode, ki izvirajo iz ponudnika, kjer so na voljo, preverite vsak odziv na strani prehoda, dajte prednost klicem orodij za dejanja, vzdržujte matriko zmogljivosti, sheme različic in blokirajte stranske učinke, dokler semantična preverjanja ne opravijo uspešno.

Napovedi: podpora ponudnika za strukturirane izhode bo verjetno postala močnejša in doslednejša, vendar bo prenosljivost ostala skrb prehoda, ker družine modelov, podnabori shem in zanke klicev orodij ne bodo postale enake čez noč. Ekipe, ki zdaj gradijo preverjanje veljavnosti, opazljivost in različice shem, bodo v boljšem položaju za sprejemanje novih funkcij ponudnika, ne da bi prepisale vsak potek dela.

Kontrolni seznam uporabne izvedbe

1. Določite normalizirano strukturirano izhodno obliko zahteve za vaše aplikacije.
2. Ustvarite matriko zmogljivosti ponudnika za vsak model v vaši usmerjevalni skupini.
3. Načrtujte sheme z uporabo prenosnega podnabora shem JSON.
4. Prevedi zahteve v stroge izvorne mehanizme ponudnika, če so podprti.
5. Preverite razčlenljivost, skladnost sheme in poslovno pravilnost po ustvarjanju.
6. Uporabite klice orodij za stranske učinke.
7. Zahtevaj avtorizacijo, idempotenco in potrditev zunaj modela.
8. Različica sheme dnevnika, ponudnik, napake pri preverjanju, ponovni poskusi, zakasnitev, stroški in stanje dejanja.
9. Določite nadomestno vedenje glede na stopnjo tveganja delovnega toka.
10. Stare sheme naj bodo na voljo, dokler se odvisne avtomatizacije ne preselijo.

Praktični cilj ni doseči, da bi se vsi modeli obnašali enako. Razvijalcem aplikacij daje eno stabilno pogodbo, medtem ko prehod pošteno obravnava razlike med ponudniki. Strukturirani izhodi so potrebna infrastruktura za zanesljivo avtomatizacijo umetne inteligence, vendar je proizvodna meja validator in plast pravilnika, ki odloča, ali je predmet varen za uporabo.

Sorodno branje

• nadomestno usmerjanje brez semantične regresije
• Avtorizacija ključa API in nadzor ekipe
• sledenje stroškom žetona in zakasnitvi za ponovne poskuse