Creeu una capa de compatibilitat de l'API de respostes en una passarel·la de l'API d'IA

No implementeu /v1/responses traduint totes les sol·licituds a /v1/chat/completions i esperant que la forma estigui prou a prop. Aquest adaptador pot retornar text, però pot perdre silenciosament les parts que importen als desenvolupadors: elements de resposta, estat del servidor, trucades d'eines, continuïtat del raonament, esdeveniments del cicle de vida del flux, semàntica de cancel·lació i atribució d'ús a nivell d'element.

L'objectiu pràctic és una capa de compatibilitat que tracti l'API de Respostes com un protocol més ric. Manteniu la compatibilitat amb les finalitzacions de xat per als clients existents, però creeu Respostes com la seva pròpia superfície de passarel·la amb el seu propi model d'estat, normalitzador de fluxos, registre de trucades d'eines, matriu de capacitats i regles alternatives.

Què és fet, què és política i què és predicció?

Fets: OpenAI descriu l'API de Respostes com a capacitats d'unificació que anteriorment estaven dividides entre les finalitzacions de xat i els assistents, inclosa la compatibilitat amb eines com ara la cerca web, la cerca de fitxers i l'ús de l'ordinador. L'API exposa camps com ara previous_response_id, streaming, selecció d'eines i eines integrades. La documentació de l'SDK mostra que previous_response_id pot proporcionar continuïtat a la conversa, mentre que les instruccions anteriors no es traslladen automàticament i s'han de tornar a enviar quan encara s'hagin d'aplicar. La referència de transmissió en temps real d'OpenAI inclou un cicle de vida de resposta i esdeveniments de sortida diferents en lloc de només deltas de testimoni.

Recomanacions: una passarel·la hauria de preservar aquesta semàntica en lloc d'aplanar-les de manera predeterminada. Hauria de rebutjar o rebaixar explícitament les sol·licituds quan un proveïdor de destinació no admet el comportament requerit.

Predicció: més càrregues de treball d'agent dependran de l'estructura de l'element de resposta, les traces d'execució de l'eina i el context de raonament amb estat. Les passarel·les que modelin aquests conceptes ara seran més fàcils d'ampliar que les passarel·les que tracten les respostes com un punt final estètic.

Definiu un contracte de compatibilitat independent per a les Respostes

El primer error d'implementació és suposar que compatible amb OpenAI significa un esquema de sol·licitud i resposta universal. A la pràctica, /v1/chat/completions i /v1/responses haurien de ser contractes de compatibilitat separats.

Conserveu una capa d'autenticació, facturació, quota i encaminament compartida, però separeu la capa de protocol:

• Apareixen les finalitzacions del xat: missatges, opcions, deltes, trucades a eines en format de xat, comportament del client heretat.
• Apareixen les respostes: elements d'entrada, elements de sortida, identificadors de resposta, referències de respostes anteriors, esdeveniments d'eines més rics, esdeveniments de flux de cicle de vida, camps relacionats amb el raonament i estat de resposta final.

Aquesta divisió és important per a les proves de conformitat. Un adaptador de proveïdor que superi les proves de xat encara pot fallar les proves de Respostes perquè no pot conservar l'previous_response_id, la comanda d'elements, l'estructura de denegació, les metadades de l'eina allotjada o els noms d'esdeveniments en temps real.

Un contracte de compatibilitat mínima hauria de respondre:

• Quins camps de sol·licitud s'accepten, es rebutgen, es transformen o s'ignoren?
• Quins tipus d'elements de resposta es conserven?
• Quins tipus d'eines s'admeten per proveïdor i model?
• El proveïdor pot mantenir l'estat de la conversa o l'ha de mantenir la passarel·la?
• Què passa quan es demana store=false?
• Quins esdeveniments de reproducció estan garantits?
• Com es registren la cancel·lació, el temps d'espera i l'ús parcial?

Si ja teniu una porta d'enllaç API AI, tracteu el suport de Respostes com una expansió de protocol, no com un àlies de ruta.

Utilitza un model d'elements de resposta canònic

L'API Responses retorna més d'un missatge d'assistent. Pot representar diferents elements de sortida i esdeveniments. La vostra passarel·la necessita un model canònic intern abans que s'assigni a qualsevol proveïdor.

Un esquema d'element intern pràctic pot començar així:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-predeterminat",
  "proveïdor": "openai",
  "articles": [
    {
      "item_id": "element_1",
      "type": "text",
      "rol": "assistent",
      "contingut": [{ "type": "output_text", "text": "..." }],
      "status": "completat"
    },
    {
      "item_id": "element_2",
      "type": "function_call",
      "call_id": "call_abc",
      "nom": "ordre_de_cerca",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "completat"
    }
  ],
  "ús": {
    "input_tokens": 0,
    "output_tokens": 0,
    "resoning_tokens": nul,
    "unitats_eines": []
  },
  "status": "completat"
}

