Vytvořte vrstvu kompatibility rozhraní Responses API v bráně AI API

Neimplementujte /v1/responses tak, že překládáte každý požadavek do /v1/chat/completions a doufáte, že je tvar dostatečně blízko. Tento adaptér může vrátit text, ale může v tichosti ztratit části, o které se vývojáři starají: položky odpovědí, stav na straně serveru, volání nástrojů, kontinuita uvažování, události životního cyklu streamu, sémantika zrušení a přiřazení použití na úrovni položky.

Praktickým cílem je vrstva kompatibility, která zachází s odpověďmi API jako s bohatším protokolem. Udržujte podporu dokončování chatu pro stávající klienty, ale sestavujte odpovědi jako vlastní povrch brány s vlastním modelem stavu, normalizátorem proudu, knihou volání nástrojů, maticí schopností a nouzovými pravidly.

Co je fakt, co je zásada a co je předpověď?

Fakta: OpenAI popisuje odpovědi API jako sjednocující funkce, které byly dříve rozděleny mezi dokončování chatu a asistenty, včetně podpory nástrojů, jako je vyhledávání na webu, vyhledávání souborů a používání počítače. API odhaluje pole jako previous_response_id, streamování, výběr nástrojů a vestavěné nástroje. Dokumentace SDK ukazuje, že previous_response_id může zajistit kontinuitu konverzace, zatímco předchozí pokyny se automaticky nepřenášejí a musí být znovu odeslány, pokud by měly stále platit. Reference OpenAI o streamování zahrnuje odlišný životní cyklus odezvy a výstupní události, nikoli pouze delty tokenů.

Doporučení: Brána by měla tuto sémantiku zachovat, nikoli ji ve výchozím nastavení sloučit. Pokud cílový poskytovatel nemůže podporovat požadované chování, měl by odmítnout nebo výslovně snížit požadavky na nižší verzi.

Predikce: Větší pracovní zatížení agentů bude záviset na struktuře položky odezvy, trasování provádění nástroje a kontextu stavového uvažování. Brány, které tyto koncepty modelují, se nyní budou snadněji rozšiřovat než brány, které považují odpovědi za kosmetický koncový bod.

Definujte samostatnou smlouvu o kompatibilitě pro odpovědi

První chybou implementace je předpoklad, že OpenAI-kompatibilní znamená jedno univerzální schéma požadavku a odpovědi. V praxi by /v1/chat/completions a /v1/responses měly být samostatné smlouvy o kompatibilitě.

Zachovat sdílenou vrstvu ověřování, fakturace, kvóty a směrování, ale oddělit vrstvu protokolu:

• Povrch dokončení chatu: zprávy, volby, delty, volání nástrojů ve formátu chatu, chování starších klientů.
• Povrch odpovědí: vstupní položky, výstupní položky, ID odpovědí, odkazy na předchozí odpovědi, bohatší události nástroje, události streamu životního cyklu, pole související s uvažováním a konečný stav odpovědi.

Toto rozdělení je důležité pro testy shody. Adaptér poskytovatele, který projde testy chatu, může stále selhat v testech odpovědí, protože nedokáže zachovat previous_response_id, řazení položek, strukturu odmítnutí, metadata hostovaného nástroje ani názvy událostí streamování.

Smlouva o minimální kompatibilitě by měla odpovídat:

• Která pole požadavku jsou přijata, zamítnuta, transformována nebo ignorována?
• Které typy položek odpovědí jsou zachovány?
• Jaké typy nástrojů jsou podporovány podle poskytovatele a modelu?
• Může poskytovatel udržovat stav konverzace, nebo jej musí udržovat brána?
• Co se stane, když je požadováno store=false?
• Jaké streamované události jsou zaručeny?
• Jak se zaznamenává zrušení, časový limit a částečné využití?

Pokud již máte bránu AI API, považujte podporu odpovědí za rozšíření protokolu, nikoli za alias trasy.

Použít kanonický model položky odpovědi

Odpovědi API vrací více než jednu zprávu asistenta. Může představovat různé výstupní položky a události. Vaše brána potřebuje interní kanonický model, než se namapuje na jakéhokoli poskytovatele.

Praktické interní schéma položky může začít takto:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-default",
  "provider": "openai",
  "items": [
    {
      "item_id": "item_1",
      "type": "text",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "..." }],
      "status": "completed"
    },
    {
      "item_id": "item_2",
      "type": "function_call",
      "call_id": "call_abc",
      "name": "lookup_order",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "tool_units": []
  },
  "status": "completed"
}

