MGModel Gate
Logi sisseAlustage
Juhend ja ülevaade

Looge AI API lüüsis vastuste API ühilduvuskiht

Responses API lüüs ei ole lihtsalt uue marsruudiga vestluse lõpetamise puhverserver. Säilitage esmaklassilise ühilduvuskihiga vastuseüksused, olek, tööriistakutsed, vood, arutluskäikude järjepidevus, kasutuse omistamine ja alandamise käitumine.

11 min lugedaModel Gate Editorial Team

Ärge rakendage koodi /v1/responses, tõlkides iga päringu vormingusse /v1/chat/completions ja lootes, et kujund on piisavalt lähedane. Adapter võib küll teksti tagastada, kuid see võib vaikselt kaotada osad, millest arendajad hoolivad: vastuseüksused, serveripoolne olek, tööriistakutsed, põhjenduste järjepidevus, elutsükli sündmuste voog, tühistamise semantika ja üksuse tasemel kasutuse omistamine.

Praktiline eesmärk on ühilduvuskiht, mis käsitleb Responses API-d rikkalikuma protokollina. Säilitage vestluse lõpetamise tugi olemasolevatele klientidele, kuid looge vastused oma lüüsipinnana koos oma olekumudeli, voo normaliseerija, tööriistakõnede pearaamatu, võimemaatriksi ja varureeglitega.

Mis on fakt, mis on poliitika ja mis on ennustamine?

Faktid: OpenAI kirjeldab Responses API-t kui ühendavaid võimalusi, mis olid varem jagatud vestluste lõpetamise ja abiliste vahel, sealhulgas selliste tööriistade tugi nagu veebiotsing, failiotsing ja arvutikasutus. API paljastab sellised väljad nagu previous_response_id, voogesitus, tööriistade valik ja sisseehitatud tööriistad. SDK dokumentatsioon näitab, et previous_response_id võib tagada vestluse järjepidevuse, samas kui varasemaid juhiseid ei kanta automaatselt edasi ja need tuleb uuesti saata, kui need peaksid kehtima. OpenAI voogesituse viide sisaldab pigem erinevat vastuse elutsüklit ja väljundsündmusi, mitte ainult märgide deltasid.

Soovitused: lüüs peaks selle semantika säilitama, mitte vaikimisi tasandama. Kui sihtpakkuja ei saa nõutavat käitumist toetada, peaks see taotlused tagasi lükkama või selgesõnaliselt madalamale versioonile üle minema.

Prognoos: suurem agendi töökoormus sõltub vastuse üksuse struktuurist, tööriista täitmisjälgedest ja olekupõhisest arutluskontekstist. Neid kontseptsioone praegu modelleerivaid lüüsi on lihtsam laiendada kui lüüsi, mis käsitleb vastuseid kosmeetilise lõpp-punktina.

Määratlege vastuste jaoks eraldi ühilduvusleping

Esimene rakendusviga on eeldada, et OpenAI-ga ühilduvus tähendab üht universaalset päringu- ja vastuseskeemi. Praktikas peaksid /v1/chat/completions ja /v1/responses olema eraldi ühilduvuslepingud.

Säilitage jagatud autentimis-, arveldus-, kvoodi- ja marsruutimiskiht, kuid eraldage protokollikiht.

  • Vestluse lõpetamise pind: sõnumid, valikud, deltad, tööriistakutsed vestlusvormingus, pärandkliendi käitumine.
  • Vastuse pind: sisendüksused, väljundüksused, vastuse ID-d, varasemate vastuste viited, rikkalikumad tööriistasündmused, elutsükli voo sündmused, arutluskäiguga seotud väljad ja lõplik vastuse olek.

See jaotus on vastavustestide jaoks oluline. Pakkuja adapter, mis läbib vestlustestid, võib siiski vastuste testid ebaõnnestuda, kuna see ei suuda säilitada previous_response_id, üksuste järjekorda, keeldumise struktuuri, hostitud tööriista metaandmeid ega voogesituse sündmuste nimesid.

