Strukturerte utganger i en multi-modell API-gateway: JSON-skjema, verktøyanrop og semantiske rekkverk

Å be en modell om å "returnere JSON" er ikke en produksjonskontrakt. Den kan produsere gyldig JSON med feil enum, utelate en påkrevd forretningsregel eller trygt be om en handling som brukeren aldri har autorisert. I en arbeidsflyt med flere leverandører blir problemet vanskeligere: hver leverandør avslører forskjellige strukturerte utdata- og verktøybruksmekanismer, og hver enkelt støtter bare deler av JSON Schema-universet.

Den praktiske løsningen er ikke én magisk oppfordring. Det er et lagdelt gateway-mønster: normaliser utviklerens ønskede skjema, oversett det til leverandør-native strukturerte utdata- eller verktøy-anropsformater der det er mulig, valider det returnerte objektet og bruk semantiske rekkverk før enhver bivirkning.

Denne veiledningen skiller tre forskjellige mål som ofte blandes sammen:

• Syntaksvaliditet: svaret er parsebar JSON.
• Skjemagyldighet: JSON samsvarer med obligatoriske felt, typer, oppsummeringer og strukturelle regler.
• Forretningsmessig korrekthet: Objektet er trygt, tro mot brukerhensikten og gyldig for nedstrømshandlingen.

Produksjonsfeilen: gyldig JSON, feil handling

Vurder en støtteautomatisering som ruter innkommende billetter:

{
  "ticket_id": "t_481",
  "category": "fakturering",
  "priority": "haster",
  "action": "refund_customer",
  "amount_usd": 499
}

Dette objektet er syntaktisk gyldig. Den kan til og med sende et enkelt skjema hvis handling er en streng og amount_usd er et tall. Men det kan fortsatt være feil. Kanskje kunden bare ba om en fakturakopi. Kanskje krever refusjon over 100 USD godkjenning fra lederen. Kanskje brukeren ikke er autorisert til å utløse refusjoner i det hele tatt.

Strukturerte utganger reduserer analyseringsfeil. De erstatter ikke autorisasjon, policykontroller, lagerkontroller, priskontroller, idempotens eller menneskelig bekreftelse for risikable operasjoner.

Fakta: hva leverandørens strukturerte utdatamoduser gjør og ikke lover

Tilbyderlandskapet endres raskt, men flere stabile fakta har betydning for arkitekturen:

• JSON-modus kan bidra til å produsere gyldig JSON, men gyldig JSON er ikke det samme som samsvar med et spesifikt skjema.
• Provider-native strukturerte utdatamoduser er utviklet for å forbedre skjemaoverholdelse, men de støtter vanligvis bare et undersett av JSON-skjemaet.
• Verktøykall passer vanligvis bedre for handlinger enn JSON i fritt format fordi modellen velger et erklært verktøy og returnerer strukturerte argumenter, mens applikasjonen fortsatt er ansvarlig for utførelse.
• Ulike leverandører avslører ulike kontrakter. En kan bruke et strengt JSON-skjema-svarformat, en annen kan bruke verktøyinndataskjemaer, og en annen kan kreve en validering-og-forsøk på nytt.
• Selv skjemagyldig utdata kan være semantisk feil før den når en database, arbeidsflyt eller betalt handling.

Den arkitektoniske implikasjonen er enkel: en OpenAI-kompatibel API kan standardisere klientgrensesnittet, men pålitelighetslaget må fortsatt forstå leverandørens evner og validere utdata etter generering.

Anbefalt arkitektur: adapteren for strukturert utgang

Bruk en gateway-sideadapter mellom programkode og leverandør-API-er. Applikasjonen sender én skjemaintensjon. Gatewayen kartlegger hensikten til den sterkeste støttede leverandørmekanismen.

1. Godta én normalisert forespørsel fra applikasjonen

Klienten skal ikke trenge separate kodestier for hver leverandør. En praktisk forespørselskonvolutt inkluderer modellpreferanse, oppgaveinndata, skjema, skjemametadata og risikonivå:

{
  "model": "auto:nøyaktig",
  "meldinger": [
    {"role": "system", "content": "Trekk ut fakturafelt. Ikke antyd manglende verdier."},
    {"role": "user", "content": "Fakturatekst..."}
  ],
  "structured_output": {
    "schema_id": "invoice_extraction",
    "schema_version": "2026-08-01",
    "mode": "json_schema",
    "streng": sant,
    "skjema": {
      "type": "objekt",
      "additionalProperties": usant,
      "required": ["invoice_number", "vendor_name", "total", "currency", "dee_date"],
      "properties": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "total": {"type": "nummer", "minimum": 0},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "string", "format": "date"},
        "confidence": {"type": "nummer", "minimum": 0, "maksimum": 1}
      }
    }
  },
  "metadata": {
    "workflow": "kontoer",
    "risk_level": "middels"
  }
}

Denne kontrakten gir gatewayen nok informasjon til å velge en leverandørbasert implementering, kjøre validering og logge meningsfulle feildata.

2. Oppretthold en leverandørkapasitetsmatrise

Gatewayen bør ha en maskinlesbar kapasitetsmatrise, ikke stole på forutsetninger som "alle OpenAI-kompatible modeller støtter samme skjemaatferd." En nyttig matrise inkluderer:

• Leverandør og modellnavn.
• Støtter JSON-modus.
• Støtter JSON Schema-svarformat.
• Støtter verktøykall.
• Støtter streng skjemamodus.
• Kjente begrensninger for JSON Schema-delsett.
• Om parallelle verktøykall er kompatible med streng skjemamodus.
• Tilbakegangsatferd når den forespurte modusen ikke støttes.

Eksempel på kapasitetspost:

{
  "provider": "provider_a",
  "model": "model_x",
  "json_mode": sant,
  "json_schema_response": sant,
  "tool_calls": sant,
  "strict_schema": sant,
  "schema_limitations": ["no oneOf", "begrenset formatvalidering"],
  "fallback": "reject_or_route_to_compatible_model"
}

Denne matrisen bør være versjonert og testet. Når en leverandør endrer atferd eller en ny modell legges til, bør strukturert utdatakompatibilitet verifiseres før produksjonsruting.

3. Oversett til den sterkeste leverandør-native kontrakten

Adapteren bør følge en klar preferanserekkefølge:

1. Bruk strenge leverandørbaserte strukturerte utdata når det støttes av den valgte modellen og skjemaet.
2. Bruk leverandørbasert verktøy som krever handlinger og funksjonslignende oppgaver.
3. Bruk ikke-streng strukturert utdata eller JSON-modus med validering og forsøk på nytt når streng modus ikke er tilgjengelig.
4. Avvis forespørselen, rute til en kompatibel reservemodell, eller returner et ikke-handlingssvar for arbeidsflyter med høy risiko.

Ikke nedgrader i det stille en høyrisikooperasjon fra streng skjemamodus til «best innsats JSON». Hvis applikasjonen ba om streng oppførsel og den valgte leverandøren ikke kan støtte det, bør gatewayen gjøre det synlig gjennom en feil, rutingbeslutning eller eksplisitt nedgraderingsflagg.

Tre valideringslag før utførelse

Lag 1: analysere validering

Først avgjør om svaret kan analyseres inn i den forventede konvolutten. Mislykkes raskt på misformet JSON, manglende blokkering av verktøyanrop, avkortede svar eller blandet naturlig språk og JSON når kontrakten forbyr det.

funksjon parseStructuredResponse(rå) {
  prøv {
    return { ok: sann, verdi: JSON.parse(rå) };
  } catch (feil) {
    return { ok: false, failure_type: "parse_failure", feil: String(error) };
  }
}

Tilbydernative verktøykall krever kanskje ikke å analysere en råtekstklump, men de krever fortsatt konvoluttvalidering: valgte modellen et kjent verktøy, ga den argumenter, og stoppet den for verktøykjøring som forventet?

Lag 2: JSON-skjemavalidering

Deretter validerer du objektet mot det deklarerte skjemaet ved hjelp av en validator på serversiden. Gjør dette selv når leverandøren krever streng skjemastøtte. Validering på gatewaysiden gir deg konsekvent feillogging, beskytter mot integrasjonsfeil og fanger opp nedstrømsinkompatibiliteter.

const validate = schemaValidator.compile(schema);
const gyldig = validere(objekt);
if (!gyldig) {
  returnere {
    ok: usant,
    failure_type: "schema_failure",
    feil: validere.feil
  };
}

For portabilitet, utform skjemaer med det vanlige delsettet i tankene:

• Foretrekk eksplisitt type, påkrevd, egenskaper, enum og additionalProperties: false.
• Unngå komplekse kombinasjoner som dypt nestede oneOf, anyOf og betingede skjemaer med mindre du vet at målleverandøren støtter dem.
• Hold handlingsargumenter små og konkrete.
• Bruk strenger for ID-er, datoer og koder med mindre nedstrømssystemer krever en annen type.
• Representer usikkerhet eksplisitt med felt som confidence, missing_fields eller requires_human_review.

Lag 3: semantisk og forretningsvalidering

Til slutt, valider om det strukturerte resultatet er riktig for oppgaven. Dette laget er domenespesifikt og kan ikke outsources til JSON Schema alene.

For fakturautvinning kan semantiske kontroller omfatte:

• Totalen er ikke-negativ og samsvarer med ordrelinjer innenfor toleranse.
• Valutaen vises i kildedokumentet.
• Forfallsdatoen ligger ikke umulig langt i fortiden eller fremtiden.
• Leverandøren finnes i en godkjent leverandørliste.
• Konfidensen er høy nok for automatisk inntasting.

For potensielle kvalifiseringer kan sjekkene omfatte:

• Det valgte segmentet er et av salgsteamets aktive segmenter.
• Det forespurte budsjettet er ikke oppfunnet når brukeren ikke oppga et.
• En "bokdemo"-handling utføres ikke med mindre brukeren uttrykkelig har bedt om det.

For Partner API-automatisering kan sjekkene omfatte:

• Forhandlerkontoen er autorisert til å opprette den forespurte kunden eller nøkkelen.
• Den forespurte forbruksgrensen er innenfor partnerens retningslinjer.
• Operasjonen har en idempotensnøkkel.
• Handlingen registreres i en revisjonslogg før utførelse.

Verktøykall: behandle modellutdata som en forespørsel, ikke en utførelse

Tool calling er det riktige mønsteret når modellen må be applikasjonen om å gjøre noe: opprette en billett, sende en Telegram-bot-kommando, slå opp priser, oppdatere en kundepost eller starte en arbeidsflyt.

En sikker verktøyløkke ser slik ut:

1. Appen erklærer tilgjengelige verktøy og deres inndataskjemaer.
2. Modellen returnerer et verktøykall med strukturerte argumenter.
3. Gatewayen validerer verktøynavnet og argumentene.
4. Appen sjekker autorisasjons-, policy-, idempotens- og brukerbekreftelseskrav.
5. Først da kjører applikasjonen verktøyet.
6. Verktøyresultatet sendes tilbake til modellen hvis samtalen må fortsette.

Behandle aldri et verktøykall som et bevis på at handlingen skal skje. Behandle det som et strukturert forslag. Søknaden forblir autoriteten for bivirkninger.

Sikker reservestige for arbeidsflyter med flere modeller

En gateway bør definere reserveatferd før hendelser oppstår. En praktisk stige er:

1. Primær: strengt strukturert utdata på den foretrukne modellen.
2. Kompatibel reserve: en annen modell som støtter de samme strenge skjemakravene.
3. Validering og prøv på nytt: en leverandør uten streng støtte, brukes kun når risikoen tillater det.
4. Menneskelig vurdering: sett det strukturerte resultatet og kildeinnholdet i kø for godkjenning.
5. Ikke-handling: forklar at systemet ikke kan fullføre operasjonen på en sikker måte.

Forsøk på nytt er nyttige for formatering eller mindre skjemafeil, men de er ikke en sikkerhetsstrategi. Hvis objektet er semantisk usikkert, kan gjentatte spørsmål gjøre en korrekt avvisning til et farlig kjørbart objekt. For handlinger med høy risiko, foretrekk gjennomgang eller avslag fremfor gjentatte forsøk på å fremtvinge suksess.

Observbarhet: logg hver beslutning om strukturert utdata

Strukturerte utgangsfeil er driftssignaler. Logg dem med nok detaljer til å forbedre ruting, skjemaer og forespørsler uten å avsløre unødvendig sensitivt innhold.

Anbefalte felt:

• schema_id og schema_version.
• Leverandør og modell.
• Forespurt modus og faktisk modus brukt.
• Parse feilstatus.
• Skjemafeilstatus og valideringsfeil.
• Årsak til feil ved semantisk validering.
• Prøv å telle på nytt.
• Forsinkelse.
• Tokenbruk og kostnad.
• Endelig handlingsstatus: utført, satt i kø, avvist eller returnert til brukeren.
• Team-, prosjekt-, API-nøkkel eller partnerkontoidentifikator der det er aktuelt.

