ВходЗапазете среща

Глава 2.14

Доставчици и модели на ИИ

Как маршрутизаторът на доставчици на изкуствен интелект (ИИ) избира модел от собствения пул от ключове на организацията и как скриптове и инструменти за ИИ се свързват с Nexus отвън.

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

16 минути за четене

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, машината за работни процеси. След това оркестраторът пита маршрутизатора от името на плъгина. Ето защо една изтекла тайна на плъгин може да действа като този плъгин, но не може да изразходва ничий бюджет за модели.

Вляво: три кутии една върху друга – „Асистент“, „Стъпка от работен процес“, „Умение“ – всяка със стрелка към кутия „UNO диспечер (nexus-orchestrator)“. Стрелка с етикет „желания: предпочитан доставчик, предпочитан модел, профил на възможностите“ отива надясно в голяма кутия „AI Provider Router (nexus-gateway)“. Вътре в кутията на маршрутизатора има три малки кутии в редица: „Роля“, „Пул на организацията“, „Политика за маршрутизиране“. От маршрутизатора три стрелки отиват надясно към „Локален модел (ai.localProvider.baseUrl)“, „Ключ А за хостван доставчик“, „Ключ Б за хостван доставчик“. Под маршрутизатора има отделна кутия „nexus-auth: пулът от ключове на организацията (криптиран)“ с пунктирана стрелка нагоре към маршрутизатора с етикет „ключове, извличани при всяко извикване“.
Как заявката достига до модел.

Пулът от ключове на организацията

Ключовете за модели принадлежат на организацията. Всяка организация използва собствен акаунт при доставчик и плаща собствената си сметка, а ключът се намира в пула на организацията, криптиран в 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/24

ai.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. Самият ключ никога повече не се показва, след като го добавите.

ИИ комутаторът
ИИ комутаторът
ИИ комутаторът изброява всеки доставчик с информация кой е задал ключа му и кои задачи изпълнява. Един ключ е в покой след неуспешни опити, друг е изключен, а страницата указва къде могат да отиват данните.
Модели за ИИ
Модели за ИИ
Базовият маршрутизатор в Community: организационен ключ, локален модел на собствената машина на организацията и кой модел коя задача изпълнява.

Чрез 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: създаване и изброяване, след това четене, промяна, отмяна или ротация на един ключ по неговия идентификатор.

Един ключ за скриптове
Един ключ за скриптове
Един ключ за скриптове. Страницата показва обхвата на ключа, кой го е създал, крайната му дата, извикванията по дни и по услуги и резултата от всяко извикване; тайната завършва на …7QK2 и никога не се показва отново.

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.

Извикванията на инструменти, които се нуждаят от модел, преминават през маршрутизатора като всичко останало, под организацията на лицето.