API жауабындағы нақты модельді болжамсыз анықтау

Модель алиасы клиентке ыңғайлы, бірақ сұрауды нақты кім өңдегенін дәлелдемейді. Өндірістік ортада бұл айырмашылық тез арада практикалық мәселеге айналады: команда шығынның өскенін, жауап сапасының күтпеген өзгергенін немесе деректердің орналасуына қатысты шағымды байқайды да, журналда тек model: "smart-route" деген жол бар екенін көреді.

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

Алиас ниетті сипаттайды, орындалуды емес

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

Мәселе бір өріске екі түрлі сұраққа жауап бергізуге тырысқанда басталады:

• Клиент не сұрады?
• Инференсті іс жүзінде не орындады?

Бірінші сұрақ қолданбаңыздың келісімшартына жатады. Екіншісі орындалу бақылануына қатысты. Оларды араластырсаңыз, fallback-тан, қайталап көруден немесе саясаттың ауысуынан кейін нәтижені түсіндіру мүмкіндігін жоғалтасыз.

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

Аудит интерфейсінде алиасты «жауап берген модель» деп атамаңыз. Оны requested_alias немесе requested_model деп атаңыз. Атаулардағы осы шағын тәртіп инцидентті талдау кезінде көптеген қате қорытындының алдын алады.

Төрт идентификаторды бір жолға біріктіруге болмайды

Трассалау үшін кемінде төрт түрлі мән керек, өйткені әрқайсысы бөлек сұраққа жауап береді.

requested_alias клиенттің таңдауын көрсетеді. Ол legal-review, fast-chat немесе өнім тобы қолданатын атау болуы мүмкін. Алиас сіздің саясатыңызбен бірге өзгеріп отырады және әдетте бірнеше айдағы нәтижелерді салыстыруға жарамайды.

resolved_model маршрутизатор анықтаған канондық идентификаторды көрсетеді. Оған витринадағы атауға тәуелсіз формат керек. OpenRouter каталогының құжаттамасы id, экранда көрсетілетін атау және модельдің тұрақты идентификаторы ретінде ұсынылатын canonical_slug мәндерін ажыратады. Бұл пайдалы бөлініс: әдемі атауды адамдар оқиды, ал өзгермейтін идентификатор журналдар мен ережелерге керек.

provider әрекетке қызмет көрсеткен ұйымды немесе есептеу контурын көрсетеді. Бір модель әртүрлі аймақтары, кезектері, бағасы және параметрлерді қолдауы бар бірнеше жеткізушіде қолжетімді болғанда, бұл өрістің маңызы артады.

execution_model нақты endpoint-ке берілген немесе сол жерде расталған идентификаторды көрсетеді. Кейде ол resolved_model мәнімен бірдей болады. Кейде провайдер орналастырудың дәлірек атауын ашады. Егер мұндай мән болмаса, оған алиасты қоймаңыз және каталогтағы мәнді көшірмеңіз. null қойып, дереккөз оны бермегенін белгілеңіз.

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

Нәтиже келісімшарты фактілерді болжамдардан бөлуі керек

Жақсы схема барлық өрісті кез келген бағамен толтыруға тырыспайды. Ол әр мәннің дереккөзін сақтап, белгісіздікке мүмкіндік береді. Бұл модель нұсқасы үшін маңызды: отбасының жария атауы, каталогтағы күн және нақты орналастырудың revision-ы бір нәрсе емес.

Мен әдетте әртүрлі жерден келетін өрістердің жанына source қосамын. Провайдердің жауабымен расталған мән маршрутизация баптауынан жасалған болжамнан сенімдірек. Шлюз есептеген өріс те пайдалы, бірақ оны провайдер растаған дерек ретінде көрсетуге болмайды.

Төменде қорытынды жауаптың пайдалы бөлігі көрсетілген. Бұл әмбебап стандарт емес, оны кәдімгі OpenAI-үйлесімді жауап объектісінің жанына орналастыруға болатын келісімшарт.

