Zgradite plast združljivosti Responses API v prehodu AI API

Ne izvajajte /v1/responses tako, da vsako zahtevo prevedete v /v1/chat/completions in upate, da je oblika dovolj blizu. Ta adapter lahko vrne besedilo, vendar lahko tiho izgubi dele, ki jih zanimajo razvijalci: postavke odziva, stanje na strani strežnika, klice orodij, kontinuiteto razmišljanja, dogodke življenjskega cikla toka, semantiko preklica in dodeljevanje uporabe na ravni elementov.

Praktični cilj je združljivostna plast, ki odzive API obravnava kot bogatejši protokol. Ohranite podporo za dokončanje klepeta za obstoječe odjemalce, vendar zgradite odzive kot lastno površino prehoda z lastnim modelom stanja, normalizatorjem toka, knjigo orodnih klicev, matriko zmogljivosti in nadomestnimi pravili.

Kaj je dejstvo, kaj politika in kaj napoved?

Dejstva: OpenAI opisuje odgovore API kot poenotenje zmožnosti, ki so bile prej razdeljene na zaključke klepeta in pomočnike, vključno s podporo za orodja, kot so spletno iskanje, iskanje datotek in uporaba računalnika. API izpostavi polja, kot so previous_response_id, pretakanje, izbira orodij in vgrajena orodja. Dokumentacija SDK kaže, da previous_response_id lahko zagotovi kontinuiteto pogovora, medtem ko se prejšnja navodila ne prenesejo samodejno in jih je treba znova poslati, ko bi morala še veljati. Referenca pretakanja OpenAI vključuje ločen življenjski cikel odziva in izhodne dogodke namesto le delt žetonov.

Priporočila: Prehod naj ohrani to semantiko, namesto da bi jo privzeto izravnal. Zavrniti ali izrecno znižati zahteve, ko ciljni ponudnik ne more podpirati zahtevanega vedenja.

Predvidevanje: Več delovnih obremenitev agentov bo odvisnih od strukture elementov odziva, sledi izvajanja orodja in konteksta razmišljanja s stanjem. Prehode, ki modelirajo te koncepte, bo zdaj lažje razširiti kot prehode, ki obravnavajo odzive kot kozmetično končno točko.

Določite ločeno pogodbo o združljivosti za odgovore

Prva implementacijska napaka je domneva, da OpenAI-compatible pomeni eno univerzalno shemo zahteve in odgovora. V praksi bi morali biti /v1/chat/completions in /v1/responses ločeni pogodbi o združljivosti.

Ohranite skupno plast preverjanja pristnosti, zaračunavanja, kvote in usmerjanja, vendar ločite plast protokola:

• Površina dokončanja klepeta: sporočila, izbire, delte, klici orodij v obliki klepeta, starejše vedenje odjemalca.
• Površina odzivov: vhodni elementi, izhodni elementi, ID-ji odgovorov, prejšnje reference odgovorov, bogatejši dogodki orodij, dogodki toka življenjskega cikla, polja, povezana z razmišljanjem, in končno stanje odgovora.

Ta delitev je pomembna za teste skladnosti. Adapter ponudnika, ki opravi preizkuse klepeta, morda še vedno ne bo uspel preizkusov odzivov, ker ne more ohraniti previous_response_id, vrstnega reda elementov, strukture zavrnitve, metapodatkov o gostovanem orodju ali imen pretočnih dogodkov.

Pogodba o minimalni združljivosti mora odgovarjati:

• Katera polja zahteve so sprejeta, zavrnjena, preoblikovana ali prezrta?
• Kateri tipi odgovorov so ohranjeni?
• Katere vrste orodij so podprte glede na ponudnika in model?
• Ali lahko ponudnik vzdržuje stanje pogovora ali ga mora vzdrževati prehod?
• Kaj se zgodi, ko je zahteva store=false?
• Kateri pretočni dogodki so zagotovljeni?
• Kako se beležijo preklic, časovna omejitev in delna uporaba?

Če že imate AI API prehod, obravnavajte podporo Responses kot razširitev protokola, ne kot vzdevek poti.

Uporabite model kanoničnega odgovora

Odziv API vrne več kot eno sporočilo pomočnika. Predstavlja lahko različne izhodne postavke in dogodke. Vaš prehod potrebuje notranji kanonični model, preden se preslika v katerega koli ponudnika.

