Chat Completions пен Responses API-ды бір шлюзде қалай біріктіруге болады?

Екі API контрактісін бір LLM шлюзінде біріктіру messages өрісін input өрісіне ауыстырумен бітпейді. Мұндай аударма бір пайдаланушы сұрауы бар демода жұмыс істегенімен, кейін функция шақыруларын, ағынды шығаруды, қатаң JSON Schema-ны және қайталама сұрауларды бұзады. Шлюз JSON пішінін емес, операцияның мағынасын аударуы керек: кім не айтты, қандай құралдарға рұқсат берілді, қандай нәтиже керек және деректердің келесі бөлігі қай аяқталмаған шақыруға жатады.

Бұл модель немесе провайдер ауысқанда әр қолданбаны қайта жазғысы келмейтін командалар үшін маңызды. Ескі сервис Chat Completions тілінде жұмыс істеуі, жаңа агент Responses API қолдануы мүмкін, ал ішкі маршрутизация ортақ болып қалуы керек. Мұндағы шекара қарапайым: сыртқы контракт клиентке, ішкі контракт шлюзге, ал провайдер контрактісі адаптерге тиесілі. Осы үш деңгейді араластырсаңыз, әр жаңа функция ерекшеліктің үстіне қосылған тағы бір ерекшелікке айналады.

Шлюз нақты нені біріктіруі керек

Шлюз екі JSON объектісі изоморфты сияқты көрінбей, сұрау мен жауаптың семантикасын біріктіруі керек. Chat Completions нәтижені choices[] және әр тармақтағы бір assistant хабарламасы айналасында құрады. Responses API мәтін, функция шақырулары, бас тартулар және басқа орындау элементтері болуы мүмкін типтелген шығу элементтерінің жиынын қайтарады. Қарапайым диалогта айырмашылық байқалмауы мүмкін. Агент циклінде ол күйді жоғалтпай жұмысты жалғастыруға болатынын анықтайды.

Шлюзге өзінің канондық сұрауы қажет. Клиенттер оны көруі міндетті емес, бірақ дәл осы объектіні тексеріп, журналға жазып, маршрутизаторға беру керек. Оның ішінде бес нәрсені бөлек ұстаған пайдалы:

• модельге арналған нұсқау мен диалог тарихы;
• пайдаланушы және ассистент контентінің бөліктері;
• құрал анықтамалары, таңдау ережелері және шектеулер;
• финалдық жауаптың талап етілетін пішіні;
• операция күйі: шақыру идентификаторлары, алдыңғы жауапты жалғастыру, ағынды режим және трассировка метадеректері.

Нашар ішкі объект әдетте аздап кеңейтілген messages[] түрінде болады. Ол тез арада response_format, previous_response_id, tool_outputs, reasoning, provider_payload өрістерімен және бірнеше логикалық жалаушамен толып кетеді. Бірнеше айдан соң бұл өрістердің қайсысы міндетті және қай кезеңде мағыналы екенін ешкім айта алмайды.

Операцияның анық моделін енгізген дұрыс. Мысалы, мәтіндік нұсқау сыртқы API-лардың бірі оны хабарламалар массивіне салғаны үшін ғана пайдаланушы хабарламасы болып көрінбеуі керек. Функция нәтижесі «ассистент хабарламасына» айналмауы тиіс: оның авторы модель емес және ол нақты call_id мәніне қатысты.