{
  "id": "req_01J9X7KQ5Y",
  "object": "chat.completion",
  "model": "support-assistant",
  "routing": {
    "requested_alias": "support-assistant",
    "resolved_model": {
      "value": "vendor-x/chat-pro",
      "source": "router_catalog"
    },
    "selected_attempt_id": "att_02",
    "policy": {
      "id": "support-default",
      "revision": "2026-07-23.3",
      "hash": "sha256:6c33c8..."
    },
    "attempts": [
      {
        "id": "att_01",
        "provider": "provider-a",
        "execution_model": null,
        "execution_model_source": "not_disclosed",
        "status": "failed",
        "failure_class": "timeout",
        "started_at": "2026-07-23T09:14:01Z",
        "finished_at": "2026-07-23T09:14:16Z"
      },
      {
        "id": "att_02",
        "provider": "provider-b",
        "execution_model": "chat-pro-2026-06",
        "execution_model_source": "provider_response",
        "model_revision": null,
        "model_revision_source": "not_disclosed",
        "status": "selected",
        "started_at": "2026-07-23T09:14:16Z",
        "finished_at": "2026-07-23T09:14:18Z"
      }
    ]
  }
}

Мұндай объектінің екі пайдалы қасиеті бар. Біріншіден, ол нұсқа туралы өтірік айтпайды: null нақты revision белгісіз екенін білдіреді. Екіншіден, ол жеңген әрекетті ғана емес, соған жеткізген жолды да көрсетеді.

Жоғарғы деңгейдегі model өрісін ескі клиент кодымен үйлесімділік үшін сақтаған жөн. Бірақ оны шындықтың жалғыз көзі етпеңіз. Жоғарыдағы келісімшартта ол нәтиженің ыңғайлы белгісі болып қалады, ал толық мәлімет бөлек routing кеңістігінде сақталады.

Fallback әрекеттер тізбегі ретінде жазылуы керек

«Сұрау сәтті орындалды» деген қорытынды тарихтың жартысын жасырады. Бірінші әрекет 429 алса, екіншісі response_format параметрін қолдамаса, ал үшіншісі мәтін қайтарса, кідірісті, шығынды және мінез-құлық айырмасын дәл осы тізбек түсіндіреді.

Әр әрекеттің жеке идентификаторы, басталу және аяқталу уақыты, мәртебесі, провайдері және бас тарту санаты болуы керек. Қате мәтінін ғана жазбаңыз. Шикі мәтін қорғалған журналда пайдалы, бірақ аналитикаға тұрақты санаттар керек: timeout, rate_limited, upstream_5xx, unsupported_parameter, policy_rejected, cancelled.

Сәтті әрекет үшін selection_reason мәнін бөлек сақтаңыз. Мысалы, мынадай мәндер жарайды:

• primary_route, бірінші таңдалған жол үшін;
• fallback_after_failure, техникалық бас тартудан кейін;
• fallback_after_policy_rejection, деректер немесе аймақ бойынша тыйымнан кейін;
• retry_same_provider, сол провайдерде қайталап көру кезінде;
• manual_override, маршрутты оператор немесе клиент ережесі бекіткенде.

Бұл тізімді еркін мәтінге айналдырмаңыз. Еркін мәтін инженерге түсіндіруге жарайды, бірақ оны дұрыс топтастыру мүмкін емес. Бір айдан кейін лимитке байланысты негізгі жолдан кеткен сұраулардың үлесін есептеу керек болады. Ол кезде мыңдаған журнал жолын тұрақты өрнектермен талдағыңыз келмейді.

Көп жағдайда еленбей қалатын жағымсыз жағдай бар. Маршрутизатор сұрауды провайдерге жібереді, провайдер генерацияны бастап үлгереді, кейін олардың арасындағы байланыс үзіледі. Толық құн есептелді ме және жауап клиентке жетті ме, сіз нақты білмеуіңіз мүмкін. Мұндай әрекетті нақтылау­сыз failed деп белгілемеңіз. unknown_outcome мәртебесін қолданыңыз және провайдер деректерімен салыстырмай тұрып, дәл биллингті уәде етпеңіз.

