Izveidojiet Responses API saderības slāni AI API vārtejā

Neieviesiet /v1/responses, pārvēršot katru pieprasījumu par /v1/chat/completions un cerot, ka forma ir pietiekami tuvu. Šis adapteris var atgriezt tekstu, taču tas var klusi pazaudēt izstrādātājiem rūpīgās daļas: atbildes vienumus, servera puses stāvokli, rīku izsaukumus, argumentācijas nepārtrauktību, straumēšanas dzīves cikla notikumus, atcelšanas semantiku un vienuma līmeņa lietojuma attiecinājumu.

Praktiskais mērķis ir saderības slānis, kas uztver Responses API kā bagātāku protokolu. Saglabājiet tērzēšanas pabeigšanas atbalstu esošajiem klientiem, bet veidojiet atbildes kā savu vārtejas virsmu ar savu stāvokļa modeli, straumes normalizētāju, rīku izsaukuma virsgrāmatu, iespēju matricu un atkāpšanās kārtulām.

Kas ir fakti, kas ir politika un kas ir prognozēšana?

Fakti: OpenAI apraksta Responses API kā vienojošas iespējas, kas iepriekš tika sadalītas starp tērzēšanas pabeigšanu un palīgiem, tostarp atbalstu tādiem rīkiem kā meklēšana tīmeklī, failu meklēšana un datora lietošana. API atklāj tādus laukus kā previous_response_id, straumēšana, rīku atlase un iebūvētie rīki. SDK dokumentācijā norādīts, ka previous_response_id var nodrošināt sarunas nepārtrauktību, savukārt iepriekšējie norādījumi netiek automātiski pārnesti, un tie ir jānosūta atkārtoti, kad tie joprojām ir spēkā. OpenAI straumēšanas atsauce ietver atšķirīgus atbildes dzīves ciklu un izvades notikumus, nevis tikai marķiera deltas.

Ieteikumi: vārtejai ir jāsaglabā šī semantika, nevis jāsaplauc tā pēc noklusējuma. Tai ir jānoraida vai nepārprotami jāpazemina pieprasījumi, ja mērķa nodrošinātājs nevar atbalstīt nepieciešamo darbību.

Paredzēšana: lielāka aģenta darba slodze būs atkarīga no atbildes vienumu struktūras, rīka izpildes trasēm un statusa argumentācijas konteksta. Vārtejas, kas tagad modelē šīs koncepcijas, būs vieglāk paplašināmas nekā vārtejas, kurās atbildes tiek uzskatītas par kosmētisku galapunktu.

Definējiet atsevišķu atbilžu saderības līgumu

Pirmā ieviešanas kļūda ir pieņemt, ka ar OpenAI saderīga ir viena universāla pieprasījuma un atbildes shēma. Praksē /v1/chat/completions un /v1/responses ir jābūt atsevišķiem saderības līgumiem.

Saglabājiet koplietotu autentifikācijas, norēķinu, kvotu un maršrutēšanas slāni, bet atdaliet protokola slāni:

• Tērzēšanas pabeigšanas virsma: ziņojumi, izvēles, deltas, rīku izsaukumi tērzēšanas formātā, mantotā klienta darbība.
• Atbilžu virsma: ievades vienumi, izvades vienumi, atbilžu ID, iepriekšējo atbilžu atsauces, bagātīgāki rīku notikumi, dzīves cikla straumes notikumi, ar argumentāciju saistīti lauki un galīgais atbildes stāvoklis.

Šis sadalījums ir svarīgs atbilstības pārbaudēm. Pakalpojumu sniedzēja adapteris, kas iztur tērzēšanas testus, joprojām var neizdoties atbilžu testos, jo tas nevar saglabāt previous_response_id, preču pasūtījumu, atteikuma struktūru, mitinātā rīka metadatus vai straumēšanas notikumu nosaukumus.

Minimālajam saderības līgumam ir jāatbild uz:

• Kuri pieprasījuma lauki tiek pieņemti, noraidīti, pārveidoti vai ignorēti?
• Kuri atbildes vienumu veidi tiek saglabāti?
• Kuri rīku veidi tiek atbalstīti katram pakalpojumu sniedzējam un modelim?
• Vai pakalpojumu sniedzējs var uzturēt sarunas stāvokli vai vārtejai tas ir jāuztur?
• Kas notiek, ja tiek pieprasīts store=false?
• Kādi straumēšanas pasākumi tiek garantēti?
• Kā tiek reģistrēta atcelšana, taimauts un daļēja izmantošana?

