JSON-i mund të jetë i vlefshëm dhe prapë i gabuar: përdor skemën

Për të marrë nga një model AI një objekt me fusha dhe tipe të paracaktuara, përkufizo një JSON Schema, dërgoje me kërkesën API dhe valido përgjigjen në aplikacion. Një përgjigje mund të lexohet si JSON pa gabim, por të ketë një fushë që mungon ose një numër të shkruar si tekst.

Kontrollo edhe nëse modeli e ka përfunduar përgjigjen dhe nëse ka refuzuar kërkesën, përpara se ta lexosh rezultatin si JSON. Skema kontrollon formën e të dhënave; përputhja e vlerave me tekstin burimor kërkon kontroll më vete. Këto kontrolle vlejnë edhe kur ofruesi premton dalje të strukturuar.

Ndërto kontratën mbi një porosi të thjeshtë

Marrim një shembull të kushtëzuar: mesazhi është «Arta kërkon 3 fletore; porosia nuk është urgjente». Aplikacionit i duhen fushat emri dhe artikulli si tekst, sasia si numër i plotë dhe urgjente si vlerë boolean. Objekti i synuar është {"emri":"Arta","artikulli":"fletore","sasia":3,"urgjente":false}.

Skema për këtë rast është {"type":"object","properties":{"emri":{"type":"string"},"artikulli":{"type":"string"},"sasia":{"type":"integer"},"urgjente":{"type":"boolean"}},"required":["emri","artikulli","sasia","urgjente"],"additionalProperties":false}. Te properties përcaktohen emrat dhe tipat; required kërkon praninë e çdo fushe; additionalProperties: false përjashton çelësa të tjerë. Mbaje këtë objekt si kontratën që përdorin si kërkesa ndaj modelit, ashtu edhe validimi lokal.

Varianti {"emri":"Arta","artikulli":"fletore","sasia":"3","urgjente":false} është JSON sintaksisht i vlefshëm. Megjithatë, ai nuk e kalon skemën, sepse sasia është string dhe kontrata kërkon integer. Nëse kodi e përdor sasinë për llogaritje, pranimi i heshtur i këtij varianti e zhvendos gabimin në një fazë tjetër të aplikacionit.

Vendos paraprakisht çfarë duhet të ndodhë kur burimi nuk e përmban një të dhënë. Nëse emri mund të mungojë, tipi i tij mund të jetë ["string","null"], ndërsa fusha mbetet në required dhe merr vlerën null. Shkruaj në udhëzim që modeli të mos shpikë një emër; detyrimi për të kthyer një fushë tekstuale pa një mënyrë për të shënuar mungesën mund të nxisë një vlerë të hamendësuar.

OpenAI: skema vendoset te text.format

Udhëzimi i OpenAI dallon JSON mode, i cili synon JSON të vlefshëm, nga Structured Outputs, i cili synon përputhjen me skemën e dhënë. Për nxjerrjen e porosisë në Responses API, vendose objektin e mësipërm te text.format.schema, cakto text.format.type si json_schema, jepi formatit një name dhe vendos strict: true.

Në të njëjtën kërkesë, dërgo mesazhin e porosisë si input dhe kërko vetëm të dhënat që shprehen në të. Përgjigjja e pritshme ka katër fushat e kontratës, me sasia si numër dhe urgjente si vlerë boolean. Ky udhëzim për përmbajtjen ka rol tjetër nga skema: tipi integer mund të zbatohet edhe kur modeli nxjerr një sasi të pasaktë nga mesazhi.

Modaliteti strict kërkon që të gjitha fushat e përcaktuara të jenë në required dhe që objektet të kenë additionalProperties: false. Nëse zgjeron skemën me objekte të ndërfutura, zbatoje rregullin edhe brenda tyre. Për një fushë që mund të mos ketë vlerë, lejo null në tip në vend që ta heqësh nga lista required.

Gemini: të njëjtat fusha, mbështjellës tjetër

