Izgradite sloj kompatibilnosti Responses API-ja u pristupniku AI API-ja

Nemojte implementirati /v1/responses prevođenjem svakog zahtjeva u /v1/chat/completions i nadajući se da je oblik dovoljno sličan. Taj adapter može vratiti tekst, ali može tiho izgubiti dijelove do kojih je razvojnim programerima stalo: stavke odgovora, stanje na strani poslužitelja, pozive alata, kontinuitet razmišljanja, događaje životnog ciklusa toka, semantiku otkazivanja i atribuciju upotrebe na razini stavke.

Praktični cilj je sloj kompatibilnosti koji tretira Responses API kao bogatiji protokol. Zadržite podršku za dovršetak razgovora za postojeće klijente, ali izgradite Response kao vlastitu pristupnu površinu s vlastitim modelom stanja, normalizatorom toka, knjigom poziva alata, matricom mogućnosti i rezervnim pravilima.

Što je činjenica, što je politika, a što predviđanje?

Činjenice: OpenAI opisuje Responses API kao mogućnosti objedinjavanja koje su prethodno bile podijeljene između dovršetaka razgovora i pomoćnika, uključujući podršku za alate kao što su pretraživanje weba, pretraživanje datoteka i korištenje računala. API izlaže polja kao što su previous_response_id, strujanje, odabir alata i ugrađeni alati. Dokumentacija SDK-a pokazuje da previous_response_id može osigurati kontinuitet razgovora, dok se prethodne upute ne prenose automatski i moraju se ponovno poslati kada bi još trebale biti primjenjive. OpenAI-jeva referenca strujanja uključuje različite životne cikluse odgovora i izlazne događaje, a ne samo delte tokena.

Preporuke: Gateway bi trebao sačuvati ovu semantiku umjesto da je izravnava prema zadanim postavkama. Trebao bi odbiti ili izričito smanjiti zahtjeve kada ciljni pružatelj ne može podržati traženo ponašanje.

Predviđanje: Dodatna radna opterećenja agenta ovisit će o strukturi odgovora, tragovima izvršenja alata i kontekstu rezoniranja s stanjem. Pristupnike koji sada modeliraju te koncepte bit će lakše proširiti nego pristupnike koji tretiraju Odgovore kao kozmetičku krajnju točku.

Definirajte zasebni ugovor o kompatibilnosti za odgovore

Prva pogreška implementacije je pretpostavka da kompatibilnost s OpenAI-om znači jednu univerzalnu shemu zahtjeva i odgovora. U praksi bi /v1/chat/completions i /v1/responses trebali biti zasebni ugovori o kompatibilnosti.

Zadržite zajedničku provjeru autentičnosti, naplatu, kvotu i sloj usmjeravanja, ali odvojite sloj protokola:

• Površine chata: poruke, izbori, delte, pozivi alata u formatu chata, naslijeđeno ponašanje klijenta.
• Površina odgovora: ulazne stavke, izlazne stavke, ID-ovi odgovora, prethodne reference odgovora, bogatiji događaji alata, događaji toka životnog ciklusa, polja povezana s obrazloženjem i konačno stanje odgovora.

Ova podjela je važna za testove sukladnosti. Adapter pružatelja usluga koji prolazi testove chata može i dalje pasti na testovima Responses jer ne može sačuvati previous_response_id, redoslijed stavki, strukturu odbijanja, metapodatke hostiranih alata ili imena strujanja događaja.

Minimalni ugovor o kompatibilnosti trebao bi odgovoriti:

• Koja su polja zahtjeva prihvaćena, odbijena, transformirana ili zanemarena?
• Koje su vrste stavki odgovora sačuvane?
• Koje su vrste alata podržane po dobavljaču i modelu?
• Može li pružatelj održavati stanje razgovora ili ga pristupnik mora održavati?
• Što se događa kada se zatraži store=false?
• Koji su događaji strujanja zajamčeni?
• Kako se bilježe otkazivanje, vremensko ograničenje i djelomična upotreba?

