Версія 1.0.0-alpha.1найновіша
Розділ 2.14
Провайдери та моделі ШІ
Як маршрутизатор провайдерів штучного інтелекту (ШІ) — AI Provider Router — вибирає модель із власного пулу ключів організації, та як скрипти й інструменти ШІ звертаються до Nexus ззовні.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Harrow Port Authority використовує дві інсталяції. Та, що працює в ізольованій (air-gapped) операційній мережі (розділ 2.10, Встановлення в ізольованому середовищі), взагалі не має хмарних провайдерів. У підключеній корпоративній інсталяції, про яку йдеться в цьому розділі, на більшість запитань відповідає модель, запущена на двох вузлах із графічними процесорами (GPU) у власній серверній кімнаті порту. Ключ Google Gemini, який оплачує Harrow, бере на себе надлишкове навантаження, коли локальна модель зайнята, а Aoife Brennan обмежила трафік штучного інтелекту (ШІ) організації межами ЄС. Ніхто в Harrow не налаштовував модель всередині сервісу чи плагіна. Вони вказали одному компоненту, чим володіє Harrow, і цей компонент ухвалює рішення щодо кожного виклику.
Цей розділ присвячено цьому компоненту — AI Provider Router, який у Частині 1 та в консолі називається комутатором ШІ (AI switchboard), а також пулу ключів, який він використовує. Наприкінці описано способи, якими скрипти та інструменти ШІ звертаються до Nexus ззовні: ключі для скриптів, прикладний програмний інтерфейс (API) передачі репрезентативного стану (REST) та Model Context Protocol (MCP).
Маршрутизатор провайдерів ШІ (AI Provider Router)
Маршрутизатор працює всередині шлюзу nexus-gateway. Це єдиний сервіс, який зберігає облікові дані моделей організації, і саме він ухвалює остаточне рішення про те, який провайдер і яка модель відповідатимуть на кожен запит. Усі інші частини Nexus звертаються до нього. Крок робочого процесу вказує свої побажання, а маршрутизатор вирішує.
Звертатися можуть лише кілька сервісів, і кожен список чітко зафіксовано в чарті:
| Що запитується | Хто може запитувати |
|---|---|
Завершення (completion) (/internal/ai/chat та його потік) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Виклики інструментів та інші внутрішні маршрути ШІ | nexus-orchestrator, nexus-workflows |
| Векторні представлення (embeddings) та переранжування (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Кожен внутрішній маршрут по черзі перевіряє дві речі: внутрішній сервісний ключ ініціатора виклику та його ідентифікатор за наведеним вище списком. Запит без ключа відхиляється з кодом MISSING_SERVICE_KEY (401), із неправильним ключем — з INVALID_SERVICE_KEY (403), запит, у якому не вказано, хто звертається, — з MISSING_CALLER_IDENTITY (403), а ініціатор поза списком — з UNAUTHORIZED_CALLER (403). Жоден із цих запитів не повторюється, оскільки жодна з цих помилок не є тимчасовим збоєм.
Застосунки та плагіни ніколи не потрапляють до цього списку. Плагін декларує свої побажання в навичках (skills), які він реєструє, і передає їх через UNO — рушій робочих процесів. Потім оркестратор звертається до маршрутизатора від імені плагіна. Ось чому в разі витоку одного секрету плагіна зловмисник може діяти від імені цього плагіна, але не може витрачати чужий бюджет на моделі.
Пул ключів організації
Ключі моделей належать організації. Кожна організація підключає власний обліковий запис провайдера та самостійно оплачує рахунки, а ключ зберігається в пулі організації в зашифрованому вигляді в nexus-auth. За організацією немає спільного ключа платформи, тому жодна організація ніколи не витрачає бюджет іншої. Ціна цього правила очевидна: організація, яка не має ключа у своєму пулі, не отримує відповідей від ШІ. Асистент показує MODEL_NOT_CONNECTED (503) і повідомляє, хто може підключити ключ.
До пулу можна додати ключ для чотирьох провайдерів:
| Ідентифікатор провайдера | Відображається як |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Власний сервер моделей
Організація також може використовувати будь-який власний сервер, що підтримує OpenAI-сумісний API, як-от модель на вузлах GPU у Harrow. Інсталятор вказує його у файлі values:
# harrow-values.yaml (Helm values): the AI part
ai:
localProvider:
baseUrl: "https://models.harrow.example/v1"
installationHosts:
- models.harrow.example
- 10.40.20.0/24
networkPolicy:
externalEgressCIDRs:
- 10.40.20.0/24ai.localProvider.baseUrl спрямовує OpenAI-сумісний адаптер шлюзу на ваш сервер. В інсталяції слот scaleway пулу звертається до цього сервера, тому ключ, який ви додаєте для scaleway, — це ключ, якого очікує ваш власний сервер.
ai.installationHosts містить перелік імен хостів, що знаходяться всередині інсталяції, окрім власного сервісного домену релізу та трьох публічних хостів. Кожен запис — це ім'я хоста, .suffix, IP-адреса або діапазон безкласової міждоменної маршрутизації IPv4 (CIDR). Маршрутизатор використовує цей список, щоб відрізнити виклик, який залишається на локальному майданчику, від того, що виходить за його межі; саме про це повідомляє перевірка «Нічого не залишає цей майданчик» на сторінці «Підключити модель на власному обладнанні».
Мережева політика важить не менше, ніж маршрутизатор. Простір імен за замовчуванням забороняє весь вихідний трафік (egress), тому шлюз може звернутися до сервера моделей за межами простору імен лише тоді, коли його діапазон вказано в networkPolicy.externalEgressCIDRs. Те саме стосується і хмарного провайдера: якщо Harrow хоче, щоб відповідав ключ Gemini, діапазони адрес провайдера також мають бути внесені до цього списку, інакше виклик ніколи не вийде за межі кластера. У розділі 2.16, Безпека та мережа, цю політику описано повністю.
Додавання та вилучення ключів
Пул організації обслуговують її власники та адміністратори. Ніхто інший не може бачити ключі чи змінювати їх, а запит від інших осіб відхиляється з кодом AUTHORITY_EXCEEDED.
У консолі
У редакції Enterprise пул зберігається в комутаторі ШІ, під рушіями. У редакції Community ті самі ключі зберігаються в меню Налаштування, Моделі ШІ. Ця сторінка є базовим маршрутизатором, де ви додаєте ключі та адресу локальної моделі, а також обираєте, яка модель виконує ту чи іншу роботу. В обох випадках біля кожного ключа вказано, хто і коли його встановив («Встановлено Aoife, 3 вер.»), а також замасковану підказку щонайбільше з останніх чотирьох символів, наприклад ••••7f2q. Сам ключ після додавання більше ніколи не відображається.
Через BFF API
Серверна частина для клієнтського інтерфейсу (BFF) консолі обслуговує три маршрути для пулу. Викликайте їх із власним токеном доступу користувача: організація визначається з токена, а не із запиту.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET повертає список провайдерів у пулі, інформацію про те, чи може кожен із них відповідати, кожен ключ за його підказкою, а також провайдерів, для яких можна додати ключ. Для додавання ключа потрібне тіло запиту у форматі JSON із двома обов'язковими полями та одним необов'язковим:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Ключ передається лише один раз. Сервіс nexus-auth шифрує його та повідомляє маршрутизатор, а у відповіді повертається лише підказка. Відповідь має статус 201 і містить ідентифікатор нового ключа та його рядок: «Додано. Ключ Google Gemini ••••7f2q додано до пулу ШІ організації, і AI Provider Router тепер може спрямовувати до нього запити». Мітка може містити щонайбільше 100 символів, а ключ — це один рядок без пробілів довжиною щонайбільше 4096 символів. Будь-яке інше поле в тілі запиту або поле, що вказує організацію чи особу, викликає відмову.
Для відкликання подається порожнє тіло запиту. Маршрутизатор одразу припиняє спрямовувати запити до цього ключа, а nexus-auth зберігає його зі статусом «відкликано», щоб збереглася його історія. Нічого з пулу ніколи не видаляється.
| Відмова | HTTP | Коли виникає |
|---|---|---|
VALIDATION_FAILED |
400 | Тіло запиту не відповідає {provider, api_key, label?}, невідомий провайдер або особиста підписка користувача, запропонована як ключ організації |
AUTHORITY_EXCEEDED |
403 | Ініціатор виклику не є власником або адміністратором організації |
RECORD_NOT_FOUND |
404 | У пулі організації немає ключа з таким ідентифікатором |
TRANSITION_NOT_PERMITTED |
409 | Ключ уже відкликано |
TENANT_NOT_A_PARAMETER |
403 | У тілі або параметрах запиту вказано організацію |
Стани ключів
Кожен ключ у пулі перебуває в одному з шести станів. На повідомлення в чаті відповідає лише активний ключ (in use).
| Стан | Що це означає |
|---|---|
in_use |
Ключ відповідає на запити до закінчення терміну дії, якщо такий встановлено. |
resting |
Маршрутизатор тимчасово призупинив його роботу після збоїв до визначеного часу. Тим часом запити спрямовуються до наступного ключа. |
exhausted |
Вичерпано ліміт ключа на боці провайдера. |
invalid |
Провайдер більше не приймає цей ключ. |
expired |
Закінчився термін дії ключа. |
withdrawn |
Адміністратор відкликав його. Він залишається в списку для історії. |
Ключ, який дав збій, відпочиває протягом 60 секунд. Після 5 збоїв поспіль маршрутизатор вимикає його, передає його частку навантаження іншим ключам і записує сповіщення PROVIDER_KEY_SWITCHED_OFF. Жоден запит не отримає відмови, доки може відповісти інший ключ.
Коли у провайдера немає активного ключа, пул повідомляє причину («Немає активного ключа: 1 відкликано, 1 прострочено»). Коли у жодного провайдера в пулі немає активного ключа, чат відхиляється з кодом NO_PROVIDER_FOR_ROLE (422) та інструкцією з виправлення: власник або адміністратор має додати ключ організації. Це стан конфігурації, і повідомлення про нього залишається на екрані, доки хтось це не виправить.
Ролі, політики та побажання
Маршрутизатор оперує ролями. Кожен запит призначений для однієї з п'яти ролей: default, fast, reasoning, code або long_context. Кожна модель також належить до певного рівня (tier): frontier, standard або fast, і вищому рівню надається перевага, коли це дозволяє роль. Організація вирішує, який провайдер обслуговує кожну роль (призначення ролей) і в якому порядку переходити на резервні варіанти в разі збою провайдера (ієрархія політики маршрутизації). Адміністратори налаштовують обидва параметри в комутаторі ШІ. Сервіс nexus-auth також надає до них доступ за адресами /auth/org/<organisation-id>/settings/ai-provider/role-assignments та /auth/org/<organisation-id>/settings/ai-provider/routing-policy для ключа адміністратора з правами ai_provider:manage.
Ініціатори викликів можуть вказувати свої побажання. Рядок навички може містити бажаного провайдера та бажану модель, а також профіль можливостей. Маршрутизатор обробляє кожен із цих параметрів по-різному:
- Бажаний провайдер враховується лише тоді, коли в організації цього провайдера увімкнено і для нього є ключ. Інакше маршрутизатор використовує заміну.
- Бажана модель враховується, якщо вона є в каталозі цього провайдера і відповідає профілю.
- Профіль можливостей — це фільтр, який сам по собі нічого не обирає. Він може вимагати мінімального контекстного вікна, використання інструментів, комп'ютерного зору, векторних представлень, довгого контексту або певної локалізації даних. Усе, що не відповідає цим вимогам, відсіюється.
Маршрутизатор здійснює вибір у фіксованому порядку. Коли це можливо, він виконує побажання, потім пробує іншу модель того самого провайдера, далі — призначення для ролі та будь-якого іншого провайдера з ключем, чий каталог підходить. Якщо було задано профіль і жоден каталог йому не відповідає, запит відхиляється з кодом MODEL_CAPABILITY_UNAVAILABLE (422). Якщо нічого не призначено і немає жодних збігів, повертається NO_PROVIDER_FOR_ROLE (422). Моделі за замовчуванням «на крайній випадок» не існує. Неналаштована роль викликає явну помилку, а маршрутизатор прямо вказує, що саме потрібно налаштувати.
Локалізація даних (data residency) — це єдине обмеження, яке не можна обійти за допомогою заміни. Профіль із параметром eu_only обслуговується провайдером у ЄС або відхиляється. Harrow встановлює це блокування для всієї організації, і комутатор відображає другого хмарного провайдера, розташованого в регіоні США, як вимкненого.
Навичка також може жорстко закріпити одну конкретну модель, якщо для роботи навички потрібна саме вона. Навіть у цьому разі маршрутизатор використовує для неї власний ключ організації, а без нього відповіді не буде. Ініціатор виклику ніколи не зможе змусити Nexus використати провайдера, якого організація не налаштувала.
Коли провайдера обрано, аварійне перемикання (failover) — це окреме питання. Помилка 429, 5xx або збій мережі переміщує запит униз ієрархією до наступного провайдера. Помилки 400, 401, 403 або 404 негайно зупиняють процес, оскільки облікові дані та структура запитів не переносяться між провайдерами, і повторна спроба лише спалила б квоту з тим самим негативним результатом.
Щоб побачити, що саме обере маршрутизатор, перш ніж хтось поставить запитання, зверніться до GET /api/ai/routing-policy/effective на шлюзі з особистим токеном користувача. Він поверне модель для організації, в яку виконано вхід, або текстове пояснення відмови маршрутизатора, якщо доступної моделі немає, не надсилаючи при цьому жодного запиту до самої моделі.
Моніторинг маршрутизатора
Смужка показників унизу кожної сторінки показує поточну модель («Модель: локальна»). У редакції Enterprise сторінка «Комутатор ШІ, наживо» в реальному часі відображає трафік маршрутизатора: запити від асистента, фонових завдань і застосунків, що проходять через ролі до провайдерів і ключів; ключ на 60-секундній паузі позначається сірим кольором, вимкнений ключ — червоним, а також показується резервне перемикання на хмарного провайдера, коли локальна модель зайнята. Поруч із потоком будуються графіки навантаження на кожного провайдера, кількості запитів за секунду та часу очікування. Tomás тримає цю сторінку відкритою протягом першого тижня після будь-яких змін у політиці маршрутизації, адже неправильне призначення ролі стає помітним там уже за кілька хвилин — як трафік, що йде туди, куди ніхто не планував.
У редакції Community на сторінці «Моделі ШІ» є кнопка «Протестувати всі моделі», яка перевіряє кожну налаштовану модель і позначає, чи вона відповідає. Це найшвидший спосіб переконатися, що новий ключ працює, перш ніж хтось почне на нього покладатися.
Векторні представлення (ембединги)
Пошук і граф знань перетворюють текст на вектори. За замовчуванням інсталяція робить це за допомогою моделі векторних представлень (embedding model), яка працює всередині кластера на процесорі, тому жоден текст не залишає майданчик для векторизації, і організації не потрібен для цього ключ. Використання хмарного провайдера для векторних представлень — це вибір самої організації; у такому разі запити проходять через той самий пул і за тими самими правилами.
Лише три сервіси можуть запитувати у маршрутизатора векторні представлення або переранжування: nexus-graphrag, nexus-skills-engine та nexus-workflows. GraphRAG створює векторні представлення від імені організації, якій належить контент, з налаштуваннями цієї організації, і не зберігає жодних власних ключів провайдерів. Коли організація змінює свою модель векторних представлень, nexus-workflows запускає завдання повторної векторизації для сховищ цієї організації.
Особисті облікові дані залишаються особистими
Деякі облікові дані належать одній конкретній особі. Типовий приклад — підписка Claude Max, вхід у яку виконано через особистий обліковий запис користувача. Такі облікові дані ніколи не стають ключем організації: пул відхиляє їх із кодом VALIDATION_FAILED, вони ніколи не відображаються в таблиці ключів організації, і жоден інший користувач не побачить їх на своєму екрані.
Ключі моделей також ніколи не потрапляють в інші місця. Сторінка «Ключі зовнішніх даних», де зберігаються ключі для зовнішніх джерел даних, відхиляє все, що схоже на ключ моделі ШІ, з кодом AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Якщо засіб читання файлів виявляє ключі моделей усередині документа чи конфігурації, де їх не має бути, він записує подію CREDENTIALS_IN_WRONG_PLACE, після чого адміністратор видаляє їх і замінює на нові.
Скрипти, REST та MCP
Nexus має три публічні хости. У Harrow це console.harrow.example для консолі, api.harrow.example для шлюзу та auth.harrow.example для входу в систему. Скрипти та інструменти використовують другий і третій.
Ключі для скриптів
Скрипт входить у систему за допомогою ключа, створеного в меню Налаштування, Ключі для скриптів. Кожен ключ має назву, область дії (наприклад, «Лише запуск підрахунку дронами на майданчику»), ім'я особи, яка його створила, та дату закінчення терміну дії; організація може обмежити максимальний термін життя ключа. Секрет показується лише один раз під час створення ключа. Скопіюйте його до сховища секретів скрипту, оскільки Nexus зберігає лише останні чотири символи. Ключ відкликається, але ніколи не видаляється: він миттєво припиняє діяти і залишається в списку разом з історією всіх виконаних ним викликів. Ротація надає ключу новий секрет і показує його один раз.
Кожен ключ має власну сторінку зі статистикою викликів за днями, розподілом викликів за сервісами та журналом активності, де зафіксовано час, адресу, сервіс і результат. Виклик, що виходить за межі області дії ключа, відхиляється і відображається в журналі.
Сервіс nexus-auth надає авторизованому користувачеві доступ до тих самих ключів за адресою https://auth.harrow.example/api-keys: тут можна створити ключ і переглянути список, а також прочитати, змінити, відкликати або виконати ротацію окремого ключа за його ідентифікатором.
REST через шлюз
Надсилайте виклики REST на адресу https://api.harrow.example із заголовком Authorization: Bearer <token-or-key>. Кожен ключ повинен належати певній організації. Ключ без організації відхиляється з кодом TOKEN_ORG_MISSING (403) кожним сервісом, який перевіряє ключі через nexus-auth.
Ініціатор виклику, який звертається надто часто, отримує відповідь 429 із кодом RATE_LIMITED, заголовком Retry-After, а також лімітом і часовим вікном у тілі відповіді. Зачекайте вказану кількість секунд. У редакції Enterprise адміністратори встановлюють ліміти для кожного ключа, застосунку та підрозділу в меню Налаштування, Обмеження частоти запитів (див. розділ 2.16, Безпека та мережа).
MCP для інструментів ШІ
Інструменти ШІ, які підтримують Model Context Protocol, підключаються до https://api.harrow.example/mcp. Вони входять у систему через сервер OAuth 2.1 (OAuth — це відкритий стандарт для делегованої авторизації) за адресою https://auth.harrow.example, який підтримує самостійну реєстрацію клієнта самим інструментом, тому такий інструмент, як Claude Code або Cursor, реєструється сам і відкриває браузер користувача для входу. Після цього з'єднання діє від імені цієї конкретної особи, виключно в межах її прав. Авторизований користувач може завантажити готову конфігурацію для інструменту командного рядка з https://auth.harrow.example/api/v1/mcp/cli-config.
Виклики інструментів, які потребують моделі, проходять через маршрутизатор, як і все інше, в межах організації цього користувача.




