Керування каналами в AI-шлюзі

«Канал (Channel)» — це конфігурація точки підключення постачальника в AI-шлюзі. Вона зберігає адресу постачальника, справжній API Key, доступні моделі, а також інформацію про ціноутворення та ліміти. Саме на основі цих каналів шлюз маршрутизує запити від застосунків до відповідного постачальника. У цій статті описано, як додавати, налаштовувати, тестувати й керувати каналами.

Попередні умови

• ServBay встановлено й запущено, і ви ввійшли в обліковий запис ServBay (перед додаванням каналу потрібно ввійти).
• Підготовлено справжній API Key цільового постачальника (для локальних постачальників, як-от Ollama / LM Studio, його можна не заповнювати).
• Якщо ви ще не ознайомилися із загальною архітектурою AI-шлюзу, радимо спершу прочитати Вступ до AI-шлюзу.

Додавання каналу

Перейдіть на сторінку AI Gateway → Канали (Channels) і натисніть Додати (Add), щоб відкрити майстер. Майстер складається з трьох кроків.

Крок 1. Вибір постачальника

Постачальники згруповані за категоріями; натисніть картку, щоб вибрати:

• Основні (Mainstream)：OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Китайські (China)：DeepSeek, Qwen (Tongyi Qianwen), Zhipu GLM, Kimi, Doubao · Volcano, ERNIE Bot, Hunyuan, MiniMax, 01.AI, StepFun.
• Локальні (Local)：Ollama, LM Studio.
• Користувацькі (Custom)：OpenAI Compatible, Custom.

Після вибору постачальника шлюз автоматично підставить Base URL за замовчуванням для цього постачальника.

Перемикання між двома регіонами

Китайські постачальники, як-от Qwen, Zhipu GLM, Kimi, Doubao · Volcano, Hunyuan, MiniMax і StepFun, пропонують два набори ендпоінтів: локальний для Китаю та глобальний. Коли ви вибираєте такого постачальника, у майстрі з’являється перемикач «Регіон» (🇨🇳 Китай / 🌐 Глобальний), після перемикання Base URL автоматично оновлюється на адресу відповідного регіону.

Крок 2. Заповнення конфігурації

• Назва каналу (обов’язково) — використовується для ідентифікації каналу в списку; можна задати власну.
• Base URL (обов’язково) — адреса API постачальника. Для більшості постачальників вона вже заповнена автоматично; для Azure OpenAI і Custom потрібно заповнити вручну.
• API Key (необов’язково) — справжній ключ постачальника. Якщо залишити порожнім, можна лише перевірити доступність ендпоінта, але не валідність ключа; для локальних постачальників (Ollama / LM Studio) його зазвичай не потрібно заповнювати.
• Моделі — є два способи, виберіть один:
  • Автоматичне виявлення: натисніть «Виявити», і шлюз звернеться до API списку моделей постачальника, щоб отримати доступні моделі; ви можете вибрати кілька у вигляді тегів (chip).
  • Ручне заповнення: введіть назву моделі безпосередньо. Для каналів Azure потрібно вказати назву розгортання (Deployment name), а не назву моделі.
• Пріоритет / вага — коли кілька каналів можуть обслуговувати одну модель, шлюз використовує це для вибору маршруту та розподілу навантаження.

Увага щодо Azure OpenAI

У полі «Моделі» для каналу Azure слід вказати назву розгортання (Deployment name), створеного вами в порталі Azure, а не назву базової моделі. У Base URL також потрібно вказати ендпоінт вашого ресурсу Azure.

Крок 3. Підтвердження та надсилання

Перевірте підсумок конфігурації та надішліть. Після успішного надсилання новий канал з’явиться в списку каналів і показуватиме стан працездатності в реальному часі.

Перевірка можливостей і стратегія маршрутизації

Після додавання каналу шлюз виконує для нього перевірку можливостей (capability probing) — це найважливіший механізм інтелектуальної маршрутизації AI-шлюзу. Результати перевірки визначають, чи зможуть такі інструменти, як Claude Code, використовувати канал напряму, чи потрібно створювати зіставлення моделей, а також як вибирати цільову модель.

Два ключові показники перевірки

Шлюз перевіряє для кожного каналу два ключові факти (обидва мають три стани: true / false / не визначено):

Показник перевірки	Значення	true	false	Не визначено
Розпізнає назви моделей Claude (accepts_claude_names)	Чи канал нативно розпізнає назви моделей claude-opus-* / claude-sonnet-* / claude-haiku-*	Можна підключати напряму, зіставлення не потрібне	Не розпізнає, потрібно створити зіставлення, щоб перетворити назви claude-* на реальні назви моделей upstream	Перевірка не запускалася або завершилася невдало; висновок зробити не можна
Розрізняє рівні (tier_aware)	Чи upstream сам повертає різні моделі залежно від рівня opus / sonnet / haiku	Upstream уже розрізняє рівні, достатньо передати йому обробку	Не розрізняє (повертає ту саму модель для всіх рівнів), потрібне зіставлення на боці шлюзу	Визначити не вдалося або перевірка не проводилася

