Strukturált kimenetek többmodell API-átjáróban: JSON-séma, eszközhívások és szemantikus védőkorlátok

A modell „JSON visszaküldésére” felszólítása nem gyártási szerződés. Előfordulhat, hogy érvényes JSON-fájlt állít elő rossz névsorral, kihagy egy kötelező üzleti szabályt, vagy magabiztosan kér olyan műveletet, amelyet a felhasználó soha nem engedélyezett. Egy több szolgáltatóra kiterjedő munkafolyamat esetén a probléma még nehezebbé válik: minden szolgáltató különböző strukturált kimeneti és eszközhasználati mechanizmusokat tesz közzé, és mindegyik a JSON-séma-univerzumnak csak egy részét támogatja.

A gyakorlati megoldás nem egyetlen varázslat. Ez egy réteges átjáróminta: normalizálja a fejlesztő kívánt sémáját, fordítsa le szolgáltatói natív strukturált kimenetre vagy eszközhívási formátumokra, ahol lehetséges, érvényesítse a visszaadott objektumot, és alkalmazzon szemantikus védőkorlátokat minden mellékhatás előtt.

Ez az útmutató három különböző célt különböztet meg, amelyek gyakran keverednek egymással:

• Szintaxis érvényessége: a válasz elemezhető JSON.
• Séma érvényessége: a JSON megfelel a kötelező mezőknek, típusoknak, felsorolásoknak és szerkezeti szabályoknak.
• Üzleti helyesség: az objektum biztonságos, hű a felhasználói szándékhoz, és érvényes a későbbi műveletekre.

A termelési hiba: érvényes JSON, helytelen művelet

Fontoljon egy támogatási automatizálást, amely irányítja a bejövő jegyeket:

{
  "ticket_id": "t_481",
  "kategória": "számlázás",
  "priority": "sürgős",
  "action": "refund_customer",
  "összeg_usd": 499
}

Ez az objektum szintaktikailag érvényes. Még egy egyszerű sémát is átadhat, ha az action egy karakterlánc, az amount_usd pedig egy szám. De attól még lehet baj. Lehet, hogy az ügyfél csak egy számla másolatot kért. Lehet, hogy a 100 dollár feletti visszatérítéshez vezetői jóváhagyás szükséges. Lehetséges, hogy a felhasználó egyáltalán nem jogosult visszatérítést indítani.

A strukturált kimenetek csökkentik az elemzési hibákat. Nem helyettesítik az engedélyezést, az irányelv-ellenőrzést, a készletellenőrzést, az árellenőrzést, az idempotenciát vagy a kockázatos műveletek emberi megerősítését.

Tények: mit ígérnek és mit nem ígérnek a szolgáltatói strukturált kimeneti módok

A szolgáltató környezet gyorsan változik, de számos stabil tény számít az építészet szempontjából:

• A JSON mód segíthet érvényes JSON létrehozásában, de az érvényes JSON nem ugyanaz, mint egy adott sémának való megfelelés.
• A szolgáltatói natív strukturált kimeneti módok célja a sémakövetés javítása, de általában csak a JSON-séma egy részhalmazát támogatják.
• Az eszközhívás általában jobban illeszkedik a műveletekhez, mint a szabad formájú JSON, mivel a modell kiválaszt egy deklarált eszközt, és strukturált argumentumokat ad vissza, miközben az alkalmazás továbbra is felelős a végrehajtásért.
• A különböző szolgáltatók különböző szerződéseket kötnek. Az egyik szigorú JSON-séma válaszformátumot, egy másik eszközbeviteli sémákat használhat, a másik pedig érvényesítési és újrapróbálkozási tartalékot igényel.
• Még a sémaérvényes kimenet is lehet szemantikailag hibás, mielőtt elérné az adatbázist, a munkafolyamatot vagy a fizetett műveletet.

Az architektúra egyszerű: egy OpenAI-kompatibilis API szabványosíthatja az ügyfélfelületet, de a megbízhatósági rétegnek továbbra is értenie kell a szolgáltatói képességeket, és a generálás után ellenőriznie kell a kimeneteket.

Javasolt architektúra: a strukturált kimeneti adapter