Ako već imate AI API pristupnik, tretirajte podršku Responses kao proširenje protokola, a ne alias rute.

Koristite kanonski model stavke odgovora

Responses API vraća više od jedne poruke pomoćnika. Može predstavljati različite izlazne stavke i događaje. Vaš pristupnik treba interni kanonski model prije mapiranja na bilo kojeg pružatelja usluga.

Praktična interna shema stavki može započeti ovako:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "odgovor_...",
  "tenant_id": "ten_123",
  "key_id": "ključ_456",
  "model_alias": "zadani agent",
  "pružatelj": "otvori",
  "stavke": [
    {
      "item_id": "stavka_1",
      "vrsta": "tekst",
      "uloga": "pomoćnik",
      "content": [{ "type": "output_text", "text": "..." }],
      "status": "dovršeno"
    },
    {
      "item_id": "stavka_2",
      "tip": "poziv_funkcije",
      "call_id": "abc_poziva",
      "ime": "redoslijed_traženja",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "dovršeno"
    }
  ],
  "upotreba": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "jedinice_alata": []
  },
  "status": "dovršeno"
}

Uključite vrste stavki čak i prije nego što ih svaki dobavljač može proizvesti. Korisne kategorije uključuju:

• Izlaz teksta
• Odbijanja
• Pozivi funkcija
• Izlazi funkcija koje šalje aplikacija
• Sažeci obrazloženja ili metapodaci povezani s obrazloženjem ako su dostupni
• Reference datoteka
• Pretraživanje weba, pretraživanje datoteka, korištenje računala ili drugi događaji hostiranih alata
• Konačni metapodaci o upotrebi i naplati

Smisao nije izložiti vlasničku shemu korisnicima. Poanta je spriječiti gateway da odbaci informacije prije nego što ih može revidirati, naplatiti, strujati, ponovno reproducirati ili transformirati.

Izradite državnu knjigu u vlasništvu pristupnika

previous_response_id je polje koje najviše otkriva razliku između proxyja chata bez stanja i kompatibilnosti odgovora. Ako se klijent poziva na prethodni odgovor, pristupnik mora znati što taj ID znači, smije li ga zakupac koristiti i može li pružatelj nastaviti s njega.

Stvorite državnu knjigu s ključem zakupca i 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": "ključ_456",
  "model": "gpt-...",
  "pružatelj": "otvori",
  "store_mode": "provider|gateway|none",
  "retention_policy": "standardno|nula_zadržavanja|prilagođeno_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "stvoreno_na": "...",
  "isteče_na": "...",
  "deleted_at": nula
}

Važno pravilo: nemojte automatski oponašati previous_response_id ponovnim prikazivanjem cijele povijesti razgovora osim ako stanar nije izričito dopustio takvo ponašanje zadržavanja i troškova. Reprodukcija može povećati cijenu tokena, promijeniti položaj privatnosti i promijeniti ponašanje modela. Sigurnije je vratiti pogrešku jasne mogućnosti nego tiho poslati pohranjeni sadržaj razgovora za koji aplikacija nije očekivala da ćete ga zadržati ili ponovno upotrijebiti.

Načini rukovanja stanjem

• Stanje pružatelja: Uzlazni pružatelj pohranjuje dovoljno konteksta, a pristupnik preslikava ID-ove odgovora pristupnika u ID-ove odgovora pružatelja.
• Stanje pristupnika: pristupnik pohranjuje potrebne prethodne stavke i rekonstruira kontekst kada je to dopušteno.
• Nema stanja: zahtjev koristi store=false ili pravila zakupca zabranjuju zadržavanje. previous_response_id treba odbiti osim ako pružatelj ne može ispuniti zahtjev bez zadržavanja pristupnika i pravila to dopuštaju.

Također imajte na umu da će klijent možda trebati ponovno poslati prethodne upute kada će se one nastaviti primjenjivati. Gateway ne bi trebao izmišljati skrivene upute za kompenzaciju osim ako takvo ponašanje nije dio izričite politike zakupca.

