Hozzon létre egy Responses API-kompatibilitási réteget egy AI API-átjáróban

Ne valósítsa meg a /v1/responses parancsot úgy, hogy minden kérést lefordít a /v1/chat/completions nyelvre, és reméli, hogy az alakzat elég közel van. Ez az adapter visszaadhat szöveget, de csendben elveszítheti azokat a részeket, amelyek a fejlesztők számára fontosak: válaszelemek, szerveroldali állapot, eszközhívások, érvelési folytonosság, adatfolyam életciklus-események, törlési szemantika és elemszintű használati hozzárendelés.

A gyakorlati cél egy olyan kompatibilitási réteg, amely a Responses API-t gazdagabb protokollként kezeli. Tartsa meg a Chat Completions támogatást a meglévő ügyfelek számára, de építse fel a Válaszokat saját átjárófelületként saját állapotmodelljével, folyamnormalizálójával, eszközhívási főkönyvével, képességmátrixával és tartalékszabályaival.

Mi a tényszerűség, mi a politika és mi az előrejelzés?

Tények: Az OpenAI leírása szerint a Responses API olyan egyesítő képességek, amelyeket korábban a Chat Completions és Assistant között osztottak fel, beleértve az olyan eszközök támogatását, mint az internetes keresés, a fájlkeresés és a számítógéphasználat. Az API olyan mezőket tesz közzé, mint a previous_response_id, az adatfolyam, az eszközválasztás és a beépített eszközök. Az SDK dokumentációja azt mutatja, hogy a previous_response_id biztosíthatja a beszélgetés folytonosságát, míg a korábbi utasítások nem kerülnek automatikusan továbbításra, és újra el kell küldeni őket, amikor még érvényesek. Az OpenAI streaming referenciája külön válaszéletciklust és kimeneti eseményeket tartalmaz, nem csak token-deltákat.

Javaslatok: Az átjárónak meg kell őriznie ezeket a szemantikákat, nem pedig alapértelmezés szerint kiegyenlítenie őket. El kell utasítania vagy kifejezetten vissza kell állítania a kéréseket, ha a célszolgáltató nem tudja támogatni a szükséges viselkedést.

Előrejelzés: Több ügynöki munkaterhelés függ a válaszelem szerkezetétől, az eszköz végrehajtási nyomaitól és az állapotalapú érvelési kontextustól. Azokat az átjárókat, amelyek most modellezik ezeket a koncepciókat, könnyebb lesz kiterjeszteni, mint azokat az átjárókat, amelyek a válaszokat kozmetikai végpontként kezelik.

Határozzon meg egy külön kompatibilitási szerződést a válaszokhoz

Az első megvalósítási hiba azt feltételezi, hogy az OpenAI-kompatibilis egyetlen univerzális kérés- és válaszsémát jelent. A gyakorlatban a /v1/chat/completions és a /v1/responses külön kompatibilitási szerződésnek kell lennie.

Maradjon megosztott hitelesítési, számlázási, kvóta- és útválasztási réteg, de válassza szét a protokollréteget:

• Csevegés befejezésének felülete: üzenetek, választási lehetőségek, delták, eszközhívások csevegési formátumban, régi kliens viselkedés.
• Válaszfelület: bemeneti elemek, kimeneti elemek, válaszazonosítók, korábbi válaszreferenciák, gazdagabb eszközesemények, életciklus-folyam eseményei, érveléssel kapcsolatos mezők és végső válaszállapot.

Ez a felosztás számít a megfelelőségi teszteknél. A csevegési teszteken átmenő szolgáltatói adapter továbbra is sikertelen lehet a választeszteken, mert nem tudja megőrizni a previous_response_id elemet, a tételek sorrendjét, az elutasítási struktúrát, a tárolt eszköz metaadatait vagy a streamelési események neveit.

A minimális kompatibilitási szerződésnek a következő választ kell adnia:

• Mely kérésmezőket fogadja el, utasítja el, alakítja át vagy hagyja figyelmen kívül?
• Mely válaszelem-típusok maradnak meg?
• Mely eszköztípusok támogatottak szolgáltatónként és modellenként?
• A szolgáltató fenntarthatja a beszélgetés állapotát, vagy az átjárónak kell fenntartania?
• Mi történik, ha a store=false kódot kérik?
• Milyen streamesemények garantáltak?
• Hogyan rögzítik a törlést, az időtúllépést és a részleges használatot?