Használjon átjáróoldali adaptert az alkalmazáskód és a szolgáltatói API-k között. Az alkalmazás egy séma szándékot küld. Az átjáró leképezi a legerősebb támogatott szolgáltatói mechanizmust.

1. Fogadjon el egy normalizált kérést az alkalmazástól

Az ügyfélnek nem kell külön kódútvonalakra minden szolgáltatóhoz. A praktikus kérésboríték tartalmazza a modellpreferenciát, a feladatbevitelt, a sémát, a séma metaadatait és a kockázati szintet:

{
  "modell": "auto:pontos",
  "üzenetek": [
    {"role": "system", "content": "Számlamezők kibontása. Ne következtessen hiányzó értékekre."},
    {"role": "user", "content": "Számla szövege..."}
  ],
  "strukturált_kimenet": {
    "schema_id": "számla_kivonat",
    "schema_version": "2026-08-01",
    "mode": "json_schema",
    "szigorú": igaz,
    "séma": {
      "type": "objektum",
      "additionalProperties": hamis,
      "required": ["számla száma", "szállító_neve", "összesen", "pénznem", "esedékességi_dátum"],
      "tulajdonságok": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "összesen": {"típus": "szám", "minimum": 0},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "string", "format": "date"},
        "bizalom": {"típus": "szám", "minimum": 0, "maximum": 1}
      }
    }
  },
  "metaadatok": {
    "workflow": "accounts_payable",
    "risk_level": "közepes"
  }
}

Ez a szerződés elegendő információt biztosít az átjáró számára a szolgáltató natív megvalósításának kiválasztásához, az érvényesítés futtatásához és a jelentős hibaadatok naplózásához.

2. Karbantartson egy szolgáltatói képességmátrixot

Az átjárónak gépileg olvasható képességmátrixot kell tartania, nem szabad olyan feltevésekre hagyatkoznia, mint például: „Minden OpenAI-kompatibilis modell ugyanazt a sémaviselkedést támogatja”. Egy hasznos mátrix a következőket tartalmazza:

• Szállító és modell neve.
• Támogatja a JSON módot.
• Támogatja a JSON-séma válaszformátumát.
• Támogatja az eszközhívásokat.
• Támogatja a szigorú séma módot.
• A JSON-séma részhalmazának ismert korlátai.
• A párhuzamos eszközhívások kompatibilisek-e a szigorú sémamóddal.
• Tartalék viselkedés, ha a kért mód nem támogatott.

Példa képességrekordra:

{
  "szolgáltató": "szolgáltató_a",
  "modell": "model_x",
  "json_mode": igaz,
  "json_schema_response": igaz,
  "tool_calls": igaz,
  "strict_schema": igaz,
  "schema_limitations": ["no oneOf", "limited format validation"],
  "tartalék": "elutasítás_vagy_útvonal_kompatibilis_modellhez"
}

Ezt a mátrixot verziózni és tesztelni kell. Ha egy szolgáltató viselkedése megváltozik, vagy új modellt adnak hozzá, a strukturált kimenetek kompatibilitását ellenőrizni kell az éles útválasztás előtt.

3. Fordítsa le a legerősebb szolgáltató-natív szerződés

Az adapternek egyértelmű preferenciasorrendet kell követnie:

1. Használjon szigorú szolgáltatói natív strukturált kimeneteket, ha azt a kiválasztott modell és séma támogatja.
2. Használjon natív szolgáltatói eszközhívást műveletekhez és funkciószerű feladatokhoz.
3. Használjon nem szigorú strukturált kimenetet vagy JSON módot az érvényesítéssel, és próbálkozzon újra, ha a szigorú mód nem érhető el.
4. A kérés elutasítása, kompatibilis tartalékmodellhez való irányítás, vagy művelet nélküli válasz visszaküldése magas kockázatú munkafolyamatok esetén.

Ne állítsa vissza csendesen a magas kockázatú műveleteket szigorú sémamódról „legjobb erőfeszítést igénylő JSON-ra”. Ha az alkalmazás szigorú viselkedést kért, és a kiválasztott szolgáltató nem tudja támogatni, akkor az átjárónak ezt láthatóvá kell tennie egy hiba, az útválasztási döntés vagy az explicit downgrade jelző segítségével.

