Strukturerade utgångar i en API-gateway för flera modeller: JSON-schema, verktygsanrop och semantiska skyddsräcken

Att uppmana en modell att "returnera JSON" är inte ett produktionskontrakt. Den kan producera giltig JSON med fel enum, utelämna en obligatorisk affärsregel eller med tillförsikt begära en åtgärd som användaren aldrig godkände. I ett arbetsflöde med flera leverantörer blir problemet svårare: varje leverantör exponerar olika strukturerade utdata- och verktygsanvändningsmekanismer, och var och en stöder endast en del av JSON Schema-universumet.

Den praktiska lösningen är inte en enda magisk uppmaning. Det är ett lager gatewaymönster: normalisera utvecklarens önskade schema, översätt det till leverantörsbaserade strukturerade utdata- eller verktygsanropsformat där det är möjligt, validera det returnerade objektet och använd semantiska skyddsräcken före eventuella biverkningar.

Den här guiden separerar tre olika mål som ofta blandas ihop:

• Syntaxvaliditet: svaret är tolkbar JSON.
• Schemaets giltighet: JSON matchar obligatoriska fält, typer, uppräkningar och strukturella regler.
• Verksamhetens korrekthet: objektet är säkert, troget användarens avsikt och giltigt för nedströmsåtgärden.

Produktionsfelet: giltig JSON, fel åtgärd

Överväg en supportautomatisering som dirigerar inkommande biljetter:

{
  "ticket_id": "t_481",
  "category": "fakturering",
  "priority": "bråttom",
  "action": "refund_customer",
  "amount_usd": 499
}

Detta objekt är syntaktiskt giltigt. Det kan till och med passera ett enkelt schema om action är en sträng och amount_usd är ett tal. Men det kan fortfarande vara fel. Kunden kanske bara bad om en fakturakopia. Återbetalningar över 100 USD kanske kräver chefens godkännande. Kanske är användaren inte behörig att utlösa återbetalningar alls.

Strukturerade utdata minskar analysfel. De ersätter inte auktorisation, policykontroller, lagerkontroller, priskontroller, idempotens eller mänsklig bekräftelse för riskfyllda operationer.

Fakta: vad leverantörens strukturerade utdatalägen gör och inte lovar

Leverantörslandskapet förändras snabbt, men flera stabila fakta är viktiga för arkitekturen:

• JSON-läge kan hjälpa till att skapa giltig JSON, men giltig JSON är inte detsamma som överensstämmelse med ett specifikt schema.
• Providernative strukturerade utdatalägen är utformade för att förbättra schemaefterlevnaden, men de stöder vanligtvis bara en delmängd av JSON Schema.
• Verktygsanrop passar vanligtvis bättre för åtgärder än JSON i fritt format eftersom modellen väljer ett deklarerat verktyg och returnerar strukturerade argument, medan programmet förblir ansvarigt för exekvering.
• Olika leverantörer avslöjar olika kontrakt. En kan använda ett strikt JSON Schema-svarsformat, en annan kan använda verktygsinmatningsscheman och en annan kan kräva en validering-och-försök igen.
• Till och med schemagiltig utdata kan vara semantiskt fel innan den når en databas, arbetsflöde eller betald åtgärd.

Den arkitektoniska implikationen är enkel: ett OpenAI-kompatibelt API kan standardisera klientgränssnittet, men tillförlitlighetslagret måste fortfarande förstå leverantörens kapacitet och validera utdata efter generering.

Rekommenderad arkitektur: adaptern för strukturerad utdata

Använd en adapter på gatewaysidan mellan programkod och leverantörs-API:er. Applikationen skickar en schemaavsikt. Gatewayen mappar som avser den starkast stödda leverantörsmekanismen.

1. Acceptera en normaliserad begäran från applikationen

Klienten ska inte behöva separata kodsökvägar för varje leverantör. Ett praktiskt förfrågningskuvert inkluderar modellpreferens, uppgiftsinmatning, schema, schemametadata och risknivå:

{
  "model": "auto:exakt",
  "meddelanden": [
    {"role": "system", "content": "Extrahera fakturafält. Dra inte slutsatsen att saknade värden."},
    {"role": "user", "content": "Fakturatext..."}
  ],
  "structured_output": {
    "schema_id": "faktura_extraktion",
    "schema_version": "2026-08-01",
    "mode": "json_schema",
    "strikt": sant,
    "schema": {
      "type": "objekt",
      "additionalProperties": false,
      "required": ["fakturanummer", "leverantörsnamn", "totalt", "valuta", "förfallodatum"],
      "egenskaper": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "total": {"type": "nummer", "minimum": 0},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "sträng", "format": "datum"},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1}
      }
    }
  },
  "metadata": {
    "workflow": "leverantörsreskontra",
    "risk_level": "medium"
  }
}

Det här kontraktet ger gatewayen tillräckligt med information för att välja en leverantörsbaserad implementering, köra validering och logga meningsfulla feldata.

2. Underhåll en leverantörskapacitetsmatris

Gatewayen bör ha en maskinläsbar funktionsmatris, inte förlita sig på antaganden som "alla OpenAI-kompatibla modeller stöder samma schemabeteende." En användbar matris inkluderar:

• Leverantör och modellnamn.
• Stöder JSON-läge.
• Stöder JSON Schema-svarsformat.
• Stöder verktygsanrop.
• Stöder strikt schemaläge.
• Kända begränsningar för JSON Schema-delmängder.
• Om parallella verktygsanrop är kompatibla med strikt schemaläge.
• Reservbeteende när det begärda läget inte stöds.

Exempel på kapacitetspost:

{
  "provider": "provider_a",
  "model": "model_x",
  "json_mode": sant,
  "json_schema_response": sant,
  "tool_calls": sant,
  "strict_schema": sant,
  "schema_limitations": ["ingen av", "begränsat formatvalidering"],
  "fallback": "reject_or_route_to_compatible_model"
}

Denna matris bör vara versionerad och testad. När en leverantör ändrar beteende eller en ny modell läggs till, bör strukturerad utdatakompatibilitet verifieras innan produktionsdirigering.

3. Översätt till det starkaste leverantörsbaserade kontraktet

Adaptern bör följa en tydlig preferensordning:

1. Använd strikt leverantörsbaserade strukturerade utdata när de stöds av den valda modellen och schemat.
2. Använd leverantörsbaserade verktyg som kräver åtgärder och funktionsliknande uppgifter.
3. Använd icke-strikt strukturerad utdata eller JSON-läge med validering och försök igen när strikt läge inte är tillgängligt.
4. Avvisa begäran, dirigera till en kompatibel reservmodell eller returnera ett icke-åtgärdssvar för högrisk-arbetsflöden.

Nedgradera inte i tysthet en högriskoperation från strikt schemaläge till "bästa försök JSON." Om applikationen begärde strikt beteende och den valda leverantören inte kan stödja det, bör gatewayen göra det synligt genom ett fel, routingbeslut eller explicit nedgraderingsflagga.

Tre valideringslager före körning

Layer 1: parse validering

Bestäm först om svaret kan tolkas i det förväntade kuvertet. Misslyckas snabbt på felaktigt format JSON, saknade verktygsanropsblock, trunkerade svar eller blandat naturligt språk och JSON när kontraktet förbjuder det.

funktion parseStructuredResponse(rå) {
  prova {
    return { ok: sant, värde: JSON.parse(rå) };
  } fånga (fel) {
    return { ok: false, failure_type: "parse_failure", fel: String(error) };
  }
}

Providernative verktygsanrop kanske inte kräver att en råtextblobb analyseras, men de kräver fortfarande kuvertvalidering: valde modellen ett känt verktyg, gav den argument och stoppade den för verktygskörning som förväntat?

Lager 2: JSON Schema validering

Nästa, validera objektet mot det deklarerade schemat med hjälp av en validator på serversidan. Gör detta även när leverantören hävdar strikt schemastöd. Validering på gatewaysidan ger dig konsekvent felloggning, skyddar mot integrationsmisstag och fångar nedströms inkompatibiliteter.

const validate = schemaValidator.compile(schema);
const giltig = validera(objekt);
if (!giltig) {
  returnera {
    ok: falskt,
    failure_type: "schema_failure",
    fel: validera.fel
  };
}

För portabilitet, designa scheman med den gemensamma delmängden i åtanke:

• Föredrar explicit typ, required, properties, enum och additionalProperties: false.
• Undvik komplexa kombinationer som djupt kapslade oneOf, anyOf och villkorliga scheman om du inte vet att målleverantören stöder dem.
• Håll handlingsargumenten små och konkreta.
• Använd strängar för ID, datum och koder om inte nedströms system kräver en annan typ.
• Representera osäkerhet explicit med fält som confidence, missing_fields eller requires_human_review.

Lager 3: semantisk och affärsvalidering

Verifiera slutligen om det strukturerade resultatet är korrekt för uppgiften. Det här lagret är domänspecifikt och kan inte läggas ut på enbart JSON Schema.

För fakturautvinning kan semantiska kontroller inkludera:

• Summan är icke-negativ och matchar rader inom tolerans.
• Valutan visas i källdokumentet.
• Förfallodatumet ligger inte omöjligt långt i det förflutna eller framtiden.
• Leverantören finns i en godkänd leverantörslista.
• Konfidensen är tillräckligt hög för automatisk inloggning.

För leadkvalificering kan kontroller inkludera:

• Det valda segmentet är ett av säljteamets aktiva segment.
• Den begärda budgeten är inte uppfunnen när användaren inte angav en.
• En "bokdemo"-åtgärd utförs inte om inte användaren uttryckligen har bett om det.

För Partner API-automatisering kan kontroller inkludera:

• Återförsäljarkontot är auktoriserat att skapa den begärda kunden eller nyckeln.
• Den begärda utgiftsgränsen ligger inom partnerpolicyn.
• Operationen har en idempotensnyckel.
• Åtgärden registreras i en granskningslogg innan den körs.

Verktygsanrop: behandla modellutdata som en begäran, inte en exekvering

Verktygsanrop är det rätta mönstret när modellen behöver be applikationen att göra något: skapa en biljett, skicka ett Telegram-botkommando, slå upp priser, uppdatera en kundpost eller starta ett arbetsflöde.

En säker verktygsslinga ser ut så här:

1. Applikationen deklarerar tillgängliga verktyg och deras inmatningsscheman.
2. Modellen returnerar ett verktygsanrop med strukturerade argument.
3. Gatewayen validerar verktygets namn och argument.
4. Applikationen kontrollerar krav på behörighet, policy, idempotens och användarbekräftelse.
5. Först då kör programmet verktyget.
6. Verktygsresultatet skickas tillbaka till modellen om konversationen behöver fortsätta.

Behandla aldrig ett verktygsanrop som ett bevis på att åtgärden ska ske. Behandla det som ett strukturerat förslag. Ansökan förblir myndigheten för biverkningar.

Säker reservstege för arbetsflöden i flera modeller

En gateway bör definiera reservbeteende innan incidenter inträffar. En praktisk stege är:

1. Primär: strikt strukturerad utdata på den föredragna modellen.
2. Kompatibel reserv: en annan modell som stöder samma strikta schemakrav.
3. Validera-och-försök igen: en leverantör utan strikt support, som endast används när risken tillåter det.
4. Mänsklig granskning: ställ det strukturerade resultatet och källinnehållet i kö för godkännande.
5. Icke-åtgärdssvar: förklara att systemet inte kan slutföra operationen på ett säkert sätt.

Omförsök är användbara för formatering eller mindre schemafel, men de är inte en säkerhetsstrategi. Om objektet är semantiskt osäkert kan upprepad prompt förvandla ett korrekt avslag till ett farligt körbart objekt. För högriskåtgärder, föredra granskning eller avslag framför upprepade försök att tvinga fram framgång.

Observerbarhet: logga varje beslut om strukturerad produktion

Strukturerade utgångsfel är driftssignaler. Logga dem med tillräckligt med detaljer för att förbättra routing, scheman och meddelanden utan att avslöja onödigt känsligt innehåll.

Rekommenderade fält:

• schema_id och schema_version.
• Leverantör och modell.
• Begärt läge och faktisk läge som används.
• Parse felstatus.
• Schemafelstatus och valideringsfel.
• Orsak till misslyckande med semantisk validering.
• Försök att räkna igen.
• Latens.
• Tokenanvändning och kostnad.
• Slutlig åtgärdsstatus: utförd, köad, avvisad eller returnerad till användaren.
• Identifierare för team, projekt, API-nyckel eller partnerkonto där så är lämpligt.

