Өнім мен қолдау үшін LLM API қате кодтарын біріздендіру

Бір ақау неге әртүрлі көрінеді

Бір ғана мәселе сирек бір форматта келеді. Бір провайдер шамадан тыс жүктеме кезінде 429 қайтарады, екіншісі 503 береді, ал үшіншісі жай ғана қосылымды timeout арқылы үзіп тастайды. Пайдаланушы үшін бұл бір жағдай: «сұрау орындалмады». Ал өнім, қолдау және аналитика үшін бұл үш түрлі оқиға.

Сондықтан LLM API қате кодтарын біріздендіру — ұсақ-түйек емес, сыртқы көріністі ғана өзгертетін нәрсе емес. Егер жауаптарды ортақ сөздікке жинамасаңыз, команда ақаудың себебі туралы емес, оның қалай жазылатыны туралы дауласа бастайды. Қолдау ұқсас жағдайларды қолмен іздейді, ал өнім проблемалардың жиілігі туралы бұрмаланған сурет көреді.

Шатасу бірнеше деңгейде бірден пайда болады. Провайдерлер бірдей шамадан тыс жүктемені әртүрлі кодтайды. Бір провайдердің модельдері қате мәтінін әртүрлі береді. SDK мен прокси кейде бастапқы статус орнына өз exception-ін қояды. Мониторинг ұқсас ақауларды бөлек метрикаға бөліп жібереді.

Сондықтан «генерация тұрып қалды» деген шағым логтарда әртүрлі көрінеді. Бір жүйеде 504 gateway timeout, басқасында 429 rate limit, үшіншісінде — upstream request failed сияқты анық коды жоқ нәрсе көресіз. Ал түпкі себеп көбіне біреу: провайдер кезекке немесе қатаң лимитке байланысты сұрауды уақытында өңдеп үлгермеген.

Қате мәтіні де сенімсіз. Бір модель context length exceeded деп жазады, екіншісі — too many tokens, үшіншісі — invalid request. Осы жолдарды сол күйі алсаңыз, қолдау бір себепке үш түрлі сценарий алады: сұрау тым үлкен.

Тіпті бір шлюз арқылы жұмыс істегенде де айырмашылықтар өздігінен жойылмайды. Шлюз бірнеше модельге қол жеткізуді жеңілдетеді, бірақ өнімге бәрібір қате туралы өз ортақ тілі керек. Әйтпесе модель ауыстыру тек жауап сапасы мен бағасын ғана емес, қолдаудың мінез-құлқын да өзгертеді.

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

Сөздікте қандай қате топтарын ұстау керек

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

Бірінші топ — таймауттар және қосылымның үзілуі. Бұған модель тым ұзақ жауап берген, қосылым үзілген, stream ортасында тоқтаған немесе шлюз жауапты күтіп үлгермеген жағдайлар кіреді. Пайдаланушы үшін бұл «сұрау тұрып қалды» немесе «жауап келмеді» болып көрінеді.

Екіншісі — лимиттер және таусылған квота. Бір провайдер 429 қайтарады, екіншісі rate limit дейді, үшіншісі кредит жетпейтінін хабарлайды. Сөздікте бұл бір топ, бірақ ішінде қысқа жүктеме секірісі мен бюджеттің толық таусылуын ажыратқан пайдалы.

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

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

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

Қарапайым тест бар: топтың атауын көрген адам бірден келесі қадамды түсінуі тиіс. Әзірлеуші сұрауды түзетеді, платформа шақыруды қайта жасайды, қолдау қолжетімділікті тексереді, ал өнім абстрактілі «AI бұзылды» емес, нақты ақау түрін көреді.

Егер команда бірнеше модельге бір шлюз арқылы кірсе, мұндай сөздік әсіресе тез ақталады. Мысалы, AI Router арқылы жұмыс істегенде әртүрлі провайдерлер бәрібір context length exceeded, bad request немесе жай 400 қайтара алады. Қолдау үшін бұл үш бөлек мәселе емес, бір мәселе: сұрау рұқсат етілген өлшемнен асып кеткен, оны қысқарту немесе бөлу керек.

