Sortides estructurades en una passarel·la d'API multimodel: esquema JSON, trucades d'eines i baranes semàntiques

Demanar a un model que "retorni JSON" no és un contracte de producció. Pot produir un JSON vàlid amb una enumeració incorrecta, ometre una regla empresarial necessària o sol·licitar amb confiança una acció que l'usuari mai va autoritzar. En un flux de treball amb diversos proveïdors, el problema es fa més difícil: cada proveïdor exposa diferents mecanismes de sortida estructurada i d'ús d'eines, i cadascun només admet una part de l'univers de l'esquema JSON.

La solució pràctica no és una indicació màgica. És un patró de passarel·la en capes: normalitzeu l'esquema desitjat del desenvolupador, traduïu-lo a formats de sortida estructurada o de trucada d'eines natius del proveïdor, sempre que sigui possible, valideu l'objecte retornat i apliqueu baranes semàntiques abans de qualsevol efecte secundari.

Aquesta guia separa tres objectius diferents que sovint es barregen:

• Validesa de la sintaxi: la resposta és JSON analitzable.
• Validesa de l'esquema: el JSON coincideix amb els camps, els tipus, les enumeracions i les regles estructurals obligatoris.
• Correcció empresarial: l'objecte és segur, fidel a la intenció de l'usuari i vàlid per a l'acció posterior.

Error de producció: JSON vàlid, acció incorrecta

Penseu en una automatització d'assistència que encamine els bitllets entrants:

{
  "ticket_id": "t_481",
  "category": "facturació",
  "priority": "urgent",
  "action": "refund_customer",
  "import_usd": 499
}

Aquest objecte és sintàcticament vàlid. Fins i tot pot passar un esquema simple si action és una cadena i amount_usd és un número. Però encara pot estar equivocat. Potser el client només va demanar una còpia de la factura. Potser els reembossaments superiors a 100 $ requereixen l'aprovació del gestor. Potser l'usuari no té cap autorització per activar reembossaments.

Les sortides estructurades redueixen els errors d'anàlisi. No substitueixen l'autorització, les comprovacions de polítiques, les comprovacions d'inventari, les comprovacions de preus, la idempotència o la confirmació humana per a operacions de risc.

Fets: quins modes de sortida estructurada del proveïdor fan i no prometen

El panorama del proveïdor canvia ràpidament, però hi ha diversos fets estables importants per a l'arquitectura:

• El mode JSON pot ajudar a produir JSON vàlid, però el JSON vàlid no és el mateix que la conformitat amb un esquema específic.
• Els modes de sortida estructurada nadius del proveïdor estan dissenyats per millorar l'adherència de l'esquema, però normalment només admeten un subconjunt de l'esquema JSON.
• La trucada a l'eina sol ser més adequada per a les accions que el JSON de forma lliure perquè el model selecciona una eina declarada i retorna arguments estructurats, mentre que l'aplicació segueix sent responsable de l'execució.
• Diferents proveïdors exposen contractes diferents. Un pot utilitzar un format de resposta d'esquema JSON estricte, un altre pot utilitzar esquemes d'entrada d'eines i un altre pot requerir una alternativa de validació i reintent.
• Fins i tot la sortida vàlida per l'esquema pot ser semànticament incorrecta abans d'arribar a una base de dades, un flux de treball o una acció de pagament.

La implicació arquitectònica és senzilla: una API compatible amb OpenAI pot estandarditzar la interfície del client, però la capa de fiabilitat encara ha d'entendre les capacitats del proveïdor i validar els resultats després de la generació.

Arquitectura recomanada: l'adaptador de sortida estructurada

Utilitzeu un adaptador de passarel·la entre el codi de l'aplicació i les API del proveïdor. L'aplicació envia una intenció d'esquema. La passarel·la mapeja aquesta intenció amb el mecanisme de proveïdor compatible més fort.

1. Accepteu una sol·licitud normalitzada de l'aplicació

El client no hauria de necessitar camins de codi separats per a cada proveïdor. Un sobre de sol·licitud pràctic inclou la preferència del model, l'entrada de la tasca, l'esquema, les metadades de l'esquema i el nivell de risc:

{
  "model": "auto:precís",
  "missatges": [
    {"role": "system", "content": "Extreu els camps de la factura. No deduïu els valors que falten."},
    {"role": "usuari", "content": "Text de la factura..."}
  ],
  "sortida_estructurada": {
    "schema_id": "extracció_factura",
    "schema_version": "2026-08-01",
    "mode": "json_schema",
    "estricte": cert,
    "esquema": {
      "type": "objecte",
      "additionalProperties": fals,
      "required": ["invoice_number", "vendor_name", "total", "currency", "due_date"],
      "propietats": {
        "invoice_number": {"tipus": "cadena"},
        "vendor_name": {"tipus": "cadena"},
        "total": {"tipus": "nombre", "mínim": 0},
        "currency": {"type": "cadena", "enum": ["USD", "EUR", "GBP"]},
        "due_date": {"type": "cadena", "format": "data"},
        "confiança": {"tipus": "nombre", "mínim": 0, "màxim": 1}
      }
    }
  },
  "metadades": {
    "workflow": "comptes_pagables",
    "risk_level": "mitjà"
  }
}

Aquest contracte proporciona a la passarel·la informació suficient per triar una implementació nativa del proveïdor, executar la validació i registrar dades significatives d'errors.

2. Mantenir una matriu de capacitat del proveïdor

La passarel·la hauria de mantenir una matriu de capacitat llegible per màquina, no basar-se en supòsits com ara "tots els models compatibles amb OpenAI admeten el mateix comportament d'esquema". Una matriu útil inclou:

• Nom del proveïdor i del model.
• Admet el mode JSON.
• Admet el format de resposta de l'esquema JSON.
• Admet trucades d'eines.
• Admet el mode d'esquema estricte.
• Limitacions conegudes del subconjunt de l'esquema JSON.
• Si les trucades d'eines paral·leles són compatibles amb el mode d'esquema estricte.
• Comportament de reserva quan el mode sol·licitat no és compatible.

Exemple de registre de capacitat:

{
  "proveïdor": "proveïdor_a",
  "model": "model_x",
  "json_mode": cert,
  "json_schema_response": cert,
  "tool_calls": cert,
  "strict_schema": cert,
  "schema_limitations": ["no oneOf", "validació de format limitada"],
  "fallback": "reject_or_route_to_compatible_model"
}

Aquesta matriu s'hauria de versionar i provar. Quan un proveïdor canvia de comportament o s'afegeix un model nou, s'ha de verificar la compatibilitat de la sortida estructurada abans de l'encaminament de producció.

3. Traduïu al contracte natiu del proveïdor més sòlid

L'adaptador ha de seguir un ordre de preferències clar:

1. Utilitzeu sortides estructurades natives del proveïdor estrictes quan ho admeten el model i l'esquema seleccionats.
2. Utilitzeu l'eina nativa del proveïdor que demana accions i tasques semblants a funcions.
3. Utilitzeu una sortida estructurada no estricta o el mode JSON amb validació i reintents quan el mode estricte no estigui disponible.
4. Rebutja la sol·licitud, encamina a un model alternatiu compatible o retorna una resposta sense acció per a fluxos de treball d'alt risc.

No rebaixes silenciosament una operació d'alt risc del mode d'esquema estricte a "el millor esforç JSON". Si l'aplicació va sol·licitar un comportament estricte i el proveïdor seleccionat no l'admet, la passarel·la hauria de fer-ho visible mitjançant un error, una decisió d'encaminament o una marca explícita de baixada de nivell.

Tres capes de validació abans de l'execució

Capa 1: validació d'anàlisi

Primer, determineu si la resposta es pot analitzar al sobre esperat. Falla ràpidament en JSON amb format incorrecte, blocs de trucades d'eines que falten, respostes truncades o llenguatge natural i JSON barrejats quan el contracte ho prohibeix.

funció parseStructuredResponse(raw) {
  prova {
    retorn { ok: true, valor: JSON.parse(raw)};
  } captura (error) {
    retorn { ok: false, failure_type: "parse_failure", error: String (error) };
  }
}

És possible que les trucades d'eines natives del proveïdor no requereixin l'anàlisi d'un blob de text en brut, però encara requereixen la validació de l'embolcall: el model va seleccionar una eina coneguda, va proporcionar arguments i es va aturar per a l'execució de l'eina com s'esperava?

Capa 2: validació de l'esquema JSON

A continuació, valideu l'objecte amb l'esquema declarat mitjançant un validador del costat del servidor. Feu-ho fins i tot quan el proveïdor reclama un suport estricte d'esquemes. La validació de la passarel·la us ofereix un registre d'errors coherent, protegeix contra errors d'integració i detecta incompatibilitats aigües avall.

