JSON mód helyett séma: így nem csúszik szét az MI válasza

Ha az alkalmazásnak elég egy beolvasható JSON-válasz, a JSON mode megfelelő lehet. Ha a következő programlépés meghatározott mezőket, típusokat vagy felsorolt értékeket vár, válassz szigorú sémát követő Structured Outputs-kimenetet: az OpenAI API-útmutatója szerint a JSON mode a JSON érvényességét biztosítja, a megadott sémához való igazodást önmagában nem.

A szigorú séma a megfelelően befejezett válasz szerkezetét rögzíti. A visszautasítást és a megszakadt generálást külön eredményként kell kezelni, a mezőkben szereplő értékeket pedig az alkalmazásnak kell ellenőriznie, ha későbbi művelet épül rájuk. Így három kérdés válik szét: beolvasható-e a kimenet, megfelel-e a várt szerkezetnek, és használható-e a tartalma.

Mikor elég az érvényes JSON?

A JSON mode akkor lehet ésszerű választás, ha a fogadó kód többféle szerkezetet is elfogad, és a modell válaszát először csak JSON-ként kell beolvasni. Egy belső kísérletben például az alkalmazás dönthet arról, mely kulcsokat használja fel, és hogyan kezeli a hiányzó adatot. A modellnek ilyenkor is kifejezetten JSON-kimenetet kell kérni az utasításban; a formátum beállítása önmagában nem helyettesíti ezt.

Más a helyzet, ha egy mező hiánya vagy eltérő típusa megakasztaná a következő lépést. Egy feltételes példában a „rendeles_azonosito” kulcsra épülő feldolgozó nem tud mit kezdeni az „azonosito” kulccsal, noha mindkettő szerepelhet szabályos JSON-ban. Ha a választott modell vagy API-végpont nem támogatja a szigorú sémakimenetet, a JSON mode mellé alkalmazásoldali sémavizsgálat kell; sikertelen vizsgálat után a kódnak el kell utasítania az adatot, vagy szabályozott újrapróbálást kell indítania.

Mitől lesz használható a séma?

A sémát a tényleges feldolgozási szerződésből érdemes felépíteni: mely mezőket olvassa a program, milyen típusú értéket vár, és hol létezik valóban zárt értékkészlet. Az enum például alkalmas egy előre rögzített állapot kifejezésére, de egy bizonytalan besorolást nem tesz helyessé pusztán attól, hogy az eredmény a felsorolt címkék egyikébe kerül. A mező neve és jelentése legyen egyértelmű a modell és a fogadó kód számára is.

Az OpenAI szigorú sémakimenetében az objektum minden mezőjét kötelezőként kell megadni, és az előre nem definiált további kulcsokat az additionalProperties: false beállítással kell kizárni. A hiányozható adatot olyan típussal lehet leírni, amely a null értéket is megengedi: a kulcs ekkor jelen van, az értéke pedig jelzi a hiányt. Ez különbözik attól, hogy a modell tetszés szerint elhagyhatja a mezőt.

A támogatott JSON Schema-kifejezések köre szolgáltatónként és modellnél eltérhet. Ezért a sémát a használni kívánt végpont szabályaihoz kell igazítani, nem elegendő egy általános JSON Schema-ellenőrzőben érvényesnek talált definíció. A túl részletes séma is lehet rossz szerződés, ha olyan mezőket követel meg, amelyekhez a bemenet nem tartalmaz adatot; ezeknél a hiány jelentését előre meg kell határozni.

Eszközhívást vagy végső választ formázol?

Az eszköznek átadott argumentumok és a felhasználónak szánt válasz eltérő helyen kapnak sémát. A Microsoft Azure OpenAI-leírása az eszközhívásnál a strict: true beállítást, a strukturált válasznál pedig a Chat Completions response_format, illetve a Responses text.format mezőjét mutatja be. A fogadó függvény argumentumait tehát az eszköz definíciójában rögzítsd; a megjelenítésre vagy további feldolgozásra szánt válasz alakját a válaszformátumban.

Ez a különbség a feldolgozás során is számít. Egy eszközhívásnál az alkalmazás a kapott argumentumok alapján műveletet indíthat, ezért a jogosultságot és a művelet előfeltételeit saját kódjában kell ellenőriznie. A felhasználónak szánt strukturált válasznál a séma a megjelenítéshez szükséges mezőket adhatja meg. Azonos adatmező mindkét helyen előfordulhat, de a modellnek adott szerkezeti utasítás nem helyettesíti a fogadó művelet szabályait.

Mi történjen visszautasításkor vagy megszakadáskor?

A kimenet beolvasása előtt vizsgáld meg az API-válasz állapotát. Ha a generálás a kimeneti tokenkorlát vagy tartalomszűrés miatt félbeszakadt, a részleges szöveg nem tekinthető teljes üzleti rekordnak. A befejezési ok vagy az incomplete állapot alapján különítsd el ezt az esetet; tokenkorlátnál nagyobb keret vagy kisebb feladat lehet indokolt. A hiányzó JSON-rész utólagos odaképzelése már új adat előállítása volna.

A visszautasítás másik ág: a modell ilyenkor nem feltétlenül a megadott sémában válaszol. Az API visszautasítást jelző mezőjét vagy tartalomtípusát kezeld önálló eredményként, és csak az elfogadott, teljes választ add át a JSON-feldolgozónak. Így egy biztonsági okból visszautasított kérés nem keveredik össze a hibás szerkezetű adattal, és a felhasználói felület is a megfelelő állapotot tudja megjeleníteni.

Érdemes a hibautakat a sikeres ágtól külön modellezni a kódban. A hálózati vagy API-hiba, a megszakadás és a visszautasítás eltérő döntést igényelhet; csak ezután következik a teljes kimenet beolvasása. JSON mode esetén itt kell lefuttatni az alkalmazás sémavizsgálatát is. Szigorú séma mellett is célszerű ellenőrizni, hogy valóban azt a sikeresen lezárt választ dolgozod fel, amelyre a szerkezeti garancia vonatkozik.

A helyes szerkezet után mi marad az alkalmazásra?

A séma egy mező alakját vagy megengedett értékeit szabályozza, nem igazolja a mezőben szereplő állítást. Az OpenAI Structured Outputs-bejelentése külön jelzi, hogy a modell a JSON-értékeken belül továbbra is hibázhat. Egy dátum lehet megfelelő típusú, mégis téves; egy felsorolásból választott állapot lehet formailag megengedett, de az adott ügyre helytelen.

Az üzleti ellenőrzés ezért az adott művelethez tartozik. Az alkalmazás az azonosítót összevetheti a saját nyilvántartásával, az összeget a tranzakció adataival, a dátumot pedig a munkafolyamat időrendjével. Ha nincs megbízható összehasonlítási alap, a mezőt ellenőrizetlenként lehet kezelni, vagy emberi jóváhagyást lehet kérni a következményes döntés előtt. Ez a vizsgálat mindkét kimeneti mód mellett szükséges, amikor a tartalom helyessége számít.

A döntési sorrend röviden: beolvasható JSON-hoz választható a JSON mode; rögzített mezőkhöz és típusokhoz szigorú séma kell, ha a környezet támogatja. A beérkező választ előbb az API-állapot és a visszautasítás alapján válaszd szét, utána olvasd be, majd ellenőrizd azokat az értékeket, amelyekre a program tényleges műveletet épít. Így a formátumra vonatkozó ígéret pontosan addig terjed, ameddig a szolgáltatás garantálja, az alkalmazás saját döntései pedig ellenőrzött adatra támaszkodhatnak.