Қатені бір ортақ форматта қалай сипаттау керек

Егер сізде бірнеше провайдер мен модель болса, бір ғана мәселе тез арада бейберекетке айналады. Бір API 429 қайтарады, екіншісі rate limit жазады, үшіншісі 503-ті көмескі мәтінмен береді. Өнім мен қолдау үшін бұл бір жағдай, сондықтан оны бір ішкі кодпен сипаттаған дұрыс.

Алдымен қысқа ішкі кодтар сөздігін жасаңыз. Атаулар қарапайым әрі бірмәнді болсын: timeout_upstream, rate_limited, invalid_request, auth_failed, model_unavailable. Мұндай код провайдерге тәуелді емес және бірден нақты не бұзылғанын көрсетеді.

Содан кейін әр кодқа клиент көретін HTTP статусын бекітіңіз. Бұл командалар арасындағы артық таласты азайтады. Мысалы, invalid_request әдетте 400 болып кетеді, auth_failed — 401 немесе 403, rate_limited — 429, ал timeout_upstream — 504. Сыртқы статусды айна-қатесіз қайталау міндет емес. Клиентке түсінікті, тұрақты келісім керек.

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

Қате мәтінін екі қабатқа бөлген жөн. Интерфейсте ішкі кухнясыз қысқа әрі сабырлы мәтін керек: «Сервис уақытында жауап бермеді. Бір минуттан кейін қайта көріңіз». Қолдау үшін басқа формат керек: себеп, әрекет және сөздікке сілтеме. Мысалы: timeout_upstream: провайдер 30 секунд ішінде жауап бермеді, қайталау қауіпсіз, жүктеме секірісін және маршрут таймаутын тексеріңіз.

Логтарда талдауды жеңілдететін негізгі өрістерді сақтаңыз: provider, model, request_id, latency, internal_error_code. Егер сұраулар роутер арқылы өтсе, маршрутты, қайталау санын және fallback іске қосылды ма, соны да қосқан дұрыс.

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

Сөздікті логтардан қалай құрастыруға болады

Бастау үшін провайдерлердің құжаттамасынан емес, өз логтарыңыздан бастаған дұрыс. Соңғы 2-3 аптада әдетте қажеттінің бәрі болады: таймауттар, 429, bad request, stream-нің үзілуі, бос жауаптар және сирек 5xx. Тек HTTP кодын ғана емес, қате мәтінін, провайдерді, модельді, сұрау түрін және қайталау көмектесті ме, соны да сақтаңыз.

Келесі қадамды қарапайым ретпен жасаған ыңғайлы:

1. Алдымен қолмен тазартып әуре болмай, барлық шикі қателерді шығарып алыңыз.
2. Сосын дубликаттарды мәтіні бойынша емес, мағынасы бойынша біріктіріңіз.
3. Әр топқа бір ішкі код беріңіз.
4. Әр код үшін әрекет ережесін жазыңыз: қайталау керек пе, қандай backoff қолдану керек, қашан модель ауыстыру керек және қашан инцидент ашу керек.
5. Соңында барлық провайдерден келген тест жауаптарына маппингті тексеріп шығыңыз.

Қарапайым сөздіктің жақсы белгісі — бірдей мәнге бірдей әрекет. Егер бір провайдер 408 қайтарса, ал екіншісі прокси арқылы 524 берсе, бірақ екі жағдайда да сұрау тұрып қалып, бірнеше секундтан кейін қайталау көбіне көмектесе берсе, бір ішкі кодты ұстаңыз. Қолдауға бөтен тұжырымдардың мұражайы керек емес. Оларға нақты жауап керек: не болды және әрі қарай не істеу керек.

Өнім мен қолдау көретін өрістерді бөлек тексеріңіз. Пайдаланушыға әдетте «модель уақытында жауап бермеді» деген қысқа статус жеткілікті. Операторға болса бастапқы код, провайдер, trace id, қайталау саны және fallback іске қосылды ма — солар керек.

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