Validirajte alate prije slanja

Odgovori čine korištenje alata središnjim. Sloj kompatibilnosti trebao bi obrađivati dvije široke kategorije:

• Aplikacijski alati: Definicije funkcija koje daje klijent, izvršavaju se izvan pružatelja modela, s rezultatima koji se šalju natrag u API.
• Alati hostiranog pružatelja usluga: pretraživanje weba, pretraživanje datoteka, korištenje računala, izvršavanje koda, uzemljenje ili slični alati koje izvršava pružatelj ili infrastruktura koju kontrolira pristupnik.

Na ulazu provjerite sheme alata prije usmjeravanja:

• Rano odbacite nevažeću JSON shemu.
• Nametnite maksimalnu veličinu sheme i dubinu ugniježđivanja.
• Provjerite kompatibilnost davatelja naziva alata.
• Primijenite opsege stanara, ključa, korisnika i okruženja.
• Zahtijevati vrata odobrenja za alate koji pišu podatke, troše novac, pristupaju osjetljivim sustavima ili pozivaju vanjske konektore.

Za pozivanje funkcije aplikacije potreban je stabilan ID poziva. Model emitira poziv funkcije s call_id; aplikacija šalje izlaz alata pozivajući se na taj ID; pristupnik bilježi oboje u istom tragu. Bez tog ključa pridruživanja, revizijski zapisnici i ponovni pokušaji postaju dvosmisleni.

Za hostirane alate rezervirajte proračun prije otpreme i podmirite troškove naknadno. Hostirani alati mogu dodati naknade izvan uobičajenog računovodstva tokena, stoga povežite knjigu alata s objedinjenom naplatom AI API-ja umjesto skrivanja tih troškova unutar generičkog ukupnog modela poziva.

Normalizirajte strujanje kao događaje, a ne tekst tokena

Proxy za chat često se može izvući s prosljeđivanjem delta tokena. Pristupnik za odgovore ne može. Stream ima značenje životnog ciklusa: odgovor može započeti, izlazne stavke mogu započeti i završiti, tekst može stići u deltama, pozivi alata mogu se sastavljati postupno, korištenje može stići na kraju ili tijekom strujanja, a odgovor može ne uspjeti ili biti otkazan.

Definirajte shemu događaja pristupnika, a zatim mapirajte svaki tok pružatelja usluga u nju:

događaj: response_started
podaci: { "response_id": "gw_resp_123", "status": "in_progress" }

događaj: output_item_startedpodaci: { "item_id": "item_1", "type": "text" }

događaj: text_delta
podaci: { "item_id": "item_1", "delta": "Pozdrav" }

događaj: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

događaj: usage_delta
podaci: { "output_tokens": 12 }

događaj: završen
podaci: { "response_id": "gw_resp_123", "usage": { ... } }

Preporučeni normalizirani događaji:

• response_started
• output_item_started
• output_item_completed
• text_delta
• delta_odbijanja
• tool_call_delta
• tool_result_received
• usage_delta
• dovršeno
• otkazano
• nije uspjelo

Kada se klijent prekine, propagirajte otkazivanje uzvodno ako pružatelj to podržava. Zabilježite stanje djelomičnog odgovora na bilo koji način. Ako pružatelj kasnije vrati konačnu upotrebu putem odgođenog povratnog poziva ili konačnog dijela, uskladite knjigu. Kompatibilnost strujanja tiče se računa i životnog ciklusa koliko i kašnjenja.

Stvorite matricu mogućnosti pružatelja

Usmjeravanje s više modela korisno je samo kada pristupnik razumije što se može sigurno usmjeriti. Dodajte mogućnosti specifične za odgovore u svoj katalog modela:

{
  "model_alias": "zadani agent",
  "rute": [
    {
      "pružatelj": "otvori",
      "model": "...",
      "supports_responses": točno,
      "supports_previous_response_id": točno,
      "supports_store_false": točno,
      "supports_builtin_web_search": točno,
      "podržava_pozivanje_funkcije": točno,
      "supports_stream_lifecycle_events": točno,
      "supports_reasoning_context_continuity": točno,
      "max_tool_schema_bytes": 65536
    },
    {
      "provider": "provider_b",
      "model": "...",
      "supports_responses": netočno,
      "chat_adapter_available": točno,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

Rezervni bi trebao biti svjestan gubitaka. Ako zahtjev zahtijeva ugrađeno web-pretraživanje, a zamjenski pružatelj to ne može izvesti, nemojte tiho odgovoriti bez pretraživanja. Ako zahtjev ovisi o očuvanom kontekstu obrazloženja i rezervna ruta ga ne može sačuvati, vrati pogrešku mogućnosti ili odgovor na nižu verziju koju je klijent izričito izabrao.

Korisna opcija zahtjeva je:

{
  "model": "zadani agent",
  "unos": "...",
  "rezervna_pravila": {
    "allow_lossy": netočno,
    "dopušteni_gubici": []
  }
}

Za manje osjetljive slučajeve upotrebe, zakupci mogu dopustiti određene gubitke na nižu verziju:

{
  "rezervna_pravila": {
    "allow_lossy": točno,
    "allowed_losses": ["flattened_stream", "no_reasoning_summary"]
  }
}

Gateway bi trebao zabilježiti rezervnu odluku u svakom slučaju. To omogućuje kasnije otklanjanje pogrešaka kada se agent ponaša drugačije nakon prekida pružatelja usluga ili preusmjeravanja modela.

Korištenje atributa na razini odgovora i stavke

Pozivi s odgovorima mogu koštati više od ekvivalentnih dovršetaka chata jer mogu uključivati izvršavanje alata, dulji kontekst, tokene obrazloženja, pretraživanje datoteka, pretraživanje weba ili ponovljene upute. Jedan skupni broj tokena nije dovoljan za nadzornu ploču analitike upotrebe AI API-ja.

Bilježite korištenje na dvije razine:

• Razina odgovora: stanar, ključ, korisnik, model, pružatelj, latencija, konačni status, ulazni tokeni, izlazni tokeni, tokeni obrazloženja gdje su prijavljeni, ukupni trošak i povratna ruta.
• Razina stavke/alata: naziv alata, ID poziva, hostirane jedinice alata, ID-ovi datoteka, broj upita za pretraživanje ako je dostupan, kašnjenje alata, cijena alata i rezultat pravila odobrenja.

Ovo programerima omogućuje odgovore na konkretna pitanja:

• Je li se trošak povećao zbog duljeg stanja, napora u razmišljanju, pozivanja alata ili rezerve?
• Koji stanar ili API ključ generira troškove hostiranog alata?
• Koji odgovor nije uspio nakon poziva alata, ali prije konačnog teksta?
• Koji su otkazani streamovi još uvijek imali uzvodnu upotrebu?

Nulto zadržavanje i brisanje tretirajte kao prvorazredno ponašanje

Stanje na strani poslužitelja je korisno, ali mijenja obveze zadržavanja pristupnika. Ugradite pravila u sloj protokola umjesto da ih tretirate kao postavku zapisivanja.

Za svaki zahtjev za odgovore, riješite:

• Pravila zadržavanja stanara
• Postavke trgovine na razini zahtjeva
• Kompatibilnost zadržavanja pružatelja usluga
• Je li dopušteno ponavljanje pristupnika
• Mogu li se unosi i izlazi alata pohraniti
• Ponašanje isteka i brisanja za stanje odgovora

Ako je zadržavanje onemogućeno, pristupnik i dalje može zadržati minimalne operativne metapodatke: vremenske oznake, ID-ove, status, brojeve tokena, troškove i odluke o politici. Izbjegavajte pohranjivanje neobrađenih upita, potpunih izlaza alata ili rekonstruirane povijesti osim ako to pravila ne dopuštaju.

Uredbe za usklađenost koje treba dodati prije pokretanja

Nemojte se oslanjati na ručne testove sretnog puta. Dodajte fixture koje provjeravaju ponašanje protokola preko izravnih OpenAI ruta, ruta prilagođenih pružatelju usluga i rezervnih scenarija.

Minimalni skup testova

• Osnovni odgovor: tekstualna stavka vraća se sa stabilnim ID-om odgovora i upotrebom.
• Višestruko stanje: drugi zahtjev upućuje na previous_response_id; pristupnik potvrđuje vlasništvo stanara i način stanja.
• Upute koje se ponavljaju: provjerite da pristupnik nije tiho izmislio izostavljene upute.
• Povratni poziv funkcije: model emitira ID poziva; aplikacija šalje izlaz; konačni odgovor spaja oba zapisa.
• Pravila o hostiranom alatu: neovlašteni ugrađeni alat blokiran je prije slanja.
• Redoslijed strujanja: početak odgovora, početak stavke, delte, završetak stavke, upotreba i završetak emitiraju se valjanim redoslijedom.
• Otkazivanje streama: prekid veze s klijentom pokreće otkazivanje uzlaznog toka gdje je to podržano i bilježi djelomičnu upotrebu.
• Rezervno odbijanje: pružatelj bez potrebne semantike odgovora vraća pogrešku mogućnosti.
• Uključivanje zamjene s gubicima: zahtjev s dopuštenim gubicima dobiva izričitu oznaku za vraćanje na nižu verziju.
• Način nultog zadržavanja: ponovna reprodukcija stanja i zadržavanje upita na strani pristupnika su blokirani.

Preporučeni redoslijed uvođenja

1. Izložite beta rutu. Dodajte /v1/responses bez mijenjanja postojećeg ponašanja chata.
2. Prvo implementirajte prolaz za pružatelje s izvornom podrškom za odgovore. Sačuvajte ID-ove, stavke, tokove, upotrebu i pogreške.
3. Dodajte državnu knjigu. Preslikajte ID-ove pristupnika na ID-ove pružatelja usluga i nametnite vlasništvo stanara.
4. Dodajte kanonske stavke. Pohranite metapodatke o stavkama potrebne za reviziju, naplatu i rekonstrukciju streama.
5. Dodajte upravljanje alatom. Potvrdite sheme, nametnite opsege i zabilježite spajanja poziva alata.
6. Dodajte normalizaciju streama. Pretvorite streamove specifične za pružatelja usluga u događaje životnog ciklusa pristupnika.
7. Dodajte usmjeravanje s obzirom na mogućnosti. Prema zadanim postavkama dopustite samo sigurne zamjene.
8. Dodajte analitiku i obračun naplate. Odvojeno dodijelite token, obrazloženje i upotrebu alata.
9. Objavite bilješke o kompatibilnosti. Recite programerima koja su polja izvorna, emulirana, nepodržana ili izgubljena.

Zaključak koji se može poduzeti

Sloj kompatibilnosti Responses API-ja trebao bi sačuvati značenje protokola, a ne samo vratiti uvjerljiv tekst. Izgradite ga oko pet trajnih objekata: kanonski model stavke odgovora, knjiga stanja razgovora, knjiga poziva alata, normalizator događaja strujanja i matrica mogućnosti pružatelja.

Najsigurnija zadana vrijednost je stroga kompatibilnost: ako ruta ne može očuvati potrebno stanje, alate, kontekst razmišljanja, događaje toka ili ponašanje zadržavanja, vrati jasnu pogrešku mogućnosti. Dodajte opt-in zamjenu s gubitkom samo kada programeri shvate što će biti odbačeno. Taj se pristup može činiti manje praktičnim od automatskog izravnavanja, ali sprječava najgori način kvara: aplikaciju koja se čini kompatibilnom dok tiho gubi semantiku zbog koje je uopće koristila Responses API.

Povezano čitanje

• račun tokena strujanja i otkazivanje rukovanje