Ha már rendelkezik AI API-átjáróval, a Responses támogatást protokollbővítésként kezelje, ne útvonal-aliasként.

Használjon kanonikus válaszelem-modellt

A Responses API egynél több segédüzenetet ad vissza. Különböző kimeneti elemeket és eseményeket képviselhet. Az átjárónak belső kanonikus modellre van szüksége, mielőtt bármely szolgáltatóhoz leképezné.

Egy gyakorlati belső tételséma a következőképpen kezdődhet:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "bérlő_azonosítója": "tíz_123",
  "key_id": "key_456",
  "model_alias": "agent-default",
  "szolgáltató": "openai",
  "elemek": [
    {
      "item_id": "item_1",
      "type": "text",
      "role": "asszisztens",
      "content": [{ "type": "output_text", "text": "..." }],
      "állapot": "befejezett"
    },
    {
      "item_id": "item_2",
      "type": "function_call",
      "call_id": "call_abc",
      "name": "lookup_order",
      "arguments_json": "{\"order_id\":\"123\"}",
      "állapot": "befejezett"
    }
  ],
  "használat": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "eszköz_egységek": []
  },
  "állapot": "befejezett"
}

Még azelőtt adja meg a cikktípusokat, hogy minden szolgáltató elkészíthetné azokat. A hasznos kategóriák a következők:

• Szövegkimenet
• Elutasítások
• Funkcióhívások
• Az alkalmazás által benyújtott funkciók kimenetei
• Érvelési összefoglalók vagy érveléshez kapcsolódó metaadatok, ahol rendelkezésre állnak
• Fájlhivatkozások
• Webes keresés, fájlkeresés, számítógép-használat vagy egyéb tárolt eszközesemények
• Végső használati és számlázási metaadatok

A lényeg nem az, hogy egy szabadalmaztatott sémát tárjanak fel a felhasználók számára. A lényeg az, hogy az átjáró ne dobja el az információkat, mielőtt azokat auditálni, számlázni, streamelni, visszajátszani vagy átalakítani tudná.

Átjáró tulajdonában lévő állami főkönyv készítése

previous_response_id az a mező, amely leginkább felfedi az állapot nélküli csevegési proxy és a válaszok kompatibilitás közötti különbséget. Ha egy ügyfél egy korábbi válaszra hivatkozik, az átjárónak tudnia kell, hogy mit jelent az azonosító, hogy a bérlő használhatja-e, és hogy a szolgáltató folytathatja-e azt.

Hozzon létre egy állapotkönyvet a bérlővel és a válaszazonosítóval:

{
  "gateway_response_id": "gw_resp_789",
  "provider_response_id": "resp_provider_789",
  "previous_gateway_response_id": "gw_resp_456",
  "bérlő_azonosítója": "tíz_123",
  "user_id": "user_999",
  "key_id": "key_456",
  "modell": "gpt-...",
  "szolgáltató": "openai",
  "store_mode": "szolgáltató|átjáró|nincs",
  "retention_policy": "standard|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": null
}

Fontos szabály: ne emulálja automatikusan a previous_response_id-t a teljes csevegési előzmények újrajátszásával, kivéve, ha a bérlő kifejezetten engedélyezte ezt a megőrzési és költségviselkedést. Az újrajátszás növelheti a token költségét, megváltoztathatja az adatvédelmi testtartást és megváltoztathatja a modell viselkedését. Biztonságosabb egyértelmű képességhibát visszaadni, mint csendben elküldeni a tárolt beszélgetési tartalmat, amelyre az alkalmazás nem számított, hogy megőrizze vagy újra felhasználja.

Állapotkezelési módok

• Szolgáltató állapota: Az upstream szolgáltató elegendő kontextust tárol, és az átjáró leképezi az átjáró válaszazonosítóit a szolgáltató válaszazonosítóira.
• Átjáró állapota: Az átjáró tárolja a szükséges korábbi elemeket, és rekonstruálja a kontextust, ha engedélyezve van.
• Nincs állapot: A kérelem a store=false kódot használja, vagy a bérlői szabályzat tiltja a megőrzést. A previous_response_id értéket el kell utasítani, hacsak a szolgáltató nem tudja teljesíteni a kérést az átjáró megtartása nélkül, és a házirend ezt lehetővé teszi.