Minimaalne ühilduvusleping peaks vastama järgmisele:

  • Millised päringuväljad aktsepteeritakse, lükatakse tagasi, muudetakse või ignoreeritakse?
  • Millised vastuseüksuse tüübid säilitatakse?
  • Milliseid tööriistatüüpe pakkuja ja mudeli järgi toetatakse?
  • Kas teenusepakkuja saab säilitada vestluse olekut või peab seda säilitama lüüs?
  • Mis juhtub, kui küsitakse store=false?
  • Millised voosündmused on garanteeritud?
  • Kuidas registreeritakse tühistamine, ajalõpp ja osaline kasutamine?

Kui teil juba on AI API lüüs, käsitlege vastuste tuge protokolli laiendusena, mitte marsruudi aliasena.

Kasutage kanoonilist vastuseüksuse mudelit

Responses API tagastab rohkem kui ühe assistendi sõnumi. See võib esindada erinevaid väljundelemente ja sündmusi. Teie lüüs vajab sisemist kanoonilist mudelit, enne kui see kaardistatakse mis tahes pakkujaga.

Praktiline sisemine üksuste skeem võib alata järgmiselt:

kood>{ "gateway_response_id": "gw_resp_...", "provider_response_id": "resp_...", "üürniku_id": "kümme_123", "key_id": "key_456", "model_alias": "agent-default", "provider": "openai", "esemed": [ { "item_id": "item_1", "tüüp": "tekst", "roll": "assistent", "content": [{ "type": "output_text", "text": "..." }], "staatus": "lõpetatud" }, { "item_id": "item_2", "type": "function_call", "call_id": "call_abc", "nimi": "otsingu_järjekord", "arguments_json": "{\"order_id\":\"123\"}", "staatus": "lõpetatud" } ], "kasutus": { "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": null, "tööriistaühikud": [] }, "staatus": "lõpetatud" }

Kaasake üksuste tüübid isegi enne, kui iga pakkuja saab neid toota. Kasulikud kategooriad on järgmised:

  • Tekstiväljund
  • Keeldumised
  • Funktsioonikutsed
  • Rakenduse esitatud funktsioonide väljundid
  • Põhjenduste kokkuvõtted või põhjendustega seotud metaandmed, kui need on saadaval
  • Failiviited
  • Veebiotsing, failiotsing, arvutikasutus või muud hostitud tööriistasündmused
  • Lõpliku kasutuse ja arvelduse metaandmed

Mõte ei ole selles, et kasutajad saaksid avalikustada patenteeritud skeemi. Asi on selles, et värav ei viskaks teavet enne, kui see saab seda auditeerida, arveldada, voogesitada, taasesitada või muuta.

Lüüsile kuuluva osariigi pearaamatu koostamine

previous_response_id on väli, mis näitab kõige enam erinevust olekuta vestluse puhverserveri ja vastuste ühilduvuse vahel. Kui klient viitab eelmisele vastusele, peab lüüs teadma, mida see ID tähendab, kas rentnikul on lubatud seda kasutada ja kas pakkuja saab sellest jätkata.

Looge üürniku ja vastuse ID abil olekureskontra:

kood>{ "gateway_response_id": "gw_resp_789", "provider_response_id": "resp_provider_789", "previous_gateway_response_id": "gw_resp_456", "üürniku_id": "kümme_123", "user_id": "user_999", "key_id": "key_456", "mudel": "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 }

Oluline reegel: ärge emuleerige automaatselt atribuuti previous_response_id, esitades uuesti täieliku vestlusajaloo, välja arvatud juhul, kui rentnik on seda säilitamis- ja kulukäitumist selgesõnaliselt lubanud. Taasesitus võib suurendada märgi maksumust, muuta privaatsusasendit ja muuta mudeli käitumist. Kindlam on tagastada selge suutlikkuse viga, kui vaikselt saata salvestatud vestluse sisu, mida rakendus ei oodanud, et te säilitaksite või taaskasutate.

Oleku käsitlemise režiimid

  • Pakkuja olek: ülesvoolu teenusepakkuja salvestab piisavalt konteksti ja lüüs seostab lüüsi vastuse ID-d pakkuja vastuse ID-dega.
  • Lüüsi olek: lüüs salvestab vajalikud eelnevad üksused ja rekonstrueerib konteksti, kui see on lubatud.
  • Olek puudub: taotluses on kasutatud store=false või üürniku eeskirjad keelavad säilitamise. previous_response_id tuleks tagasi lükata, välja arvatud juhul, kui pakkuja saab taotlust täita ilma lüüsi säilitamiseta ja eeskirjad seda lubavad.

Pidage meeles ka seda, et kliendil võib olla vaja varasemad juhised uuesti saata, kui need peaksid kehtima. Lüüs ei tohiks leiutada kompenseerimiseks peidetud juhiseid, välja arvatud juhul, kui see käitumine on osa selgesõnalisest üürnikupoliitikast.

Kinnitage tööriistad enne saatmist

Vastused muudavad tööriista kasutamise kesksemaks. Ühilduvuskiht peaks käsitlema kahte laia kategooriat:

  • Rakendustööriistad: kliendi esitatud funktsioonide määratlused, mis täidetakse väljaspool mudeli pakkujat ja mille väljundid saadetakse API-le tagasi.
  • Majutatud pakkuja tööriistad: veebiotsing, failiotsing, arvutikasutus, koodi käitamine, maandus või sarnased tööriistad, mida käivitab pakkuja või lüüsi juhitav infrastruktuur.

Sisenemisel kontrollige enne marsruutimist tööriistaskeeme:

  • Keelduge kehtetu JSON-skeem varakult tagasi.
  • Kehtige skeemi maksimaalne suurus ja pesastussügavus.
  • Kontrollige tööriistade nimede ühilduvust pakkujaga.
  • Rakendage rentniku, võtme, kasutaja ja keskkonna ulatuseid.
  • Nõua kinnitusväravaid tööriistadele, mis kirjutavad andmeid, kulutavad raha, pääsevad juurde tundlikele süsteemidele või helistavad välistele konnektoritele.

Rakenduse funktsioonide helistamiseks on vaja stabiilset kõne ID-d. Mudel väljastab funktsioonikutsega call_id; taotlus esitab sellele ID-le viitava tööriista väljundi; värav salvestab mõlemad samasse jälge. Ilma selle liitumisvõtmeta muutuvad auditilogid ja korduskatsed ebaselgeks.

Majutatud tööriistade puhul reserveerige eelarve enne saatmist ja tasuge kulud pärast seda. Hostitud tööriistad võivad lisada tasusid väljaspool tavalist märgiarvestust, seega ühendage tööriistade pearaamat ühtse AI API arveldusega, selle asemel, et peita need kulud üldise mudelikõne kogusumma sisse.

Voigedastuse normaliseerimine sündmustena, mitte märgitekstina

Vestluse puhverserver võib sageli pääseda edasisaatmise loa deltadest. Vastuste lüüs ei saa seda teha. Vool on elutsükli tähendus: vastus võib alata, väljundüksused võivad alata ja lõpule viia, tekst saabuda deltadena, tööriistakutseid saab kokku panna järk-järgult, kasutus võib jõuda voo lõpus või voo ajal ning vastus võib ebaõnnestuda või tühistada.

Määratlege lüüsi sündmuste skeem ja seejärel kaardistage iga pakkuja voog sellesse:

sündmus: vastus_alustatud
andmed: { "response_id": "gw_resp_123", "status": "in_progress" }

sündmus: output_item_startedandmed: { "item_id": "item_1", "type": "text" }

sündmus: tekst_delta
andmed: { "item_id": "item_1", "delta": "Tere" }

sündmus: tool_call_delta
andmed: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"tellimus" }

sündmus: usage_delta
andmed: { "väljundmärgid": 12}

sündmus: lõpetatud
andmed: { "response_id": "gw_resp_123", "usage": { ... } }