Praktična notranja shema elementa se lahko začne takole:

{
  "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"
}

Vključite vrste elementov, še preden jih lahko proizvaja vsak ponudnik. Uporabne kategorije vključujejo:

• Izpis besedila
• Zavrnitve
• Klici funkcij
• Izhodi funkcij, ki jih predloži aplikacija
• Povzetki sklepanja ali metapodatki, povezani z obrazložitvijo, kjer so na voljo
• Sklici na datoteke
• Spletno iskanje, iskanje datotek, uporaba računalnika ali drugi dogodki gostujočega orodja
• Končni metapodatki o uporabi in obračunu

Bistvo ni razkriti lastniške sheme uporabnikom. Bistvo je preprečiti, da bi prehod zavrgel informacije, preden jih lahko revidira, zaračuna, pretaka, ponovno predvaja ali preoblikuje.

Izdelajte državno knjigo v lasti prehoda

previous_response_id je polje, ki najbolj izpostavi razliko med posredovanjem klepeta brez stanja in združljivostjo odzivov. Če se stranka sklicuje na prejšnji odgovor, mora prehod vedeti, kaj ta ID pomeni, ali ga sme najemnik uporabljati in ali lahko ponudnik nadaljuje z njega.

Ustvarite državno knjigo s ključem najemnika in ID odgovora:

{
  "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
}

Pomembno pravilo: ne posnemajte samodejno previous_response_id s ponovnim predvajanjem celotne zgodovine klepetov, razen če je najemnik izrecno dovolil to vedenje pri ohranjanju in stroških. Ponovno predvajanje lahko poveča stroške žetonov, spremeni položaj zasebnosti in spremeni vedenje modela. Varneje je vrniti napako jasne zmožnosti kot tiho poslati shranjeno vsebino pogovora, za katero aplikacija ni pričakovala, da jo boste obdržali ali ponovno uporabili.

Načini ravnanja s stanjem

• Stanje ponudnika: Gornji ponudnik shrani dovolj konteksta, prehod pa preslika ID-je odgovorov prehoda v ID-je odgovorov ponudnika.
• Stanje prehoda: Prehod shrani potrebne predhodne elemente in rekonstruira kontekst, ko je dovoljeno.
• Brez stanja: Zahteva uporablja store=false ali pravilnik najemnika prepoveduje hrambo. previous_response_id je treba zavrniti, razen če lahko ponudnik izpolni zahtevo brez hrambe prehoda in pravilnik to dovoljuje.

Upoštevajte tudi, da bo morala stranka morda znova poslati prejšnja navodila, ko bodo še naprej veljala. Prehod si ne bi smel izmišljati skritih navodil za nadomestilo, razen če je to vedenje del izrecne politike najemnika.

Preverjanje orodij pred pošiljanjem

Odzivi naredijo uporabo orodja bolj osrednjo. Združljivostna plast mora obravnavati dve široki kategoriji:

• Aplikacijska orodja: Definicije funkcij, ki jih zagotovi odjemalec, izvedene zunaj ponudnika modela, z izhodi, poslanimi nazaj API.
• Orodja gostujočega ponudnika: spletno iskanje, iskanje datotek, uporaba računalnika, izvajanje kode, ozemljitev ali podobna orodja, ki jih izvaja ponudnik ali infrastruktura, ki jo nadzoruje prehod.

Na vstopu preverite sheme orodij pred usmerjanjem:

• Zgodaj zavrni neveljavno JSON shemo.
• Uveljavi največjo velikost sheme in globino gnezdenja.
• Preverite združljivost imen orodij s ponudniki.
• Uporabi obsege najemnika, ključa, uporabnika in okolja.
• Zahtevaj prehode za odobritev za orodja, ki pišejo podatke, trošijo denar, dostopajo do občutljivih sistemov ali kličejo zunanje priključke.

Za klicanje funkcij aplikacije zahtevajte stabilen ID klica. Model odda klic funkcije z call_id; aplikacija predloži izpis orodja, ki se sklicuje na ta ID; prehod oba beleži v isto sled. Brez tega ključa za pridružitev postanejo revizijski dnevniki in ponovni poskusi dvoumni.

