Vytvorte vrstvu kompatibility rozhrania Responses API v bráne AI API

Neimplementujte /v1/responses preložením každej požiadavky do /v1/chat/completions a dúfajte, že tvar je dostatočne blízky. Tento adaptér môže vrátiť text, ale môže v tichosti stratiť časti, o ktoré sa vývojári zaujímajú: položky odpovedí, stav na strane servera, volania nástrojov, kontinuita uvažovania, udalosti životného cyklu streamu, sémantika zrušenia a pripisovanie použitia na úrovni položky.

Praktickým cieľom je vrstva kompatibility, ktorá považuje rozhranie Responses API za bohatší protokol. Ponechajte podporu dokončenia chatu pre existujúcich klientov, ale vytvorte odpovede ako svoj vlastný povrch brány s vlastným modelom stavu, normalizátorom toku, knihou volaní nástrojov, maticou schopností a záložnými pravidlami.

Čo je fakt, čo je politika a čo je predpoveď?

Fakty: OpenAI popisuje Responses API ako zjednocujúce funkcie, ktoré boli predtým rozdelené medzi dokončovania rozhovorov a asistentov, vrátane podpory nástrojov, ako je vyhľadávanie na webe, vyhľadávanie súborov a používanie počítača. Rozhranie API odhaľuje polia ako previous_response_id, streamovanie, výber nástrojov a vstavané nástroje. Dokumentácia k súprave SDK ukazuje, že previous_response_id môže zabezpečiť kontinuitu konverzácie, zatiaľ čo predchádzajúce pokyny sa neprenášajú automaticky a musia sa znova odoslať, keď majú stále platiť. Odkaz na streamovanie OpenAI zahŕňa odlišný životný cyklus odozvy a výstupné udalosti, a nie iba delty tokenov.

Odporúčania: Brána by mala zachovať túto sémantiku a nie ju predvolene sploštiť. Ak cieľový poskytovateľ nemôže podporovať požadované správanie, mal by odmietnuť alebo výslovne znížiť požiadavky na nižšiu verziu.

Predpoveď: Viac pracovných zaťažení agentov bude závisieť od štruktúry položky odpovede, trasovania vykonávania nástroja a kontextu uvažovania stavu. Brány, ktoré teraz modelujú tieto koncepty, bude jednoduchšie rozšíriť ako brány, ktoré považujú odpovede za kozmetický koncový bod.

Definujte samostatnú zmluvu o kompatibilite pre odpovede

Prvou chybou implementácie je predpoklad, že kompatibilita s OpenAI znamená jednu univerzálnu schému požiadavky a odpovede. V praxi by /v1/chat/completions a /v1/responses mali byť samostatné zmluvy o kompatibilite.

Ponechajte zdieľanú vrstvu overenia, fakturácie, kvóty a smerovania, ale oddeľte vrstvu protokolu:

• Plocha dokončenia rozhovoru: správy, voľby, delty, volania nástrojov vo formáte rozhovoru, staršie správanie klienta.
• Povrch odpovedí: vstupné položky, výstupné položky, ID odpovedí, referencie predchádzajúcich odpovedí, bohatšie udalosti nástroja, udalosti toku životného cyklu, polia súvisiace s úvahami a konečný stav odpovede.

Toto rozdelenie je dôležité pre testy zhody. Adaptér poskytovateľa, ktorý prejde testami četu, môže stále zlyhať v testoch odpovedí, pretože nedokáže zachovať previous_response_id, poradie položiek, štruktúru odmietnutia, metadáta hosteného nástroja ani názvy udalostí streamovania.

Zmluva o minimálnej kompatibilite by mala zodpovedať:

• Ktoré polia žiadosti sú prijaté, odmietnuté, transformované alebo ignorované?
• Ktoré typy položiek odpovede sú zachované?
• Ktoré typy nástrojov sú podporované podľa poskytovateľa a modelu?
• Môže poskytovateľ udržiavať stav konverzácie alebo ho musí udržiavať brána?
• Čo sa stane, keď sa požaduje store=false?
• Aké streamové udalosti sú zaručené?
• Ako sa zaznamenáva zrušenie, časový limit a čiastočné využitie?