Ja jums jau ir AI API vārteja, uzskatiet atbilžu atbalstu kā protokola paplašinājumu, nevis maršruta aizstājvārdu.

Izmantojiet kanonisko atbildes vienuma modeli

Atbilžu API atgriež vairāk nekā vienu asistenta ziņojumu. Tas var attēlot dažādus izvades vienumus un notikumus. Jūsu vārtejai ir nepieciešams iekšējs kanoniskais modelis, pirms tā tiek kartēta ar jebkuru pakalpojumu sniedzēju.

Praktiska iekšējā vienumu shēma var sākties šādi:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-default",
  "provider": "openai",
  "preces": [
    {
      "item_id": "item_1",
      "tips": "teksts",
      "loma": "palīgs",
      "content": [{ "type": "output_text", "text": "..." }],
      "statuss": "pabeigts"
    },
    {
      "item_id": "item_2",
      "tips": "function_call",
      "call_id": "call_abc",
      "name": "lookup_order",
      "arguments_json": "{\"order_id\":\"123\"}",
      "statuss": "pabeigts"
    }
  ],
  "izmantošana": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "rīku_vienības": []
  },
  "statuss": "pabeigts"
}

Iekļaujiet vienumu veidus pat pirms katrs pakalpojumu sniedzējs var tos ražot. Noderīgas kategorijas ir šādas:

• Teksta izvade
• Atteikumi
• Funkciju izsaukumi
• Lietojumprogrammas iesniegtie funkciju rezultāti
• Pamatojumu kopsavilkumi vai ar pamatojumu saistīti metadati, ja tie ir pieejami
• Failu atsauces
• Meklēšana tīmeklī, failu meklēšana, datora lietošana vai citi mitināti rīka pasākumi
• Galīgā lietojuma un norēķinu metadati

Nolūks nav atklāt lietotājiem patentētu shēmu. Mērķis ir nodrošināt, lai vārteja neizmestu informāciju, pirms tā var to pārbaudīt, rēķināt, straumēt, atskaņot vai pārveidot.

Veidojiet vārtejai piederošu valsts virsgrāmatu

previous_response_id ir lauks, kas visvairāk atklāj atšķirību starp bezvalsts tērzēšanas starpniekserveri un atbilžu saderību. Ja klients atsaucas uz iepriekšējo atbildi, vārtejai ir jāzina, ko šis ID nozīmē, vai nomniekam ir atļauts to izmantot un vai pakalpojumu sniedzējs var to turpināt.

Izveidojiet stāvokļa virsgrāmatu, kas norādīta nomnieka un atbildes ID:

{
  "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",
  "modelis": "gpt-...",
  "provider": "openai",
  "store_mode": "provider|gateway|none",
  "retention_policy": "standarta|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": null
}

Svarīgs noteikums: automātiski neatdariniet parametru previous_response_id, atkārtoti atskaņojot pilnu tērzēšanas vēsturi, ja vien nomnieks nav skaidri atļāvis šādu saglabāšanas un izmaksu darbību. Atkārtota atskaņošana var palielināt marķiera izmaksas, mainīt privātuma stāju un mainīt modeļa uzvedību. Drošāk ir atgriezt skaidru iespēju kļūdu, nekā klusi nosūtīt saglabāto sarunas saturu, ko lietojumprogramma nebija paredzējusi saglabāt vai izmantot atkārtoti.

Stāvokļa apstrādes režīmi

• Pakalpojumu sniedzēja statuss: augšējais pakalpojumu sniedzējs saglabā pietiekami daudz konteksta, un vārteja kartē vārtejas atbildes ID ar pakalpojumu sniedzēja atbildes ID.
• Vārtejas stāvoklis: vārteja saglabā nepieciešamos iepriekšējos vienumus un rekonstruē kontekstu, kad tas ir atļauts.
• Nav stāvokļa: pieprasījumā tiek izmantots store=false vai nomnieka politika aizliedz saglabāšanu. previous_response_id ir jānoraida, ja vien pakalpojumu sniedzējs nevar izpildīt pieprasījumu bez vārtejas saglabāšanas un politika to atļauj.

Ņemiet vērā arī to, ka klientam, iespējams, būs atkārtoti jānosūta iepriekšējie norādījumi, kad tie jāturpina piemērot. Vārteja nedrīkst izgudrot slēptus norādījumus, lai kompensētu, ja vien šāda rīcība nav daļa no skaidras nomnieka politikas.

Apstipriniet rīkus pirms nosūtīšanas