Чому потрібна перевірка, а не припущення

Поведінка різних постачальників дуже відрізняється. OpenAI нативно не розпізнає назви моделей claude-*; деякі проміжні постачальники розпізнають їх через переспрямування; а постачальники з пакетами для програмування (наприклад, підписки Claude Pro/Max) можуть розпізнавати лише конкретні назви моделей, прив’язані до підписки. Шлюз не вгадує за типом каналу, а спершу виконує перевірку й лише потім визначає стратегію маршрутизації.

Визначення маршрутизації: п’ять станів

Коли ви на сторінці AI Gateway → Керування підключенням → Клієнти виконуєте для Claude Code «захоплення в один клік», шлюз агрегує результати перевірки всіх каналів-кандидатів і формує визначення маршрутизації:

Стан каналів-кандидатів	Визначення	Значення
Немає доступних каналів-кандидатів (немає каналів / усі нездорові / у межах області віртуального ключа немає каналів)	Немає каналів-кандидатів	Потрібно спершу додати або виправити канал
Для будь-якого каналу-кандидата значення перевірки не визначено	Не перевірено	Потрібно спершу виконати перевірку; не можна створювати зіставлення без підтвердження
Усі канали-кандидати розпізнають назви моделей Claude	Пряме підключення	Зіставлення не створюється, запити передаються як є
Усі канали-кандидати не розпізнають назви моделей Claude	Потрібне зіставлення	Шлюз створює зіставлення для трьох рівнів, перетворюючи claude-* на реальні назви моделей upstream
Серед кандидатів є як ті, що розпізнають, так і ті, що не розпізнають	Змішаний	Потрібне ручне рішення (ті, що розпізнають, працюють напряму; ті, що не розпізнають, — через зіставлення)

Зіставлення моделей: перетворення claude-* на реальні моделі upstream

Коли визначено «Потрібне зіставлення», шлюз створює для Claude Code три правила зіставлення моделей, по одному для кожного рівня:

Назва моделі, яку надсилає Claude Code	Правило зіставлення (wildcard)	Зіставляється з
claude-opus-*	Відповідає всім запитам рівня opus	Флагманською моделлю серед каналів-кандидатів
claude-sonnet-*	Відповідає всім запитам рівня sonnet	Флагманською або стандартною моделлю серед каналів-кандидатів
claude-haiku-*	Відповідає всім запитам рівня haiku	Легкою моделлю серед каналів-кандидатів

Правила вибору цільової моделі (відкат за пріоритетом):

1. Сімейні пресети: якщо серед моделей-кандидатів є відоме ключове слово сімейства (наприклад, glm), беріть флагманську модель цього сімейства (наприклад, glm-5.2) як ціль для рівнів opus/sonnet, а легку модель цього сімейства (наприклад, glm-4.7-flash) — як ціль для рівня haiku.
2. Збіг за ключовими словами: якщо сімейного пресета немає, для opus/sonnet беріть першу модель зі списку кандидатів; для haiku беріть першу модель серед кандидатів, що відповідає легким ключовим словам (flash / mini / lite / air / small / turbo / haiku).
3. Резервний варіант: якщо збігу все ще немає, для всіх трьох рівнів беріть першу модель зі списку кандидатів.

Помилка на рівні haiku коштує найдорожче

Рівень haiku в Claude Code використовується найчастіше (кожен легкий виклик у діалозі використовує його). Якщо помилково підставити флагманську модель на рівень haiku, рахунок може зрости в кілька разів. Таблиця збігу ключових слів у шлюзі охоплює 7 легких суфіксів (flash / mini / lite / air / small / turbo / haiku), що гарантує, що важка модель не потрапить на рівень haiku.

Механізм запису зіставлень

Після підтвердження захоплення шлюз записує записи зіставлень через API /admin/model-mappings. Кожен запис зіставлення містить:

• Вихідний протокол (source_protocol): anthropic (запити, які надсилає Claude Code, мають формат Anthropic)
• Шаблон вихідної моделі (source_model_pattern): wildcard, наприклад claude-opus-*
• Цільовий протокол (target_protocol): openai (уніфіковано перетворюється на формат OpenAI перед надсиланням upstream)
• Цільова модель (target_model): конкретна назва моделі, вибрана під час перевірки