{
  "model_hint": "general-reasoning",
  "instructions": [
    {"kind": "text", "text": "Отвечай по правилам кредитного продукта."}
  ],
  "turns": [
    {
      "role": "user",
      "parts": [
        {"kind": "text", "text": "Можно ли досрочно погасить заем?"}
      ]
    }
  ],
  "tools": [
    {
      "kind": "function",
      "name": "find_loan_terms",
      "description": "Возвращает условия займа по типу продукта.",
      "parameters": {
        "type": "object",
        "properties": {
          "product": {"type": "string"}
        },
        "required": ["product"],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "tool_policy": {"mode": "auto"},
  "output_contract": {"kind": "text"},
  "stream": true
}

Бұл клиенттерге арналған «үшінші API» емес. Бұл шлюздің есеп кітабы. Мұнда әр өріс бір мағынаға жауап береді, ал адаптерлер тек екі түрлендіруді орындайды: сыртқы сұраудан канондық операцияға және канондық операциядан модель диалектісіне.

Хабарламаларды жолдар массивіне айналдыруға болмайды

Мәтіндік хабарламалар тек сырттай ұқсайды. Chat Completions жүйесінде клиент әдетте developer, system, user, assistant және tool рөлдері бар messages жібереді. Responses API жүйесінде кіріс хабарламалар мен жеке элементтерден тұруы мүмкін, ал нұсқау instructions ішінде орналасады. Бұған қоса, API алдыңғы жауап идентификаторы арқылы жұмысты жалғастыра алады, сондықтан контекст көзі өзгереді.

OpenAI-дың Chat Completions құжаттамасы endpoint-ті хабарламалар тізімі бойынша жауап генерациялау ретінде сипаттайды. Ал Responses API анықтамалығы жұмысты кіріс және шығыс элементтерінің жиыны бар жауап жасау ретінде модельдейді. Мұны косметикалық айырмашылық деп қабылдамаңыз. Бірінші көрініс үйреншікті чатқа ыңғайлы, екіншісі агенттің орындалу барысын жақсырақ көрсетеді.

Нормализатор әр жүріс ішіндегі бөліктердің ретін сақтауы керек. Бір пайдаланушы хабарламасында мәтін және бірнеше тіркеме болуы мүмкін. Адаптер оларды бір жолға біріктірсе, түрін, ретін және рұқсат етілген модальділіктерді тексеру мүмкіндігін жоғалтады. Таңдалған провайдер тек мәтін қабылдаса, шлюз жібермей тұрып бас тартуы немесе алдын ала жарияланған түрлендіру саясатын қолдануы керек. Тіркемені байқатпай алып тастап, модель оны оқығандай әсер қалдыруға болмайды.

Рөлдерге де тәртіп керек. Мен әдетте мынадай ережелерді қолданамын:

• developer және system бастапқы реті сақталған жеке нұсқаулар жиынына түседі;
• user және assistant диалог жүрістеріне айналады;
• tool кәдімгі жүріске айналмайды, құрал шақыруымен байланысады;
• белгісіз рөл схема қатесін туғызады, user рөліне ауыстырылмайды;
• name және басқа көмекші өрістерді мақсатты контракт көрсете алса, жүріс метадеректерінде сақтайды.

system және instructions мәселесін көбіне тым қарапайым шешеді. System prompt-ты түгел instructions ішіне көшіруге тек диалогты жалғастыру саясатын таңдағаннан кейін болады. Клиент previous_response_id қолданса, ескі нұсқауды қайта жіберу контексті өзгертуі немесе кіріс көлемін ұлғайтуы мүмкін. Ал шлюз тарихты өзі сақтаса, сақталған күйге қай нұсқаулардың кіргенін, қайсысын клиент ауыстырғысы келетінін білуі тиіс.

Мөлдірлік жоқ жерде толық мөлдірлікке уәде бермеңіз. Серверлік жауап идентификаторы арқылы жалғастыру режимін күйсіз Chat Completions ішінде шығынсыз көрсету мүмкін емес. Екі адал нұсқа бар: канондық жүрістердің жеке журналын сақтап, тарихты қалпына келтіру немесе бұл мүмкіндікті тек Responses API үшін қолжетімді деп жариялау. Бірінші нұсқа тасымалдануды береді, бірақ контекст көлемі мен деректерді сақтау жауапкершілігін арттырады. Екіншісі пайдалануға оңай, алайда контракт кеңейеді.

Құрал шақыруы өзара байланысты үш оқиғадан тұрады

Құралды сұрау өрісі деп қарауға болмайды. Ол цикл құрайды: модель функцияны таңдайды, қолданба оны орындайды, содан кейін нәтижені модель сұраған дәл сол шақыруға қайтарады. Осы оқиғалар арасындағы байланысты жоғалту агентті сәтсіз промпттен де сенімдірек бұзады.

Chat Completions жүйесінде функция анықтамасы tools[] ішіне function ретінде енгізіледі. Модель tool_calls[] мәнін ассистент хабарламасында қайтарады, ал клиент диалогты tool_call_id бар role: "tool" хабарламасымен жалғастырады. Responses API жүйесінде функция анықтамасы әдетте жазық болады: аты, сипаттамасы, параметрлердің JSON Schema-сы және қатаңдық баптауы. Шақыру жеке function_call элементі ретінде келеді, ал нәтиже сол call_id бар жеке function_call_output кіріс элементі арқылы жіберіледі.

Төмендегі схема функция анықтамасын ең аз көлемде аударуды көрсетеді. Шлюз JSON Schema-ны «әдемі болсын» деп қайта жазбауы керек: оны өзгеріссіз сақтап, мақсатты модель қай схема ішкі жиынын қабылдайтынын бөлек тексеруі қажет.

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "find_loan_terms",
        "description": "Возвращает условия займа по типу продукта.",
        "parameters": {
          "type": "object",
          "properties": {
            "product": {"type": "string"}
          },
          "required": ["product"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ]
}

Responses-пен үйлесімді адаптер үшін осы канондық функция мына мағынадағы объектіге айналуы керек:

{
  "tools": [
    {
      "type": "function",
      "name": "find_loan_terms",
      "description": "Возвращает условия займа по типу продукта.",
      "parameters": {
        "type": "object",
        "properties": {
          "product": {"type": "string"}
        },
        "required": ["product"],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

Генерациядан кейін функция аргументтері дерлік әрдайым JSON жолы түрінде келеді. Оларды шекарада себепсіз қайта парсинг жасап, қайта сериализацияламаңыз. Бастапқы arguments мәнін сақтап, орындаудан бұрын схема бойынша тексеріңіз және талданған объектіні орындаушының қауіпсіз контекстіне қосыңыз. Қайта сериализация сандарды, өрістер ретін және экрандауды өзгертуі мүмкін. Көп JSON үшін бұл маңызды емес, бірақ қолтаңбада, дәл трассировкада немесе тест фикстураларын салыстырғанда айырмашылық кедергі болады.

Екі бағыттағы аударудан өтуі тиіс маңызды үзінді мынадай:

{
  "call_id": "call_8f31",
  "name": "find_loan_terms",
  "arguments_raw": "{\"product\":\"consumer_loan\"}",
  "status": "requested"
}

Қолданба жұмысын аяқтағанда, нәтижені мәтіндік ассистент жауабы ретінде бермеңіз. Канондық элемент былай көрінуі керек:

{
  "kind": "tool_result",
  "call_id": "call_8f31",
  "output": "{\"early_repayment\":true,\"fee\":0}",
  "status": "completed"
}

Chat Completions адаптері оны role: "tool", tool_call_id: "call_8f31" түріне айналдырады. Responses API адаптері type: "function_call_output", call_id: "call_8f31" түріне айналдырады. call_id мәнін бағыттардың бірінде жеке UUID-мен ауыстыруға болмайды. Клиент, модель және аудит бір тізбекті көруі керек.

Параллель шақыруларды бөлек тексеріңіз. Модель әртүрлі идентификаторлары бар екі шақыру қайтара алады. Қолданба оларды қатар орындауы мүмкін, бірақ нәтижелерді таңдалған контракт анық қолдайтын ретпен қайтарған дұрыс. Нәтижені функция атымен байланыстырмаңыз: бір құрал әртүрлі аргументтермен екі рет шақырылуы мүмкін.

Құрылымдалған жауап пен JSON mode әртүрлі міндет шешеді

Құрылымдалған жауап дегеніміз «JSON қайтар» деген өтініш емес, нәтиже пішініне арналған контракт. Шлюз response_format өрісін json=true деген бір логикалық өріспен біріздендіруге тырысқанда, осы айырмашылық жиі ұмыт қалады.

Chat Completions жүйесінде ескі JSON mode response_format: {"type":"json_object"} арқылы беріледі. Ол синтаксистік жағынан дұрыс JSON алуға көмектеседі, бірақ қажетті схемаға сәйкестікті дәлелдемейді. Схема үшін схема атауы, сипаттамасы, schema объектісі және strict баптауы бар json_schema режимі қажет. OpenAI құжаттамасында JSON mode пен Structured Outputs нақты бөлінген, ал схеманы қолдайтын модельдер үшін екінші нұсқа ұсынылады.

Responses API жүйесінде схема мағынасы мәтін пішімінің баптауында орналасады. Сондықтан канондық модельде сыртқы response_format өрісін емес, нәтиже объектісін сақтаған пайдалы:

{
  "output_contract": {
    "kind": "json_schema",
    "name": "loan_answer",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "eligible": {"type": "boolean"},
        "reason": {"type": "string"}
      },
      "required": ["eligible", "reason"],
      "additionalProperties": false
    }
  }
}

Мұндай объектіні Chat Completions үшін response_format және Responses API үшін text.format ретінде көрсетуге болады. Бірақ шлюз тағы бір қадам жасауы тиіс: контрактіні нақты модельдің мүмкіндіктерімен салыстыру. Әртүрлі модельдер мен провайдерлерде қатаң режимді, кірістірілген схемаларды, JSON Schema-ның жеке кілтсөздерін және schema output пен function calling үйлесімін қолдау әртүрлі.

Ең нашар саясат тартымды көрінеді: провайдер strict қолдамаса, жалаушаны алып тастап, жалғастыру. Команда оны «сәтті жауаптар санын көбейту» үшін таңдайды. Шын мәнінде бұл API уәдесін өзгертеді. Клиент нәтижені қалпына келтіру эвристикасынсыз талдауға сенеді, ал артық өрісі, массив орнына жолы немесе JSON алдында мәтіні бар объект алады. Банк, медицина және автоматтандыруда бұл ұсақ төмендеу емес, тәуекелдің басқа режимі.

Мүмкіндіктерді үш класқа бөліңіз:

• дәл қолдау: шлюз семантиканы өзгертпей сұрау жібереді;
• бақыланатын түрлендіру: шлюз пішінді өзгертеді, бірақ жарияланған мағынаны сақтайды;
• қолдау жоқ мүмкіндік: шлюз модельге қоңырау шалмай тұрып қатені қайтарады.

Мысалы, response_format.json_schema мәнін text.format.json_schema түріне аудару бақыланатын түрлендіру болуы мүмкін. strict: true мәнін алып тастау олай емес. Егер best effort режимін енгізсеңіз, ол клиенттің анық жалаушасын талап етіп, жауапта немесе трассировка метадеректерінде кепілдік төмендегенін көрсетуі керек.

Құрылымдалған нәтижені екі рет тексеріңіз. Модель немесе провайдер схеманы қолдайтынын мәлімдеуі мүмкін, бірақ қолданба бизнес логикасына бермес бұрын финалдық JSON-ды бәрібір тексеруі керек. Бірінші бақылау шлюздің шығу контрактісін, екіншісі нақты әрекетті, мысалы төлем тапсырмасын жасауды қорғайды. Бір валидатор екіншісін алмастырмайды.

Ағынды шығару екі күй машинасын қажет етеді

Контрактілер арасындағы streaming-ті SSE оқиғасының атын ауыстыру арқылы жасауға болмайды. Chat Completions пен Responses API екеуі де деректерді бөліктермен береді, бірақ бөліктердің құрылымы мен келу реті әртүрлі.

Chat Completions жүйесінде клиент chunk объектілерінің тізбегін күтеді. Мәтін көбіне choices[0].delta.content ішінде, ал функция аргументтері delta.tool_calls ішінде фрагменттермен жиналады. Responses API ағыны жауаптың жасалғанын, output item қосылғанын, мәтін дельтасын, шақыру аргументтерінің дельтасын және аяқталғанын бөлек хабарлайтын типтелген оқиғалардан тұрады.

Шлюз жауаптың ішкі күй машинасын құруы керек. Әр шығу элементі үшін ол идентификаторды, түрді, индексті, жиналған мәтінді, жиналған аргументтерді және күйді ұстайды. Содан кейін сыртқы сериализатор оқиғаларды қажетті түрде шығарады. Бұл тікелей проксиден күрделірек, бірақ басқа жағдайда классикалық қате пайда болады: мәтін клиентке кетіп үлгереді, функция кейінірек келеді, ал шлюз finish_reason: "stop" деп жауапты ерте аяқтап қояды.

Негізгі күйлерді ашық көрсеткен пайдалы:

1. started: шлюз сұрауды қабылдап, жауап контрактісін бекітті.
2. emitting: мәтін, бас тарту немесе құрал аргументтерінің бөліктері келіп жатыр.
3. awaiting_tool: модель ағымдағы жауапты функция шақыруларымен аяқтады.
4. completed, failed немесе cancelled: операция соңғы күйге жетті.

Басқа API-дың токенизациясын қайта жасауға тырыспаңыз. Responses провайдері мәтін дельтасын ірі фрагментпен берсе, Chat адаптері оны бір delta.content ретінде шығара алады. Клиентке әдетте әр chunk көлемі емес, таңбалардың реті маңызды. Керісінше, Chat провайдері шақыру аргументтерін бөліктермен берсе, Responses адаптері бір call_id мәнін сақтап, аргумент дельталарын бір элементтің бөліктері ретінде жіберуі керек.

Жартылай JSON-ға қатысты жағымсыз жағдай да бар. Модель құрылымдалған жауапты шығара бастап, жабылатын жақшаға жетпей байланыс үзілуі мүмкін. Жиналған мазмұнды дұрыс финалдық объект ретінде беруге тырыспаңыз. Ағынды клиент аралық мәтінді көрсете алады, бірақ финалдық жауап қате күйін алуы керек. Аудитте себебін де сақтаңыз: клиенттің бас тартуы, шлюз тайм-ауты, провайдермен байланыстың үзілуі немесе модель қатесі.

Қателер тек HTTP кодын емес, себебін де сақтауы керек

Біртұтас шлюз барлық клиентке бірдей қате JSON-ын қайтаруға міндетті емес, бірақ ішкі жүйеде ақауларды бірізді жіктеуі керек. Провайдердің 429 қатесі, кілттің жергілікті лимиті және қолдау жоқ схемадан бас тарту сырттай бір кодқа ұқсас болуы мүмкін, алайда қайталап көру мен тексеру үшін бұл үш бөлек себеп.

OpenAI-үйлесімді endpoint үшін сыртқы пішінді таныс күйде қалдырған орынды:

{
  "error": {
    "message": "Модель таңдалған маршрут үшін strict JSON Schema қолдамайды.",
    "type": "invalid_request_error",
    "param": "response_format",
    "code": "capability_not_supported"
  }
}

Ішкі жағында клиентке көрсету міндетті емес өзгермейтін өрістерді қосыңыз: gateway_request_id, client_request_id, route_id, провайдер идентификаторы, бастапқы қате коды, әрекет нөмірі және қайталанғыштық класы. Провайдердің бастапқы жауап денесін message өрісіне салмаңыз. Онда промпт бөліктері, құрал деректері немесе маршруттың ішкі мәліметтері болуы мүмкін.

Практикалық жіктеу мынадай болуы мүмкін:

• контрактіні тексеру қатесі: қайталамау, сұрауды түзету;
• модель мүмкіндіктерінен бас тарту: сол маршрутпен қайталамау, клиент саясаты рұқсат етсе ғана анық fallback қолдану;
• шлюз немесе провайдер лимиті: сұрау идемпотентті болса, басқарылатын кідіріспен қайталау;
• провайдердің уақытша қатесі: әрекет саны мен уақыт бюджеті шегінде қайталау;
• құралды орындау қатесі: қолданба саясаты рұқсат етсе ғана оны модельге құрал нәтижесі ретінде қайтару.

Соңғы тармақ жиі қате іске асырылады. Ішкі іздеу сервисі 500 қайтарса, оны автоматты түрде LLM сұрауының HTTP қатесіне айналдыруға болмайды. Кейде агент пайдаланушыға уақытша қолжетімсіздік туралы айтып, басқа жол ұсына алады. Кейде қолданба мұндай сервистің барын немесе ақау мәліметін ашуға құқылы емес. Бұл шешім API адаптеріне емес, құрал саясатына жатады.

Маршрутизация қатесін модель қатесінен де бөліңіз. Шлюз сұрауды аймақтық ереже, data residency шектеулері немесе қажетті функциясы бар модельдің жоқтығы себепті қабылдамауы мүмкін. Бұл кезде модель ештеңе орындаған жоқ. Сапа есептерінде мұндай жағдайларды «модель қателеріне» жатқызуға болмайды, әйтпесе промптті түзете бастайсыз, ал шын мәнінде маршрут таңдау ережесін өзгерту керек.

Үйлесімділік уәде емес, матрица болуы керек

«OpenAI API қолдаймыз» деген сөз нақты үйлесімділікті сипаттамайды. Оның артында ондаған үйлесім бар: мәтіндік чат, суреттер, tool choice, бірнеше шақыру, қатаң схема, streaming, күйді жалғастыру, метадеректер, тоқтау себептері және usage. Бір маршрут мәтін мен функциялармен жақсы жұмыс істеп, жауаптың қатаң пішімін қолдамауы мүмкін. Басқасы JSON Schema-ны тамаша беріп, диалогты серверлік жалғастыра алмауы мүмкін.

Әр адаптер мен маршрут үшін мүмкіндіктер матрицасын жасаңыз. Жолдар нақты болуы керек: text, image input, function call, parallel function calls, strict function schema, json schema output, streaming, server-side state, usage details. Бағандарда шлюз мүмкіндікті қабылдай ма, оны өзгеріссіз бере ме, түрлендіре ме, нәтижені тексере ала ма және бас тартқанда қандай код қайтарады деген сұрақтар болсын.

Матрицаны жарияланған күні ескіретін қолмен жасалған құжатқа айналдырмаңыз. Оны конфигурация деректері ретінде сақтап, маршрутизацияға дейін пайдаланыңыз. Сонда шешім тексерілетін болады:

{
  "route": "provider-a/model-x",
  "capabilities": {
    "function_call": true,
    "parallel_function_calls": true,
    "strict_function_schema": false,
    "json_schema_output": true,
    "streaming": true,
    "server_side_state": false
  }
}

Клиент құрал үшін strict: true жібергенде, маршрутизатор бұл маршрутты желілік шақыруға дейін алып тастайды. Саясат fallback-қа рұқсат етсе, қажетті мүмкіндігі бар маршруттарды ғана таңдайды. Рұқсат етпесе, түсінікті қате қайтарады. Бұл провайдерден қай өріс кепілдіктен айырылғанын түсіндірмейтін бұлыңғыр 400 алғаннан жақсы.

AI Router бұл шекараны әсіресе ұқыпты ұстай алады: бір OpenAI-үйлесімді endpoint бұрынғы SDK мен кодты сақтауға мүмкіндік береді, бірақ әр модельдің жаңа мүмкіндіктерін ұқсас параметр атауларына сенбей, бәрібір матрица бойынша тексеру керек.

Аударуды жеке сұраулармен емес, тізбектермен тексеріңіз

Бір request fixture шлюзді тексермейді. Келесі сұрау алдыңғысының идентификаторы мен мағынасына тәуелді болатын сценарийлер керек. Ең пайдалы тестілер көбіне қарапайым көрінеді, бірақ қателерді продакшенге жетпей табады.

Бірінші сценарий: пайдаланушы мәтіні, бір функция шақыруы, функция нәтижесі және финалдық мәтін. Chat Completions-тен Responses API-ға және кері бағытта жүргенде функция аты, аргументтердің бастапқы JSON-ы және call_id өзгермейтінін тексеріңіз.

Екінші сценарий: әртүрлі аргументтері бар бір функцияның екі параллель шақыруы. Нәтижелердің аты бойынша бірігіп кетпегенін және біріншісінің аяқталуы бүкіл жауапты аяқталған деп белгілемейтінін тексеріңіз.

Үшінші сценарий: қосымша өрістерге тыйым салынған қатаң JSON Schema. Үш тармақты тексеріңіз: модель схеманы қолдайды, модель схеманы қолдамайды және модель жарамсыз нәтиже қайтарды. Екінші жағдайда шлюз генерация басталмай тұрып бас тартуы керек. Үшінші жағдайда ол контракт қатесін қайтарып, бұзылған JSON-ды әрі қарай жібермеуі тиіс.

Төртінші сценарий: аргументтері бірнеше дельтамен келетін функцияның ағынды шақырылуы. Тест оларды дәл бір жолға жинап, финалдық күй соңғы бөлікке дейін пайда болмағанын тексеруі керек.

Бесінші сценарий: тайм-ауттан кейінгі қайталама сұрау. Шлюз жіберуді қайталаса, құралды жанама әсерімен екі рет орындамауы керек. Өтінім жасау, ақша аудару немесе хабарлама жіберу сияқты операцияларға құрал жағында идемпотенттік кілт қажет. Модель сұрауын қайталау мен бизнес әрекетін қайталау екі бөлек тәуекел.

Бүкіл жауапты байт бойынша емес, семантикалық инварианттар бойынша салыстырыңыз. Жасалған уақыт, провайдер жауап идентификаторы, техникалық өрістердің реті және usage өзгеше болуы мүмкін. Аударудың мәнін тексеріңіз: жүрістер реті, элемент түрлері, шақыру идентификаторлары, аргументтер, финалдық күй, қате коды және JSON Schema-ға сәйкестік.

Регрессия үшін екі фикстура тобын сақтаңыз. Біріншісінде кіріс пен күтілетін канондық операция болады. Екіншісінде канондық операция және әр адаптер үшін күтілетін сыртқы JSON болады. Бұл ақаудың қай жерде екенін тез көрсетеді: кіріс контракті парсерінде, ішкі көріністе немесе жауап сериализаторында.

Күйді, аудитті және деректерді сақтауды адаптерге қалдырмаңыз

Responses API серверлік күйді ыңғайлы етеді, бірақ бұл ыңғайлылық сақтау мен аудит мәселелерін жоймайды. Шлюз previous_response_id қолдаса, тарихтың қайда орналасқанын білуі керек: сыртқы провайдерде, шлюздің өзінде немесе екеуінде де. Бұл нұсқалардың құны, кідірісі, өшіру ережелері және құқықтық салдары әртүрлі.

OpenAI деректерді бақылау құжаттамасында /v1/chat/completions және /v1/responses үшін сақтау ережелері бөлек сипатталған; Responses API жағдайында қолданба күйі әдепкі бойынша платформа жағында сақталуы мүмкін. Бұл екі endpoint-ті ұқсас нәтиже үшін ғана бірдей деп жариялауға болмайтынын көрсетеді. Сақтау саясаты model өрісіне емес, операция контрактісіне қатысты.

Қазақстан және Орталық Азия жүйелері үшін канондық операцияға өңдеу белгілерін қосыңыз: деректер класы, data residency талаптары, рұқсат етілген аймақтар, аудит мерзімі, PII маскировкасы және сыртқы күйді қолдану мүмкіндігі. Маршрутизатор модель таңдамай тұрып бұл белгілерді оқуы керек. Мұны сұрау адаптациясынан кейін жасасаңыз, құпия деректер рұқсат етілмеген жерге кетіп қалуы мүмкін.

Аудит журналы толық промптті сақтауға міндетті емес. Көбіне нормаланған операцияның хешін, рұқсат етілген метадеректер жиынын, маршрутты, модельді, қолданылған мүмкіндіктерді, ұзақтықты, usage мәнін, қате кластарын және құрал шақыруларының байланысын сақтау жеткілікті. Толық мәтін тек бөлек қолжетімділігі мен сақтау мерзімі бар тар ақауларды жөндеу сценарийлеріне қажет.

Мұны «техникалық бөлшектер» деп жасырмаңыз. Шлюз екі контрактіні біріктіргенде, әр endpoint-тен көбірек контекст алады: тарихты, құралдарды, жауап схемасын және маршрутты. Демек, қолжетімділік ережелері жұмсағырақ емес, анығырақ болуы керек.

Анық бас тарту қажет жерде әмбебап аударма жасамаңыз

Шлюздің артықшылығы кез келген JSON-ды қабылдауында емес, қолдау көрсетілетін мағынаны болжамды түрде қабылдауында. Chat Completions пен Responses API-ды бір архитектурада қызмет көрсетуге болады, егер оның канондық операциясы, құрал нәтижелерімен қатаң байланысы, мүмкіндіктер матрицасы және ағын үшін бөлек күй машиналары болса.

Клиенттерге қажет жерде үйреншікті контрактіні қалдырыңыз. Ескі Chat Completions-ті жасанды түрде кедей Responses API-ға айналдырмаңыз және жаңа мүмкіндіктердің бәрі ескі choices[0].message ішіне сыйғандай көрсетпеңіз. Өрнектеу мүмкін емес әр жағдай үш шешімнің бірін алуы керек: шлюздің жеке күйі, анық шектелген режим немесе түсінікті қате.

Егер сізде прокси бар болса, ең қарапайым чаттан емес, ең жағымсыз тесттен бастаңыз: екі параллель tool call, ағынды аргументтер және бір тізбектегі қатаң JSON Schema. Бұл сценарий идентификаторларды ауыстырмай, stop мәнін ерте бермей және strict белгісін үнсіз алып тастамай өтсе, шлюздің негізі дұрыс құрылған.