Három érvényesítési réteg a végrehajtás előtt

1. réteg: elemzési ellenőrzés

Először is határozza meg, hogy a válasz értelmezhető-e a várt borítékba. Gyorsan meghiúsul a rosszul formázott JSON, hiányzó eszközhívási blokkok, csonkolt válaszok vagy vegyes természetes nyelv és JSON, ha a szerződés ezt tiltja.

function parseStructuredResponse(raw) {
  próbáld meg {
    return { ok: igaz, érték: JSON.parse(raw)};
  } fogás (hiba) {
    return { ok: false, error_type: "elemzési_hiba", hiba: String(hiba)};
  }
}

Előfordulhat, hogy a szolgáltató natív eszközhívásai nem igényelnek nyers szöveges blob elemzését, de még mindig szükség van a borítékellenőrzésre: kiválasztott-e a modell egy ismert eszközt, adott-e argumentumokat, és a várt módon leállt-e az eszköz végrehajtása?

2. réteg: JSON-séma ellenőrzése

Ezután ellenőrizze az objektumot a deklarált sémával szemben egy kiszolgálóoldali érvényesítő segítségével. Tegye ezt akkor is, ha a szolgáltató szigorú séma támogatást igényel. Az átjáróoldali érvényesítés konzisztens hibanaplózást biztosít, védelmet nyújt az integrációs hibák ellen, és elkapja a későbbi inkompatibilitásokat.

const validate = schemaValidator.compile(schema);
const valid = validate(object);
if (!valid) {
  return {
    rendben: hamis,
    error_type: "schema_failure",
    hibák: validate.errors
  };
}

A hordozhatóság érdekében tervezzen sémákat a közös részhalmazt szem előtt tartva:

• Előnyben részesítse az explicit type, szükséges, properties, enum és additionalProperties: false értékeket.
• Kerülje az összetett kombinációkat, például a mélyen beágyazott oneOf, anyOf és feltételes sémákat, hacsak nem tudja, hogy a célszolgáltató támogatja ezeket.
• A cselekvési érvek legyenek kicsik és konkrétak.
• Használjon karakterláncokat azonosítókhoz, dátumokhoz és kódokhoz, hacsak a későbbi rendszerek nem igényelnek más típust.
• A bizonytalanságot kifejezetten ábrázolja olyan mezőkkel, mint a bizalom, missing_fields vagy requires_human_review.

3. réteg: szemantikai és üzleti ellenőrzés

Végül ellenőrizze, hogy a strukturált eredmény megfelelő-e a feladathoz. Ez a réteg tartományfüggő, és nem lehet kiszervezni egyedül a JSON-sémára.

A számla kivonatánál a szemantikai ellenőrzések a következőket tartalmazhatják:

• A végösszeg nem negatív, és a tűréshatáron belül egyezik a sorokkal.
• A pénznem a forrásdokumentumban jelenik meg.
• A esedékesség dátuma nincs lehetetlenül a múltban vagy a jövőben.
• A szállító szerepel a jóváhagyott szállítók listáján.
• A bizalom elég magas az automatikus belépéshez.

A vezető minősítése esetén az ellenőrzések a következőket tartalmazhatják:

• A kiválasztott szegmens az értékesítési csapat egyik aktív szegmense.
• A kért költségkeretet nem találták ki, ha a felhasználó nem adott meg.
• A „könyvbemutató” művelet csak akkor hajtható végre, ha a felhasználó kifejezetten kéri.

A Partner API automatizálása esetén az ellenőrzések a következőket tartalmazhatják:

• A viszonteladói fiók jogosult a kért ügyfél vagy kulcs létrehozására.
• A kért költési korlát a partnerekre vonatkozó irányelvek hatálya alá tartozik.
• A művelethez tartozik egy idempotenciakulcs.
• A művelet végrehajtása előtt rögzítésre kerül egy auditnaplóban.

Eszközhívások: a modellkimenetet kérésként kezelik, nem végrehajtásként

