Версия 1.0.0-alpha.1последно
Глава 2.14
Доставчици и модели на ИИ
Как маршрутизаторът на доставчици на изкуствен интелект (ИИ) избира модел от собствения пул от ключове на организацията и как скриптове и инструменти за ИИ се свързват с 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 (representational state transfer) и Model Context Protocol (MCP).
Маршрутизаторът на доставчици на ИИ
Маршрутизаторът работи вътре в шлюза, nexus-gateway. Това е единствената услуга, която съхранява идентификационните данни за модели на дадена организация, и тя взема окончателното решение кой доставчик и кой модел да отговорят на всяка заявка. Всяка друга част на Nexus се обръща към нея. Стъпка от работен процес казва какво би желала, а маршрутизаторът решава.
Само няколко услуги могат да отправят запитвания, като всеки списък е фиксиран от чарта:
| Какво се иска | Кой може да пита |
|---|---|
Довършване на текст (/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). Нито една от тези заявки не се опитва повторно, тъй като нито една от грешките не е временна неизправност.
Приложенията и плъгините никога не фигурират в този списък. Плъгинът декларира своите желания в уменията, които регистрира и изпраща чрез UNO, машината за работни процеси. След това оркестраторът пита маршрутизатора от името на плъгина. Ето защо една изтекла тайна на плъгин може да действа като този плъгин, но не може да изразходва ничий бюджет за модели.
Пулът от ключове на организацията
Ключовете за модели принадлежат на организацията. Всяка организация използва собствен акаунт при доставчик и плаща собствената си сметка, а ключът се намира в пула на организацията, криптиран в nexus-auth. Зад организацията няма споделен платформен ключ, така че никоя организация никога не изразходва бюджета на друга. Цената на това правило е ясна: организация без ключ в своя пул не получава отговори от ИИ. Асистентът показва MODEL_NOT_CONNECTED (503) и казва кой може да свърже ключ.
В пула може да се добави ключ за четирима доставчици:
| Идентификатор на доставчик | Показва се като |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Собствен сървър за модели
Една организация може да използва и всеки поддържан от нея сървър, който работи с OpenAI-съвместим API, като например модела на GPU възлите на Harrow. Инсталаторът го указва във файла със стойности (values file):
# 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 Classless Inter-Domain Routing (CIDR). Маршрутизаторът използва списъка, за да различи извикване, което остава на място (on-site), от такова, което го напуска – именно това отчита проверката „Нищо не напуска този обект“ на страницата „Свързване на модел на собствен хардуер“.
Мрежовата политика е също толкова важна, колкото и маршрутизаторът. Пространството от имена (namespace) отказва целия изходящ трафик по подразбиране, така че шлюзът може да достигне до сървър за модели извън пространството от имена само когато неговият диапазон е в networkPolicy.externalEgressCIDRs. Същото важи и за хостван доставчик: ако Harrow иска нейният ключ за Gemini да отговаря, адресните диапазони на доставчика също трябва да бъдат изброени там, иначе извикването никога не напуска клъстера. Глава 2.16, Сигурност и мрежи, разглежда политиката изцяло.
Добавяне и оттегляне на ключове
Собствениците и администраторите на организацията поддържат нейния пул. Никой друг не може да вижда ключовете и да ги променя, а заявка от друго лице се отхвърля с AUTHORITY_EXCEEDED.
В конзолата
В Enterprise пулът се поддържа в ИИ комутатора, под машините (engines). В 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 знака, а ключът е един низ без интервали с дължина най-много 4,096 знака. Всяко друго поле в тялото или поле, назоваващо организация или лице, се отхвърля.
Оттеглянето приема празно тяло. Маршрутизаторът веднага спира да маршрутизира към ключа, а 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 |
Ключът отговаря до датата на изтичане на валидността му, ако има такава. |
resting |
Маршрутизаторът го е поставил в покой след неуспешни опити до определен час. Междувременно заявките отиват към следващия ключ. |
exhausted |
Изчерпал е лимита си при доставчика. |
invalid |
Доставчикът вече не го приема. |
expired |
Изтекъл е на датата си на валидност. |
withdrawn |
Администратор го е оттеглил. Остава в списъка като хронология. |
Ключ, който даде грешка, остава в покой за 60 секунди. След 5 поредни неуспешни опита маршрутизаторът го изключва, прехвърля дела му към другите ключове и записва известието PROVIDER_KEY_SWITCHED_OFF. Никой не получава отказ, докато друг ключ може да отговори.
Когато даден доставчик няма ключ в употреба, пулът указва защо („Няма ключ в употреба: 1 оттеглен, 1 с изтекъл срок“). Когато никой доставчик в пула няма ключ в употреба, чатът се отхвърля с NO_PROVIDER_FOR_ROLE (422) и решението: собственик или администратор да добави организационен ключ. Това е конфигурационно състояние и остава на екрана, докато някой не го отстрани.
Роли, правила и предпочитания
Маршрутизаторът работи с роли. Всяка заявка е за една от пет роли: default, fast, reasoning, code или long_context. Всеки модел също така принадлежи към дадено ниво – 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). Няма модел по подразбиране като крайна мярка. Роля, която не сте конфигурирали, се проваля явно, като самият маршрутизатор указва с текст какво трябва да се зададе.
Местоположението на данните е единственото ограничение, което не може да бъде заобиколено чрез заместване. Профил с eu_only се обслужва от доставчик в ЕС или се отхвърля. Harrow задава това заключване за цялата организация и комутаторът изобразява втория хостван доставчик, който се намира в регион в САЩ, като изключен.
Дадено умение може също да фиксира един точен модел, когато умението се нуждае от този модел, за да работи. Дори и тогава маршрутизаторът използва собствения ключ на организацията за него, а без такъв нищо не отговаря. Извикващият никога не може да накара Nexus да използва доставчик, който организацията не е конфигурирала.
След като бъде избран доставчик, резервното превключване при срив (failover) е отделен въпрос. Грешка 429, 5xx или мрежов срив преместват заявката надолу по скалата към следващия доставчик. Грешка 400, 401, 403 или 404 спира процеса веднага, тъй като идентификационните данни и структурите на заявките не са преносими между доставчиците и повторен опит би изразходвал квота, за да стигне до същия неуспех.
За да видите какво би избрал маршрутизаторът, преди някой да зададе въпрос, прочетете GET /api/ai/routing-policy/effective на шлюза със собствения токен на потребител. Той връща модела за вписаната организация или отказа на маршрутизатора с думи, когато няма такъв, и не изпраща заявка към модел.
Наблюдение на маршрутизатора
Лентата с показатели в долната част на всяка страница показва използвания модел („Модел: локален“). В Enterprise страницата „ИИ комутаторът, на живо“ изчертава трафика на маршрутизатора в реално време: заявки от асистента, задачи и приложения, преминаващи през ролите към доставчиците и ключовете, ключ в неговия 60-секунден покой, изобразен в сиво, изключен ключ, изобразен в червено, и резервно превключване към хоствания доставчик, когато локалният модел е зает. До потока тя чертае графика на натоварването по доставчици, заявките в секунда и времето за изчакване. Tomás я държи отворена през първата седмица след всяка промяна в политиката за маршрутизиране, защото грешно назначение на роля се появява там в рамките на минути като трафик, отиващ там, където никой не е възнамерявал.
В Community страницата „Модели за ИИ“ има бутон „Тествай всеки модел“, който проверява всеки конфигуриран модел и отбелязва дали отговаря. Това е най-бързият начин да се докаже, че нов ключ работи, преди някой да разчита на него.
Векторни представяния (Embeddings)
Търсенето и графът на знанията превръщат текста във вектори. По подразбиране инсталацията прави това с модел за векторни представяния (embedding модел), който работи вътре в клъстера на процесора, така че никакъв текст не напуска обекта, за да бъде векторизиран, и организацията не се нуждае от ключ за това. Използването на хостван доставчик за векторни представяния е избор, който организацията прави; тогава процесът преминава през същия пул и същите правила.
Само три услуги могат да искат от маршрутизатора векторни представяния или пренареждане: 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.
Извикванията на инструменти, които се нуждаят от модел, преминават през маршрутизатора като всичко останало, под организацията на лицето.