Inclou els tipus d'article fins i tot abans que cada proveïdor els pugui produir. Les categories útils inclouen:

• Sortie de text
• Denegacions
• Trucades de funció
• Sortides de funcions enviades per l'aplicació
• Resums de raonament o metadades relacionades amb el raonament quan estiguin disponibles
• Referències de fitxers
• Cerca web, cerca de fitxers, ús d'ordinadors o altres esdeveniments d'eines allotjades
• Metadades finals d'ús i facturació

La qüestió no és exposar un esquema propietari als usuaris. La qüestió és evitar que la passarel·la tiri informació abans que pugui auditar-la, facturar-la, reproduir-la o transformar-la.

Creeu un registre estatal propietat de la passarel·la

previous_response_id és el camp que més exposa la diferència entre el proxy de xat sense estat i la compatibilitat de Respostes. Si un client fa referència a una resposta anterior, la passarel·la ha de saber què significa aquest identificador, si l'inquilí pot utilitzar-lo i si el proveïdor pot continuar des d'ella.

Creeu un registre d'estat amb clau per l'inquilí i l'identificador de resposta:

{
  "gateway_response_id": "gw_resp_789",
  "provider_response_id": "resp_provider_789",
  "previous_gateway_response_id": "gw_resp_456",
  "tenant_id": "ten_123",
  "user_id": "user_999",
  "key_id": "key_456",
  "model": "gpt-...",
  "proveïdor": "openai",
  "store_mode": "proveïdor|gateway|cap",
  "retention_policy": "estàndard|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": nul
}

Regla important: no emuleu automàticament previous_response_id reproduint l'historial de xat complet tret que l'arrendatari hagi permès explícitament aquest comportament de retenció i cost. La reproducció pot augmentar el cost del token, canviar la postura de privadesa i alterar el comportament del model. És més segur retornar un error de capacitat clar que enviar silenciosament contingut de conversa emmagatzemat que l'aplicació no esperava que retés o reutilitzeu.

Modes de gestió de l'estat

• Estat del proveïdor: el proveïdor aigües amunt emmagatzema suficient context i la passarel·la mapeja els ID de resposta de la passarel·la als ID de resposta del proveïdor.
• Estat de la passarel·la: la passarel·la emmagatzema els elements previs necessaris i reconstrueix el context quan ho permet.
• Sense estat: la sol·licitud utilitza store=false o la política d'inquilí prohibeix la retenció. previous_response_id s'ha de rebutjar tret que el proveïdor pugui atendre la sol·licitud sense retenció de passarel·la i la política ho permeti.

També recordeu que és possible que el client hagi de tornar a enviar instruccions anteriors quan s'hagi de continuar aplicant. La passarel·la no hauria d'inventar instruccions amagades per compensar, tret que aquest comportament formi part d'una política explícita d'inquilí.

Valida les eines abans de l'enviament

Les respostes fan que l'ús de l'eina sigui més central. Una capa de compatibilitat hauria de gestionar dues categories àmplies:

• Eines d'aplicació: definicions de funcions subministrades pel client, executades fora del proveïdor del model, amb resultats enviats de nou a l'API.
• Eines del proveïdor allotjat: cerca web, cerca de fitxers, ús de l'ordinador, execució de codi, connexió a terra o eines similars executades pel proveïdor o la infraestructura controlada per passarel·la.

En entrar, valideu els esquemes d'eines abans d'enrutar:

• Rebutja abans l'esquema JSON no vàlid.
• Aplica la mida màxima de l'esquema i la profunditat d'imbricació.
• Comproveu els noms d'eines per a la compatibilitat dels proveïdors.
• Aplica àmbits d'inquilí, clau, usuari i entorn.
• Requereix portes d'aprovació per a eines que escriuen dades, gasten diners, accedeixen a sistemes sensibles o truquen a connectors externs.

Per trucar a la funció de l'aplicació, cal un identificador de trucada estable. El model emet una crida de funció amb call_id; l'aplicació envia la sortida de l'eina que fa referència a aquest identificador; la passarel·la enregistra tots dos en el mateix rastre. Sense aquesta clau d'unió, els registres d'auditoria i els reintents es tornen ambigus.

Per a les eines allotjades, reserveu el pressupost abans de l'enviament i liquideu el cost després. Les eines allotjades poden afegir càrrecs fora de la comptabilitat de testimonis ordinària, així que connecteu el llibre major d'eines a la facturació unificada de l'API AI en lloc d'amagar aquests costos dins d'un total de trucades de model genèric.

Normalitza la transmissió com a esdeveniments, no com a text de testimoni