Ak už máte bránu AI API, podporu odpovedí považujte za rozšírenie protokolu, nie za alias trasy.

Použite kanonický model položky odpovede

Rozhranie Responses API vracia viac ako jednu správu asistenta. Môže reprezentovať rôzne výstupné položky a udalosti. Vaša brána potrebuje interný kanonický model predtým, ako sa namapuje na akéhokoľvek poskytovateľa.

Praktická interná schéma položky môže začať takto:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-default",
  "poskytovateľ": "openai",
  "položky": [
    {
      "item_id": "item_1",
      "type": "text",
      "role": "asistent",
      "content": [{ "type": "output_text", "text": "..." }],
      "stav": "dokončené"
    },
    {
      "item_id": "item_2",
      "type": "volanie_funkcie",
      "call_id": "call_abc",
      "name": "lookup_order",
      "arguments_json": "{\"id_objednávky\":\"123\"}",
      "stav": "dokončené"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "tool_units": []
  },
  "stav": "dokončené"
}

Zahrňte typy položiek ešte predtým, ako ich každý poskytovateľ dokáže vyrobiť. Užitočné kategórie zahŕňajú:

• Textový výstup
• Odmietnutia
• Volania funkcií
• Výstupy funkcií odoslané aplikáciou
• Súhrny odôvodnení alebo metaúdaje súvisiace s odôvodnením, ak sú k dispozícii
• Odkazy na súbory
• Vyhľadávanie na webe, vyhľadávanie súborov, používanie počítača alebo iné udalosti hostených nástrojov
• Konečné využitie a metadáta fakturácie

Ide o to, aby ste používateľom nevystavili vlastnú schému. Ide o to, aby brána nevyhadzovala informácie skôr, ako ich môže auditovať, účtovať, streamovať, prehrávať alebo transformovať.

Vytvorenie štátnej účtovnej knihy vo vlastníctve brány

previous_response_id je pole, ktoré najviac odhaľuje rozdiel medzi bezstavovým chatovaním proxy a kompatibilitou odpovedí. Ak klient odkazuje na predchádzajúcu odpoveď, brána musí vedieť, čo toto ID znamená, či ho môže nájomca používať a či z neho môže poskytovateľ pokračovať.

Vytvorte knihu stavu kľúčovanú nájomníkom a ID odpovede:

{
  "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-...",
  "poskytovateľ": "openai",
  "store_mode": "poskytovateľ|brána|žiadna",
  "retention_policy": "standard|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": null
}

Dôležité pravidlo: neemulujte automaticky previous_response_id prehrávaním celej histórie rozhovoru, pokiaľ nájomca výslovne nepovolil toto uchovávanie a správanie nákladov. Opakované prehrávanie môže zvýšiť cenu tokenu, zmeniť postoj ochrany súkromia a zmeniť správanie modelu. Je bezpečnejšie vrátiť jasnú chybu schopnosti, než potichu odosielať uložený obsah konverzácie, ktorý aplikácia neočakávala, že si ho ponecháte alebo znova použijete.

Režimy riadenia stavu

• Stav poskytovateľa: Upstream poskytovateľ ukladá dostatok kontextu a brána mapuje ID odpovedí brány na ID odpovedí poskytovateľa.
• Stav brány: Brána ukladá potrebné predchádzajúce položky a ak je to povolené, rekonštruuje kontext.
• Žiadny stav: Žiadosť používa store=false alebo zásady nájomníka zakazujú uchovávanie. previous_response_id by mal byť odmietnutý, pokiaľ poskytovateľ nemôže vyhovieť žiadosti bez zachovania brány a pravidlá to umožňujú.

Pamätajte tiež, že klient bude možno musieť znova odoslať predchádzajúce pokyny, keď budú naďalej platiť. Brána by nemala vymýšľať skryté pokyny na kompenzáciu, pokiaľ toto správanie nie je súčasťou explicitnej politiky nájomníka.