Atbildes padara rīka lietošanu svarīgāku. Saderības slānim ir jāapstrādā divas plašas kategorijas:

• Lietojumprogrammu rīki: klienta nodrošinātas funkciju definīcijas, kas izpildītas ārpus modeļa nodrošinātāja, un izvadi tiek nosūtīti atpakaļ API.
• Misinātie pakalpojumu sniedzēja rīki: meklēšana tīmeklī, failu meklēšana, datora lietošana, koda izpilde, zemējums vai līdzīgi rīki, ko izpilda nodrošinātājs vai vārtejas kontrolēta infrastruktūra.

Ieejas brīdī pārbaudiet rīku shēmas pirms maršrutēšanas:

• Agri noraidiet nederīgu JSON shēmu.
• Ieviesiet maksimālo shēmas izmēru un ligzdošanas dziļumu.
• Pārbaudiet rīku nosaukumu saderību ar pakalpojumu sniedzēju.
• Lietojiet nomnieka, atslēgas, lietotāja un vides tvērumus.
• Pieprasīt apstiprināšanas vārti rīkiem, kas raksta datus, tērē naudu, piekļūst sensitīvām sistēmām vai izsauc ārējos savienotājus.

Lai izsauktu lietojumprogrammas funkcijas, ir nepieciešams stabils zvana ID. Modelis izstaro funkcijas izsaukumu ar call_id; pieteikums iesniedz instrumenta izvadi, atsaucoties uz šo ID; vārteja ieraksta abus vienā trasē. Bez šīs pievienošanās atslēgas audita žurnāli un atkārtojumi kļūst neskaidri.

Mitinātajiem rīkiem rezervējiet budžetu pirms nosūtīšanas un samaksājiet izmaksas pēc tam. Mitinātie rīki var pievienot izmaksas ārpus parastās marķiera uzskaites, tāpēc savienojiet rīku virsgrāmatu ar vienotajiem AI API norēķiniem, nevis slēpiet šīs izmaksas vispārējā modeļa izsaukuma kopsummā.

Straumēšanu normalizējiet kā notikumus, nevis marķiera tekstu

Tērzēšanas starpniekserveris bieži vien var izvairīties no pārsūtīšanas pilnvaras deltas. Atbilžu vārteja nevar. Straumei ir dzīves cikla nozīme: var sākties atbilde, var sākties un pabeigt izvades vienumus, tekstu var saņemt deltas, rīku izsaukumus var salikt pakāpeniski, lietojums var nonākt straumes beigās vai laikā, un atbilde var neizdoties vai tikt atcelta.

Definējiet vārtejas notikumu shēmu, pēc tam kartējiet tajā katru pakalpojumu sniedzēja straumi:

event: response_started
dati: { "response_id": "gw_resp_123", "statuss": "in_progress"}

notikums: output_item_starteddati: { "item_id": "item_1", "type": "text"}

notikums: text_delta
dati: { "item_id": "item_1", "delta": "Sveiki" }

notikums: tool_call_delta
dati: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"pasūtījums"}

notikums: usage_delta
dati: { "output_tokens": 12}

pasākums: pabeigts
dati: { "response_id": "gw_resp_123", "usage": { ... } }

Ieteicamie normalizētie notikumi:

• response_started
• output_item_started
• output_item_completed
• text_delta
• atteikuma_delta
• tool_call_delta
• rīks_rezultāts_saņemts
• izmantošanas_delta
• pabeigts
• atcelts
• neizdevās

Kad klients atvienojas, veiciet atcelšanu, ja pakalpojumu sniedzējs to atbalsta. Jebkurā gadījumā ierakstiet daļējas atbildes stāvokli. Ja pakalpojumu sniedzējs vēlāk atgriež galīgo lietojumu, izmantojot aizkavētu atzvanīšanu vai pēdējo daļu, saskaņojiet virsgrāmatu. Straumēšanas saderība ir saistīta ne tikai ar uzskaiti un dzīves ciklu, bet arī ar latentumu.

Izveidojiet nodrošinātāja iespēju matricu

Vairāku modeļu maršrutēšana ir noderīga tikai tad, ja vārteja saprot, ko var droši maršrutēt. Pievienojiet savam modeļu katalogam atbildes specifiskas iespējas:

{
  "model_alias": "agent-default",
  "maršruti": [
    {
      "provider": "openai",
      "modelis": "...",
      "supports_responses": taisnība,
      "supports_previous_response_id": patiess,
      "supports_store_false": patiess,
      "supports_builtin_web_search": taisnība,
      "supports_function_calling": patiess,
      "supports_stream_lifecycle_events": taisnība,
      "supports_reasoning_context_continuity": patiess,
      "max_tool_schema_bytes": 65536
    },
    {
      "provider": "provider_b",
      "modelis": "...",
      "supports_responses": nepatiess,
      "chat_adapter_available": patiess,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

Atkāpšanās gadījumā ir jāapzinās zaudējumi. Ja pieprasījumam ir nepieciešama iebūvēta meklēšana tīmeklī un rezerves nodrošinātājs to nevar veikt, neatbildiet klusi, neveicot meklēšanu. Ja pieprasījums ir atkarīgs no saglabātā argumentācijas konteksta un atkāpšanās maršruts to nevar saglabāt, atgrieziet iespēju kļūdu vai atteikumu par pazemināšanu, ko klients ir skaidri izvēlējies.

Noderīga pieprasījuma iespēja ir:

{
  "modelis": "aģents-noklusējums",
  "input": "...",
  "fallback_policy": {
    "allow_lossy": nepatiess,
    "allowed_losses": []
  }
}

Mazāk sensitīviem lietošanas gadījumiem nomnieki var atļaut īpašu zaudējumu pazemināšanu:

{
  "fallback_policy": {
    "allow_lossy": taisnība,
    "allowed_losses": ["flattened_stream", "no_reasoning_summary"]
  }
}

Vārtejai jebkurā gadījumā ir jāreģistrē atkāpšanās lēmums. Tas padara iespējamu vēlāku atkļūdošanu, ja aģents rīkojas citādi pēc pakalpojumu sniedzēja darbības pārtraukuma vai modeļa maiņas.

Atribūtu lietojums atbildes un vienuma līmenī

Atbilžu zvani var maksāt vairāk nekā līdzvērtīgas tērzēšanas pabeigšanas, jo tie var ietvert rīka izpildi, garāku kontekstu, argumentācijas pilnvaras, failu meklēšanu, meklēšanu tīmeklī vai atkārtotas instrukcijas. AI API lietojuma analīzes informācijas panelim nepietiek ar vienu apkopotu pilnvaru skaitu.

Ierakstīt lietojumu divos līmeņos:

• Atbildes līmenis: nomnieks, atslēga, lietotājs, modelis, nodrošinātājs, latentums, galīgais statuss, ievades pilnvaras, izvades marķieri, argumentācijas pilnvaras, ja tiek ziņots, kopējās izmaksas un rezerves maršruts.
• Vienuma/rīka līmenis: rīka nosaukums, izsaukuma ID, mitinātās rīku vienības, failu ID, meklēšanas vaicājumu skaits, ja pieejams, rīka latentums, instrumenta izmaksas un apstiprināšanas politikas rezultāts.

Tas ļauj izstrādātājiem atbildēt uz konkrētiem jautājumiem:

• Vai izmaksas palielinājās ilgāka stāvokļa, argumentācijas piepūles, rīku izsaukumu vai atkāpšanās dēļ?
• Kura nomnieka vai API atslēga ģenerē mitinātā rīka maksas?
• Kura atbilde neizdevās pēc rīka izsaukšanas, bet pirms galīgā teksta?
• Kuras atceltās straumes joprojām tika izmantotas iepriekš?

Uzturēšanu un dzēšanu apstrādājiet kā pirmšķirīgu rīcību

Servera puses stāvoklis ir noderīgs, taču tas maina vārtejas saglabāšanas pienākumus. Iebūvējiet politiku protokola slānī, nevis uzskatiet to par reģistrēšanas iestatījumu.

Katram atbilžu pieprasījumam atrisiniet:

• Īrnieku saglabāšanas politika
• Pieprasījuma līmeņa veikala preference
• Pakalpojumu sniedzēja saglabāšanas saderība
• Vai vārtejas atkārtošana ir atļauta
• Vai instrumenta ievades un izvades var tikt saglabātas
• Atbildes stāvokļa derīguma termiņš un dzēšana

Ja saglabāšana ir atspējota, vārteja joprojām var saglabāt minimālu darbības metadatu: laikspiedolu, ID, statusu, pilnvaru skaitu, izmaksas un politikas lēmumus. Izvairieties no neapstrādātu uzvedņu, pilnu rīku izvadu vai rekonstruētas vēstures glabāšanas, ja vien politika to neatļauj.

Atbilstības ķermeņi, kas jāpievieno pirms palaišanas

Nepaļaujieties uz laimīgā ceļa manuālajiem testiem. Pievienojiet aprīkojumu, kas pārbauda protokola darbību tiešos OpenAI maršrutos, pakalpojumu sniedzējam pielāgotos maršrutos un rezerves scenārijos.

Minimālā testa kopa

• Pamata atbilde: teksta vienums tiek atgriezts ar stabilu atbildes ID un lietojumu.
• Vairāku apgriezienu statuss: otrā pieprasījuma atsauces previous_response_id; vārteja apstiprina nomnieka īpašumtiesības un stāvokļa režīmu.
• Atkārtoti norādījumi: pārbaudiet, vai vārteja nav klusi izdomājusi izlaistos norādījumus.
• Funkciju zvans turp un atpakaļ: modelis izstaro zvana ID; pieteikums iesniedz produkciju; galīgā atbilde pievieno abus ierakstus.
• Misinātā rīka politika: nesankcionēts iebūvētais rīks tiek bloķēts pirms nosūtīšanas.
• Straumēšanas secība: atbildes sākums, vienuma sākums, deltas, vienuma pabeigšana, lietojums un pabeigšana tiek izvadīti derīgā secībā.
• Straumes atcelšana: klienta atvienošana aktivizē augšupejošu atcelšanu, ja tiek atbalstīta, un reģistrē daļēju lietojumu.
• Atkāpšanās noraidīšana: nodrošinātājs bez obligātās atbildes semantikas atgriež iespēju kļūdu.
• Atkāpšanās izvēle: pieprasījums ar atļautajiem zaudējumiem saņem skaidru pazemināšanas atzīmi.
• Nulles saglabāšanas režīms: ir bloķēta stāvokļa atkārtošana un vārtejas puses uzvednes saglabāšana.

Ieteicamā izlaišanas secība

1. Atklājiet beta maršrutu. Pievienojiet /v1/responses, nemainot esošās tērzēšanas darbības.
2. Vispirms ieviesiet caurlaides pakalpojumu sniedzējiem ar vietējo atbilžu atbalstu. Saglabājiet ID, vienumus, straumes, lietojumu un kļūdas.
3. Pievienojiet valsts virsgrāmatu. Kartējiet vārtejas ID ar pakalpojumu sniedzēja ID un ieviesiet nomnieka īpašumtiesības.
4. Pievienojiet kanoniskos vienumus. Saglabājiet vienumu metadatus, kas nepieciešami auditēšanai, norēķiniem un straumes rekonstrukcijai.
5. Pievienojiet rīka pārvaldību. Validējiet shēmas, piespiediet tvērumus un ierakstiet rīka izsaukuma savienojumus.
6. Pievienojiet straumēšanas normalizēšanu. Pārvērtiet pakalpojumu sniedzējam specifiskas straumes vārtejas dzīves cikla notikumos.
7. Pievienojiet iespējām atbilstošu maršrutēšanu. Pēc noklusējuma atļaujiet tikai drošas atkāpšanās iespējas.
8. Pievienojiet analīzi un norēķinu norēķinus. Atribūtu marķieri, pamatojumu un rīka lietojumu norādiet atsevišķi.
9. Publicēt saderības piezīmes. Pastāstiet izstrādātājiem, kuri lauki ir vietējie, emulēti, neatbalstīti vai ar zaudējumiem.

Lietojams secinājums

Responses API saderības slānim jāsaglabā protokola nozīme, nevis jāatgriež tikai ticams teksts. Veidojiet to, izmantojot piecus izturīgus objektus: kanonisko atbildes vienumu modeli, sarunu stāvokļa virsgrāmatu, rīku izsaukuma virsgrāmatu, straumēšanas notikumu normalizētāju un nodrošinātāja iespēju matricu.

Drošākais noklusējuma veids ir stingra saderība: ja maršruts nevar saglabāt nepieciešamo stāvokli, rīkus, argumentācijas kontekstu, straumes notikumus vai saglabāšanas uzvedību, atgriež skaidru iespēju kļūdu. Pievienojiet izvēles zaudējumu atkāpšanos tikai tad, kad izstrādātāji saprot, kas tiks atmests. Šāda pieeja var šķist mazāk ērta nekā automātiskā saplacināšana, taču tā novērš sliktāko kļūmes režīmu: lietojumprogrammu, kas šķiet saderīga, vienlaikus klusi zaudējot semantiku, kuras dēļ tā vispirms izmantoja Responses API.

Saistīta informācija

• streaming-token-api-ga"> apstrāde