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 API za odzive 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 Responses 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 razkriva polja, kot so previous_response_id, pretakanje, izbira orodja in vgrajena orodja. Dokumentacija SDK-ja kaže, da previous_response_id lahko zagotovi kontinuiteto pogovora, medtem ko se prejšnja navodila ne prenesejo samodejno naprej in jih je treba znova poslati, ko bi morala še veljati. Referenca pretakanja OpenAI vključuje razloč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 agenta bo odvisnih od strukture elementa odziva, sledi izvajanja orodja in konteksta razmišljanja s stanjem. Prehode, ki sedaj oblikujejo te koncepte, bo 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 odzive

Prva implementacijska napaka je domneva, da združljivost z OpenAI pomeni eno univerzalno shemo zahtev in odgovorov. 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 stanje končnega odgovora.

Ta razdelitev je pomembna za preskuse skladnosti. Adapter ponudnika, ki opravi preizkuse klepeta, morda še vedno ne uspe preizkusiti 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 odgovoriti:

• 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 se zahteva store=false?
• Kateri pretočni dogodki so zagotovljeni?
• Kako se beležijo preklic, časovna omejitev in delna uporaba?

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

Uporabite model kanoničnega odgovora

API Responses 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": "ključ_456",
  "model_alias": "privzeti agent",
  "ponudnik": "odpri",
  "predmeti": [
    {
      "item_id": "item_1",
      "vrsta": "besedilo",
      "vloga": "pomočnik",
      "content": [{ "type": "output_text", "text": "..." }],
      "status": "dokončano"
    },
    {
      "item_id": "item_2",
      "tip": "klic_funkcije",
      "call_id": "call_abc",
      "ime": "vrstni red_iskanja",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "dokončano"
    }
  ],
  "uporaba": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": nič,
    "orodne_enote": []
  },
  "status": "dokončano"
}

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 utemeljitve ali z utemeljitvijo povezani metapodatki, 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 zaračunavanju

Bistvo ni v tem, da bi uporabnikom razkrili lastniško shemo. 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 odjemalec 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": "uporabnik_999",
  "key_id": "ključ_456",
  "model": "gpt-...",
  "ponudnik": "odpri",
  "store_mode": "ponudnik|prehod|brez",
  "retention_policy": "standard|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "ustvarjeno_pri": "...",
  "expires_at": "...",
  "deleted_at": nič
}

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 odziva prehoda v ID-je odziva 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 stranka morda morala 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.

Potrdite orodja pred pošiljanjem

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

• Aplikacijska orodja: Definicije funkcij, ki jih zagotovi odjemalec, izvedene zunaj ponudnika modela, z izhodi, poslanimi nazaj v 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:

• Predčasno zavrnite neveljavno shemo JSON.
• Uveljavi največjo velikost sheme in globino gnezdenja.
• Preverite imena orodij glede združljivosti ponudnikov.
• 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 s 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 odpremo 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 obračunavanjem API-ja AI, namesto da bi skrili te stroške znotraj skupne skupne vrednosti klica modela.

Normalizirajte pretakanje kot dogodke, ne besedilo žetona

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.

Definirajte shemo dogodka prehoda in nato vanj preslikajte vsak tok ponudnika:

dogodek: response_started
podatki: { "response_id": "gw_resp_123", "status": "in_progress" }

dogodek: output_item_startedpodatki: { "item_id": "item_1", "type": "text" }

dogodek: text_delta
podatki: { "item_id": "item_1", "delta": "Pozdravljeni" }

dogodek: tool_call_delta
podatki: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

dogodek: usage_delta
podatki: { "output_tokens": 12 }

dogodek: končan
podatki: { "response_id": "gw_resp_123", "usage": { ... } }

Priporočeni normalizirani dogodki:

• response_started
• output_item_started
• output_item_completed
• text_delta
• delta_zavrnitve
• tool_call_delta
• tool_result_received
• usage_delta
• končano
• preklicano
• ni uspelo

Ko odjemalec prekine povezavo, razširite 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 računovodstvom 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": "privzeti agent",
  "poti": [
    {
      "ponudnik": "odpri",
      "model": "...",
      "supports_responses": drži,
      "supports_previous_response_id": drži,
      "supports_store_false": drži,
      "supports_builtin_web_search": drži,
      "supports_function_calling": drži,
      "supports_stream_lifecycle_events": drži,
      "supports_reasoning_context_continuity": drži,
      "max_tool_schema_bytes": 65536
    },
    {
      "ponudnik": "ponudnik_b",
      "model": "...",
      "supports_responses": false,
      "chat_adapter_available": res,
      "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": "privzeti agent",
  "vnos": "...",
  "nadomestna_politika": {
    "allow_lossy": napačno,
    "dovoljene_izgube": []
  }
}

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

{
  "nadomestna_politika": {
    "allow_lossy": drži,
    "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 agent 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 nadzorno ploščo za analitiko uporabe AI API.

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 ključ API 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
• Nastavitev trgovine na 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 odgovora

Če je hramba onemogočena, lahko prehod še vedno hrani minimalne operativne metapodatke: časovne žige, ID-je, stanje, š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 zagonom

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

Najmanjši testni niz

• Osnovni odgovor: besedilni element je vrnjen s stabilnim odgovorom ID in uporabo.
• Večkratno stanje: druga zahteva se sklicuje na 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 oddaja ID klica; aplikacija predloži izhod; končni odgovor združi oba zapisa.
• Pravilnik gostujočega orodja: 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 podprt, in zabeleži delno uporabo.
• Nadomestna zavrnitev: ponudnik brez zahtevane semantike odgovorov vrne napako zmožnosti.
• Možnost nadomestne možnosti za izgubo: zahteva z dovoljenimi izgubami prejme eksplicitno oznako znižanja.
• Način brez 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, ne da bi spremenili obstoječe vedenje 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, obračunavanje in rekonstrukcijo toka.
5. Dodajte upravljanje orodij. Preverite sheme, uveljavite obsege in zabeležite združitve klicev orodij.
6. Dodajte normalizacijo pretakanja. Pretvorite tokove, specifične za ponudnika, v dogodke življenjskega cikla prehoda.
7. Dodajte usmerjanje glede na zmogljivost. Privzeto dovolite samo varne nadomestne možnosti.
8. Dodajte analitiko in poravnavo zaračunavanja. Ločeno dodelite žeton, utemeljitev in uporabo orodja.
9. Objavite opombe o združljivosti. Povejte razvijalcem, katera polja so izvorna, emulirana, nepodprta ali izgubljena.

Dejanski sklep

Sloj združljivosti API-ja Responses mora ohraniti pomen protokola, ne pa samo vračati verjetnega besedila. Zgradite ga okrog petih trajnih predmetov: 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 Responses API.

Sorodno branje

• obračunavanje in preklic pretočnega žetona ravnanje