Soovitatavad normaliseeritud sündmused:

  • response_started
  • output_item_started
  • output_item_completed
  • tekst_delta
  • refusal_delta
  • tool_call_delta
  • tool_result_received
  • kasutus_delta
  • lõpetatud
  • tühistatud
  • ebaõnnestus

Kui klient katkestab ühenduse, levitage tühistamist ülesvoolu, kui teenusepakkuja seda toetab. Salvestage osalise vastuse olek mõlemal viisil. Kui teenusepakkuja tagastab hiljem lõppkasutuse viivitatud tagasihelistamise või lõpliku osa kaudu, ühildage pearaamat. Voogesituse ühilduvus sõltub nii arvestusest ja elutsüklist kui ka latentsusest.

Looge pakkuja võimete maatriks

Mitme mudeliga marsruutimine on kasulik ainult siis, kui lüüs mõistab, mida saab ohutult marsruutida. Lisage oma mudelikataloogi vastuste spetsiifilised võimalused:

kood>{ "model_alias": "agent-default", "marsruudid": [ { "provider": "openai", "mudel": "...", "supports_responses": tõsi, "supports_previous_response_id": tõsi, "supports_store_false": tõsi, "supports_builtin_web_search": tõsi, "supports_function_calling": tõsi, "supports_stream_lifecycle_events": tõsi, "supports_reasoning_context_continuity": tõsi, "max_tool_schema_bytes": 65536 }, { "provider": "provider_b", "mudel": "...", "supports_responses": vale, "chat_adapter_available": tõsi, "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"] } ] }

Tagavara peaks olema kahjuteadlik. Kui päring nõuab sisseehitatud veebiotsingut ja varupakkuja ei saa seda teha, ärge vastake vaikselt ilma otsinguta. Kui taotlus sõltub säilinud arutluskontekstist ja varumarsruut ei saa seda säilitada, tagastage võimekuse viga või vastus alandamisele, mille klient sõnaselgelt lubas.

Kasulik päringuvalik on:

kood>{ "mudel": "agent-default", "input": "...", "fallback_policy": { "allow_lossy": vale, "allowed_losses": [] } }

Vähem tundlikel kasutusjuhtudel võivad üürnikud lubada konkreetseid kadudega madalamaid versioone.

kood>{ "fallback_policy": { "allow_lossy": tõsi, "allowed_losses": ["flattened_stream", "no_reasoning_summary"] } }

Lüüs peaks varuotsuse mõlemal juhul logima. See muudab hilisema silumise võimalikuks, kui agent käitub pärast pakkuja katkestust või mudeli ümbersuunamist teisiti.

Atribuudi kasutamine vastuse ja üksuse tasemel

Vastuskõned võivad maksta rohkem kui samaväärsed vestluse lõpetamised, kuna need võivad hõlmata tööriista täitmist, pikemat konteksti, arutlusmärke, failiotsingut, veebiotsingut või korduvaid juhiseid. AI API kasutusanalüüsi juhtpaneeli jaoks ei piisa ühest koondlubade arvust.

Kasutamise salvestamine kahel tasemel:

  • Vastuse tase: rentnik, võti, kasutaja, mudel, pakkuja, latentsusaeg, lõplik olek, sisendmärgid, väljundmärgid, põhjenduste märgid, kui need on esitatud, kogukulu ja varumarsruut.
  • Üksuse/tööriista tase: tööriista nimi, kõne ID, hostitud tööriistaüksused, faili ID-d, otsingupäringute arv, kui see on saadaval, tööriista latentsusaeg, tööriista maksumus ja kinnituspoliitika tulemus.

See võimaldab arendajatel vastata konkreetsetele küsimustele:

  • Kas kulud suurenesid pikema oleku, arutluskäigu, tööriistakutsete või tagavara tõttu?
  • Milline rentnik või API võti genereerib hostitud tööriista tasu?
  • Milline vastus ebaõnnestus pärast tööriista kutsumist, kuid enne lõplikku teksti?
  • Milliseid tühistatud voogusid veel ülesvoolu kasutati?