Sovint, un servidor intermediari de xat pot sortir-se amb la seva delta de testimoni de reenviament. Una passarel·la de Respostes no pot. El flux té un significat de cicle de vida: pot començar una resposta, els elements de sortida poden començar i completar-se, el text pot arribar en deltes, les trucades d'eines es poden muntar de manera incremental, l'ús pot arribar al final o durant el flux i la resposta pot fallar o cancel·lar-se.

Definiu un esquema d'esdeveniments de passarel·la i, a continuació, assigneu-hi cada flux de proveïdors:

esdeveniment: response_started
dades: { "response_id": "gw_resp_123", "estat": "en curs" }

esdeveniment: output_item_starteddades: { "item_id": "item_1", "type": "text" }

esdeveniment: text_delta
dades: { "item_id": "item_1", "delta": "Hola" }

esdeveniment: tool_call_delta
dades: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

esdeveniment: usage_delta
dades: { "output_tokens": 12 }

esdeveniment: finalitzat
dades: { "response_id": "gw_resp_123", "ús": { ... } }

Esdeveniments normalitzats recomanats:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• usage_delta
• completat
• cancel·lat
• error

Quan el client es desconnecti, propaga la cancel·lació aigües amunt si el proveïdor ho admet. Enregistreu l'estat de resposta parcial de qualsevol manera. Si el proveïdor retorna més tard l'ús final mitjançant una devolució de trucada retardada o un tros final, concilieu el llibre major. La compatibilitat de reproducció en temps real és tant sobre la comptabilitat i el cicle de vida com sobre la latència.

Creeu una matriu de capacitat del proveïdor

L'encaminament multimodel només és útil quan la passarel·la entén què es pot encaminar de manera segura. Afegiu capacitats específiques de Respostes al vostre catàleg de models:

{
  "model_alias": "agent-predeterminat",
  "rutes": [
    {
      "proveïdor": "openai",
      "model": "...",
      "supports_responses": cert,
      "supports_previous_response_id": cert,
      "supports_store_false": cert,
      "supports_builtin_web_search": cert,
      "supports_function_calling": cert,
      "supports_stream_lifecycle_events": cert,
      "supports_reasoning_context_continuity": cert,
      "max_tool_schema_bytes": 65536
    },
    {
      "proveïdor": "proveïdor_b",
      "model": "...",
      "supports_responses": fals,
      "chat_adapter_available": cert,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

La alternativa hauria de ser conscient de les pèrdues. Si la sol·licitud requereix una cerca web integrada i el proveïdor de reserva no la pot dur a terme, no respongueu en silenci sense cercar. Si la sol·licitud depèn del context de raonament conservat i la ruta alternativa no la pot conservar, retorneu un error de capacitat o una resposta de rebaixa que el client ha optat explícitament.

Una opció de sol·licitud útil és:

{
  "model": "agent-predeterminat",
  "entrada": "...",
  "política_de_fallback": {
    "allow_loss": fals,
    "pèrdues_permeses": []
  }
}

Per als casos d'ús menys sensibles, els llogaters poden permetre rebaixes específiques amb pèrdues:

{
  "política_de_fallback": {
    "allow_loss": cert,
    "allowed_losses": ["flattened_stream", "no_reasoning_summary"]
  }
}

La passarel·la hauria de registrar la decisió alternativa de qualsevol manera. Això fa possible la depuració posterior quan un agent es comporta de manera diferent després d'una interrupció del proveïdor o una reorientació del model.

Ús d'atributs a nivell de resposta i element

Les trucades de respostes poden costar més que les finalitzacions de xat equivalents perquè poden incloure execució d'eines, context més llarg, fitxes de raonament, cerca de fitxers, cerca web o instruccions repetides. Un únic recompte de testimonis agregat no és suficient per a un tauler d'anàlisi d'ús de l'API AI.

Registreu l'ús a dos nivells:

• Nivell de resposta: llogater, clau, usuari, model, proveïdor, latència, estat final, testimonis d'entrada, testimonis de sortida, testimonis de raonament on s'ha informat, cost total i ruta alternativa.
• Nivell d'element/eina: nom de l'eina, identificador de trucada, unitats d'eines allotjades, identificadors de fitxers, nombre de consultes de cerca si està disponible, latència de l'eina, cost de l'eina i resultat de la política d'aprovació.

Això permet als desenvolupadors respondre preguntes concretes:

• Va augmentar el cost a causa d'un estat més llarg, d'un esforç de raonament, de trucades d'eines o d'una alternativa?
• Quin inquilí o clau d'API genera càrrecs per l'eina allotjada?
• Quina resposta ha fallat després d'una trucada a l'eina però abans del text final?
• Quines reproduccions cancel·lades encara s'han fet servir aigües amunt?

Gestioneu la retenció i la supressió zero com a comportament de primera classe

L'estat del servidor és útil, però canvia les obligacions de retenció de la passarel·la. Creeu una política a la capa de protocol en lloc de tractar-la com una configuració de registre.

Per a cada sol·licitud de Respostes, resol:

• Política de retenció de llogaters
• Preferència de emmagatzema a nivell de sol·licitud
• Compatibilitat amb la retenció de proveïdors
• Si es permet la reproducció de passarel·la
• Si es poden emmagatzemar les entrades i sortides de l'eina
• Comportament de caducitat i supressió de l'estat de resposta

Si la retenció està desactivada, és possible que la passarel·la mantingui metadades operatives mínimes: segells de temps, identificadors, estat, recomptes de testimonis, cost i decisions polítiques. Eviteu emmagatzemar les indicacions en brut, les sortides completes de les eines o l'historial reconstruït tret que la política ho permeti.

Accesos de conformitat per afegir abans del llançament

No confieu en proves manuals de Happy-path. Afegiu accessoris que verifiquen el comportament del protocol a les rutes directes d'OpenAI, les rutes adaptades al proveïdor i els escenaris de reserva.

Conjunt de proves mínim

• Resposta bàsica: l'element de text es retorna amb un identificador de resposta i un ús estables.
• Estat de múltiples girs: la segona sol·licitud fa referència a previous_response_id; La passarel·la valida la propietat de l'inquilí i el mode d'estat.
• Instruccions repetides: comproveu que les instruccions omeses no les inventa silenciosament la passarel·la.
• Funció de trucada d'anada i tornada: el model emet l'identificador de trucada; l'aplicació envia sortida; la resposta final uneix els dos registres.
• Política d'eines allotjades: l'eina integrada no autoritzada està bloquejada abans de l'enviament.
• Ordre de reproducció en temps real: l'inici de la resposta, l'inici de l'element, els deltas, la finalització de l'element, l'ús i la finalització s'emeten en un ordre vàlid.
• Cancel·lació de la seqüència de dades: la desconnexió del client activa la cancel·lació amunt quan s'admet i registra l'ús parcial.
• Rebuig de reserva: el proveïdor sense la semàntica de Respostes requerida retorna un error de capacitat.
• Activació de reserva amb pèrdues: la sol·licitud amb pèrdues permeses rep un marcador explícit de rebaixa.
• Mode de retenció zero: la reproducció de l'estat i la retenció de sol·licituds a la passarel·la estan bloquejades.

Seqüència de llançament recomanada

1. Exposa una ruta beta. Afegeix /v1/responses sense canviar el comportament del xat existent.
2. Primer implementeu la transmissió per als proveïdors amb compatibilitat nativa de Respostes. Preserveu els identificadors, els elements, els fluxos, l'ús i els errors.
3. Afegiu el registre estatal. Assigna els identificadors de passarel·la als identificadors de proveïdors i imposa la propietat de l'inquilí.
4. Afegiu elements canònics. Emmagatzemeu les metadades d'elements necessàries per a l'auditoria, la facturació i la reconstrucció del flux.
5. Afegiu govern d'eines. Valideu esquemes, apliqueu àmbits i registreu les unions de trucades d'eines.
6. Afegiu la normalització de la transmissió. Convertiu els fluxos específics del proveïdor en esdeveniments del cicle de vida de la passarel·la.
7. Afegiu un encaminament conscient de la capacitat. Per defecte, només permeteu les alternatives segures.
8. Afegiu analítiques i liquidació de facturació. Atribuïu el testimoni, el raonament i l'ús de l'eina per separat.
9. Publica notes de compatibilitat. Digues als desenvolupadors quins camps són natius, emulats, no compatibles o amb pèrdua.

Conclusió accionable

Una capa de compatibilitat de l'API de Responses hauria de conservar el significat del protocol, no només retornar un text plausible. Creeu-lo al voltant de cinc objectes duradors: un model d'elements de resposta canònic, un registre d'estat de conversa, un registre de trucades d'eines, un normalitzador d'esdeveniments en temps real i una matriu de capacitat del proveïdor.

El valor predeterminat més segur és la compatibilitat estricta: si una ruta no pot conservar l'estat requerit, les eines, el context de raonament, els esdeveniments de transmissió o el comportament de retenció, retorneu un error de capacitat clar. Afegiu una alternativa amb pèrdua d'activació només quan els desenvolupadors entenguin què es deixarà. Aquest enfocament pot semblar menys convenient que l'aplanament automàtic, però evita el pitjor mode de fallada: una aplicació que sembla compatible mentre perd en silenci la semàntica que va fer que utilitzés l'API de Respostes en primer lloc.

Lectura relacionada