Strukturētas izejas vairāku modeļu API vārtejā: JSON shēma, rīku izsaukumi un semantiskās aizsargsliedes

Modeļa aicinājums “atgriezt JSON” nav ražošanas līgums. Tas var izveidot derīgu JSON ar nepareizu uzskaitījumu, izlaist nepieciešamo uzņēmējdarbības noteikumu vai pārliecinoši pieprasīt darbību, kuru lietotājs nekad nav pilnvarojis. Vairāku pakalpojumu sniedzēju darbplūsmā problēma kļūst grūtāka: katrs pakalpojumu sniedzējs atklāj dažādus strukturētas izvades un rīku lietošanas mehānismus, un katrs atbalsta tikai daļu no JSON shēmas kopuma.

Praktiskais risinājums nav tikai maģisks pamudinājums. Tas ir slāņveida vārtejas modelis: normalizējiet izstrādātāja vēlamo shēmu, pēc iespējas pārveidojiet to nodrošinātāja strukturētās izvades vai rīka izsaukuma formātos, apstipriniet atgriezto objektu un lietojiet semantiskās aizsargmargas pirms jebkādas blakusparādības.

Šajā rokasgrāmatā ir izdalīti trīs dažādi mērķi, kas bieži tiek sajaukti kopā:

• Sintakses derīgums: atbilde ir parsējams JSON.
• Shēmas derīgums: JSON atbilst obligātajiem laukiem, veidiem, uzskaitījumiem un strukturālajiem noteikumiem.
• Uzņēmējdarbības pareizība: objekts ir drošs, uzticams lietotāja nodomam un derīgs pakārtotajai darbībai.

Ražošanas kļūme: derīgs JSON, nepareiza darbība

Apsveriet atbalsta automatizāciju, kas maršrutē ienākošās biļetes:

{
  "ticket_id": "t_481",
  "kategorija": "norēķini",
  "prioritāte": "steidzami",
  "action": "refund_customer",
  "summa_usd": 499
}

Šis objekts ir sintaktiski derīgs. Tā var pat nodot vienkāršu shēmu, ja darbība ir virkne un amount_usd ir skaitlis. Bet tas joprojām var būt nepareizi. Varbūt klients prasīja tikai rēķina kopiju. Varbūt atmaksai, kas pārsniedz 100 ASV dolārus, ir nepieciešams pārvaldnieka apstiprinājums. Iespējams, lietotājs vispār nav pilnvarots aktivizēt atmaksu.

Strukturētas izejas samazina parsēšanas kļūmes. Tie neaizstāj autorizāciju, politikas pārbaudes, krājumu pārbaudes, cenu pārbaudes, idempotenci vai cilvēka apstiprinājumu riskantām darbībām.

Fakti: ko sniedz un ko nesola nodrošinātāja strukturētās izvades režīmi

Pakalpojumu sniedzēja ainava ātri mainās, taču arhitektūrai ir svarīgi vairāki stabili fakti:

• JSON režīms var palīdzēt izveidot derīgu JSON, taču derīgs JSON nav tas pats, kas atbilstība noteiktai shēmai.
• Pakalpojumu sniedzēja vietējie strukturētās izvades režīmi ir paredzēti, lai uzlabotu shēmas atbilstību, taču tie parasti atbalsta tikai JSON shēmas apakškopu.
• Rīku izsaukšana parasti ir labāk piemērota darbībām nekā brīvas formas JSON, jo modelis atlasa deklarētu rīku un atgriež strukturētus argumentus, bet lietojumprogramma joprojām ir atbildīga par izpildi.
• Dažādi pakalpojumu sniedzēji piedāvā dažādus līgumus. Viens var izmantot stingru JSON shēmas atbildes formātu, cits var izmantot rīku ievades shēmas, bet citam var būt nepieciešama atkāpšanās pārbaude un mēģinājums vēlreiz.
• Pat shēmai derīga izvade var būt semantiski nepareiza, pirms tā nonāk datu bāzē, darbplūsmā vai apmaksātā darbībā.

Arhitektūras nozīme ir vienkārša: ar OpenAI saderīga API var standartizēt klienta saskarni, taču uzticamības slānim joprojām ir jāsaprot nodrošinātāja iespējas un jāapstiprina izvadi pēc ģenerēšanas.