Käsitlege null-säilitamist ja kustutamist esmaklassilise käitumisena

Serveripoolne olek on kasulik, kuid see muudab lüüsi säilitamiskohustusi. Ehitage poliitika protokollikihi sisse, selle asemel, et käsitleda seda logimisseadena.

Iga vastusetaotluse puhul lahendage:

  • Üürniku säilitamise eeskirjad
  • Taotluse taseme poe eelistus
  • Pakkuja säilitamise ühilduvus
  • Kas lüüsi kordus on lubatud?
  • Kas tööriista sisendeid ja väljundeid saab salvestada
  • Vastuseoleku aegumise ja kustutamise käitumine

Kui säilitamine on keelatud, võib lüüs siiski säilitada minimaalselt operatiivseid metaandmeid: ajatemplid, ID-d, olek, lubade arv, kulu ja poliitikaotsused. Vältige töötlemata viipade, täielike tööriistaväljundite või rekonstrueeritud ajaloo salvestamist, kui eeskirjad seda ei luba.

Enne käivitamist lisatavad vastavusseadmed

Ärge lootke õnneliku tee käsitsitestidele. Lisage seadmed, mis kontrollivad protokolli käitumist otsestel OpenAI marsruutidel, pakkuja kohandatud marsruutidel ja varustsenaariumides.

Minimaalne testikomplekt

  • Põhivastus: tekstiüksus tagastatakse stabiilse vastuse ID ja kasutusega.
  • Mitme pöörde olek: teise päringu viited previous_response_id; lüüs kinnitab rentniku omandiõiguse ja olekurežiimi.
  • Korduvad juhised: veenduge, et lüüs ei leiutaks vaikselt välja jäetud juhiseid.
  • Funktsioonikõne edasi-tagasi reis: mudel väljastab kõne ID; taotlus esitab väljundi; lõplik vastus ühendab mõlemad kirjed.
  • Hostitud tööriista eeskirjad: volitamata sisseehitatud tööriist blokeeritakse enne saatmist.
  • Voogesituse järjekord: vastuse algus, üksuse algus, deltad, üksuse valmimine, kasutamine ja lõpetamine väljastatakse kehtivas järjekorras.
  • Voo tühistamine: kliendi katkestamine käivitab ülesvoolu tühistamise, kui seda toetatakse, ja salvestab osalise kasutuse.
  • Tagasilükkamine: ilma nõutud vastuste semantika pakkuja tagastab võime vea.
  • Kaotusega varulubamine: lubatud kahjudega taotlus saab selgesõnalise alandamise markeri.
  • Null-säilitusrežiim: oleku taasesitus ja lüüsipoolne viipade säilitamine on blokeeritud.

Soovitatav levitamise järjestus

  1. Avatage beeta marsruut. Lisage /v1/responses olemasolevat vestluskäitumist muutmata.
  2. Rakendage esmalt native Responses toega teenusepakkujate jaoks edastamine. Säilitage ID-d, üksused, vood, kasutus ja vead.
  3. Lisage osariigi pearaamat. Seotage lüüsi ID-d pakkuja ID-dega ja jõustage rentniku omandiõigus.
  4. Lisage kanoonilisi üksusi. Salvestage üksuste metaandmed, mis on vajalikud auditeerimiseks, arveldamiseks ja voo taastamiseks.
  5. Lisage tööriistade haldust. Kinnitage skeeme, jõustage ulatusi ja salvestage tööriistakutsingu liite.
  6. Lisage voogesituse normaliseerimine. Teisendage teenusepakkujapõhised vood lüüsi elutsükli sündmusteks.
  7. Lisage võimeteadlik marsruutimine. Lubage vaikimisi ainult turvalised varud.
  8. Lisage analüütika ja arveldusarve. Atribuudi tunnus, põhjendus ja tööriistakasutus eraldi.
  9. Avaldage ühilduvusmärkmeid. Öelge arendajatele, millised väljad on loomulikud, emuleeritud, toetamata või kadudega.

