JSON mode tryggir ekki skemað — notaðu Structured Outputs og sannprófun

Ef svar mállíkans á að fara í API, gagnagrunn eða sjálfvirkt verkflæði skaltu skilgreina JSON Schema, óska eftir skemastýrðu svari og sannprófa það áður en kerfið notar gögnin. Leiðbeiningar OpenAI greina á milli JSON mode, sem tryggir gilt JSON við venjulegar aðstæður, og Structured Outputs, sem bindur fullgert svar við tiltekið skema. Neitun og ófullgert svar þarf að meðhöndla sérstaklega.

Skemafylgni segir til um gerð reita, skyldureiti og leyfð gildi; hún staðfestir ekki að upplýsingarnar séu réttar. Líkan getur skilað leyfðum flokki og tilvísun á réttum stað en samt valið tilvísun sem finnst hvergi í erindinu. Samþætting þarf því bæði að sannprófa gagnahlutinn og bera mikilvæg gildi saman við inntak eða áreiðanleg frumgögn.

Skemað á að lýsa nákvæmlega því sem kerfið tekur við

Í skilyrtu dæmi flokkar líkan erindi sem „beiðni“ eða „kvörtun“ og skilar tilvísun úr texta erindisins. Gagnahluturinn hefur reitina flokkur og tilvisun. Settu flokkur sem streng með enum-gildunum „beiðni“ og „kvörtun“, tilvisun sem streng, báða reiti í required og additionalProperties sem false. Þannig er svar með öðrum flokki, vantar annan reitinn eða bætir við óvæntum lykli utan samningsins.

Skilyrt JSON Schema: {"type":"object","properties":{"flokkur":{"type":"string","enum":["beiðni","kvörtun"]},"tilvisun":{"type":"string"}},"required":["flokkur","tilvisun"],"additionalProperties":false}. Í Python er þetta orðabók þar sem síðasta gildið er False; í TypeScript er það false. Hvorugt formið segir þó hvort tilvísunin sé til eða hvort flokkunin samræmist merkingu erindisins.

Hafðu skemað eins lítið og verkefnið leyfir. Þegar reitur má vera án gildis í viðskiptalegum skilningi þarf það að sjást í samningnum, til dæmis með null þar sem viðkomandi API styður slíka gerð. Að öðrum kosti getur krafan um streng þrýst líkaninu til að fylla reit með ágiskun. Lýstu líka skýrt hvaðan tilvísunin á að koma; lýsingin leiðbeinir líkaninu en kemur ekki í stað samanburðar við upprunalega erindið.

Python: athugaðu stöðu áður en þú lest JSON

Í Responses API fer skema loka­svarsins í text.format. Lágmarksdæmið notar sömu Python-orðabók og að ofan: client = OpenAI(timeout=10.0, max_retries=0); r = client.responses.create(model=MODEL, input=TEXT, text={'format':{'type':'json_schema','name':'flokkun','strict':True,'schema':schema}}). MODEL táknar líkan sem styður stillinguna og TEXT er erindið. Tímamörkin eru val í þessu skilyrta dæmi; slökkt er á sjálfvirkum endurprófunum svo forritið geti stýrt þeim sjálft.

Lesið ekki r.output_text fyrr en r.status er 'completed'. Leitið jafnframt að efnislið með type 'refusal' í skilaboðum r.output; neitun er sérstök niðurstaða og á ekki að verða að tómum gagnahlut. Að þessum athugunum loknum má nota json.loads(r.output_text) og síðan validate(instance=data, schema=schema) úr jsonschema. Ef úttakið er ógilt þrátt fyrir skemastillinguna á staðbundin sannprófun að stöðva það áður en nokkur færsla er vistuð.

Greindu villur eftir orsök. APITimeoutError má setja í eina afmarkaða endurprófun ef beiðnin hefur engar aukaverkanir; beiðnin gæti hafa verið unnin þótt biðlarinn hafi misst sambandið. BadRequestError sem stafar af óstuddu eða gölluðu skema kallar á lagfæringu á beiðninni, ekki endurtekningu hennar óbreyttrar. Ófullgert svar, til dæmis þegar úttaksmörk stöðva myndun, fer heldur ekki sjálfkrafa í JSON-þáttun.