Streaming жауабы фактіні тек соңында растайды

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

Сұрауды жоғарыға жібермей тұрып әрекет жазбасын жасаңыз. Алғашқы оқиғада first_byte_at мәнін белгілеңіз. Қалыпты аяқталғанда finished_at, соңғы finish_reason, usage және selected мәртебесін қосыңыз. Ағын үзілсе, белгілі болған деректерді сақтап, stream_interrupted, client_disconnected немесе unknown_outcome мәртебелерінің бірін қойыңыз.

Оқиғалар схемасы мынадай болуы мүмкін:

request accepted
  -\u003e attempt created
  -\u003e upstream connected
  -\u003e first token received
  -\u003e final usage received
  -\u003e attempt selected
  -\u003e client stream closed

Барлық провайдер usage мәнін ағын соңында бірдей жолмен жібермейді. Сондықтан usage_reported_by_provider және usage_estimated_by_gateway өрістерін бөліңіз. Бірін есепті салыстыру үшін пайдалануға болады. Екіншісі жедел аналитикаға жарайды, бірақ бағалау екенін көрсетуі керек.

OpenRouter-дың ағын режиміне арналған құжаттамасы клиент елемеуі тиіс қызметтік SSE түсініктемелері туралы да ескертеді. Аудит үшін қарапайым ереже бар: әр кіріс оқиғесінде жаңа әрекет жасамаңыз және мәртебені өзгертпеңіз, алдымен оқиға түрін жіктеңіз.

Модель нұсқасы тек дереккөзі белгілі болса пайдалы

model_version өрісін схемаға көбіне белгі үшін қосып, кейін оны модельдің маркетингтік атауымен толтырады. Бұлай жасауға болмайды. Chat Pro, chat-pro, chat-pro-latest және chat-pro-2026-06 отбасыны, алиасты, жаңарту арнасын және нақты жинақты білдіруі мүмкін. Олар бір-бірін алмастырмайды.

Кемінде мына үш өрісті бөліңіз:

• model_family, белгілі болса тұрақты модель отбасы үшін;
• model_release, провайдер жариялаған релиз немесе snapshot үшін;
• deployment_revision, жұмыс істеп тұрған орналастырудың нақты нұсқасы үшін.

Провайдерлер көбіне біріншісін ғана ашады. Кейде екіншісін де береді. Үшіншісі, әсіресе жабық модельдерде, сирек қолжетімді. Аудит бұл шектеуді адал көрсетуі керек: null және not_disclosed деген белгі болжамнан құрастырылған жолдан әлдеқайда дұрыс.

Жеке open-weight орналастыруларында жағдай басқа. Онда салмақтар хэшін, токенизатор нұсқасын, чат шаблонын, контейнер revision-ын және GPU пулының идентификаторын тіркеуге әрі тіркеу қажет. Әйтпесе «біз сол модельді іске қостық» деген сөз ештеңені дәлелдемейді. Чат шаблонының немесе кванттаудың өзгеруі модель атауы өзгермесе де жауапқа айтарлықтай әсер етуі мүмкін.

Жабық сыртқы endpoint пен жеке кластерді бірдей егжей-тегжейлі сипаттауға тырыспаңыз. Ортақ өрістерді қалдырып, арнайы мәліметтерді provider_metadata ішіне шығарыңыз. Сонымен бірге келісімшарттың негізгі бөлігінде тексерілмейтін өрістерге тыйым салыңыз.

Маршрут саясаты қайта орындалатындай болуы керек

Нақты орындаушы шешімнің өзін түсіндірмейді. Жауапты provider-b бергенін білсеңіз де, сол сәтте қандай ережелер жұмыс істегенін білмесеңіз, таңдау күтілгендей болды ма, түсіне алмайсыз.

