Strukturované výstupy ve vícemodelové bráně API: schéma JSON, volání nástrojů a sémantické zábradlí

Výzva modelu k „vrácení JSON“ není produkční smlouvou. Může vytvořit platný JSON s nesprávným výčtem, vynechat požadované obchodní pravidlo nebo s jistotou vyžadovat akci, kterou uživatel nikdy neautorizoval. V pracovním postupu s více poskytovateli je problém těžší: každý poskytovatel odhaluje různé mechanismy strukturovaného výstupu a použití nástrojů a každý podporuje pouze část vesmíru schématu JSON.

Praktické řešení není jedna magická výzva. Jedná se o vrstvený vzor brány: normalizujte požadované schéma vývojáře, převeďte jej do nativních formátů strukturovaného výstupu nebo volání nástrojů, kde je to možné, ověřte vrácený objekt a použijte sémantické ochranné zábradlí před jakýmkoli vedlejším efektem.

Tento průvodce odděluje tři různé cíle, které se často kombinují:

• Platnost syntaxe: odpověď je analyzovatelný JSON.
• Platnost schématu: JSON odpovídá povinným polím, typům, výčtům a strukturálním pravidlům.
• Obchodní správnost: objekt je bezpečný, věrný záměru uživatele a platný pro následnou akci.

Selhání produkce: platný JSON, nesprávná akce

Zvažte automatizaci podpory, která směruje příchozí vstupenky:

{
  "ticket_id": "t_481",
  "category": "fakturace",
  "priorita": "naléhavé",
  "action": "refund_customer",
  "částka_usd": 499
}

Tento objekt je syntakticky platný. Může dokonce projít jednoduchým schématem, pokud action je řetězec a amount_usd je číslo. Ale i tak to může být špatně. Možná zákazník požadoval pouze kopii faktury. Možná, že vrácení peněz nad 100 USD bude vyžadovat souhlas správce. Uživatel možná vůbec nemá oprávnění k vrácení peněz.

Strukturované výstupy snižují selhání analýzy. Nenahrazují autorizaci, kontroly zásad, inventarizace, cenové kontroly, idempotenci ani lidské potvrzení pro rizikové operace.

Fakta: co režimy strukturovaného výstupu poskytovatele dělají a co neslibují

Prostředí poskytovatelů se rychle mění, ale pro architekturu záleží na několika stabilních faktech:

• Režim JSON může pomoci vytvořit platný JSON, ale platný JSON není totéž jako soulad s konkrétním schématem.
• Režimy strukturovaného výstupu nativního poskytovatele jsou navrženy tak, aby zlepšily dodržování schématu, ale běžně podporují pouze podmnožinu schématu JSON.
• Volání nástroje je obvykle pro akce vhodnější než volný JSON, protože model vybere deklarovaný nástroj a vrátí strukturované argumenty, zatímco aplikace zůstává odpovědná za provádění.
• Různí poskytovatelé vystavují různé smlouvy. Jeden může používat přísný formát odpovědi schématu JSON, jiný může používat vstupní schémata nástroje a další může vyžadovat záložní ověření a opakování.
• I výstup s platným schématem může být sémanticky nesprávný, než se dostane do databáze, pracovního postupu nebo placené akce.

Architektonický důsledek je jednoduchý: API kompatibilní s OpenAI může standardizovat klientské rozhraní, ale vrstva spolehlivosti musí stále rozumět možnostem poskytovatele a po vygenerování ověřovat výstupy.

Doporučená architektura: adaptér se strukturovaným výstupem

Používejte adaptér na straně brány mezi kód aplikace a rozhraní API poskytovatele. Aplikace odešle jeden záměr schématu. Brána mapuje záměr na nejsilnější podporovaný mechanismus poskytovatele.

1. Přijměte jeden normalizovaný požadavek z aplikace

Klient by neměl potřebovat samostatné cesty kódu pro každého poskytovatele. Praktická obálka požadavku obsahuje preferenci modelu, zadání úlohy, schéma, metadata schématu a úroveň rizika:

{
  "model": "auto:přesný",
  "zprávy": [
    {"role": "system", "content": "Extrahujte pole faktury. Neodvozujte chybějící hodnoty."},
    {"role": "user", "content": "Text faktury..."}
  ],
  "strukturovaný_výstup": {
    "schema_id": "extrakce_faktury",
    "schema_version": "2026-08-01",
    "mode": "json_schema",
    "přísný": pravda,
    "schéma": {
      "type": "objekt",
      "additionalProperties": false,
      "povinné": ["číslo_faktury", "název_dodavatele", "celkem", "měna", "datum_splatnosti"],
      "vlastnosti": {
        "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"},
        "důvěra": {"type": "number", "minimum": 0, "maximum": 1}
      }
    }
  },
  "metadata": {
    "workflow": "accounts_payable",
    "riziková_úroveň": "střední"
  }
}

Tato smlouva poskytuje bráně dostatek informací, aby si mohla vybrat implementaci nativního poskytovatele, spustit ověření a zaznamenat smysluplná data o selhání.

2. Udržujte matici schopností poskytovatele

Brána by si měla zachovat strojově čitelnou matici schopností a nespoléhat se na předpoklady jako „všechny modely kompatibilní s OpenAI podporují stejné chování schématu.“ Užitečná matice zahrnuje:

• Název poskytovatele a modelu.
• Podporuje režim JSON.
• Podporuje formát odpovědi schématu JSON.
• Podporuje volání nástrojů.
• Podporuje přísný režim schématu.
• Známá omezení podmnožiny schématu JSON.
• Zda jsou volání paralelních nástrojů kompatibilní s režimem přísného schématu.
• Záložní chování, když požadovaný režim není podporován.

Příklad záznamu schopností:

{
  "provider": "poskytovatel_a",
  "model": "model_x",
  "json_mode": true,
  "json_schema_response": true,
  "tool_calls": true,
  "strict_schema": true,
  "schema_limitations": ["no oneOf", "ověření omezeného formátu"],
  "fallback": "reject_or_route_to_compatible_model"
}

Tato matice by měla být verzována a otestována. Když poskytovatel změní chování nebo je přidán nový model, měla by být před produkčním směrováním ověřena kompatibilita strukturovaného výstupu.

3. Přeložte na nejsilnější poskytovatel-nativní smlouvu

Adaptér by se měl řídit jasným pořadím preferencí:

1. Používejte striktně nativní strukturované výstupy poskytovatele, pokud je podporuje vybraný model a schéma.
2. Používejte nativní nástroj pro volání akcí a funkcí podobných úloh.
3. Použijte nepřísný strukturovaný výstup nebo režim JSON s ověřením a opakováním, když není přísný režim k dispozici.
4. Odmítněte požadavek, nasměrujte jej na kompatibilní záložní model nebo v případě vysoce rizikových pracovních postupů vraťte odpověď bez akce.

Nev tichosti nesnižujte vysoce rizikovou operaci z režimu přísného schématu na „nejlepší snahu JSON“. Pokud aplikace požadovala přísné chování a vybraný poskytovatel to nemůže podporovat, brána by to měla zviditelnit prostřednictvím chyby, rozhodnutí o směrování nebo explicitního příznaku downgradu.

Tři vrstvy ověření před provedením

Vrstva 1: ověření analýzy

Nejprve určete, zda lze odpověď analyzovat do očekávané obálky. Rychle selžou na chybném formátu JSON, chybějících blocích volání nástrojů, zkrácených odpovědích nebo smíšeném přirozeném jazyce a JSON, když to smlouva zakazuje.

function parseStructuredResponse(raw) {
  zkuste {
    return { ok: true, hodnota: JSON.parse(raw) };
  } catch (chyba) {
    return { ok: false, failure_type: "parse_failure", error: String(error) };
  }
}

Volání nástroje nativního poskytovatele nemusí vyžadovat analýzu nezpracovaného textového blobu, ale stále vyžadují ověření obálky: vybral model známý nástroj, poskytl argumenty a zastavil se kvůli spuštění nástroje podle očekávání?

Vrstva 2: Ověření schématu JSON

Dále ověřte objekt proti deklarovanému schématu pomocí validátoru na straně serveru. Udělejte to, i když poskytovatel požaduje přísnou podporu schématu. Ověření na straně brány vám poskytuje konzistentní protokolování selhání, chrání před chybami při integraci a zachycuje nekompatibility ve směru proudu.

const validate = schemaValidator.compile(schema);
const valid = validate(object);
if (!valid) {
  vrátit {
    ok: nepravda,
    fail_type: "schema_failure",
    chyby: validate.errors
  };
}

Pro přenositelnost navrhujte schémata s ohledem na společnou podmnožinu:

• Preferujte explicitní typ, povinné, vlastnosti, enum a další vlastnosti: false.
• Vyhněte se složitým kombinacím, jako jsou hluboce vnořené jeden z, jakýkoli z a podmíněná schémata, pokud nevíte, že je cílový poskytovatel podporuje.
• Akční argumenty udržujte malé a konkrétní.
• Používejte řetězce pro ID, data a kódy, pokud navazující systémy nevyžadují jiný typ.
• Představte nejistotu explicitně pomocí polí jako důvěra, missing_fields nebo requires_human_review.

Vrstva 3: sémantické a obchodní ověření

Nakonec ověřte, zda je strukturovaný výsledek pro daný úkol správný. Tato vrstva je specifická pro doménu a nelze ji externě zadat pouze schématu JSON.

Při extrakci faktur mohou sémantické kontroly zahrnovat:

• Celkový počet není záporný a odpovídá řádkovým položkám v rámci tolerance.
• Měna se zobrazí ve zdrojovém dokumentu.
• Datum dokončení není příliš daleko v minulosti nebo budoucnosti.
• Dodavatel existuje v seznamu schválených dodavatelů.
• Důvěryhodnost je dostatečně vysoká pro automatické zadání.

V případě kvalifikace potenciálního zákazníka mohou kontroly zahrnovat:

• Vybraný segment je jedním z aktivních segmentů prodejního týmu.
• Požadovaný rozpočet není vynalezen, když jej uživatel neposkytne.
• Akce „ukázka knihy“ se neprovede, pokud o to uživatel výslovně nepožádá.

U automatizace Partner API mohou kontroly zahrnovat:

• Účet distributora je oprávněn vytvořit požadovaného zákazníka nebo klíč.
• Požadovaný limit útraty je v rámci zásad pro partnery.
• Operace má klíč idempotence.
• Akce se před provedením zaznamená do protokolu auditu.

Volání nástrojů: považujte výstup modelu za požadavek, nikoli za provedení

Volání nástroje je tím správným vzorem, když model potřebuje požádat aplikaci, aby něco provedla: vytvořila tiket, odeslala příkaz robota Telegram, vyhledávala ceny, aktualizovala záznam zákazníka nebo zahájila pracovní postup.

Bezpečná smyčka nástroje vypadá takto:

1. Aplikace deklaruje dostupné nástroje a jejich vstupní schémata.
2. Model vrací volání nástroje se strukturovanými argumenty.
3. Brána ověří název nástroje a argumenty.
4. Aplikace kontroluje autorizaci, zásady, idempotenci a požadavky na potvrzení uživatele.
5. Aplikace nástroj spustí až poté.
6. Pokud konverzace potřebuje pokračovat, bude výsledek nástroje odeslán zpět modelu.

Nikdy nepovažujte volání nástroje za důkaz, že k akci má dojít. Berte to jako strukturovaný návrh. Aplikace zůstává autoritou pro vedlejší účinky.

Bezpečný záložní žebříček pro vícemodelové pracovní postupy

Brána by měla definovat nouzové chování dříve, než dojde k incidentům. Praktický žebřík je:

1. Primární: striktně strukturovaný výstup na preferovaném modelu.
2. Kompatibilní záložní: další model, který podporuje stejné přísné požadavky na schéma.
3. Validation-and-retry: Poskytovatel bez přísné podpory, který se používá pouze tehdy, když to riziko dovolí.
4. Kontrola člověkem: zařaďte strukturovaný výsledek a zdrojový obsah ke schválení.
5. Reakce bez akce: Vysvětlete, že systém nemůže bezpečně dokončit operaci.

Opakování je užitečné při formátování nebo menších selháních schématu, ale nejde o bezpečnostní strategii. Pokud je objekt sémanticky nebezpečný, opakované výzvy mohou proměnit správné odmítnutí v nebezpečný spustitelný objekt. U vysoce rizikových akcí upřednostňujte kontrolu nebo odmítnutí před opakovanými pokusy vynutit si úspěch.

Pozorovatelnost: zaznamenejte každé rozhodnutí o strukturovaném výstupu

Chyby strukturovaného výstupu jsou provozní signály. Zaprotokolujte je dostatečně podrobně, abyste zlepšili směrování, schémata a výzvy, aniž by došlo k odhalení zbytečného citlivého obsahu.

Doporučená pole:

• schema_id a schema_version.
• Poskytovatel a model.
• Požadovaný režim a skutečně použitý režim.
• Stav selhání analýzy.
• Stav selhání schématu a chyby ověření.
• Důvod selhání sémantického ověření.
• Počet opakování.
• Latence.
• Využití tokenu a cena.
• Stav konečné akce: provedena, zařazena do fronty, zamítnuta nebo vrácena uživateli.
• Tým, projekt, klíč API nebo případně identifikátor partnerského účtu.

Tyto protokoly podporují ladění, analýzu nákladů, porovnání poskytovatelů a správu týmového rozhraní API. Pomáhají také odpovědět na otázky jako: „Která verze schématu způsobuje nejvíce opakování?“ a „Který záložní model projde syntaxí, ale selže při obchodním ověření?“

Pravidla verzování schématu

Schémata jsou produkční rozhraní. Zacházejte s nimi jako s API kontrakty.

• Zahrňte schema_id a schema_version do metadat a protokolů požadavku.
• Neměňte potichu povinná pole pro stávající automatizaci.
• Zachovejte dostupná stará schémata, zatímco klienti migrují.
• Nová volitelná pole přidejte dříve, než je nastavíte jako povinná.
• Otestujte schémata proti každému poskytovateli a záložnímu modelu ve fondu směrování.
• Zaznamenejte, která verze schématu byla použita pro každou akci s vedlejšími účinky.

Změna verzí se stává obzvláště důležitou pro agentury, prodejce a automatizaci rozhraní API pro partnery, kde mnoho následných zákazníků může záviset na stabilní strukturované smlouvě.

Kdy nespustit strukturovaný výsledek

Pokud nastane některá z následujících podmínek, použijte pevné zastavení:

• Odpověď nelze analyzovat.
• U objektu se nezdařilo ověření schématu JSON.
• Hodnota výčtu není podporována nebo je vymyšlena.
• Množství, cena, datum nebo měna nejsou možné.
• Výsledek je v rozporu se záměrem uživatele.
• Model vyjadřuje nízkou spolehlivost nebo chybějící důkazy.
• Pokyny pro uživatele jsou nejednoznačné.
• Akce má vedlejší účinky a chybí potvrzení.
• Účet, tým nebo klíč API nejsou autorizovány.
• Odpověď poskytovatele zahrnuje odmítnutí nebo neodpověď související s bezpečností.

Doporučení vs. předpovědi

Doporučení: používejte strukturované výstupy nativní poskytovatele, pokud jsou k dispozici, ověřujte každou stranu brány odpovědí, upřednostňujte volání nástrojů k akcím, udržujte matici schopností, schémata verzí a blokujte vedlejší efekty, dokud neprojdou sémantické kontroly.

Předpovědi: Podpora poskytovatelů pro strukturované výstupy bude pravděpodobně silnější a konzistentnější, ale přenositelnost zůstane problémem brány, protože rodiny modelů, podmnožiny schémat a smyčky volání nástrojů se nestanou přes noc identické. Týmy, které nyní vytvářejí ověřování, pozorovatelnost a verzování schémat, budou mít lepší pozici pro přijetí nových funkcí poskytovatele, aniž by museli přepisovat každý pracovní postup.

Akční kontrolní seznam implementace

1. Definujte normalizovaný formát požadavku strukturovaného výstupu pro své aplikace.
2. Vytvořte matici schopností poskytovatele pro každý model ve vašem fondu směrování.
3. Navrhujte schémata pomocí přenosné podmnožiny schémat JSON.
4. Pokud jsou podporovány, překládejte požadavky do přísných nativních mechanismů poskytovatele.
5. Po vygenerování ověřte analyzovatelnost, shodu schématu a obchodní správnost.
6. Používejte volání nástrojů pro operace s vedlejšími efekty.
7. Vyžadovat autorizaci, idempotenci a potvrzení mimo model.
8. Zaznamenat verzi schématu, poskytovatele, selhání ověření, opakování, latenci, cenu a stav akce.
9. Definujte záložní chování podle úrovně rizika pracovního postupu.
10. Ponechat stará schémata dostupná do migrace závislých automatizací.

Praktickým cílem není, aby se každý model choval identicky. Je to dát vývojářům aplikací jednu stabilní smlouvu, zatímco brána poctivě řeší rozdíly mezi poskytovateli. Strukturované výstupy jsou nezbytnou infrastrukturou pro spolehlivou automatizaci AI, ale produkční hranicí je validátor a vrstva zásad, která rozhoduje, zda je použití objektu bezpečné.

Související informace

• regrese
• Autorizace klíče API a týmové kontroly
• sledovací cena tokenu a latence pro opakování