Ne feledje továbbá, hogy előfordulhat, hogy az ügyfélnek újra el kell küldenie a korábbi utasításokat, amikor továbbra is alkalmazni kell azokat. Az átjáró nem találhat ki rejtett utasításokat a kompenzáció érdekében, kivéve, ha ez a viselkedés egy kifejezett bérlői szabályzat része.

Elküldés előtt ellenőrizze az eszközöket

A válaszok központibbá teszik az eszközhasználatot. A kompatibilitási rétegnek két nagy kategóriát kell kezelnie:

• Alkalmazási eszközök: Az ügyfél által biztosított függvénydefiníciók, a modellszolgáltatón kívül végrehajtva, az API-nak visszaküldött kimenetekkel.
• Hostolt szolgáltatói eszközök: Internetes keresés, fájlkeresés, számítógéphasználat, kódvégrehajtás, földelés vagy hasonló eszközök, amelyeket a szolgáltató vagy az átjáró által vezérelt infrastruktúra hajt végre.

Belépéskor ellenőrizze az eszközsémákat az útválasztás előtt:

• Az érvénytelen JSON-séma korai elutasítása.
• A maximális sémaméret és beágyazási mélység kényszerítése.
• Ellenőrizze az eszköznevek szolgáltatói kompatibilitását.
• Alkalmazza a bérlői, kulcs-, felhasználói- és környezeti hatóköröket.
• Jóváhagyási kaput kell megkövetelni olyan eszközökhöz, amelyek adatokat írnak, pénzt költenek, érzékeny rendszerekhez hozzáférnek vagy külső csatlakozókat hívnak.

Alkalmazásfunkciók hívásához stabil hívásazonosító szükséges. A modell függvényhívást bocsát ki a következővel: call_id; az alkalmazás benyújtja az eszköz kimenetét az adott azonosítóra hivatkozva; az átjáró mindkettőt ugyanabban a nyomvonalban rögzíti. A csatlakozási kulcs nélkül a megfigyelési naplók és az újrapróbálkozások nem egyértelműek.

A tárolt eszközök esetében foglaljon le költségvetést a feladás előtt, és utána rendezze a költségeket. A tárolt eszközök a szokásos token-elszámoláson kívül is hozzáadhatnak költségeket, ezért csatlakoztassa az eszközkönyvet az egységes AI API-számlázáshoz, ahelyett, hogy ezeket a költségeket egy általános modellhívás-összegbe rejtené.

A streamelés normalizálása eseményként, nem token szövegként

A csevegőproxy gyakran megúszhatja a továbbítási token deltákat. A Responses Gateway nem tud. A streamnek életciklus-jelentése van: a válasz elindulhat, a kimeneti elemek elindulhatnak és befejeződhetnek, szöveg érkezhet deltában, az eszközhívások fokozatosan összeállíthatók, a használat a stream végén vagy közben érkezhet, és a válasz meghiúsulhat vagy törölhető.

Határozza meg az átjáró eseménysémáját, majd rendelje hozzá az egyes szolgáltatói adatfolyamokat:

esemény: response_started
adatok: { "response_id": "gw_resp_123", "status": "in_progress" }

esemény: output_item_startedadatok: { "item_id": "item_1", "type": "text" }

esemény: text_delta
adatok: { "item_id": "item_1", "delta": "Hello" }

esemény: tool_call_delta
adatok: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"rendelés" }

esemény: usage_delta
adatok: { "output_tokens": 12}

esemény: befejeződött
adatok: { "response_id": "gw_resp_123", "usage": { ... } }

Javasolt normalizált események:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• result_result_received
• használati_delta
• befejezve
• törölve
• sikertelen

Amikor a kliens megszakítja a kapcsolatot, terjessze a törlést felfelé, ha a szolgáltató támogatja. Mindkét módon rögzítse a részleges válasz állapotát. Ha a szolgáltató később késleltetett visszahíváson vagy végső részleten keresztül visszaadja a végső felhasználást, egyeztetje a főkönyvet. Az adatfolyam-kompatibilitás éppúgy a könyvelésről és az életciklusról szól, mint a késleltetésről.

Hozzon létre egy szolgáltatói képességmátrixot

A többmodelles útválasztás csak akkor hasznos, ha az átjáró megérti, hogy mi irányítható biztonságosan. Adjon hozzá válaszspecifikus képességeket modellkatalógusához:

{
  "model_alias": "agent-default",
  "útvonalak": [
    {
      "szolgáltató": "openai",
      "modell": "...",
      "supports_responses": igaz,
      "supports_previous_response_id": igaz,
      "supports_store_false": igaz,
      "supports_builtin_web_search": igaz,
      "supports_function_calling": igaz,
      "supports_stream_lifecycle_events": igaz,
      "supports_reasoning_context_continuity": igaz,
      "max_tool_schema_bytes": 65536
    },
    {
      "szolgáltató": "szolgáltató_b",
      "modell": "...",
      "supports_responses": hamis,
      "chat_adapter_available": igaz,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

A tartaléknak tudatában kell lennie a veszteségnek. Ha a kérés beépített webes keresést igényel, és a tartalék szolgáltató nem tudja végrehajtani, ne válaszoljon csendben keresés nélkül. Ha a kérés a megőrzött érvelési kontextustól függ, és a tartalék útvonal nem tudja megőrizni, adjon vissza egy képességhibát vagy egy olyan visszaminősítési választ, amelyet az ügyfél kifejezetten engedélyez.

Hasznos kérési lehetőség:

{
  "modell": "agent-default",
  "input": "...",
  "fallback_policy": {
    "allow_lossy": hamis,
    "allowed_losses": []
  }
}

Kevésbé kényes használati esetekben a bérlők bizonyos veszteséges visszaminősítéseket engedélyezhetnek:

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

Az átjárónak mindkét esetben naplóznia kell a tartalék döntést. Ez lehetővé teszi a későbbi hibakeresést, amikor egy ügynök másként viselkedik a szolgáltató leállása vagy a modell átirányítása után.

Attribútumhasználat válasz- és elemszinten

A válaszhívások többe kerülhetnek, mint az egyenértékű csevegés befejezése, mert tartalmazhatnak eszköz végrehajtását, hosszabb kontextust, érvelési tokeneket, fájlkeresést, internetes keresést vagy ismételt utasításokat. Egyetlen összesített tokenszám nem elegendő egy AI API használati elemzési irányítópulthoz.

A használat rögzítése két szinten:

• Válaszszint: bérlő, kulcs, felhasználó, modell, szolgáltató, várakozási idő, végső állapot, beviteli tokenek, kimeneti tokenek, érvelési tokenek, ahol jelentették, teljes költség és tartalék útvonal.
• Elem/eszköz szint: az eszköz neve, hívásazonosító, tárolt eszközegységek, fájlazonosítók, keresési lekérdezések száma, ha elérhető, az eszköz késleltetése, az eszköz költsége és a jóváhagyási irányelv eredménye.

Ezzel a fejlesztők konkrét kérdésekre válaszolhatnak:

• Növekedtek a költségek a hosszabb állapot, az érvelési erőfeszítés, az eszközhívások vagy a tartalék miatt?
• Melyik bérlő vagy API-kulcs generálja a tárolt eszköz díjait?
• Melyik válasz sikertelen az eszközhívás után, de a végső szöveg előtt?
• Melyik törölt közvetítéseket használták még felfelé?

A nulla megőrzést és a törlést első osztályú viselkedésként kezelje

A kiszolgálóoldali állapot hasznos, de megváltoztatja az átjáró megőrzési kötelezettségeit. Építse be a házirendet a protokollrétegbe ahelyett, hogy naplózási beállításként kezelné.

Minden válaszkéréshez oldja meg a következőt:

• Bérlői megőrzési szabályzat
• Kérés szintű üzlet preferencia
• Szolgáltatói adatmegőrzési kompatibilitás
• Engedélyezett-e az átjáró-visszajátszás?
• A szerszámbemenetek és -kimenetek tárolhatók-e
• Lejárati és törlési viselkedés a válaszállapothoz

Ha a megőrzés le van tiltva, az átjáró továbbra is minimális működési metaadatot tarthat meg: időbélyegeket, azonosítókat, állapotot, tokenszámot, költségeket és irányelveket. Kerülje a nyers promptok, a teljes eszközkimenetek vagy a rekonstruált előzmények tárolását, hacsak a szabályzat nem engedi.

Információ előtt hozzáadandó megfelelő fixtures

Ne hagyatkozzon a boldog út kézi tesztjére. Adjon hozzá olyan rögzítőket, amelyek ellenőrzik a protokoll viselkedését a közvetlen OpenAI útvonalakon, a szolgáltatóhoz igazított útvonalakon és tartalék forgatókönyveken.

Minimális tesztkészlet

• Alap válasz: a szöveges elem stabil válaszazonosítóval és használattal kerül visszaadásra.
• Többfordulós állapot: a második kérés hivatkozásai: previous_response_id; az átjáró ellenőrzi a bérlői tulajdonjogot és az állapot módot.
• Ismétlődő utasítások: ellenőrizze, hogy a kihagyott utasításokat nem az átjáró találta ki csendben.
• Funkcióhívás oda-vissza: a modell hívásazonosítót bocsát ki; a pályázat kimenetet nyújt be; a végső válasz mindkét rekordhoz csatlakozik.
• Hosztolt eszközre vonatkozó szabályzat: a jogosulatlan beépített eszközt a rendszer blokkolja a feladás előtt.
• Streamelési sorrend: a válasz kezdete, az elem indítása, a delták, a tétel befejezése, a használat és a befejezés érvényes sorrendben.
• Adatfolyam megszakítása: az ügyfélkapcsolat leválasztása felfelé irányuló lemondást vált ki, ahol ez támogatott, és rögzíti a részleges használatot.
• Tartalék elutasítás: a szolgáltató a kötelező válaszok szemantikája nélkül képességhibát ad vissza.
• Veszteséges tartalék feliratkozás: az engedélyezett veszteségeket tartalmazó kérelem kifejezett visszaminősítési jelzőt kap.
• Zéró megőrzési mód: az állapotvisszajátszás és az átjáróoldali felszólítás megőrzése le van tiltva.

Ajánlott közzétételi sorrend

1. Nyomja meg a béta útvonalat. Adja hozzá a /v1/responses elemet a meglévő csevegési viselkedés megváltoztatása nélkül.
2. Először a natív válaszok támogatásával rendelkező szolgáltatók esetében valósítsa meg az áthárítást. Őrizze meg az azonosítókat, elemeket, adatfolyamokat, használatot és hibákat.
3. Adja hozzá az állapotkönyvet. Az átjáró-azonosítók hozzárendelése a szolgáltatói azonosítókhoz, és érvényesítse a bérlői tulajdonjogot.
4. Kanonikus elemek hozzáadása. Tárolja az ellenőrzéshez, számlázáshoz és adatfolyam-rekonstrukcióhoz szükséges elemek metaadatait.
5. Eszközirányítás hozzáadása. Érvényesítse a sémákat, kényszerítse ki a hatóköröket, és rögzítse az eszközhívásos összekapcsolásokat.
6. Adjon hozzá adatfolyam-normalizálást. A szolgáltató-specifikus adatfolyamokat átjáró életciklus-eseményekké alakíthatja.
7. Adjon hozzá képesség-tudatos útválasztást. Alapértelmezés szerint csak biztonságos tartalékokat engedélyez.
8. Analitika és számlázási elszámolás hozzáadása. A tokent, az érvelést és az eszközhasználatot külön adja meg.
9. Tegyen közzé kompatibilitási megjegyzéseket. Mondja el a fejlesztőknek, hogy mely mezők natívak, emuláltak, nem támogatottak vagy veszteségesek.

Intézhető következtetés

A Responses API kompatibilitási rétegnek meg kell őriznie a protokoll jelentését, nem csupán elfogadható szöveget kell visszaadnia. Építse fel öt tartós objektum köré: egy kanonikus válaszelem-modell, egy beszélgetési állapot főkönyv, egy eszközhívási főkönyv, egy adatfolyam-esemény-normalizáló és egy szolgáltatói képességmátrix.

A legbiztonságosabb alapértelmezés a szigorú kompatibilitás: ha egy útvonal nem tudja megőrizni a szükséges állapotot, eszközöket, érvelési kontextust, adatfolyam-eseményeket vagy megőrzési viselkedést, egyértelmű képességhibát ad vissza. Csak akkor adjon hozzá veszteséges tartalékot, ha a fejlesztők megértik, hogy mi kerül eldobásra. Lehet, hogy ez a megközelítés kevésbé kényelmes, mint az automatikus kiegyenlítés, de megakadályozza a legrosszabb hibaüzenetet: egy olyan alkalmazást, amely kompatibilisnek tűnik, miközben csendben elveszti azt a szemantikát, amely eleve a Responses API használatára késztette.

Kapcsolódó olvasmány

• kezelés