Disse loggene støtter feilsøking, kostnadsanalyse, leverandørsammenligning og team-API-styring. De hjelper også med å svare på spørsmål som: "Hvilken skjemaversjon forårsaker flest forsøk?" og "Hvilken reservemodell passerer syntaks, men mislykkes med forretningsvalidering?"

Regler for skjemaversjon

Skjemaer er produksjonsgrensesnitt. Behandle dem som API-kontrakter.

• Inkluder schema_id og schema_version i forespørselsmetadata og logger.
• Ikke endre obligatoriske felt stille for eksisterende automatiseringer.
• Hold gamle skjemaer tilgjengelige mens klienter migrerer.
• Legg til nye valgfrie felt før du gjør dem obligatoriske.
• Test skjemaer mot alle leverandører og reservemodeller i rutingpoolen.
• Registrer hvilken skjemaversjon som ble brukt for hver bivirkning.

Versjonsbehandling blir spesielt viktig for byråer, forhandlere og Partner API-automatisering, der mange nedstrømskunder kan være avhengige av en stabil strukturert kontrakt.

Når man ikke skal utføre et strukturert resultat

Bruk en hard stop når noen av følgende forhold oppstår:

• Responsen kan ikke analyseres.
• Objektet mislykkes i JSON-skjemavalideringen.
• En enum-verdi støttes ikke eller er oppfunnet.
• En mengde, pris, dato eller valuta er umulig.
• Resultatet er i konflikt med brukerens uttalte hensikt.
• Modellen uttrykker lav tillit eller manglende bevis.
• Brukerinstruksjonen er tvetydig.
• Handlingen har bivirkninger og mangler bekreftelse.
• Kontoen, teamet eller API-nøkkelen er ikke autorisert.
• Tilbyderens svar inkluderer et avslag eller sikkerhetsrelatert ikke-svar.

Anbefalinger kontra spådommer

Anbefalinger: bruk leverandørnative strukturerte utdata der det er tilgjengelig, valider hver responsgatewayside, foretrekk verktøyoppfordringer for handlinger, oppretthold en funksjonsmatrise, versjonsskjemaer og blokker bivirkninger inntil semantiske kontroller passerer.

Spådommer: leverandørstøtte for strukturerte utdata vil sannsynligvis bli sterkere og mer konsistent, men portabilitet vil forbli en gateway-bekymring fordi modellfamilier, skjemaundersett og verktøyanropsløkker ikke blir identiske over natten. Team som bygger validering, observerbarhet og skjemaversjon nå, vil være bedre posisjonert til å ta i bruk nye leverandørfunksjoner uten å omskrive hver arbeidsflyt.

Hjelpbar implementeringssjekkliste

1. Definer et forespørselsformat for normalisert strukturert utdata for applikasjonene dine.
2. Lag en leverandørkapasitetsmatrise for hver modell i rutingpoolen din.
3. Design skjemaer med et bærbart JSON Schema-undersett.
4. Oversett forespørsler til strenge leverandørbaserte mekanismer når de støttes.
5. Valider parsebarhet, skjemakonformitet og forretningskorrekthet etter generering.
6. Bruk verktøykall for bivirkninger.
7. Krev autorisasjon, idempotens og bekreftelse utenfor modellen.
8. Loggskjemaversjon, leverandør, valideringsfeil, gjenforsøk, ventetid, kostnad og handlingsstatus.
9. Definer reserveatferd etter arbeidsflytrisikonivå.
10. Hold gamle skjemaer tilgjengelige til avhengige automatiseringer migrerer.

Det praktiske målet er ikke å få alle modeller til å oppføre seg likt. Det er å gi applikasjonsutviklere én stabil kontrakt mens gatewayen håndterer leverandørforskjeller ærlig. Strukturerte utganger er nødvendig infrastruktur for pålitelig AI-automatisering, men produksjonsgrensen er validatoren og policylaget som avgjør om et objekt er trygt å bruke.

Relatert lesing

• sem-routing-3-model-fall-back-retries regresjoner
• API-nøkkelautorisasjon og teamkontroller
• sporing av tokenkostnad og forsinkelse for gjenforsøk