Struktureeritud väljundid mitme mudeli API-lüüsis: JSON-skeem, tööriistakutsed ja semantilised kaitsepiirded

Seda maatriksit tuleks versioonida ja testida. Kui pakkuja muudab käitumist või lisatakse uus mudel, tuleks enne tootmise marsruutimist kontrollida struktureeritud väljundi ühilduvust.

3. Tõlgi tugevaimale pakkuja-omaleping

Adapter peaks järgima selget eelistuste järjekorda:

1. Kui valitud mudel ja skeem seda toetavad, kasutage rangeid pakkuja struktureeritud väljundeid.
2. Kasutage teenusepakkuja natiivset tööriista, mis kutsub toiminguid ja funktsioonitaolisi ülesandeid.
3. Kasutage mitteranget struktureeritud väljundit või JSON-režiimi koos valideerimisega ja proovige uuesti, kui range režiim pole saadaval.
4. Kõrge riskiga töövoogude puhul lükake taotlus tagasi, suunake ühilduva varumudeli juurde või tagastage mittetoimiv vastus.

Ärge viige kõrge riskiga toimingut vaikselt alla rangelt skeemirežiimilt „parima jõupingutusega JSON-ile”. Kui rakendus taotles ranget käitumist ja valitud teenusepakkuja ei saa seda toetada, peaks lüüs selle vea, marsruudiotsuse või selgesõnalise madalama versiooni lipu kaudu nähtavaks tegema.

Kolm valideerimiskihti enne käivitamist

1. kiht: sõelumise valideerimine

Esmalt tehke kindlaks, kas vastust saab sõeluda oodatud ümbrikusse. Kui leping seda keelab, ebaõnnestub kiiresti vigase JSON-i, puuduvate tööriistakutseplokkide, kärbitud vastuste või loomuliku keele ja JSON-i segamise korral.

function parseStructuredResponse(raw) {
  proovi {
    return { ok: tõsi, väärtus: JSON.parse(raw)};
  } püüdmine (viga) {
    return { ok: false, error_type: "parse_failure", error: String(error)};
  }
}

Pakkuja natiivsed tööriistakutsed ei pruugi nõuda toortekstiploki sõelumist, kuid need nõuavad siiski ümbriku valideerimist: kas mudel valis teadaoleva tööriista, kas see pakkus argumente ja kas see peatus tööriista täitmiseks ootuspäraselt?

2. kiht: JSON-skeemi valideerimine

Järgmisena kinnitage objekt serveripoolse validaatori abil deklareeritud skeemi alusel. Tehke seda isegi siis, kui pakkuja nõuab ranget skeemi tuge. Lüüsipoolne valideerimine annab teile järjepideva tõrgete logimise, kaitseb integreerimisvigade eest ja tuvastab allavoolu kokkusobimatused.

const validate = schemaValidator.comile(schema);
const valid = valide(objekt);
if (!kehtiv) {
  return {
    ok: vale,
    error_type: "schema_failure",
    vead: valide.errors
  };
}

Kaasaskantavuse huvides kujundage skeemid ühist alamhulka silmas pidades:

• Eelistage selgesõnalist tüüpi, nõutavat, atribuudid, enum ja additionalProperties: false.
• Vältige keerulisi kombinatsioone, nagu sügavalt pesastatud oneOf, anyOf ja tingimuslikud skeemid, kui te ei tea, et sihtpakkuja neid toetab.
• Hoidke tegevuse argumendid väikesed ja konkreetsed.
• Kasutage ID-de, kuupäevade ja koodide jaoks stringe, välja arvatud juhul, kui allsüsteemid nõuavad teist tüüpi.
• Esitage ebakindlus selgesõnaliselt selliste väljadega nagu usaldus, missing_fields või requires_human_review.

3. kiht: semantiline ja äriline valideerimine

Lõpuks kontrollige, kas struktureeritud tulemus on ülesande jaoks õige. See kiht on domeenispetsiifiline ja seda ei saa tellida ainult JSON-skeemile.

Arve väljavõtmiseks võivad semantilised kontrollid hõlmata järgmist.

• Kokkusumma ei ole negatiivne ja vastab reaüksustele tolerantsi piires.
• Valuuta kuvatakse lähtedokumendis.
• Tähtaeg ei ole võimatult kauges minevikus ega tulevikus.
• Teenusepakkuja on kinnitatud hankijate loendis.
• Usaldus on automaatseks sisestamiseks piisavalt kõrge.