Za gostujoča orodja rezervirajte proračun pred pošiljanjem in poravnajte stroške pozneje. Gostujoča orodja lahko dodajo stroške zunaj običajnega obračunavanja žetonov, zato povežite knjigo orodij z poenotenim AI API obračunavanjem, namesto da bi skrili te stroške znotraj splošnega skupnega zneska klicev modela.

Normaliziraj pretakanje kot dogodke, ne besedilo žetonov

Proxy za klepet se lahko pogosto izogne deltam posredovanja žetonov. Prehod za odzive ne more. Tok ima pomen življenjskega cikla: odgovor se lahko začne, izhodni elementi se lahko začnejo in dokončajo, besedilo lahko prispe v deltah, klici orodij se lahko sestavljajo postopoma, uporaba lahko prispe na koncu ali med tokom in odziv lahko ne uspe ali je preklican.

Določite shemo dogodka prehoda in nato vanj preslikajte vsak tok ponudnika:

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": { ... } }

Priporočeni normalizirani dogodki:

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

Ko odjemalec prekine povezavo, razširi preklic navzgor, če ponudnik to podpira. Zabeležite stanje delnega odgovora tako ali drugače. Če ponudnik pozneje vrne končno uporabo prek odloženega povratnega klica ali končnega kosa, uskladite glavno knjigo. Združljivost s pretakanjem je toliko povezana z obračunavanjem in življenjskim ciklom kot z zakasnitvijo.

Ustvarite matriko zmogljivosti ponudnika

Usmerjanje z več modeli je uporabno le, če prehod razume, kaj je mogoče varno usmeriti. V svoj katalog modelov dodajte zmožnosti, specifične za odzive:

{
  "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"]
    }
  ]
}

Nadomestna rešitev se mora zavedati izgub. Če zahteva zahteva vgrajeno spletno iskanje in ga nadomestni ponudnik ne more izvesti, ne odgovorite tiho brez iskanja. Če je zahteva odvisna od ohranjenega konteksta sklepanja in ga nadomestna pot ne more ohraniti, vrni napako zmogljivosti ali odgovor na znižanje, ki ga je odjemalec izrecno sprejel.

Uporabna možnost zahteve je:

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

Za manj občutljive primere uporabe lahko najemniki dovolijo določene znižane stopnje z izgubo:

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

Prehod mora v vsakem primeru zabeležiti nadomestno odločitev. To omogoča poznejše odpravljanje napak, ko se posrednik po izpadu ponudnika ali preusmeritvi modela obnaša drugače.

Uporaba atributa na ravni odgovora in postavke

Odzivni klici lahko stanejo več kot enakovredni zaključki klepeta, ker lahko vključujejo izvajanje orodja, daljši kontekst, žetone sklepanja, iskanje datotek, spletno iskanje ali ponavljajoča se navodila. En sam skupni žeton ne zadostuje za AI API nadzorno ploščo za analizo uporabe.

Beležite uporabo na dveh ravneh:

• Raven odziva: najemnik, ključ, uporabnik, model, ponudnik, zakasnitev, končno stanje, vhodni žetoni, izhodni žetoni, žetoni razlogov, kjer so bili sporočeni, skupni stroški in nadomestna pot.
• Raven predmeta/orodja: ime orodja, ID klica, gostujoče orodne enote, ID-ji datotek, število iskalnih poizvedb, če je na voljo, zakasnitev orodja, cena orodja in rezultat pravilnika o odobritvi.

To razvijalcem omogoča odgovore na konkretna vprašanja:

• Ali so se stroški povečali zaradi daljšega stanja, razmišljanja, klicev orodij ali nadomestnega načina?
• Kateri najemnik ali API ključ ustvarja stroške gostujočega orodja?
• Kateri odgovor ni uspel po klicu orodja, vendar pred končnim besedilom?
• Kateri preklicani tokovi so še vedno povzročili uporabo navzgor?

Obravnavajte ničelno hrambo in brisanje kot prvovrstno vedenje

Stanje na strani strežnika je koristno, vendar spremeni obveznosti hrambe prehoda. Vgradite pravilnik v sloj protokola, namesto da ga obravnavate kot nastavitev beleženja.

Za vsako zahtevo za odgovore razrešite:

• Politika zadrževanja najemnikov
• Prednost store ravni zahteve
• Združljivost zadrževanja ponudnika
• Ali je dovoljeno ponovno predvajanje na prehodu
• Ali se lahko shranijo vhodi in izhodi orodja
• Vedenje poteka in brisanja za stanje odziva