Ieteicamā arhitektūra: strukturētas izvades adapteris

Izmantojiet vārtejas adapteri starp lietojumprogrammas kodu un nodrošinātāja API. Lietojumprogramma nosūta vienu shēmas nolūku. Vārteja norāda uz spēcīgāko atbalstīto pakalpojumu sniedzēja mehānismu.

1. Pieņemiet vienu normalizētu pieprasījumu no lietojumprogrammas

Klientam nav nepieciešami atsevišķi koda ceļi katram pakalpojumu sniedzējam. Praktiskā pieprasījuma aploksnē ir iekļauta modeļa izvēle, uzdevuma ievade, shēma, shēmas metadati un riska līmenis:

{
  "modelis": "automātiski: precīzs",
  "Ziņojumi": [
    {"role": "system", "content": "Izvilkt rēķina laukus. Neseciniet trūkstošās vērtības."},
    {"role": "user", "content": "Rēķina teksts..."}
  ],
  "structured_output": {
    "schema_id": "invoice_extraction",
    "schema_version": "2026-08-01",
    "režīms": "json_schema",
    "stingrs": patiess,
    "shēma": {
      "tips": "objekts",
      "additionalProperties": nepatiess,
      "required": ["rēķina_numurs", "vendor_name", "kopā", "valūta", "maksas_datums"],
      "īpašības": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "kopā": {"tips": "skaitlis", "minimums": 0},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "string", "format": "date"},
        "pārliecība": {"tips": "skaitlis", "minimums": 0, "maksimums": 1}
      }
    }
  },
  "metadati": {
    "darbplūsma": "accounts_payable",
    "risk_level": "vidējs"
  }
}

Šis līgums sniedz vārtejai pietiekami daudz informācijas, lai izvēlētos nodrošinātāja vietējo ieviešanu, veiktu validāciju un reģistrētu nozīmīgus kļūdu datus.

2. Saglabājiet nodrošinātāja iespēju matricu

Vārtejai ir jāsaglabā mašīnlasāma matrica, nevis jāpaļaujas uz pieņēmumiem, piemēram, “visi ar OpenAI saderīgi modeļi atbalsta vienu un to pašu shēmas darbību”. Noderīga matrica ietver:

• Pakalpojumu sniedzēja un modeļa nosaukums.
• Atbalsta JSON režīmu.
• Atbalsta JSON shēmas atbildes formātu.
• Atbalsta rīku izsaukumus.
• Atbalsta stingru shēmu režīmu.
• Zināmie JSON shēmas apakškopas ierobežojumi.
• Vai paralēlie rīku izsaukumi ir saderīgi ar stingru shēmas režīmu.
• Atkāpšanās darbība, ja pieprasītais režīms netiek atbalstīts.

Iespēju ieraksta piemērs:

{
  "provider": "provider_a",
  "modelis": "model_x",
  "json_mode": taisnība,
  "json_schema_response": patiess,
  "tool_calls": taisnība,
  "strict_schema": taisnība,
  "schema_limitations": ["no oneOf", "limited format validation"],
  "atkāpšanās": "noraidīt_vai_maršruts uz saderīgu_modeli"
}

Šī matrica ir jāveido un jāpārbauda. Ja pakalpojumu sniedzējs maina uzvedību vai tiek pievienots jauns modelis, pirms ražošanas maršrutēšanas ir jāpārbauda strukturētās produkcijas saderība.

3. Tulkojiet uz spēcīgāko pakalpojumu sniedzēja vietējo līgumu

Adapterim ir jāievēro skaidra preferenču secība:

1. Izmantojiet stingras nodrošinātāja vietējās strukturētas izvades, ja to atbalsta atlasītais modelis un shēma.
2. Izmantojiet pakalpojumu sniedzēja vietējo rīku, kas izsauc darbības un funkcijām līdzīgus uzdevumus.
3. Izmantojiet ne-stingru strukturētu izvadi vai JSON režīmu ar validāciju un mēģiniet vēlreiz, ja stingrais režīms nav pieejams.
4. Noraidīt pieprasījumu, novirzīt uz saderīgu rezerves modeli vai nosūtīt atbildi bez darbības augsta riska darbplūsmām.