Müügivihje kvalifikatsiooni kontrollimine võib hõlmata järgmist.

• Valitud segment on üks müügimeeskonna aktiivsetest segmentidest.
• Taotletud eelarvet ei leiutatud, kui kasutaja seda ei esitanud.
• Toimingut „raamatu demo” ei teostata, välja arvatud juhul, kui kasutaja seda selgesõnaliselt palub.

Partner API automatiseerimise puhul võivad kontrollid hõlmata järgmist.

• Edasimüüja kontol on õigus luua soovitud klient või võti.
• Taotletud kululimiit on partneri eeskirjadega kooskõlas.
• Tehtesel on idempotentsuse võti.
• Toiming salvestatakse enne täitmist auditilogi.

Tööriistakutsed: käsitlege mudeli väljundit päringu, mitte täitmisena

Tööriista kutsumine on õige muster, kui mudel peab paluma rakendusel midagi teha: luua pilet, saata Telegrami robotkäsk, otsida hinnakujundust, värskendada kliendikirjet või alustada töövoogu.

Turvaline tööriistasilmus näeb välja selline:

1. Rakendus deklareerib saadaolevad tööriistad ja nende sisestusskeemid.
2. Mudel tagastab struktureeritud argumentidega tööriistakutse.
3. Lüüs kinnitab tööriista nime ja argumendid.
4. Rakendus kontrollib autoriseerimist, eeskirju, idempotentsust ja kasutaja kinnitusnõudeid.
5. Alles seejärel käivitab rakendus tööriista.
6. Tööriista tulemus saadetakse mudelile tagasi, kui vestlust on vaja jätkata.

Ärge käsitlege tööriistakutset kunagi tõendina, et toiming peaks toimuma. Käsitle seda struktureeritud ettepanekuna. Rakendus jääb kõrvalmõjude eest vastutavaks.

Ohutu tagavararedel mitme mudeliga töövoogude jaoks

Lüüs peaks enne vahejuhtumite tekkimist määratlema varukäitumise. Praktiline redel on:

1. Esmane: eelistatud mudeli range struktureeritud väljund.
2. Ühilduv varu: teine mudel, mis toetab samu rangeid skeeminõudeid.
3. Kinnitamine ja uuesti proovimine: ilma range toeta pakkuja, mida kasutatakse ainult siis, kui risk seda võimaldab.
4. Inimese läbivaatamine: seadke struktureeritud tulemus ja lähtesisu kinnitamiseks järjekorda.
5. Mittetegevuse vastus: selgitage, et süsteem ei saa toimingut ohutult lõpule viia.

Korduskatsed on kasulikud vormindamise või väiksemate skeemitõrgete korral, kuid need ei ole ohutusstrateegia. Kui objekt on semantiliselt ohutu, võib korduv viip muuta õige tagasilükkamise ohtlikuks käivitatavaks objektiks. Kõrge riskiga toimingute puhul eelistage läbivaatamist või keeldumist korduvatele edu saavutamise katsetele.

Vaatlus: logige kõik struktureeritud väljundi otsused

Struktureeritud väljundi tõrked on töösignaalid. Logige need piisavalt üksikasjalikult, et parandada marsruutimist, skeeme ja viipasid ilma tarbetut tundlikku sisu paljastamata.

Soovitatud väljad:

• schema_id ja schema_version.
• Pakkuja ja mudel.
• Kasutatud on taotletud režiim ja tegelik režiim.
• Parsimise ebaõnnestumise olek.
• Skeemi tõrke olek ja valideerimisvead.
• Semantilise valideerimise ebaõnnestumise põhjus.
• Proovi loendamist uuesti.
• Laitentsus.
• Tokenide kasutamine ja hind.
• Lõpliku toimingu olek: teostatud, järjekorda pandud, tagasi lükatud või kasutajale tagastatud.
• Meeskonna, projekti, API-võtme või partneri konto identifikaator, kui see on asjakohane.

Need logid toetavad silumist, kulude analüüsi, pakkujate võrdlust ja meeskonna API juhtimist. Samuti aitavad need vastata küsimustele, nagu: „Milline skeemi versioon põhjustab kõige rohkem kordusi?” ja „Milline varumudel läbib süntaksi, kuid ei suuda ettevõtte valideerimist?”