Tehtitav järeldus

Responses API ühilduvuskiht peaks säilitama protokolli tähenduse, mitte lihtsalt tagastama usutava teksti. Ehitage see viie vastupidava objekti ümber: kanooniline vastuse üksuse mudel, vestluse oleku pearaamat, tööriistade helistamise pearaamat, voogesituse sündmuste normaliseerija ja pakkuja võimete maatriks.

Kõige turvalisem vaikeseade on range ühilduvus: kui marsruut ei suuda säilitada nõutavat olekut, tööriistu, arutluskonteksti, voosündmusi või säilituskäitumist, tagastab selge võimevea. Lisage lubamise kadudega tagavara ainult siis, kui arendajad mõistavad, millest loobutakse. See lähenemine võib tunduda vähem mugav kui automaatne lamendamine, kuid see hoiab ära halvima tõrkerežiimi: rakenduse, mis näib ühilduvat, kaotades samal ajal vaikselt semantika, mis pani selle esmalt kasutama Responses API-t.

Seotud lugemine

FAQ

Korduma kippuvad küsimused

Kas lüüs saab rakendada Responses API-t, tõlkides kõik vestluse lõpetamiseks?
Ainult kitsale kadudega alamhulgale. Põhiteksti genereerimine võib toimida, kuid olek, vastuseüksused, hostitud tööriistad, arutluskäiguga seotud kontekst, keeldumise struktuur, voo elutsükli sündmused ja üksusetaseme kasutus võivad kaotsi minna. Tootmisvärav peaks avaldama vastused eraldi ühilduvuspinnana.
Kas lüüs peaks taasesitama salvestatud vestluste ajaloo, et emuleerida previous_response_id?
Vaikimisi mitte. Taasesitus muudab säilitamiskäitumist, kulusid ja mõnikord ka mudeli käitumist. Üürnik peaks selgesõnaliselt lubama lüüsipoolse oleku säilitamise ja taasesituse, enne kui lüüs seda strateegiat kasutab.
Mis peaks juhtuma, kui varupakkujad ei saa vastuste semantikat toetada?
Kõige turvalisem vaikeseade on võimeviga. Kui rentnik valib kadudeta varu, peaks lüüs tagastama selgesõnalise alandamise markeri ja registreerima, milline semantika loobuti.
Miks registreerida kasutust vastuseüksuse tasemel?
Vastuskutsed võivad hõlmata tööriistakutseid, hostitud tööriistatasusid, arutlusmärke, osalisi vooge ja varukäitumist. Üksuse tasemel kasutamine muudab arveldamise, silumise ja rentniku analüüsi selgitatavaks.
Jätka lugemist

Seotud artiklid

Vaata kõiki artikleid →

AI API lüüside juhtimistasandi kontrolljäljed: võtme-, rentniku- ja kulumuudatuste rekonstrueerimine intsidentide ajal

Käitusaja logid selgitavad mudelikutseid, kuid juhtumite vastus sõltub sageli administraatori ajaloost: kes lõi võtme, muutis kululimiiti, reklaamis marsruutimisprofiili või tühistas juurdepääsu. Looge ainult lisatav kontrolljälg, mis ühendab lüüsi, partneri API, identiteedi, pakkuja ja kasutussündmusi ilma vaikimisi töötlemata viipasid salvestamata.

Loe artiklit →

MCP-ühenduse haldamine AI API lüüsi kaudu: OAuthi märgid, tööriistade ulatus ja kasutajapõhine omistamine

Kaug-MCP-serverid ja teenusekonnektorid muudavad agentide töövood kasulikuks, kuid teisaldavad ka autoriseerimise, säilitamise ja intsidentidele reageerimise mudelikutsest väljapoole. Käsitlege konnektori autoriseerimist lüüsi juhttasandi objektina: loa elutsükkel, ulatuse poliitika, kinnituse kontrollid, tühistamise olek ja ühendatud auditi logid.

Loe artiklit →