Neklusējot nepazeminiet augsta riska darbību no stingras shēmas režīma uz “vislabāko JSON”. Ja lietojumprogramma pieprasīja stingru darbību un atlasītais pakalpojumu sniedzējs to nevar atbalstīt, vārtejai tas jāpadara redzams, izmantojot kļūdu, maršrutēšanas lēmumu vai nepārprotamu pazemināšanas karogu.

Trīs validācijas slāņi pirms izpildes

1. slānis: parsēšanas validācija

Vispirms nosakiet, vai atbildi var parsēt paredzētajā aploksnē. Ātri neizdodas nepareizi veidots JSON, trūkst rīku izsaukuma bloku, saīsinātas atbildes vai jaukta dabiskā valoda un JSON, ja līgums to aizliedz.

function parseStructuredResponse(raw) {
  mēģināt {
    return { ok: true, value: JSON.parse(raw)};
  } nozveja (kļūda) {
    return { ok: false, error_type: "parse_failure", error: String(error)};
  }
}

Pakalpojumu sniedzēja rīka izsaukumiem, iespējams, nav jāparsē neapstrādāta teksta lāse, taču tiem joprojām ir nepieciešama aploksnes validācija: vai modelis atlasīja zināmu rīku, sniedza argumentus un vai tas apturēja rīka izpildi, kā paredzēts?

2. slānis: JSON shēmas validācija

Pēc tam pārbaudiet objektu atbilstoši deklarētajai shēmai, izmantojot servera puses pārbaudītāju. Dariet to pat tad, ja pakalpojumu sniedzējs pieprasa stingru shēmas atbalstu. Vārtejas validācija nodrošina konsekventu kļūdu reģistrēšanu, aizsargā pret integrācijas kļūdām un novērš pakārtotās nesaderības.

const valide = schemaValidator.comile(schema);
const derīgs = validēt(objekts);
if (!derīgs) {
  return {
    labi: nepatiesi,
    error_type: "schema_failure",
    kļūdas: valide.errors
  };
}

Lai nodrošinātu pārnesamību, izstrādājiet shēmas, ņemot vērā kopējo apakškopu:

• Izvēlieties skaidru tipu, obligātu, rekvizītus, enum un additionalProperties: false.
• Izvairieties no sarežģītām kombinācijām, piemēram, dziļi ligzdotām oneOf, anyOf un nosacījumu shēmām, ja vien nezināt, ka mērķa nodrošinātājs tās atbalsta.
• Saglabājiet darbības argumentus mazus un konkrētus.
• Izmantojiet virknes ID, datumiem un kodiem, ja vien pakārtotajām sistēmām nav nepieciešams cits veids.
• Tieši attēlojiet nenoteiktību ar tādiem laukiem kā uzticamība, missing_fields vai requires_human_review.

3. slānis: semantiskā un biznesa validācija

Visbeidzot pārbaudiet, vai strukturētais rezultāts ir pareizs uzdevumam. Šis slānis ir specifisks domēnam, un to nevar izmantot tikai JSON shēmai.

Rēķinu izgūšanai semantiskās pārbaudes var ietvert:

• Kopējā summa nav negatīva un atbilst rindas vienībām pielaides robežās.
• Valūta ir norādīta avota dokumentā.
• Maksājuma datums nav neiespējami tālu pagātnē vai nākotnē.
• Pārdevējs ir apstiprinātā piegādātāju sarakstā.
• Ticība ir pietiekami augsta automātiskai ievadīšanai.

Pārbaudot potenciālā pirkuma kvalifikāciju, var būt:

• Atlasītais segments ir viens no pārdošanas komandas aktīvajiem segmentiem.
• Pieprasītais budžets nav izdomāts, ja lietotājs to nenorādīja.
• Grāmatas demonstrācijas darbība netiek izpildīta, ja vien lietotājs to nav skaidri lūdzis.

Partner API automatizācijas pārbaudēs var būt:

• Tālākpārdevēja konts ir pilnvarots izveidot pieprasīto klientu vai atslēgu.
• Pieprasītais tēriņu ierobežojums atbilst partneru politikai.
• Darbībai ir idempotences atslēga.
• Pirms izpildes darbība tiek ierakstīta audita žurnālā.

Rīku izsaukumi: modeļa izvadi uzskata par pieprasījumu, nevis izpildi