const validate = schemaValidator.compile(schema);
const valid = validar(objecte);
si (! vàlid) {
  tornar {
    d'acord: fals,
    failure_type: "error_esquema",
    errors: validar.errors
  };
}

Per a la portabilitat, dissenyeu esquemes tenint en compte el subconjunt comú:

• Preferiu tipus explícit, obligatori, propietats, enum i additionalProperties: false.
• Eviteu combinacions complexes com ara oneOf, anyOf i esquemes condicionals, tret que sàpigues que el proveïdor de destinació els admet.
• Mantingueu els arguments d'acció petits i concrets.
• Utilitzeu cadenes per als identificadors, les dates i els codis tret que els sistemes posteriors requereixin un altre tipus.
• Representeu la incertesa de manera explícita amb camps com ara confiança, missing_fields o requires_human_review.

Capa 3: validació semàntica i empresarial

Finalment, valideu si el resultat estructurat és correcte per a la tasca. Aquesta capa és específica del domini i no es pot subcontractar només a l'esquema JSON.

Per a l'extracció de factures, les comprovacions semàntiques poden incloure:

• El total no és negatiu i coincideix amb les línies de comanda dins de la tolerància.
• La moneda apareix al document d'origen.
• La data de venciment no és impossible en el passat o el futur.
• El venedor existeix en una llista de proveïdors aprovats.
• La confiança és prou alta per a l'entrada automàtica.

Per a la qualificació del client potencial, les comprovacions poden incloure:

• El segment seleccionat és un dels segments actius de l'equip de vendes.
• El pressupost sol·licitat no s'inventa quan l'usuari no n'ha proporcionat.
• No s'executa una acció "demo del llibre" tret que l'usuari ho sol·liciti explícitament.

Per a l'automatització de l'API de partners, les comprovacions poden incloure:

• El compte del distribuïdor està autoritzat a crear el client o la clau sol·licitats.
• El límit de despesa sol·licitat està dins de la política de partners.
• L'operació té una clau d'idempotència.
• L'acció s'enregistra en un registre d'auditoria abans de l'execució.

Cricades d'eines: tracteu la sortida del model com una sol·licitud, no com una execució

La trucada a l'eina és el patró adequat quan el model ha de demanar a l'aplicació que faci alguna cosa: crear un bitllet, enviar una ordre de bot de Telegram, buscar preus, actualitzar un registre de client o iniciar un flux de treball.

Un bucle d'eina segur té aquest aspecte:

1. L'aplicació declara les eines disponibles i els seus esquemes d'entrada.
2. El model retorna una crida d'eina amb arguments estructurats.
3. La passarel·la valida el nom i els arguments de l'eina.
4. L'aplicació comprova els requisits d'autorització, política, idempotència i confirmació de l'usuari.
5. Només llavors l'aplicació executa l'eina.
6. El resultat de l'eina es torna a enviar al model si la conversa ha de continuar.

No tracteu mai una crida d'eina com una prova que l'acció hauria de passar. Tracta-ho com una proposta estructurada. L'aplicació continua sent l'autoritat per als efectes secundaris.

Escala alternativa segura per a fluxos de treball multimodel

Una passarel·la hauria de definir un comportament alternatiu abans que es produeixin incidents. Una escala pràctica és:

1. Primària: sortida estructurada estricta del model preferit.
2. Recurs alternatiu compatible: un altre model que admet els mateixos requisits estrictes d'esquema.
3. Validació i reintent: un proveïdor sense suport estricte, que només s'utilitza quan el risc ho permet.
4. Revisió humana: poseu a la cua el resultat estructurat i el contingut d'origen per a l'aprovació.
5. Resposta sense acció: expliqueu que el sistema no pot completar l'operació de manera segura.

Els reintents són útils per a errors de format o d'esquema menors, però no són una estratègia de seguretat. Si l'objecte és semànticament insegur, les sol·licituds repetides poden convertir un rebuig correcte en un objecte executable perillós. Per a les accions d'alt risc, preferiu la revisió o la negativa als intents repetits de forçar l'èxit.

Observabilitat: registre totes les decisions de sortida estructurada

Les fallades de sortida estructurada són senyals operatius. Registreu-los amb prou detalls per millorar l'encaminament, els esquemes i les indicacions sense exposar contingut sensible innecessari.

Camps recomanats:

• schema_id i schema_version.
• Proveïdor i model.
• Mode sol·licitat i mode real utilitzat.
• Estat d'error de l'anàlisi.
• Estat d'error de l'esquema i errors de validació.
• Motiu de la fallada de la validació semàntica.
• Recompte de proves.
• Latència.
• Ús i cost del testimoni.
• Estat de l'acció final: executada, posada a la cua, rebutjada o retornada a l'usuari.
• Equip, projecte, clau d'API o identificador del compte de soci, si escau.

Aquests registres admeten la depuració, l'anàlisi de costos, la comparació de proveïdors i el govern de l'API d'equip. També ajuden a respondre preguntes com ara: "Quina versió d'esquema provoca més intents?" i "Quin model alternatiu passa la sintaxi però falla la validació empresarial?"

Regles de versions d'esquemes

Els esquemes són interfícies de producció. Tracteu-los com contractes API.

• Inclou schema_id i schema_version a les metadades i registres de la sol·licitud.
• No canvieu en silenci els camps obligatoris per a les automatitzacions existents.
• Mantenir els esquemes antics disponibles mentre els clients migren.
• Afegiu nous camps opcionals abans de fer-los obligatoris.
• Prova els esquemes amb tots els proveïdors i models alternatius del grup d'encaminament.
• Anoteu quina versió d'esquema s'ha utilitzat per a cada acció amb efectes secundaris.

El control de versions esdevé especialment important per a les agències, els distribuïdors i l'automatització de l'API per a partners, on molts clients posteriors poden dependre d'un contracte estructurat estable.

Quan no s'ha d'executar un resultat estructurat

Feu servir una parada dura quan aparegui alguna de les condicions següents:

• La resposta no es pot analitzar.
• L'objecte falla la validació de l'esquema JSON.
• Un valor d'enum no és compatible o s'ha inventat.
• És impossible una quantitat, un preu, una data o una moneda.
• El resultat entra en conflicte amb la intenció declarada de l'usuari.
• El model expressa poca confiança o falten proves.
• La instrucció de l'usuari és ambigua.
• L'acció té efectes secundaris i no té confirmació.
• El compte, l'equip o la clau de l'API no estan autoritzats.
• La resposta del proveïdor inclou una negativa o una no resposta relacionada amb la seguretat.

Recomanacions versus prediccions

Recomanacions: utilitzeu sortides estructurades natives del proveïdor quan estiguin disponibles, valideu totes les respostes al costat de la passarel·la, preferiu les crides d'eines per a accions, mantingueu una matriu de capacitats, esquemes de versions i bloquegeu els efectes secundaris fins que passin les comprovacions semàntiques.

Prediccions: el suport del proveïdor per a les sortides estructurades és probable que sigui més fort i més coherent, però la portabilitat continuarà sent una preocupació per a la passarel·la perquè les famílies de models, els subconjunts d'esquemes i els bucles de trucada d'eines no seran idèntics de la nit al dia. Els equips que creen validació, observabilitat i versions d'esquemes ara estaran en una millor posició per adoptar noves funcions del proveïdor sense reescriure tots els fluxos de treball.

Llista de verificació d'implementació accionable

1. Definiu un format de sol·licitud de sortida estructurada normalitzada per a les vostres aplicacions.
2. Creeu una matriu de capacitat del proveïdor per a cada model del vostre grup d'encaminament.
3. Dissenyeu esquemes mitjançant un subconjunt d'esquemes JSON portàtil.
4. Tradueix les sol·licituds a mecanismes estrictes natius del proveïdor quan sigui compatible.
5. Valideu l'analització, la conformitat de l'esquema i la correcció empresarial després de la generació.
6. Utilitzeu les trucades d'eines per a operacions amb efectes secundaris.
7. Requereix autorització, idempotència i confirmació fora del model.
8. Registreu la versió de l'esquema, el proveïdor, els errors de validació, els reintents, la latència, el cost i l'estat de l'acció.
9. Definiu el comportament alternatiu segons el nivell de risc del flux de treball.
10. Mantingueu els esquemes antics disponibles fins que les automatitzacions dependents migrin.

L'objectiu pràctic no és que tots els models es comportin de la mateixa manera. Es tracta d'oferir als desenvolupadors d'aplicacions un contracte estable mentre la passarel·la gestiona les diferències dels proveïdors amb honestedat. Les sortides estructurades són una infraestructura necessària per a una automatització d'IA fiable, però el límit de producció és el validador i la capa de política que decideix si un objecte és segur d'utilitzar.

Lectura relacionada

• Autorització de claus de l'API i controls d'equip
• cost del testimoni de seguiment i latència per als reintents