Overte nástroje pred odoslaním

Odpovede robia používanie nástroja centrálnejším. Vrstva kompatibility by mala spracovať dve široké kategórie:

• Nástroje aplikácie: Definície funkcií dodané klientom, spustené mimo poskytovateľa modelu, s výstupmi odoslanými späť do rozhrania API.
• Nástroje hosteného poskytovateľa: vyhľadávanie na webe, vyhľadávanie súborov, používanie počítača, spúšťanie kódu, uzemnenie alebo podobné nástroje spúšťané poskytovateľom alebo infraštruktúrou riadenou bránou.

Pri vstupe overte schémy nástrojov pred smerovaním:

• Včas odmietnite neplatnú schému JSON.
• Vynútiť maximálnu veľkosť schémy a hĺbku vnorenia.
• Skontrolujte kompatibilitu názvov nástrojov s poskytovateľmi.
• Použite rozsahy nájomníka, kľúča, používateľa a prostredia.
• Vyžadovať schvaľovacie brány pre nástroje, ktoré zapisujú údaje, míňajú peniaze, pristupujú k citlivým systémom alebo volajú externé konektory.

Na volanie funkcie aplikácie vyžaduje stabilné ID volania. Model generuje volanie funkcie s call_id; aplikácia odošle výstup nástroja s odkazom na toto ID; brána zaznamenáva oboje v rovnakom slede. Bez tohto kľúča spojenia sa protokoly auditu a opakované pokusy stanú nejednoznačnými.

V prípade hostených nástrojov si rezervujte rozpočet pred odoslaním a následne urovnajte náklady. Hosťované nástroje môžu pridávať poplatky mimo bežného účtovania tokenov, preto pripojte knihu nástrojov k zjednotenej fakturácii rozhrania AI API namiesto toho, aby ste tieto náklady skrývali v rámci celkového počtu hovorov podľa modelu.

Normalizovať streamovanie ako udalosti, nie ako text tokenu

Proxy na čet sa často môže zbaviť delta tokenov preposielania. Brána odpovedí nemôže. Prúd má význam životného cyklu: odpoveď sa môže spustiť, výstupné položky sa môžu spustiť a dokončiť, text môže prísť v deltách, volania nástrojov sa môžu zostavovať postupne, použitie môže prísť na konci alebo počas prúdu a odpoveď môže zlyhať alebo byť zrušená.

Definujte schému udalosti brány a potom do nej namapujte každý stream poskytovateľa:

udalosť: response_started
údaje: { "response_id": "gw_resp_123", "status": "in_progress" }

udalosť: output_item_startedúdaje: { "item_id": "item_1", "type": "text" }

udalosť: text_delta
údaje: { "item_id": "item_1", "delta": "Dobrý deň" }

udalosť: tool_call_delta
údaje: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"objednávka" }

udalosť: use_delta
údaje: { "output_tokens": 12 }

udalosť: dokončená
údaje: { "response_id": "gw_resp_123", "usage": { ... } }

Odporúčané normalizované udalosti:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• usage_delta
• dokončené
• zrušené
• zlyhalo

Keď sa klient odpojí, propagujte zrušenie upstream, ak to poskytovateľ podporuje. Zaznamenajte stav čiastočnej odozvy v oboch smeroch. Ak poskytovateľ neskôr vráti konečné použitie prostredníctvom oneskoreného spätného volania alebo posledného bloku, zosúlaďte účtovnú knihu. Kompatibilita streamovania je rovnako o účtovníctve a životnom cykle ako o latencii.

Vytvorte maticu schopností poskytovateľa

Smerovanie viacerých modelov je užitočné iba vtedy, keď brána rozumie tomu, čo možno bezpečne smerovať. Pridajte do katalógu modelov funkcie špecifické pre odpovede:

{
  "model_alias": "agent-default",
  "trasy": [
    {
      "poskytovateľ": "openai",
      "model": "...",
      "supports_responses": pravda,
      "supports_previous_response_id": pravda,
      "supports_store_false": pravda,
      "supports_builtin_web_search": pravda,
      "supports_function_calling": pravda,
      "supports_stream_lifecycle_events": pravda,
      "supports_reasoning_context_continuity": pravda,
      "max_tool_schema_bytes": 65536
    },
    {
      "poskytovateľ": "poskytovateľ_b",
      "model": "...",
      "supports_responses": nepravda,
      "chat_adapter_available": pravda,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

Záložná reklama by mala počítať so stratou. Ak požiadavka vyžaduje vstavané vyhľadávanie na webe a záložný poskytovateľ ho nemôže vykonať, neodpovedajte ticho bez vyhľadávania. Ak požiadavka závisí od zachovaného kontextu uvažovania a záložná cesta ju nemôže zachovať, vráťte chybu schopnosti alebo odpoveď na prechod na nižšiu verziu, ktorú klient výslovne aktivoval.

Užitočná možnosť žiadosti je:

{
  "model": "agent-default",
  "input": "...",
  "fallback_policy": {
    "allow_lossy": nepravda,
    "allowed_losses": []
  }
}

V prípade menej citlivých prípadov použitia môžu nájomníci povoliť konkrétne stratové nižšie verzie:

{
  "fallback_policy": {
    "allow_lossy": pravda,
    "allowed_losses": ["flattened_stream", "no_reasoning_summary"]
  }
}

Brána by mala zaznamenať záložné rozhodnutie v oboch smeroch. To umožňuje neskoršie ladenie, keď sa agent po výpadku poskytovateľa alebo presmerovaní modelu správa inak.

Použitie atribútov na úrovni odpovede a položky

Hovory s odpoveďami môžu stáť viac ako ekvivalentné dokončenia rozhovoru, pretože môžu zahŕňať spustenie nástroja, dlhší kontext, tokeny uvažovania, vyhľadávanie súborov, vyhľadávanie na webe alebo opakované pokyny. Jeden súhrnný počet tokenov nestačí pre hlavný panel analýzy používania AI API.

Zaznamenajte používanie na dvoch úrovniach:

• Úroveň odozvy: nájomník, kľúč, používateľ, model, poskytovateľ, latencia, konečný stav, vstupné tokeny, výstupné tokeny, zdôvodňovacie tokeny, ak sú nahlásené, celkové náklady a záložná trasa.
• Úroveň položky/nástroja: názov nástroja, ID volania, hostené jednotky nástroja, ID súborov, počet vyhľadávacích dopytov, ak je k dispozícii, latencia nástroja, cena nástroja a výsledok pravidiel schvaľovania.

To umožňuje vývojárom odpovedať na konkrétne otázky:

• Zvýšili sa náklady v dôsledku dlhšieho stavu, úsilia o uvažovanie, volaní nástrojov alebo núdzových opatrení?
• Ktorý nájomník alebo kľúč API generuje poplatky za hostený nástroj?
• Ktorá odpoveď zlyhala po vyvolaní nástroja, ale pred konečným textom?
• Ktoré zrušené streamy sa stále používajú na začiatku?

Zvládajte nulové uchovávanie a odstraňovanie ako prvotriedne správanie

Stav na strane servera je užitočný, mení však povinnosti brány uchovávať údaje. Zabudujte politiku do protokolovej vrstvy namiesto toho, aby ste ju považovali za nastavenie protokolovania.

Pre každú žiadosť o odpovede vyriešte:

• Pravidlá uchovávania nájomníkov
• Predvoľba obchodu na úrovni požiadavky
• Kompatibilita uchovávania poskytovateľa
• Či je povolené opätovné prehrávanie brány
• Či možno ukladať vstupy a výstupy nástroja
• Správanie pri vypršaní platnosti a odstraňovaní pre stav odpovede

Ak je uchovávanie vypnuté, brána môže aj tak uchovávať minimálne prevádzkové metadáta: časové pečiatky, identifikátory, stav, počty tokenov, náklady a politické rozhodnutia. Vyhnite sa ukladaniu nespracovaných výziev, úplných výstupov nástrojov alebo rekonštruovanej histórie, pokiaľ to pravidlá nepovoľujú.

Zariadenia na prispôsobenie, ktoré sa majú pridať pred spustením

Nespoliehajte sa na manuálne testy šťastnej cesty. Pridajte príslušenstvo, ktoré overí správanie protokolu v rámci priamych trás OpenAI, trás prispôsobených poskytovateľom a záložných scenárov.

Minimálna testovacia sada

• Základná odpoveď: textová položka sa vráti so stabilným ID odpovede a použitím.
• Stav s viacerými otáčkami: druhá požiadavka odkazuje na previous_response_id; brána overuje vlastníctvo nájomcu a režim stavu.
• Opakované pokyny: overte, či vynechané pokyny nie sú v tichosti vynájdené bránou.
• Obojsmerné volanie funkcie: model vydáva ID hovoru; aplikácia odošle výstup; posledná odpoveď spája oba záznamy.
• Pravidlá pre hostený nástroj: neautorizovaný vstavaný nástroj je pred odoslaním zablokovaný.
• Poradie streamovania: začiatok odpovede, začiatok položky, delty, dokončenie položky, použitie a dokončenie sa odosielajú v platnom poradí.
• Zrušenie streamu: odpojenie klienta spustí zrušenie upstream, ak je to podporované, a zaznamená čiastočné využitie.
• Záložné odmietnutie: poskytovateľ bez požadovaných odpovedí vracia chybu schopnosti sémantiky.
• Aktivácia pri záložnej strate: žiadosť s povolenými stratami dostane explicitnú značku zníženia.
• Režim nulového uchovania: prehratie stavu a uchovanie výzvy na strane brány sú zablokované.

Odporúčaná postupnosť zavádzania

1. Prezrite si beta trasu. Pridajte /v1/responses bez zmeny existujúceho správania četu.
2. Najskôr implementujte prechod pre poskytovateľov s podporou natívnych odpovedí. Zachovajte ID, položky, streamy, použitie a chyby.
3. Pridajte knihu stavu. Mapujte ID brán na ID poskytovateľov a vynucujte vlastníctvo nájomníkov.
4. Pridajte kanonické položky. Uložte metadáta položky potrebné na auditovanie, fakturáciu a rekonštrukciu streamu.
5. Pridajte správu nástrojov. Overte schémy, presadzujte rozsahy a zaznamenávajte spojenia volaní nástroja.
6. Pridajte normalizáciu streamovania. Premeňte streamy špecifické pre poskytovateľa na udalosti životného cyklu brány.
7. Pridajte smerovanie s ohľadom na možnosti. V predvolenom nastavení povoľte iba bezpečné záložné reklamy.
8. Pridajte analýzy a zúčtovanie fakturácie. Token, odôvodnenie a použitie nástroja priraďte oddelene.
9. Zverejnite poznámky o kompatibilite. Povedzte vývojárom, ktoré polia sú natívne, emulované, nepodporované alebo stratové.

Uplatniteľný záver

Vrstva kompatibility s rozhraním Responses API by mala zachovať význam protokolu, nielen vrátiť vierohodný text. Postavte ho na piatich odolných objektoch: model kanonickej položky odpovede, kniha stavu konverzácie, kniha volaní nástrojov, normalizátor udalostí streamovania a matica schopností poskytovateľa.

Najbezpečnejšou predvolenou hodnotou je prísna kompatibilita: ak trasa nedokáže zachovať požadovaný stav, nástroje, kontext uvažovania, udalosti streamu alebo správanie pri uchovávaní, vráti jasnú chybu schopnosti. Stratovú zálohu pridajte iba vtedy, keď vývojári pochopia, čo bude zrušené. Tento prístup sa môže zdať menej pohodlný ako automatické sploštenie, ale zabraňuje najhoršiemu režimu zlyhania: aplikácia, ktorá sa javí ako kompatibilná, pričom v tichosti stráca sémantiku, ktorá ju prinútila používať rozhranie Responses API na prvom mieste.

Súvisiace čítanie

• handling