Сұрау қабылданған сәттегі саясаттың өзгермейтін revision-ын сақтаңыз. Git revision нөмірі, жарияланған ереже идентификаторы және қалыпқа келтірілген конфигурацияның криптографиялық хэші жарайды. Тек default-policy атауын сақтамаңыз, өйткені оның мазмұны уақыт өте өзгереді.

Мысалы, логика fallback-қа аймақ пен деректерді өңдеу талаптарына сай маршруттар арасында ғана рұқсат беруі мүмкін:

{
  "policy_id": "claims-assistant",
  "revision": "2026-07-23.3",
  "allowed_regions": ["KZ"],
  "fallback": "same_data_boundary_only",
  "providers": ["local-gpu", "provider-kz"],
  "max_attempts": 2
}

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

AI Router ішінде мұндай метадеректер бірыңғай OpenAI-үйлесімді endpoint-ті аудитпен, PII маскасымен және деректерді Қазақстанда сақтау талаптарымен біріктіруі керек командаларға әсіресе пайдалы. Бірақ схема бір провайдермен тікелей жұмыс істегенде де керек: бүгін сізде бір жол бар, ертең резервтік контур мен сезімтал тапсырмаларға арналған бөлек ережелер пайда болуы мүмкін.

Идентификаторлар жауапты журналмен байланыстырады, бірақ журналдың орнын баспайды

Әр шақыруда кемінде екі идентификатор болуы керек. request_id шлюзде жасалып, жауапта, трассада және журналдарда пайдаланылады. client_request_id қолданбадан келеді және шақыруды пайдаланушы әрекетімен, кезек тапсырмасымен немесе CRM операциясымен байланыстырады.

Қызметіңіз бөлінген трассалауды қолданса, trace_id қосыңыз. Сонда бір trace HTTP кірісін, саясат тексерісін, деректерді маскалауды, модель сұрауын, құралдарды, нәтиже жазбасын және қайталап көруді байланыстырады. Бірақ онымен маршрут журналын алмастырмаңыз: trace сервистер жұмысының ретін көрсетеді, ал routing.attempts объектісі шешімнің мәнін сақтайды.

Клиент жауабында әдетте қысқа қорытындыны қайтару жеткілікті:

{
  "request_id": "req_01J9X7KQ5Y",
  "requested_model": "support-assistant",
  "resolved_model": "vendor-x/chat-pro",
  "routing_status": "completed"
}

Әрекеттердің толық массивін сенімді серверлік клиентке, әкімшіге немесе аудит жүйесіне берген дұрыс. Провайдер атауы, endpoint идентификаторы және ауысу себептері ішкі топология мен келісім шарттарын ашуы мүмкін. Сыртқы диагностикалық келісімшарт пен ішкі операциялық жазбаны бөліңіз.

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

Келісімшартты басқарылатын ақаулармен тексеру керек

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

Тест контурында бес тексеру жасаңыз:

1. Сұрауды алиас арқылы жіберіп, жауапта алиас пен анықталған канондық модельдің екеуі де бар екеніне көз жеткізіңіз.
2. Бірінші маршрутта timeout-ты әдейі қайтарып, failed мәртебесі бар att_01 пайда болғанын, ал att_02 selected алғанын тексеріңіз.
3. Екінші маршрут қолдамайтын параметр беріп, сұраудың үнсіз өзгертілмей, unsupported_parameter санатына түскенін тексеріңіз.
4. Бірнеше токеннен кейін ағынды үзіп, жазбаның сәтті аяқталу мәртебесін алмағанын тексеріңіз.
5. Саясатты өзгертіп, шақыруды қайталаңыз және ескі жауаптың бұрынғы revision-ға сілтеме жасап тұрғанына көз жеткізіңіз.

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

Журналда тек алиас пен HTTP мәртебесі қалса, тергеу жанама белгілер арқылы жағдайды қайта құруға айналады. Сапа, есеп немесе деректердің орналасуы бойынша айырмашылықты кейін түсіндіруге тура келмей тұрып, нақты маршрутты нәтиже келісімшартына қосыңыз.