Минулого місяця я наставляв колегу, який нещодавно змінив посаду, у створенні прототипу інтелектуальної служби підтримки. Вимоги були прості: користувач ставить запитання, модель відповідає, з невеликою пам'яттю контексту та потоковим виведенням тексту. Звучить так, ніби це можна зробити за два дні, але в результаті він спіткнувся на жорстко закодованому API Key, логіці повторних спроб і потоковій інтеграції. Я впорядкував весь процес у цій статті — сприймайте її як нотатки для наставництва новачків.
Крок перший: спочатку розберіть вимоги, потім обирайте модель
Не починайте одразу писати код. Потреби інтелектуальної служби підтримки загалом поділяються на три частини: розпізнавання намірів, запитання-відповіді на основі знань і багатоходова невимушена розмова. Розпізнавання намірів має бути швидким і дешевим — достатньо DeepSeek-V3 або API Qwen; запитання-відповіді на основі знань стосуються ваших приватних документів, тут потрібен RAG, а модель повинна розуміти довгий контекст; багатоходова невимушена розмова вимагає високого тону — Claude 4 Sonnet або GPT-4o тут надійніші.
Мій підхід полягав у тому, щоб спочатку запустити весь ланцюжок на одній універсальній моделі, а потім замінювати по черзі. Багатомодельна маршрутизація SiCore TokenWorks у цей момент економить сили: та сама кодова база, змінюєте лише назву моделі, щоб порівняти результати, без зміни автентифікації. Вибір API великої моделі — це не вибір найпотужнішої, а вибір найбільш відповідної завданню.
Крок другий: керування Key, не записуйте його в код
Жорстке кодування Key у вихідному коді — найпоширеніша помилка новачків. Щойно ви закомітите його в git, це рівносильно публікації. Правильний підхід — це розмежування рівнів через змінні середовища та файли конфігурації: локально використовуйте .env, для тестування та продакшену — конфігураційний центр або сервіс керування ключами.
Щодо ізоляції середовищ запам'ятайте три речі: для розробки, тестування та продакшену використовуйте різні Key; для кожного Key встановлюйте окрему верхню межу квоти; продакшн-Key надавайте лише серверній частині, фронтенд ніколи його не отримає. У нашому проєкті ми використовуємо SiCore TokenWorks — один Key дозволяє звертатися до GPT-4o, Claude, DeepSeek, Qwen, ERNIE, Doubao та інших провідних моделей, що позбавляє від клопоту підтримки кількох наборів автентифікації, а перемикання Key між середовищами — це лише зміна однієї змінної.
Крок третій: обгортка викликів і повторні спроби при помилках
Код, що викликає SDK напряму, неможливо підтримувати. Зробіть обгортку, яка централізовано обробляє тайм-аути, обмеження швидкості та повторні спроби. Ідея така: обгорніть виклик моделі у функцію, параметрами якої є messages і назва моделі, а всередині перехоплюйте три типи помилок — мережевий тайм-аут, обмеження швидкості 429, серверна помилка 5xx.
Стратегія повторних спроб — експоненційне відступання: перший раз чекаємо 1 секунду, другий — 2 секунди, третій — 4 секунди, максимум тричі. Для 429 потрібна особлива обробка — дивіться на заголовок retry-after, що повертається. Не повторюйте для всіх помилок: повторення помилки параметрів сто разів нічого не дасть. Цінність шлюзу моделей саме в цьому шарі — він зводить повторні спроби, деградацію та логи в одне місце, а бізнес-код лише отримує результат.
Нагадування про підводний камінь: повторні спроби мають бути ідемпотентними. Якщо виклик має побічні ефекти (наприклад, запис у базу даних), перед повторною спробою спочатку переконайтеся, що попередній раз справді не вдався.
Крок четвертий: потокове виведення та інтеграція з фронтендом
Основа досвіду служби підтримки — це «ефект друкарської машинки». Серверна частина за допомогою SSE надсилає токени шматками на фронтенд, а фронтенд приймає їх через EventSource або ReadableStream у fetch.
Ключовий момент бекенду: встановіть stream=True, розбирайте отримані delta шмат за шматом, а при зустрічі з [DONE] завершуйте. Ключовий момент фронтенду: не викликайте setState на кожен отриманий символ, накопичуйте 20–50 мілісекунд і рендерте пакетно, інакше сторінка гальмуватиме як слайд-шоу.
Ще один підводний камінь: під час потокового виведення користувач може закрити сторінку. Серверна частина повинна слухати подію розриву з'єднання й вчасно скасовувати запит до джерела, інакше токени витрачаються марно. За оплати за обсягом такі втрати накопичуються.
Крок п'ятий: моніторинг витрат і сповіщення
Перед запуском обов'язково впровадьте інструментування. Для кожного виклику записуйте: назву моделі, кількість вхідних токенів, кількість вихідних токенів, час виконання, чи була повторна спроба. Зберіть ці дані за тиждень — і ви дізнаєтеся, на що витрачаються гроші.
Налаштуйте два пороги сповіщень: сигнал про перевищення денного порогу витрат і сигнал про аномалію кількості токенів за один виклик. Якось один користувач вставив цілий документ, і за один раз було кілька десятків тисяч вхідних токенів — без сповіщення рахунок наприкінці місяця виглядав би дуже погано.
Досвід економії: для таких частих і нескладних завдань, як розпізнавання намірів, переходьте на дешевші вітчизняні моделі — витрати знижуються помітно. Оптові закупівлі та планування з зеленою енергетикою — ось чому ціни на агрегаторних платформах, як-от SiCore TokenWorks, нижчі за пряму офіційну закупівлю; за нашими порівняннями, у сценаріях з частими викликами різниця очевидна.
Одним реченням: складність прототипу інтелектуальної служби підтримки не в моделі, а в інженерних деталях. Керуйте Key добре, пишіть повторні спроби правильно, стабільно інтегруйте потокове виведення, слідкуйте за витратами — а далі залишається лише налаштування prompt. Якщо хочете заглибитися в реалізацію уніфікованої інтеграції багатьох моделей і маршрутизації моделей, продовжуйте читати за темою шлюзу API великих моделей.