Zahrňte typy položek ještě předtím, než je každý poskytovatel dokáže vyrobit. Mezi užitečné kategorie patří:

• Textový výstup
• Odmítnutí
• Volání funkcí
• Výstupy funkcí odeslané aplikací
• Souhrny odůvodnění nebo metadata související s odůvodněním, pokud jsou k dispozici
• Odkazy na soubory
• Vyhledávání na webu, vyhledávání souborů, použití počítače nebo jiné události hostovaných nástrojů
• Konečné využití a metadata fakturace

Jde o to, abyste uživatelům nevystavovali proprietární schéma. Jde o to, aby brána nevyhazovala informace dříve, než je může auditovat, účtovat, streamovat, přehrát nebo transformovat.

Vybudujte si státní knihu ve vlastnictví brány

previous_response_id je pole, které nejvíce odhaluje rozdíl mezi bezstavovým chatováním proxy a kompatibilitou odpovědí. Pokud klient odkazuje na předchozí odpověď, brána musí vědět, co toto ID znamená, zda jej tenant smí používat a zda z něj může poskytovatel pokračovat.

Vytvořte knihu stavu zadanou tenantem a ID odpovědi:

{
  "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-...",
  "provider": "openai",
  "store_mode": "provider|gateway|none",
  "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: Nenapodobujte automaticky previous_response_id přehráním celé historie chatu, pokud nájemce výslovně nepovolil toto uchování a chování nákladů. Opakované přehrávání může zvýšit cenu tokenu, změnit postoj ochrany soukromí a změnit chování modelu. Je bezpečnější vrátit jasnou chybu schopnosti, než potichu odeslat uložený obsah konverzace, u kterého aplikace neočekávala, že si jej ponecháte nebo znovu použijete.

Režimy zpracování stavu

• Stav poskytovatele: Upstreamový poskytovatel ukládá dostatek kontextu a brána mapuje ID odpovědí brány na ID odpovědí poskytovatele.
• Stav brány: Brána ukládá nezbytné předchozí položky a rekonstruuje kontext, je-li to povoleno.
• Žádný stav: Požadavek používá store=false nebo zásady tenanta zakazují uchování. previous_response_id by měl být odmítnut, pokud poskytovatel nemůže vyhovět požadavku bez zachování brány a zásady to umožňují.

Mějte také na paměti, že pokud by měly nadále platit, může být nutné, aby klient znovu poslal předchozí pokyny. Brána by neměla vymýšlet skryté pokyny k kompenzaci, pokud toto chování není součástí explicitních zásad pro nájemce.

Ověřit nástroje před odesláním

Responses činí používání nástroje centrálnějším. Vrstva kompatibility by měla zpracovávat dvě široké kategorie:

• Aplikační nástroje: Definice funkcí dodané klientem, spouštěné mimo poskytovatele modelu, s výstupy odeslanými zpět do API.
• Nástroje hostovaného poskytovatele: Vyhledávání na webu, vyhledávání souborů, používání počítače, spouštění kódu, uzemnění nebo podobné nástroje spouštěné poskytovatelem nebo infrastrukturou řízenou bránou.

Při vstupu ověřte schémata nástroje před směrováním:

• Odmítnout neplatné JSON schéma brzy.
• Vynutit maximální velikost schématu a hloubku vnoření.
• Zkontrolujte kompatibilitu názvů nástrojů.
• Použití rozsahů tenant, klíč, uživatel a prostředí.
• Vyžadovat schvalovací brány pro nástroje, které zapisují data, utrácejí peníze, přistupují k citlivým systémům nebo volají externí konektory.

Pro volání funkcí aplikace požadujte stabilní ID volání. Model generuje volání funkce s call_id; aplikace odešle výstup nástroje s odkazem na toto ID; brána zaznamená oba ve stejném trasování. Bez tohoto klíče spojení se protokoly auditu a opakované pokusy stanou nejednoznačnými.

U hostovaných nástrojů si rezervujte rozpočet před odesláním a náklady uhraďte až poté. Hostované nástroje mohou přidávat poplatky mimo běžné účtování tokenů, takže propojte knihu nástrojů s unified AI API billing místo toho, abyste tyto náklady skrývali v obecném součtu modelových hovorů.

Normalizovat streamování jako události, nikoli text tokenu

Proxy chatu často projde rozdílem tokenů pro přeposílání. Brána odpovědí nemůže. Stream má význam životního cyklu: odpověď se může spustit, výstupní položky se mohou spustit a dokončit, text může přicházet v deltách, volání nástrojů lze sestavit postupně, použití může dojít na konci nebo během streamu a odpověď může selhat nebo být zrušena.

Definujte schéma události brány a poté do něj namapujte každý stream poskytovatele:

event: response_started
data: { "response_id": "gw_resp_123", "status": "in_progress" }

event: output_item_started
data: { "item_id": "item_1", "type": "text" }

event: text_delta
data: { "item_id": "item_1", "delta": "Hello" }

event: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

event: usage_delta
data: { "output_tokens": 12 }

event: completed
data: { "response_id": "gw_resp_123", "usage": { ... } }

Doporučené normalizované události:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• usage_delta
• completed
• cancelled
• failed

Když se klient odpojí, propagujte zrušení upstream, pokud to poskytovatel podporuje. Zaznamenejte stav částečné odpovědi v obou směrech. Pokud poskytovatel později vrátí konečné využití prostřednictvím zpožděného zpětného volání nebo posledního bloku, srovnejte účetní knihu. Kompatibilita streamování je stejně tak o účetnictví a životním cyklu jako o latenci.

Vytvořit matici schopností poskytovatele

Směrování více modelů je užitečné pouze tehdy, když brána rozumí tomu, co lze bezpečně směrovat. Přidejte do katalogu modelů funkce specifické pro odpovědi:

{
  "model_alias": "agent-default",
  "routes": [
    {
      "provider": "openai",
      "model": "...",
      "supports_responses": true,
      "supports_previous_response_id": true,
      "supports_store_false": true,
      "supports_builtin_web_search": true,
      "supports_function_calling": true,
      "supports_stream_lifecycle_events": true,
      "supports_reasoning_context_continuity": true,
      "max_tool_schema_bytes": 65536
    },
    {
      "provider": "provider_b",
      "model": "...",
      "supports_responses": false,
      "chat_adapter_available": true,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

Záložní reklama by si měla být vědoma ztráty. Pokud požadavek vyžaduje vestavěné vyhledávání na webu a záložní poskytovatel jej nemůže provést, neodpovídejte tiše bez hledání. Pokud požadavek závisí na uchovaném kontextu uvažování a záložní trasa jej nemůže zachovat, vraťte chybu schopnosti nebo odpověď na downgrade, ke které se klient výslovně přihlásil.

Užitečnou možností požadavku je:

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

Pro méně citlivé případy použití mohou nájemci povolit konkrétní ztrátové downgrade:

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

Brána by měla zaprotokolovat záložní rozhodnutí v obou směrech. To umožňuje pozdější ladění, když se agent po výpadku poskytovatele nebo přesměrování modelu chová jinak.

Použití atributů na úrovni odpovědi a položky

Hovory odpovědí mohou stát více než ekvivalentní dokončení chatu, protože mohou zahrnovat spuštění nástroje, delší kontext, tokeny uvažování, vyhledávání souborů, vyhledávání na webu nebo opakované pokyny. Jeden souhrnný počet tokenů nestačí pro panel analýzy využití AI API.

Zaznamenejte využití na dvou úrovních:

• Úroveň odezvy: tenant, klíč, uživatel, model, poskytovatel, latence, konečný stav, vstupní tokeny, výstupní tokeny, argumentační tokeny, pokud byly hlášeny, celkové náklady a záložní trasa.
• Úroveň položky/nástroje: název nástroje, ID volání, jednotky hostovaného nástroje, ID souborů, počet vyhledávacích dotazů, je-li k dispozici, latence nástroje, cena nástroje a výsledek zásad schvalování.

To umožňuje vývojářům odpovědět na konkrétní otázky:

• Zvýšily se náklady kvůli delšímu stavu, úsilí o uvažování, volání nástrojů nebo záložním řešením?
• Který tenant nebo klíč API generuje poplatky za hostovaný nástroj?
• Která odpověď selhala po volání nástroje, ale před závěrečným textem?
• Které zrušené streamy stále využívají upstream?

Zvládejte nulové uchovávání a mazání jako prvotřídní chování

Stav na straně serveru je užitečný, ale mění povinnosti brány uchovat. Zabudujte zásady do vrstvy protokolu namísto toho, abyste je považovali za nastavení protokolování.

U každé žádosti o odpovědi vyřešte:

• Zásady uchování nájemníků
• úroveň požadavku store preference
• Kompatibilita uchování poskytovatelů
• Zda je povoleno opakované přehrávání brány
• Zda lze ukládat vstupy a výstupy nástroje
• Chování vypršení platnosti a mazání pro stav odpovědi

Pokud je uchovávání zakázáno, brána může stále uchovávat minimální provozní metadata: časová razítka, ID, stav, počty tokenů, náklady a rozhodnutí o zásadách. Neukládejte nezpracované výzvy, úplné výstupy nástrojů nebo rekonstruovanou historii, pokud to zásady nepovolují.

Příslušenství pro přizpůsobení, které je třeba přidat před spuštěním

Nespoléhejte se na manuální testy šťastné cesty. Přidejte příslušenství, která ověřují chování protokolu napříč přímými trasami OpenAI, trasami přizpůsobenými poskytovateli a záložními scénáři.

Minimální testovací sada

• Základní odpověď: je vrácena textová položka se stabilním ID odpovědi a použitím.
• Stav s více otáčkami: reference druhého požadavku previous_response_id; brána ověřuje vlastnictví nájemce a stavový režim.
• Opakované pokyny: ověřte, že vynechané pokyny nejsou v tichosti vymyšleny bránou.
• Function call round trip: model vysílá ID volání; aplikace odešle výstup; poslední odpověď spojí oba záznamy.
• Zásady hostovaného nástroje: neautorizovaný vestavěný nástroj je před odesláním zablokován.
• Streamování objednávky: začátek odpovědi, začátek položky, delty, dokončení položky, využití a dokončení jsou vysílány v platném pořadí.
• Zrušení streamu: odpojení klienta spouští zrušení upstreamu, pokud je podporováno, a zaznamenává částečné využití.
• Odmítnutí záložních reklam: poskytovatel bez požadavku Sémantika odpovědí vrací chybu schopnosti.
• Přihlášení ke ztrátové záložní verzi: Požadavek s povolenými ztrátami obdrží explicitní značku pro snížení verze.
• Režim nulového uchování: Přehrávání stavu a uchovávání výzvy na straně brány jsou blokovány.

Doporučená sekvence zavádění

1. Ukažte trasu beta. Přidejte /v1/responses, aniž byste změnili stávající chování chatu.
2. Implementujte nejprve předávání pro poskytovatele s podporou nativních odpovědí. Zachovejte ID, položky, streamy, využití a chyby.
3. Přidejte knihu stavu. Mapujte ID bran na ID poskytovatelů a vynucujte vlastnictví tenantů.
4. Přidat kanonické položky. Ukládat metadata položek potřebná pro audit, fakturaci a rekonstrukci streamu.
5. Přidat správu nástrojů. Ověřovat schémata, vynucovat rozsahy a zaznamenávat spojení volání nástroje.
6. Přidat normalizaci streamování. Převést streamy specifické pro poskytovatele na události životního cyklu brány.
7. Přidat směrování s ohledem na možnosti. Ve výchozím nastavení povolit pouze bezpečná záložní řešení.
8. Přidat analýzy a vypořádání fakturace. Samostatně přiřaďte token, zdůvodnění a použití nástroje.
9. Publikovat poznámky o kompatibilitě. Řekněte vývojářům, která pole jsou nativní, emulovaná, nepodporovaná nebo ztrátová.

Akční závěr

Vrstva kompatibility Responses API by měla zachovat význam protokolu, nikoli pouze vracet věrohodný text. Sestavte jej na pěti odolných objektech: kanonický model položky odezvy, kniha stavu konverzace, kniha volání nástrojů, normalizátor událostí streamování a matice schopností poskytovatele.

Nejbezpečnější výchozí nastavení je přísná kompatibilita: pokud trasa nemůže zachovat požadovaný stav, nástroje, kontext uvažování, události streamu nebo chování uchovávání, vrátí jasnou chybu schopnosti. Ztrátovou zálohu přidejte pouze tehdy, když vývojáři pochopí, co bude zrušeno. Tento přístup se může zdát méně pohodlný než automatické zploštění, ale zabraňuje nejhoršímu režimu selhání: aplikaci, která se jeví jako kompatibilní, ale v tichosti ztrácí sémantiku, kvůli které na prvním místě používala odpovědi API.

Související čtení

• účtování tokenů streamování a zpracování zrušení