Rīka izsaukšana ir pareizais modelis, kad modelim ir jālūdz lietojumprogrammai kaut kas veikt: izveidot biļeti, nosūtīt Telegram robotprogrammas komandu, meklēt cenas, atjaunināt klienta ierakstu vai sākt darbplūsmu.

Droša rīka cilpa izskatās šādi:

1. Lietojumprogramma deklarē pieejamos rīkus un to ievades shēmas.
2. Modelis atgriež rīka izsaukumu ar strukturētiem argumentiem.
3. Vārteja apstiprina rīka nosaukumu un argumentus.
4. Lietojumprogramma pārbauda autorizācijas, politikas, idempotences un lietotāja apstiprinājuma prasības.
5. Tikai pēc tam lietojumprogramma izpilda rīku.
6. Rīka rezultāts tiek nosūtīts atpakaļ modelim, ja saruna ir jāturpina.

Nekad neuzskatiet rīka izsaukumu kā pierādījumu tam, ka darbībai ir jānotiek. Uztveriet to kā strukturētu priekšlikumu. Lietojumprogramma joprojām ir iestāde par blakusparādībām.

Drošas rezerves kāpnes vairāku modeļu darbplūsmām

Vārtejai ir jādefinē atkāpšanās darbība, pirms notiek incidenti. Praktiskas kāpnes ir:

1. Primārais: stingri strukturēta izvade vēlamajā modelī.
2. Saderīgs rezerves: cits modelis, kas atbalsta tās pašas stingrās shēmas prasības.
3. Validācija un mēģinājums vēlreiz: pakalpojumu sniedzējs bez stingra atbalsta, tiek izmantots tikai tad, ja to atļauj risks.
4. Cilvēka veiktā pārskatīšana: ievietojiet strukturēto rezultātu un avota saturu apstiprināšanai rindā.
5. Atbilde bez darbības: paskaidrojiet, ka sistēma nevar droši pabeigt darbību.

Atkārtoti mēģinājumi ir noderīgi formatēšanas vai nelielas shēmas kļūmju gadījumā, taču tā nav drošības stratēģija. Ja objekts ir semantiski nedrošs, atkārtota uzvedne var pārvērst pareizu noraidījumu par bīstamu izpildāmu objektu. Augsta riska darbībām dodiet priekšroku pārskatīšanai vai atteikumam, nevis atkārtotiem mēģinājumiem gūt panākumus.

Novērojamība: reģistrējiet katru strukturētās izvades lēmumu

Strukturētas izvades kļūmes ir darbības signāli. Reģistrējiet tos ar pietiekami detalizētu informāciju, lai uzlabotu maršrutēšanu, shēmas un uzvednes, neatklājot nevajadzīgu sensitīvu saturu.

Ieteicamie lauki:

• schema_id un schema_version.
• Pakalpojumu sniedzējs un modelis.
• Pieprasītais režīms un izmantotais faktiskais režīms.
• Parsēšanas kļūmes statuss.
• Shēmas kļūmes statuss un validācijas kļūdas.
• Semantiskās validācijas kļūmes iemesls.
• Mēģiniet skaitīt vēlreiz.
• Latentums.
• Marķiera lietojums un izmaksas.
• Galīgais darbības statuss: izpildīts, ievietots rindā, noraidīts vai atgriezts lietotājam.
• Komanda, projekts, API atslēga vai partnera konta identifikators, ja nepieciešams.

Šie žurnāli atbalsta atkļūdošanu, izmaksu analīzi, pakalpojumu sniedzēju salīdzināšanu un komandas API pārvaldību. Tie arī palīdz atbildēt uz tādiem jautājumiem kā: “Kura shēmas versija izraisa visvairāk mēģinājumu?” un “Kurš atkāpšanās modelis iztur sintaksi, bet neizdodas veikt uzņēmuma validāciju?”

Shēmas versiju veidošanas noteikumi

Shēmas ir ražošanas saskarnes. Izturieties pret tiem kā pret API līgumiem.