Az eszközhívás a megfelelő minta, amikor a modellnek meg kell kérnie az alkalmazást, hogy tegyen valamit: hozzon létre egy jegyet, küldjön egy Telegram bot parancsot, keresse meg az árakat, frissítse az ügyfélrekordot vagy indítson el egy munkafolyamatot.

Egy biztonságos eszközhurok így néz ki:

1. Az alkalmazás deklarálja az elérhető eszközöket és azok beviteli sémáit.
2. A modell egy eszközhívást ad vissza strukturált argumentumokkal.
3. Az átjáró ellenőrzi az eszköz nevét és az argumentumokat.
4. Az alkalmazás ellenőrzi a jogosultsági, házirendi, idempotencia és felhasználói megerősítési követelményeket.
5. Az alkalmazás csak ezután hajtja végre az eszközt.
6. Az eszköz eredményét a rendszer visszaküldi a modellnek, ha a beszélgetést folytatni kell.

Soha ne kezelje az eszközhívást annak bizonyítékaként, hogy a műveletnek meg kell történnie. Kezelje strukturált javaslatként. A mellékhatások tekintetében továbbra is az alkalmazás jogosult.

Biztonságos tartalék létra több modelles munkafolyamatokhoz

Az átjárónak meg kell határoznia a tartalék viselkedést az incidensek bekövetkezése előtt. Egy praktikus létra:

1. Elsődleges: szigorúan strukturált kimenet a preferált modellen.
2. Kompatibilis tartalék: egy másik modell, amely ugyanazokat a szigorú sémakövetelményeket támogatja.
3. Érvényesítés és újrapróbálkozás: szigorú támogatás nélküli szolgáltató, csak akkor használható, ha a kockázat lehetővé teszi.
4. Emberi ellenőrzés: állítsa sorba a strukturált eredményt és a forrástartalmat jóváhagyásra.
5. Művelet nélküli válasz: magyarázza el, hogy a rendszer nem tudja biztonságosan befejezni a műveletet.

Az újrapróbálkozások formázási vagy kisebb sémahiba esetén hasznosak, de nem jelentenek biztonsági stratégiát. Ha az objektum szemantikailag nem biztonságos, az ismételt felszólítás a helyes elutasítást veszélyes végrehajtható objektummá változtathatja. Magas kockázatú cselekvések esetén előnyben részesítse a felülvizsgálatot vagy az elutasítást, mint a siker kikényszerítésének ismételt kísérleteit.

Megfigyelhetőség: minden strukturált kimeneti döntés naplózása

A strukturált kimeneti hibák működési jelek. Elég részletesen naplózza őket, hogy javítsa az útválasztást, a sémákat és az utasításokat anélkül, hogy szükségtelen érzékeny tartalmat fedne fel.

Javasolt mezők:

• schema_id és schema_version.
• Szállító és modell.
• A kért mód és a ténylegesen használt mód.
• Az elemzés sikertelen állapota.
• Sémahiba állapota és érvényesítési hibák.
• A szemantikai ellenőrzés sikertelenségének oka.
• Ismétszámlálás.
• Késés.
• Token használata és költsége.
• Végső művelet állapota: végrehajtva, sorba állva, elutasítva vagy visszaadva a felhasználónak.
• Csapat-, projekt-, API-kulcs vagy partnerfiók-azonosító, ha szükséges.

Ezek a naplók támogatják a hibakeresést, a költségelemzést, a szolgáltatók összehasonlítását és a csapat API-kezelését. Segítenek megválaszolni olyan kérdéseket is, mint például: „Melyik sémaverzió okozza a legtöbb újrapróbálkozást?” és „Melyik tartalék modell adja át a szintaxist, de nem sikerül az üzleti ellenőrzést?”

Sémaverziós szabályok

A sémák termelési interfészek. Kezelje őket API-szerződésként.

• A schema_id és a schema_version szerepeljen a kérés metaadataiban és naplóiban.
• Ne módosítsa csendben a kötelező mezőket a meglévő automatizálásokhoz.
• Tartsa elérhetővé a régi sémákat, amíg az ügyfelek migrálnak.
• Adjon hozzá új opcionális mezőket, mielőtt kötelezővé tenné őket.
• Tesztelje le a sémákat az útválasztási készlet minden szolgáltatójával és tartalék modelljével.
• Jegyezze fel, hogy melyik sémaverziót használta minden mellékhatást okozó művelethez.