Dokumentacioni i Gemini për Interactions API e vendos skemën te response_format.schema, me response_format.type të barabartë me text dhe mime_type të barabartë me application/json. Dërgo të njëjtin mesazh porosie si input dhe të njëjtën skemë me emri, artikulli, sasia dhe urgjente. Aplikacioni mund të presë të njëjtën formë objekti, edhe pse parametrat që e kërkojnë ndryshojnë nga ata të OpenAI.

Gemini mbështet një nënbashkësi të JSON Schema. Tipat object, string, integer dhe boolean, bashkë me properties, required dhe additionalProperties, përfshihen në vetitë e dokumentuara dhe mbulojnë shembullin e porosisë. Nëse i shton skemës kufizime të tjera, kontrollo nëse pranohen nga API që po përdor; një skemë e vlefshme për një validator lokal nuk është domosdoshmërisht e pranueshme për gjenerimin te çdo model.

Ruaj të njëjtat kuptime për fushat te të dyja kërkesat. Për shembull, sasia duhet të nënkuptojë numrin e fletoreve të përmendura në mesazh, jo numrin e rreshtave të porosisë. Një përshkrim i qartë i detyrës ndihmon nxjerrjen e vlerave, ndërsa skema vendos kufijtë e formës së përgjigjes.

Valido tipat dhe pastaj vlerat

Pas një përgjigjeje të përfunduar, lexo tekstin si JSON dhe valido objektin kundrejt skemës së ruajtur në aplikacion. Në Python, kjo do të thotë të përdorësh json.loads(teksti) për leximin dhe pastaj jsonschema.validate(instance=objekti, schema=skema). Dokumentacioni i jsonschema dallon ValidationError për të dhëna që nuk përputhen nga SchemaError për një skemë të pavlefshme.

Këto gabime kërkojnë trajtim të ndryshëm. Një tekst që nuk lexohet si JSON dështon përpara validimit; një objekt me sasia si "3" dështon te tipi; një SchemaError tregon problem në kontratën e aplikacionit. Nëse përpunon shumë përgjigje me të njëjtën skemë, mund ta kontrollosh skemën paraprakisht dhe të ripërdorësh një validator, në vend që ta kontrollosh për çdo objekt të ri.

Validimi i skemës nuk vendos nëse nxjerrja është besnike ndaj burimit. Objekti me sasia 5 do t’i përmbushte tipat dhe fushat e shembullit, por do të kundërshtonte mesazhin që kërkon 3 fletore. Për fusha që nisin pagesa, porosi ose veprime të tjera, krahaso vlerat vendimtare me hyrjen; kur formulimi është i paqartë, mbaje rezultatin për shqyrtim në vend që ta trajtosh si fakt të sigurt.

Refuzimi dhe përgjigjja e paplotë janë degë më vete

Në Responses API, kontrollo statusin e përgjigjes përpara leximit të JSON-it. Statusi incomplete kërkon trajtimin e ndërprerjes, ndërsa një përmbajtje e tipit refusal shënon refuzim dhe mund të mos ndjekë skemën e kërkuar. Asnjërën mos e dërgo si regjistër porosie te kodi që pret katër fushat.

Për kërkesën në Gemini, kontrollo nëse thirrja përfundoi me sukses dhe nëse u kthye tekst daljeje përpara se të bësh leximin dhe validimin lokal. Nëse nuk ka tekst të përdorshëm, kthe një gjendje të veçantë mungese rezultati. Një përgjigje bosh ose një gabim API nuk duhet shndërruar në një objekt me vlera të sajuara vetëm për të plotësuar skemën.

Rrjedha e aplikacionit mund t’i ndajë qartë rezultatet: objekt i pranuar, JSON i palexueshëm, mospërputhje me skemën, refuzim dhe përgjigje e paplotë. Kështu, kodi e përdor porosinë vetëm kur ka marrë një përgjigje të përfunduar, me formën e kërkuar dhe me vlera të mbështetura nga mesazhi hyrës.

Lexoni gjithashtu:

• Clockify apo Toggl Track: kursimi për vend mund të kushtojë përdorimin
• Një përmbledhje e gabuar nga AI uli kujtesën e saktë në 44,8%
• Crowdcube apo Republic Europe: dalja e hershme mund të marrë 7,5%