• Pieprasījuma metadatos un žurnālos iekļaujiet schema_id un schema_version.
• Neklusējot nemainiet obligātos laukus esošajai automatizācijai.
• Saglabājiet vecās shēmas pieejamas, kamēr klienti migrē.
• Pievienojiet jaunus neobligātos laukus, pirms tie ir obligāti.
• Pārbaudiet shēmas attiecībā pret katru nodrošinātāju un rezerves modeli maršrutēšanas pūlā.
• Ierakstiet, kura shēmas versija tika izmantota katrai blakusdarbībai.

Versiju noteikšana kļūst īpaši svarīga aģentūrām, tālākpārdevējiem un partneru API automatizācijai, kur daudzi pakārtotie klienti var būt atkarīgi no stabila strukturēta līguma.

Kad neizpildīt strukturētu rezultātu

Izmantojiet stingru apturēšanu, ja parādās kāds no šiem nosacījumiem:

• Atbilde nav parsējama.
• Objektam neizdodas JSON shēmas validācija.
• Enum vērtība netiek atbalstīta vai ir izdomāta.
• Nav iespējams norādīt daudzumu, cenu, datumu vai valūtu.
• Rezultāts ir pretrunā ar lietotāja norādīto nolūku.
• Modelis pauž zemu ticamību vai trūkst pierādījumu.
• Lietotāja norādījumi ir neskaidri.
• Darbībai ir blakusparādības, un tai trūkst apstiprinājuma.
• Konta, komandas vai API atslēga nav autorizēta.
• Pakalpojumu sniedzēja atbildē ir ietverts atteikums vai ar drošību saistīta neatbilde.

Ieteikumi salīdzinājumā ar prognozēm

Ieteikumi: izmantojiet nodrošinātāja vietējos strukturētos rezultātus, ja tie ir pieejami, apstipriniet visas atbildes vārtejas, dodiet priekšroku rīka aicinājumiem veikt darbības, uzturiet iespēju matricu, versiju shēmas un bloķējiet blakusefektus, līdz tiek veiktas semantiskās pārbaudes.

Prognozes: nodrošinātāja atbalsts strukturētiem rezultātiem, visticamāk, kļūs spēcīgāks un konsekventāks, taču pārnesamība joprojām būs vārtejas problēma, jo modeļu saimes, shēmu apakškopas un rīku izsaukuma cilpas nekļūs identiskas vienā dienā. Komandas, kas tagad veido validāciju, novērojamību un shēmas versijas, būs labāk pakļautas jaunu pakalpojumu sniedzēja funkciju ieviešanai, nepārrakstot katru darbplūsmu.

Rīcības izpildes kontrolsaraksts

1. Definējiet normalizētu strukturētas izvades pieprasījuma formātu savām lietojumprogrammām.
2. Izveidojiet nodrošinātāja iespēju matricu katram jūsu maršrutēšanas pūla modelim.
3. Izstrādājiet shēmas, izmantojot pārnēsājamu JSON shēmas apakškopu.
4. Tulkot pieprasījumus uz stingriem nodrošinātāja vietējiem mehānismiem, kad tie tiek atbalstīti.
5. Pārbaudiet parsējamību, shēmas atbilstību un uzņēmējdarbības pareizību pēc ģenerēšanas.
6. Izmantojiet rīku izsaukumus darbībām ar blakusefektiem.
7. Nepieciešama autorizācija, idempotence un apstiprinājums ārpus modeļa.
8. Žurnāla shēmas versija, nodrošinātājs, validācijas kļūmes, mēģinājumi, latentums, maksa un darbības statuss.
9. Definējiet atkāpšanās darbību pēc darbplūsmas riska līmeņa.
10. Saglabājiet vecās shēmas pieejamas līdz atkarīgo automatizācijas migrēšanai.

Praktiskais mērķis nav panākt, lai katrs modelis darbotos vienādi. Tā mērķis ir nodrošināt lietojumprogrammu izstrādātājiem vienu stabilu līgumu, kamēr vārteja godīgi apstrādā pakalpojumu sniedzēju atšķirības. Strukturētie izvadi ir nepieciešama infrastruktūra uzticamai AI automatizācijai, taču ražošanas robeža ir validators un politikas slānis, kas izlemj, vai objekts ir drošs lietošanai.

Saistīta informācija

• API atslēgas autorizācija un komandas vadīklas
• izsekošanas pilnvaras izmaksas un latentums atkārtotajiem mēģinājumiem