Skeemi versioonide loomise reeglid

Skeemid on tootmisliidesed. Kohtle neid nagu API lepinguid.

• Kaasake päringu metaandmetesse ja logidesse schema_id ja schema_version.
• Ärge muutke vaikselt olemasolevate automatiseeringute kohustuslikke välju.
• Hoidke vanad skeemid klientide migratsiooni ajal kättesaadavana.
• Enne kohustuslikuks muutmist lisage uued valikulised väljad.
• Testige skeeme kõigi marsruutimiskogumi pakkujate ja varumudelitega.
• Salvestage, millist skeemi versiooni iga kõrvalmõjuga toimingu jaoks kasutati.

Versioonide loomine muutub eriti oluliseks agentuuride, edasimüüjate ja Partner API automatiseerimise jaoks, kus paljud alljärgnevad kliendid võivad sõltuda stabiilsest struktureeritud lepingust.

Millal struktureeritud tulemust mitte käivitada

Kasutage pidurdamist, kui ilmneb mõni järgmistest tingimustest:

• Vastus ei ole sõelutav.
• Objekti JSON-skeemi valideerimine ebaõnnestub.
• Enumi väärtust ei toetata või see on leiutatud.
• Kogus, hind, kuupäev või valuuta on võimatu.
• Tulemus on vastuolus kasutaja väljendatud kavatsusega.
• Mudel väljendab madalat usaldust või puuduvad tõendid.
• Kasutajajuhised on mitmetähenduslikud.
• Toimingul on kõrvalmõjud ja sellel puudub kinnitus.
• Konto, meeskonna või API võti pole volitatud.
• Pakkuja vastus sisaldab keeldumist või ohutusega seotud mittevastust.

Soovitused vs ennustused

Soovitused: kasutage teenusepakkuja struktureeritud väljundeid, kui need on saadaval, kinnitage kõik vastuse lüüsi pooled, eelistage tööriistakutseid toiminguteks, säilitage võimete maatriks, versiooniskeemid ja blokeerige kõrvalmõjud, kuni semantilised kontrollid läbivad.

Prognoosid: pakkuja tugi struktureeritud väljunditele muutub tõenäoliselt tugevamaks ja järjepidevamaks, kuid teisaldatavus jääb lüüsiprobleemiks, sest mudelipered, skeemi alamhulgad ja tööriistakutsungid ei muutu üleöö identseks. Meeskonnad, kes loovad praegu valideerimise, vaadeldavuse ja skeemi versioonide loomise, saavad paremini kasutusele võtta uusi teenusepakkuja funktsioone ilma iga töövoogu ümber kirjutamata.

Teostatav rakendamise kontroll-loend

1. Määratlege oma rakenduste jaoks normaliseeritud struktureeritud väljundi päringu vorming.
2. Looge oma marsruutimiskogumi iga mudeli jaoks pakkuja võimete maatriks.
3. Kujundage skeeme kaasaskantava JSON-skeemi alamhulga abil.
4. Tõlgige taotlused rangetele pakkuja-põhimehhanismidele, kui seda toetatakse.
5. Kinnitage sõelutavust, skeemi vastavust ja äritegevuse korrektsust pärast genereerimist.
6. Kasutage kõrvalmõjuga toimingute jaoks tööriistakutseid.
7. Nõuge volitust, idempotentsust ja kinnitust väljaspool mudelit.
8. Logi skeemi versioon, pakkuja, valideerimise tõrked, korduskatsed, latentsusaeg, kulu ja toimingu olek.
9. Määratlege varukäitumine töövoo riskitaseme järgi.
10. Hoidke vanad skeemid kättesaadavana kuni sõltuvate automatiseeringute migreerumiseni.

Praktiline eesmärk ei ole panna iga mudelit identselt käituma. Selle eesmärk on anda rakenduste arendajatele üks stabiilne leping, samal ajal kui lüüs käsitleb pakkujate erinevusi ausalt. Struktureeritud väljundid on usaldusväärseks tehisintellekti automatiseerimiseks vajalik infrastruktuur, kuid tootmispiiriks on valideerija ja poliitikakiht, mis otsustab, kas objekti on ohutu kasutada.

Seotud lugemine

• API võtme autoriseerimine ja meeskonna juhtelemendid
• jälgimisloa kulu ja korduskatsete latentsusaeg