Запис є ідемпотентним — повторне захоплення не створює дубльованих зіставлень; перед записом шлюз отримує наявний список зіставлень для порівняння.

Правила маршрутизації під час виконання: failover і деградація

Окрім статичних зіставлень, записаних на етапі захоплення, шлюз також підтримує правила маршрутизації під час виконання (routing rules), які динамічно визначають рішення, коли запит проходить через шлюз:

Поле правила	Призначення
Умова спрацювання (condition_type)	Коли запускати деградацію, наприклад коли вичерпано ліміт каналу (quota_exhausted)
Поріг вартості (cost_threshold_usd)	Необов’язково: спрацьовує, коли сукупна вартість цього каналу перевищує поріг
Дія (action_type)	Що робити після спрацювання, наприклад перемкнутися на вказаний резервний канал (switch_to)
Цільовий канал (target_channel_id)	Резервний канал для деградації
Цільова модель (target_model)	Необов’язково: також змінити модель під час переходу на резервний канал

Комбінуючи кілька правил маршрутизації, ви можете реалізувати, наприклад: автоматичне перемикання з каналу A на оплату за фактичним використанням каналу B, коли вичерпано ліміт підписки каналу A; деградацію до дешевшої моделі, коли 24-годинна вартість каналу перевищує ліміт.

Балансування навантаження та пріоритет

Коли одну модель можуть обслуговувати кілька здорових каналів, шлюз вибирає за такою стратегією:

• Режим пріоритету (за замовчуванням): вибирається лише канал з найвищим пріоритетом; серед каналів з однаковим пріоритетом шлюз розподіляє за внутрішньою вагою.
• Режим round-robin (round_robin): запити по черзі розподіляються між усіма здоровими каналами-кандидатами.

Пріоритет задається в конфігурації каналу (більше число — вищий пріоритет), а allowed_channels віртуального ключа обмежує діапазон доступних каналів.

Перевірка з’єднання

У списку каналів можна виконати перевірку з’єднання для окремого каналу. Перевірка має два виміри:

• Доступність ендпоінта (reachable) — перевіряє, чи можна з’єднатися з Base URL (чи правильні мережа й адреса).
• Валідність ключа (authenticated) — фактично викликає API постачальника й перевіряє, чи дійсний API Key. Перевіряється лише за умови, що API Key заповнено.

Результат перевірки показує: затримку в обидва боки (мс), статусний значок та повідомлення про помилку.

TIP

У майстрі додавання, якщо ендпоінт недоступний, вас не пропустять до наступного кроку; якщо ендпоінт доступний, але ключ недійсний, буде лише попередження, і ви зможете продовжити (наприклад, якщо плануєте додати ключ пізніше).

Розширена конфігурація

Під час додавання або редагування каналу можна розгорнути розширену конфігурацію для обліку витрат і контролю лімітів:

• Множник ціни (Rate Multiplier) — множник до офіційної ціни постачальника, щоб розраховувати за вашою реальною собівартістю або ціною перепродажу; за замовчуванням 1.0.
• Структура білінгу — описує спосіб оплати цього каналу, наприклад оплата за фактичним використанням (pay as you go), підписка (subscription), пакет (package).
• Баланс — джерело балансу можна вибрати: фіксоване значення, рахунок OSS або ручне ведення; якщо вибрано рахунок OSS, можна також указати тип рахунку. Баланс і час оновлення відображаються в деталях каналу лише для читання.
• Дата закінчення підписки — для каналів типу підписки / пакета можна записати дату закінчення.
• Ліміти — можна встановити верхню межу за кількістю токенів, кількістю запитів або сумою, а також вибрати період (щодня / щотижня / щомісяця / власний). Після вичерпання ліміту канал автоматично виключається з маршрутизації — це запобіжний клапан від непередбачених перевитрат.

Редагування та видалення каналів

• Редагування — відкрийте потрібний канал у списку каналів, щоб змінити назву, Base URL, API Key, моделі та розширену конфігурацію.
• Видалення — після видалення каналу віртуальні ключі, які залежать від нього, більше не зможуть маршрутизувати запити до нього; дійте обережно.

Стан працездатності

Список каналів і сторінка огляду показують стан працездатності кожного каналу в реальному часі (норма / деградація / недоступний), що допомагає швидко виявити несправні конфігурації постачальників.

Часті запитання (FAQ)

• З: Під час додавання каналу з’являється запит на вхід?
  • В: AI-шлюз — це додаткова функція ServBay; перед додаванням каналів / ключів потрібно ввійти в обліковий запис ServBay. Просто увійдіть за підказками інтерфейсу.
• З: Повідомляє, що досягнуто ліміту кількості каналів?
  • В: Кількість каналів, які можна створити, залежить від тарифного плану облікового запису. Після дося