Егер ішкі код не істеу керегін көрсетпесе, оны қайта ойластырған дұрыс. Әйтпесе сөздік тағы бір түсініксіз атаулар тізіміне айналып кетеді.

Пайдаланушыға, қолдауға және инженерге не көрсету керек

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

Пайдаланушыға қысқа себеп пен түсінікті әрекет берген дұрыс. Мысалы: «Сервис қазірше бос емес. Сұрауды 30 секундтан кейін қайталаңыз» немесе «Сұрау тым үлкен. Мәтінді қысқартып, қайта көріңіз». upstream 429 немесе provider validation error сияқты формулировкалар тек шатастырады.

API ішінде провайдерге тәуелсіз тұрақты ішкі код ұстаңыз. Бүгін біреу rate limit exceeded жазады, екіншісі 429-ды басқа мәтінмен қайтарады, үшіншісі мұны quota error деп атайды. Өнім үшін бұл бір ғана код болуы тиіс, мысалы RATE_LIMIT. Сол сияқты UPSTREAM_TIMEOUT, INVALID_INPUT, AUTH_ERROR, CONTENT_BLOCKED те керек. Сонда аналитика, alert-тер және қайталау ережелері модель немесе маршрут ауысқан сайын бұзылмайды.

Сонымен бірге провайдердің шикі жауабын жоғалтуға болмайды. Статусты, жауаптың денесін, header-лерді, провайдердің request_id-ін, модельді, маршрутты және жауап беру уақытын сақтаңыз. Егер инфрақұрылымда аудит-логтар мен PII маскалау бұрыннан бар болса, AI Router сияқты, мұндай деректерді ұқыптырақ сақтап, инженерлерге талдауға тезірек бере аласыз.

Бір инцидентті үш қабатқа бөліп қарау ыңғайлы:

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

Қолдау үшін тек код емес, әрекетке арналған кеңес те пайдалы. Егер RATE_LIMIT келсе, жүйе бірден: «Трафиктің күрт өсуін, retry-after-ты және балама маршрутты тексеріңіз» деп көрсете алады. Егер INVALID_INPUT келсе, қолдау мынадай нұсқау көруі тиіс: «Пайдаланушыдан контексті қысқартуды немесе қолдау таппайтын параметрді алып тастауды сұраңыз».

Мұндай бөлу сұраулар бір OpenAI-үйлесімді қабат арқылы бірнеше модельге өтетін жерде жақсы жұмыс істейді. Сыртта өнім қарапайым әрі сабырлы сөйлейді. Іште API мен логтарда қажетті дәлдік сақталады.

Бірнеше модельмен жұмыс істейтін командаға мысал

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

Мәселе екі провайдер бір нәрсені әртүрлі сөзбен айтқан сәтте басталады. Бірінші модель кәдімгі HTTP 429 қайтарады. Екіншісі rate_limit_exceeded деп жауап береді, бірақ мағынасы бір: сұрау тым көп, аздап күте тұрған дұрыс.

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

Шешім қарапайым: қосымша мен модельдердің арасына ортақ маппинг қабатын қою. Ол провайдердің форматы туралы дауласпайды және интерфейске ұсақ-түйектің бәрін тықпайды. Ол әртүрлі жауаптарды бір ішкі кодқа, мысалы limit_retry_later-ге аударады.

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

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

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

Командалар көбіне қай жерде қателеседі

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

Бірінші жиі қате — пайдаланушыға провайдердің шикі мәтінін көрсету. Ондай мәтін шуылдақ, кейде үрейлі, және не істеу керегін сирек түсіндіреді. Интерфейсте қысқа хабарлама қалдырып, толық жауапты логтар мен инцидент карточкасында сақтау дұрыс.