A verziószámítás különösen fontossá válik az ügynökségek, a viszonteladók és a Partner API automatizálása számára, ahol sok későbbi ügyfél számíthat egy stabil strukturált szerződésre.

Mikor ne hajtson végre strukturált eredményt

Használjon kemény leállítást, ha a következő feltételek bármelyike megjelenik:

• A válasz nem elemezhető.
• Az objektum a JSON-séma ellenőrzése sikertelen.
• Az enum-érték nem támogatott vagy kitalált.
• A mennyiség, az ár, a dátum vagy a pénznem megadása lehetetlen.
• Az eredmény ütközik a felhasználó kinyilvánított szándékával.
• A modell alacsony megbízhatóságot vagy hiányzó bizonyítékokat jelez.
• A felhasználói utasítás nem egyértelmű.
• A műveletnek mellékhatásai vannak, és hiányzik a megerősítés.
• A fiók-, csapat- vagy API-kulcs nincs engedélyezve.
• A szolgáltató válasza elutasítást vagy biztonsági vonatkozású nem választ tartalmaz.

Javaslatok kontra előrejelzések

Javaslatok: használjon szolgáltatói natív strukturált kimeneteket, ahol elérhető, érvényesítsen minden válaszátjáró oldalt, részesítse előnyben az eszközhívásokat a műveletekre, tartson fenn képességmátrixot, verziósémákat, és blokkolja a mellékhatásokat, amíg a szemantikai ellenőrzések át nem mennek.

Előrejelzések: A strukturált kimenetek szolgáltatói támogatása valószínűleg erősebb és konzisztensebb lesz, de a hordozhatóság továbbra is átjáró probléma marad, mivel a modellcsaládok, a séma részhalmazok és az eszközhívási hurkok nem válnak azonossá egyik napról a másikra. Azok a csapatok, amelyek most az érvényesítést, a megfigyelhetőséget és a sémaverziókészítést építik ki, jobb helyzetben lesznek ahhoz, hogy új szolgáltatói funkciókat alkalmazzanak anélkül, hogy minden munkafolyamatot át kellene írniuk.

Munkálható megvalósítási ellenőrzőlista

1. Határozzon meg normalizált strukturált kimeneti kérésformátumot alkalmazásaihoz.
2. Hozzon létre egy szolgáltatói képességmátrixot az útválasztási készlet minden modelljéhez.
3. Sémák tervezése hordozható JSON-séma részhalmaz segítségével.
4. A kérések lefordítása szigorú szolgáltatói natív mechanizmusokká, ha támogatott.
5. Generáció után ellenőrizze az elemezhetőséget, a sémamegfelelőséget és az üzleti helyességet.
6. Használjon eszközhívásokat a mellékhatásokat okozó műveletekhez.
7. A modellen kívüli engedély, idempotencia és megerősítés szükséges.
8. A séma verziója, a szolgáltató, az érvényesítési hibák, az újrapróbálkozások, a várakozási idő, a költségek és a műveleti állapot naplózása.
9. Határozza meg a tartalék viselkedést a munkafolyamat kockázati szintje szerint.
10. Tartsa elérhetővé a régi sémákat a függő automatizálások migrációjáig.

A gyakorlati cél nem az, hogy minden modell azonos módon viselkedjen. Ez egy stabil szerződést biztosít az alkalmazásfejlesztőknek, miközben az átjáró őszintén kezeli a szolgáltatók közötti különbségeket. A strukturált kimenetek a megbízható mesterséges intelligencia-automatizáláshoz szükséges infrastruktúrát jelentik, de a termelés határa az érvényesítő és a házirend réteg, amely eldönti, hogy egy objektum biztonságosan használható-e.

Kapcsolódó olvasmány

• API-kulcs engedélyezése és csapatvezérlők
• követő token költsége és késleltetése az újrapróbálkozásoknál