Dessa loggar stöder felsökning, kostnadsanalys, leverantörsjämförelse och team-API-styrning. De hjälper också till att svara på frågor som: "Vilken schemaversion orsakar flest försök?" och "Vilken reservmodell klarar syntax men misslyckas med affärsvalidering?"

Schemaversioneringsregler

Schema är produktionsgränssnitt. Behandla dem som API-kontrakt.

• Inkludera schema_id och schema_version i begärande metadata och loggar.
• Ändra inte obligatoriska fält tyst för befintliga automatiseringar.
• Håll gamla scheman tillgängliga medan klienter migrerar.
• Lägg till nya valfria fält innan du gör dem obligatoriska.
• Testa scheman mot varje leverantör och reservmodell i routingpoolen.
• Anteckna vilken schemaversion som användes för varje biverkande åtgärd.

Versionering blir särskilt viktigt för byråer, återförsäljare och Partner API-automatisering, där många nedströmskunder kan vara beroende av ett stabilt strukturerat kontrakt.

När man inte ska köra ett strukturerat resultat

Använd ett hårt stopp när något av följande tillstånd uppstår:

• Svaret är inte tolkbart.
• Objektet misslyckas med JSON Schema-validering.
• Ett uppräkningsvärde stöds inte eller är påhittat.
• En kvantitet, ett pris, ett datum eller en valuta är omöjligt.
• Resultatet strider mot användarens uttalade avsikt.
• Modellen uttrycker lågt förtroende eller saknade bevis.
• Användarinstruktionen är tvetydig.
• Åtgärden har biverkningar och saknar bekräftelse.
• Kontot, teamet eller API-nyckeln är inte auktoriserad.
• Leverantörens svar inkluderar ett avslag eller säkerhetsrelaterat icke-svar.

Rekommendationer kontra förutsägelser

Rekommendationer: använd leverantörsbaserade strukturerade utdata där det är tillgängligt, validera varje svarsgateway-sida, föredra verktygsanrop för åtgärder, underhåll en kapacitetsmatris, versionsscheman och blockera bieffekter tills semantiska kontroller passerar.

Förutsägelser: leverantörsstödet för strukturerade utdata kommer sannolikt att bli starkare och mer konsekvent, men portabilitet kommer att förbli ett gatewayproblem eftersom modellfamiljer, schemaundergrupper och verktygsanropsloopar inte blir identiska över en natt. Team som bygger validering, observerbarhet och schemaversioner nu kommer att vara bättre positionerade för att anta nya leverantörsfunktioner utan att skriva om varje arbetsflöde.

Checklista för handlingsbar implementering

1. Definiera ett normaliserat format för begäran om strukturerad utdata för dina applikationer.
2. Skapa en leverantörskapacitetsmatris för varje modell i din routingpool.
3. Designa scheman med en bärbar JSON Schema-delmängd.
4. Översätt förfrågningar till strikta leverantörsbaserade mekanismer när det stöds.
5. Validera tolkbarhet, schemaöverensstämmelse och affärskorrekthet efter generering.
6. Använd verktygsanrop för sidoeffekter.
7. Kräv auktorisering, idempotens och bekräftelse utanför modellen.
8. Loggschemaversion, leverantör, valideringsfel, återförsök, latens, kostnad och åtgärdsstatus.
9. Definiera reservbeteende efter arbetsflödesrisknivå.
10. Håll gamla scheman tillgängliga tills beroende automatiseringar migrerar.

Det praktiska målet är inte att få alla modeller att bete sig identiskt. Det är att ge applikationsutvecklare ett stabilt kontrakt medan gatewayen hanterar leverantörsskillnader ärligt. Strukturerade utdata är nödvändig infrastruktur för tillförlitlig AI-automatisering, men produktionsgränsen är validatorn och policyskiktet som avgör om ett objekt är säkert att använda.

Relaterad läsning

• sem. regressioner
• API-nyckelauktorisering och teamkontroller
• spårning av tokenkostnad och fördröjning för återförsök