Če je hramba onemogočena, lahko prehod še vedno hrani minimalne operativne metapodatke: časovne žige, ID-je, status, število žetonov, stroške in odločitve o politiki. Izogibajte se shranjevanju neobdelanih pozivov, celotnih rezultatov orodij ali rekonstruirane zgodovine, razen če to dovoljuje pravilnik.

Naprave za skladnost, ki jih je treba dodati pred lansiranjem

Ne zanašajte se na ročne preizkuse srečne poti. Dodajte napeljave, ki preverjajo vedenje protokola po neposrednih OpenAI poteh, ponudniku prilagojenih poteh in nadomestnih scenarijih.

Najmanjši preskusni niz

• Osnovni odgovor: element besedila je vrnjen s stabilnim odgovorom ID in uporabo.
• Multi-turn state: reference druge zahteve previous_response_id; prehod preverja lastništvo najemnika in način stanja.
• Ponavljajoča se navodila: preverite, ali izpuščenih navodil ni tiho izmislil prehod.
• Povratni klic funkcije: model odda ID klica; aplikacija predloži izhod; končni odgovor združi oba zapisa.
• Pravilnik o gostovanem orodju: nepooblaščeno vgrajeno orodje je blokirano pred pošiljanjem.
• Vrstni red pretakanja: začetek odziva, začetek elementa, delte, dokončanje elementa, uporaba in zaključek so oddani v veljavnem vrstnem redu.
• Preklic toka: prekinitev povezave z odjemalcem sproži preklic navzgor, kjer je podprto, in zabeleži delno uporabo.
• Nadomestna zavrnitev: Ponudnik brez zahtevane semantike odgovorov vrne napako zmožnosti.
• Izgubljena nadomestna izbira: zahteva z dovoljenimi izgubami prejme izrecno oznako nižje stopnje.
• Način ničelnega zadrževanja: ponovno predvajanje stanja in zadrževanje poziva na strani prehoda sta blokirana.

Priporočeno zaporedje uvajanja

1. Razkrijte beta pot. Dodajte /v1/responses brez spreminjanja obstoječega vedenja klepeta.
2. Najprej implementirajte prehod za ponudnike z izvorno podporo za odzive. Ohranite ID-je, elemente, tokove, uporabo in napake.
3. Dodajte državno knjigo. Preslikajte ID-je prehodov v ID-je ponudnika in uveljavite lastništvo najemnika.
4. Dodajte kanonične elemente. Shranite metapodatke elementov, ki so potrebni za revizijo, zaračunavanje in rekonstrukcijo toka.
5. Dodajte upravljanje orodij. Preverjanje shem, uveljavljanje obsegov in beleženje združitev klicev orodij.
6. Dodajte normalizacijo pretakanja. Pretvorite tokove, specifične za ponudnika, v dogodke življenjskega cikla prehoda.
7. Dodajte usmerjanje glede na zmogljivosti. Privzeto dovolite samo varne nadomestne možnosti.
8. Dodajte analitiko in poravnavo zaračunavanja. Ločeno dodelite žeton, razloge in uporabo orodja.
9. Objavite opombe o združljivosti. Povejte razvijalcem, katera polja so izvorna, emulirana, nepodprta ali izgubljena.

Dejanski sklep

A Responses API mora ohraniti pomen protokola, ne pa samo vrniti verjetnega besedila. Zgradite ga okrog petih trajnih objektov: kanoničnega modela odgovora, knjige stanja pogovorov, knjige klicev orodij, normalizatorja pretočnih dogodkov in matrike zmogljivosti ponudnika.

Najvarnejša privzeta vrednost je stroga združljivost: če pot ne more ohraniti zahtevanega stanja, orodij, konteksta razmišljanja, pretočnih dogodkov ali vedenja zadrževanja, vrne jasno napako zmogljivosti. Dodajte nadomestno možnost z izgubo privolitve šele, ko razvijalci razumejo, kaj bo opuščeno. Ta pristop se morda zdi manj priročen kot samodejno izravnavanje, vendar preprečuje najhujši način napake: aplikacijo, ki se zdi združljiva, medtem ko tiho izgubi semantiko, zaradi katere je sploh uporabljala odgovore API.

Sorodno branje

• obračunavanje žetonov za pretakanje in obravnava preklica