TypeScript: sami gagnasamningur, sama aðgreining villna

Í TypeScript er samsvarandi lágmarksbeiðni: const client = new OpenAI({timeout: 10000, maxRetries: 0}); const r = await client.responses.create({model: MODEL, input: TEXT, text: {format: {type: 'json_schema', name: 'flokkun', strict: true, schema}}});. Hér er schema JavaScript-hlutur með sama enum, required og additionalProperties: false. Biðlarinn fær tímamörk í millisekúndum, en Python-dæmið notar sekúndur; gildin lýsa sömu skilyrtu bið.

Úrvinnslan byrjar á r.status og efnisliðum r.output. Ef staðan er ófullgerð er svarinu hafnað; ef efnisliður hefur type 'refusal' fer það í neitunarleið. Aðeins fullgert svar án neitunar fer í JSON.parse(r.output_text), staðbundinn JSON Schema-sannprófara og síðan prófun á viðskiptareglum. Tímamörk geta fengið eina stýrða endurprófun samkvæmt sömu reglu og í Python; hafnað beiðniskema þarf leiðréttingu áður en aftur er sent.

Rétt form getur geymt ranga staðreynd

Í skilyrta erindinu gæti líkanið skilað {"flokkur":"beiðni","tilvisun":"ABC"}. Sá hlutur stenst skemað jafnvel þótt „ABC“ komi ekki fyrir í erindinu og eigi sér enga samsvarandi færslu. Berðu því tilvisun saman við textann eða heimildarkerfi áður en hún er notuð sem lykill í gagnagrunni. Ef flokkur stýrir aðgerð þarf einnig að ákveða hvernig tvíræð erindi fara í yfirferð.

Haltu skemavillu og merkingarvillu aðskildum í villuskráningu. Skemavilla merkir að forritið fékk ekki þann gagnahlut sem það samdi um; merkingarvilla merkir að læsilegur gagnahlutur stenst ekki samanburð við staðreyndir eða reglur. Endurprófun getur stundum skilað nýju svari eftir tímabundna myndunarvillu, en sama líkan getur líka endurtekið ranga ályktun. Samanburður við frumgögn er því sjálfstætt skilyrði fyrir vistun.

Prófunarfylki sýnir hvað hver birgir tryggir

Birgjar setja skema á ólíka staði í beiðninni. Skjöl Claude lýsa output_config.format fyrir JSON-svar og strict: true fyrir inntak verkfærakalla; þau gera einnig grein fyrir takmörkunum á skemum og því að neitun geti fallið utan þeirra. Veldu snið loka­svars þegar forritið þarf gagnahlutinn sjálfan, en verkfærakall þegar líkanið á að óska eftir aðgerð í kerfinu.

Leiðbeiningar Gemini aðgreina sömuleiðis skipulagt lokasvar frá function calling, lýsa stuðningi við undirmengi JSON Schema og mæla með sannprófun gilda í forritinu. Sama skema þarf því að fara í gegnum sömu próf hjá hverjum birgi. Það nægir ekki að API samþykki heiti stillingarinnar; prófið þarf að sýna hvað gerist þegar raunverulegt svar fer yfir mörkin milli líkans og kerfis.

• Sendu skema með skyldureitum, enum og banni við aukalyklum. Skráðu hvort birgir samþykkir það óbreytt eða krefst breytinga.
• Prófaðu skýrt erindi, tvírætt erindi, neitun og svar sem stöðvast áður en því lýkur. Skráðu stöðu API-svarsins og hvort efnið má fara í þáttun.
• Sendu viljandi ógilt skema og framkallaðu tímamörk í prófunarumhverfi. Staðfestu að skemavilla stöðvi beiðnina og að aðeins tímabundin villa fari í fyrirfram ákveðna endurprófun.
• Láttu loks formlega gilt svar með rangri tilvísun fara í gegnum staðbundna sannprófun. Prófið stenst aðeins ef færslan er stöðvuð áður en hún fer í API eða gagnagrunn.

Lestu einnig:

• Whisper eða Google fyrir íslenskt tal: stuðningur tryggir ekki nákvæmni
• Ragas eða DeepEval: gagnasafnið og CI-prófið mæla ekki sama hlut
• Google Takeout velur ekki tímabil — afritaðu Gmail án þess að týna merkjum