Екінші қате — 400 мен 422-ні бір жәшікке салу, тек екеуі де «сұрау қатесі» сияқты көрінеді деп. Шындығында мағынасы бөлек. 400 әдетте сұрау қате жиналғанын білдіреді, ал 422 көбіне формат дұрыс болса да, дерек тексеруден өтпейтінін көрсетеді: енгізу тым ұзын, қолдау таппайтын параметр, өрістердің қайшылығы.

Үшінші қате — әр сәтсіз сұрауды автоматты түрде қайта жіберу. bad request үшін бұл пайдасыз: жүйе уақытты, квотаны, кейде ақшаны да жұмсайды, ал нәтиже өзгермейді. Қайталау таймауттарда, 429-дың бір бөлігінде және 5xx-тің бір бөлігінде ғана мәнді, бірақ бұзылған параметрлерде емес.

Төртінші қате — провайдердің request_id-ін жоғалту. Бұл алғаш ірі инцидентке дейін ұсақ нәрсе сияқты көрінеді. Сосын қолдау шағым көреді, инженер логтарды ашады, бірақ нақты сұрауды провайдер жауабымен байланыстыру мүмкін болмай қалады. Егер сізде бірнеше модель мен бірнеше провайдер болса, мұндай із әрдайым керек.

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

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

Релизге дейінгі жылдам тексеріс

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

Төмендегі қысқа тізім әдетте жеткілікті:

• Әр ішкі кодтың атауы қарапайым.
• Әр код бір әрекетке әкеледі.
• Қолдау кодпен қатар клиентке бірінші жауаптың нақты мысалын көреді.
• Дашборд қателерді ішкі сөздік бойынша санайды, ал провайдердің шикі жауабын жанында сақтайды.
• Автотесттер мен қолмен тексеру кем дегенде 429, таймаут, 400, 401 және 503-ті қамтиды.

Тағы бір нәрсе жиі ұмытылады: бір қате класы логтарда, қолдау панелінде және өнім есептерінде бірдей аталуы керек. Егер логта RATE_LIMIT тұрса, ал қолдау интерфейсінде — «провайдердің уақытша мәселесі» деп жазылса, шатасу бірінші аптада-ақ басталады.

Схеманы қысқа мысалмен тексерген пайдалы. Провайдер A 504 қайтарды, провайдер B статуссыз мәтіндік қате берді, ал сіздің шлюзіңіз екі жағдайда да оқиғаны UPSTREAM_TIMEOUT деп белгіледі. Қолдау клиентке не айту керегін бірден түсінеді: «Сұрау модель жағында тұрып қалды, жүйе қазір қайта көруде, бір минуттан кейін оралыңыз».

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

Әрі қарай не істеу керек

Қателердің бүкіл әлемін бірден сипаттауға тырыспаңыз. Оның орнына команда ең жиі көретін 10-15 ақауды алыңыз: таймауттар, rate limit, bad request, провайдердің бас тартуы, авторизация мәселелері, бос жауап. Егер осы жағдайлар бірдей код пен бірдей түсіндірме алса, өнім мен қолдау бір тілде сөйлей бастайды.

Сөздіктің иесі болуы керек. Әдетте бұл backend lead, платформалық инженер немесе интеграцияға жауапты адам болады. Ол жаңа кодты қай топқа жатқызуды шешеді, атауларды қадағалайды және командаға provider_timeout, model_timeout және request_expired сияқты ұқсас статустарды көбейткізбейді, егер өнім үшін бұл бір-ақ ақау болса.

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

Егер команда бірнеше модель мен провайдермен жұмыс істесе, біріздендіру қабатын бір ортақ эндпоинттің қасында ұстаған дұрыс. Сонда провайдер жауаптарының айырмашылығын әр сервисте емес, бір жерде ұстайсыз. Егер ол үшін AI Router сияқты OpenAI-үйлесімді шлюз қолданылып, бар SDK, код және промпттарды сақтап, тек base_url ауыстырсаңыз, маршрутизация мен қате сөздігін қатар алып жүру әлдеқайда оңай.

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

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