Versija 1.0.0-alpha.1jaunākā
2.14. nodaļa
MI nodrošinātāji un modeļi
Kā mākslīgā intelekta (MI) nodrošinātāju maršrutētājs izvēlas modeli no organizācijas atslēgu kopuma un kā skripti un MI rīki sasniedz Nexus no ārpuses.
Šo lapu no oriģināla angļu valodā ir tulkojis MI. Neskaidrību gadījumā par pamatu jāņem lapa angļu valodā. Lasīt šo lapu angļu valodā

Harrow Port Authority izmanto divas instalācijas. Tajā, kas darbojas izolētajā operāciju tīklā (2.10. nodaļa, Izolēta instalācija), vispār nav viesota pakalpojumu sniedzēja. Savienotajā korporatīvajā instalācijā, kurai seko šī nodaļa, uz lielāko daļu jautājumu atbild modelis, kas darbojas divos grafiskās apstrādes vienības (GPU) mezglos pašas ostas serveru telpā. Google Gemini atslēga, par kuru maksā Harrow, pārņem pārslodzi, kad lokālais modelis ir aizņemts, un Aoife Brennan ir bloķējusi organizācijas mākslīgā intelekta (MI) datplūsmu ES robežās. Neviens Harrow darbinieks nav konfigurējis modeli pakalpojumā vai spraudnī. Viņi vienam komponentam norādīja, kas pieder Harrow, un šis komponents pieņem lēmumu par katru izsaukumu.
Šajā nodaļā ir apskatīts šis komponents — MI pakalpojumu sniedzēju maršrutētājs (AI Provider Router), ko 1. daļā un konsolē dēvē par MI komutatoru, un atslēgu pūls, ko tas izmanto. Nodaļas noslēgumā ir aprakstīti veidi, kā skripti un MI rīki sasniedz Nexus no ārpuses: atslēgas skriptiem, REST (reprezentatīvā stāvokļa pārsūtīšanas) lietojumprogrammu saskarne (API) un Modeļa konteksta protokols (MCP).
MI nodrošinātāju maršrutētājs
Maršrutētājs darbojas vārtejā nexus-gateway. Tas ir vienīgais pakalpojums, kas glabā organizācijas modeļu akreditācijas datus, un tas pieņem galīgo lēmumu par to, kurš pakalpojumu sniedzējs un kurš modelis atbild uz katru pieprasījumu. Ikviena cita Nexus daļa jautā tam. Darbplūsmas solis norāda, ko tas vēlētos, un maršrutētājs izlemj.
Jautāt drīkst tikai daži pakalpojumi, un katru sarakstu nosaka Helm chart:
| Kas tiek pieprasīts | Kas drīkst pieprasīt |
|---|---|
Pabeigšana (/internal/ai/chat un tās straume) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Rīku izsaukumi un citi iekšējie MI maršruti | nexus-orchestrator, nexus-workflows |
| Iegulšana (embeddings) un pārkārtošana (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Katrs iekšējais maršruts pēc kārtas pārbauda divas lietas: izsaucēja iekšējo pakalpojuma atslēgu un izsaucēja identitāti salīdzinājumā ar iepriekš minēto sarakstu. Pieprasījums bez atslēgas tiek noraidīts ar MISSING_SERVICE_KEY (401), nepareiza atslēga — ar INVALID_SERVICE_KEY (403), pieprasījums, kurā nav norādīts izsaucējs — ar MISSING_CALLER_IDENTITY (403), un izsaucējs ārpus saraksta — ar UNAUTHORIZED_CALLER (403). Neviens no šiem pieprasījumiem netiek atkārtots, jo neviens no tiem nav pārejoša kļūme.
Lietotnes un spraudņi nekad neparādās šajā sarakstā. Spraudnis deklarē savas vēlmes prasmēs, ko tas reģistrē un nosūta caur UNO, darbplūsmas dzini. Pēc tam orķestrētājs jautā maršrutētājam spraudņa vārdā. Tāpēc viens noplūdis spraudņa noslēpums var darboties kā šis spraudnis, bet nevar iztērēt neviena modeļa budžetu.
Organizācijas atslēgu kopums
Modeļu atslēgas pieder organizācijai. Katra organizācija izmanto savu pakalpojumu sniedzēja kontu un maksā savu rēķinu, un atslēga glabājas organizācijas pūlā, šifrēta pakalpojumā nexus-auth. Aiz organizācijas nav koplietotas platformas atslēgas, tāpēc neviena organizācija nekad netērē citas budžetu. Šī noteikuma cena ir skaidra: organizācija, kuras pūlā nav atslēgas, nesaņem nekādas MI atbildes. Asistents parāda MODEL_NOT_CONNECTED (503) un norāda, kurš to var pievienot.
Pūlam var pievienot atslēgu četriem pakalpojumu sniedzējiem:
| Pakalpojumu sniedzēja ID | Parādīts kā |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Jūsu pašu modeļa serveris
Organizācija var izmantot arī jebkuru savu serveri, kas atbalsta ar OpenAI saderīgu API, piemēram, modeli Harrow GPU mezglos. Instalētājs to norāda vērtību failā:
# 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 novirza vārtejas ar OpenAI saderīgo adapteri uz jūsu serveri. Instalācijā pūla scaleway slots sasniedz šo serveri, tāpēc atslēga, ko pievienojat vienumam scaleway, ir atslēga, ko sagaida jūsu pašu serveris.
ai.installationHosts uzskaita resursdatoru nosaukumus, kas atrodas instalācijas iekšienē, neskaitot paša laidiena pakalpojuma domēnu un trīs publiskos resursdatorus. Katrs ieraksts ir resursdatora nosaukums, .suffix, IP adrese vai IPv4 bezklasu starpdomēnu maršrutēšanas (CIDR) diapazons. Maršrutētājs izmanto šo sarakstu, lai atšķirtu izsaukumu, kas paliek uz vietas, no tāda, kas to atstāj, un par to ziņo pārbaude "Nothing leaves this site" (Nekas neatstāj šo vietni) lapā Connect a model on your own hardware (Modeļa pievienošana savā aparatūrā).
Tīkla politika ir tikpat svarīga kā maršrutētājs. Nosaukumvieta pēc noklusējuma liedz visu izejošo datplūsmu, tāpēc vārteja var sasniegt modeļa serveri ārpus nosaukumvietas tikai tad, ja tā diapazons ir norādīts networkPolicy.externalEgressCIDRs. Tas pats attiecas uz viesotu pakalpojumu sniedzēju: ja Harrow vēlas, lai tā Gemini atslēga atbildētu, tur jābūt uzskaitītiem arī pakalpojumu sniedzēja adrešu diapazoniem, pretējā gadījumā izsaukums nekad neatstāj klasteri. 2.16. nodaļā, Drošība un tīklošana, šī politika ir apskatīta pilnībā.
Atslēgu pievienošana un atsaukšana
Organizācijas īpašnieki un administratori uztur tās pūlu. Neviens cits nevar redzēt atslēgas un nevar tās mainīt, un viņu pieprasījums tiek noraidīts ar AUTHORITY_EXCEEDED.
Konsolē
Enterprise versijā pūls tiek glabāts MI komutatorā, zem dziņiem. Community versijā tās pašas atslēgas tiek glabātas sadaļā Iestatījumi, MI modeļi. Šī lapa ir pamata maršrutētājs, kurā jūs pievienojat atslēgas un lokālā modeļa adresi, kā arī izvēlaties, kurš modelis veic kuru darbu. Abās vietās katrai atslēgai ir redzams, kurš un kad to iestatījis ("Set by Aoife, 3 Sept"), un maskēta norāde ar ne vairāk kā pēdējām četrām rakstzīmēm, piemēram, ••••7f2q. Pati atslēga pēc pievienošanas vairs nekad netiek rādīta.
Izmantojot BFF API
Konsoles priekšgala aizmugursistēma (BFF) apkalpo trīs pūla maršrutus. Izsauciet tos ar personas pašas piekļuves pilnvaru (token): organizācija tiek iegūta no pilnvaras, nekad no pieprasījuma.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET atbild ar pūlā esošajiem pakalpojumu sniedzējiem, to, vai katrs var atbildēt, katru atslēgu pēc tās norādes un pakalpojumu sniedzējiem, kuriem var pievienot atslēgu. Lai pievienotu atslēgu, ir nepieciešams JSON pamatteksts ar diviem obligātiem laukiem un vienu neobligātu lauku:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Atslēga ceļo vienu reizi. nexus-auth to šifrē un informē maršrutētāju, un atbilde satur tikai norādi. Atbilde ir 201 ar jaunās atslēgas ID un tās rindu: "Added. The Google Gemini key ••••7f2q is in the organisation's AI pool, and the AI Provider Router can route to it now." Etiķete ir ne vairāk kā 100 rakstzīmes gara, un atslēga ir viena virkne bez atstarpēm, kas nav garāka par 4,096 rakstzīmēm. Jebkurš cits lauks pamattekstā vai lauks, kurā nosaukta organizācija vai persona, tiek noraidīts.
Atsaukšanai ir nepieciešams tukšs pamatteksts. Maršrutētājs nekavējoties pārtrauc maršrutēšanu uz šo atslēgu, un nexus-auth to saglabā, norādot kā atsauktu, lai saglabātos tās vēsture. Nekas pūlā nekad netiek dzēsts.
| Noraidījums | HTTP | Kad |
|---|---|---|
VALIDATION_FAILED |
400 | Pamatteksts, kas nav {provider, api_key, label?}, nezināms pakalpojumu sniedzējs vai personas pašas abonements, kas piedāvāts kā organizācijas atslēga |
AUTHORITY_EXCEEDED |
403 | Izsaucējs nav organizācijas īpašnieks vai administrators |
RECORD_NOT_FOUND |
404 | Organizācijas pūlā nav atslēgas ar šādu ID |
TRANSITION_NOT_PERMITTED |
409 | Atslēga jau ir atsaukta |
TENANT_NOT_A_PARAMETER |
403 | Pamattekstā vai vaicājumā ir nosaukta organizācija |
Atslēgu stāvokļi
Katra pūla atslēga ir vienā no sešiem stāvokļiem. Tērzēšanā atbild tikai lietojama atslēga.
| Stāvoklis | Ko tas nozīmē |
|---|---|
in_use |
Atslēga atbild līdz tās derīguma termiņa beigām, ja tāds ir. |
resting |
Maršrutētājs to pēc kļūmēm ir atpūtinājis līdz noteiktam laikam. Tikmēr pieprasījumi tiek novirzīti uz nākamo atslēgu. |
exhausted |
Tā ir izsmēlusi savu limitu pie pakalpojumu sniedzēja. |
invalid |
Pakalpojumu sniedzējs to vairs nepieņem. |
expired |
Tai ir beidzies derīguma termiņš. |
withdrawn |
Administrators to ir atsaucis. Tā paliek sarakstā kā vēsture. |
Atslēga, kurai rodas kļūme, atpūšas 60 sekundes. Pēc 5 kļūmēm pēc kārtas maršrutētājs to izslēdz, pārvieto tās daļu uz citām atslēgām un reģistrē paziņojumu PROVIDER_KEY_SWITCHED_OFF. Neviens netiek noraidīts, kamēr var atbildēt cita atslēga.
Ja pakalpojumu sniedzējam nav lietojamas atslēgas, pūls norāda iemeslu ("No key in use: 1 withdrawn, 1 lapsed"). Ja nevienam pakalpojumu sniedzējam pūlā nav lietojamas atslēgas, tērzēšana tiek noraidīta ar NO_PROVIDER_FOR_ROLE (422) un risinājumu: īpašnieks vai administrators pievieno organizācijas atslēgu. Tas ir konfigurācijas stāvoklis, un tas paliek ekrānā, līdz kāds to novērš.
Lomas, politika un vēlmes
Maršrutētājs domā lomās. Katrs pieprasījums ir paredzēts vienai no piecām: default, fast, reasoning, code vai long_context. Katrs modelis ir arī kādā līmenī — frontier, standard vai fast, un augstākam līmenim tiek dota priekšroka, ja loma to atļauj. Organizācija izlemj, kurš pakalpojumu sniedzējs apkalpo katru lomu (tās lomu piešķiršana), un secību, kādā pāriet uz rezerves variantu, kad pakalpojumu sniedzējam rodas kļūme (tās maršrutēšanas politikas kāpnes). Administratori abus iestata MI komutatorā. nexus-auth tos apkalpo arī adresēs /auth/org/<organisation-id>/settings/ai-provider/role-assignments un /auth/org/<organisation-id>/settings/ai-provider/routing-policy administratora atslēgai, kurai ir ai_provider:manage.
Izsaucēji var norādīt, ko viņi vēlētos. Prasmes rindā var būt norādīts vēlamais pakalpojumu sniedzējs un vēlamais modelis, kā arī spēju profils. Maršrutētājs katru no tiem apstrādā atšķirīgi:
- Vēlamais pakalpojumu sniedzējs tiek ievērots tikai tad, ja organizācijai šis pakalpojumu sniedzējs ir iespējots un tai ir tā atslēga. Pretējā gadījumā maršrutētājs to aizstāj.
- Vēlamais modelis tiek ievērots, ja tas ir attiecīgā pakalpojumu sniedzēja katalogā un atbilst profilam.
- Spēju profils ir filtrs, kas nekad neizvēlas. Tas var pieprasīt minimālo konteksta logu, rīku izmantošanu, redzi, iegulšanu, garu kontekstu vai datu rezidenci. Nekas, kas tam neatbilst, nav piemērots.
Maršrutētājs izvēlas noteiktā secībā. Tas ievēro vēlmi, kad var, pēc tam izmēģina citu tā paša pakalpojumu sniedzēja modeli, tad lomas piešķiršanu un jebkuru citu pakalpojumu sniedzēju ar atslēgu, kura katalogs atbilst. Ja tika norādīts profils un neviens katalogs tam neatbilst, pieprasījums tiek noraidīts ar MODEL_CAPABILITY_UNAVAILABLE (422). Ja nekas nav piešķirts un nekas neatbilst, tas ir NO_PROVIDER_FOR_ROLE (422). Nav pēdējā līdzekļa noklusējuma modeļa. Loma, kuru neesat konfigurējis, pamanāmiavarē, ar paša maršrutētāja vārdiem norādot, kas jāiestata.
Datu rezidence ir vienīgais ierobežojums, kuru nevar apiet ar aizstāšanu. Profilu ar eu_only apkalpo ES pakalpojumu sniedzējs, vai arī tas tiek noraidīts. Harrow iestata šo bloķēšanu visai organizācijai, un komutators otro viesoto pakalpojumu sniedzēju, kas atrodas ASV reģionā, attēlo kā izslēgtu.
Prasme var arī piespraust vienu konkrētu modeli, ja prasmes darbībai ir nepieciešams tieši šis modelis. Pat tad maršrutētājs tam izmanto pašas organizācijas atslēgu, un bez tās nekas neatbild. Izsaucējs nekad nevar likt Nexus izmantot pakalpojumu sniedzēju, kuru organizācija nav konfigurējusi.
Kad pakalpojumu sniedzējs ir izvēlēts, kļūmjpārlēce ir atsevišķs jautājums. Kļūda 429, 5xx vai tīkla kļūme pārvieto pieprasījumu pa kāpnēm uz leju pie nākamā pakalpojumu sniedzēja. Kļūda 400, 401, 403 vai 404 apstājas nekavējoties, jo akreditācijas dati un pieprasījumu formas netiek pārnestas starp pakalpojumu sniedzējiem, un atkārtots mēģinājums tikai tērētu kvotu, lai nonāktu pie tās pašas kļūmes.
Lai redzētu, ko maršrutētājs izvēlētos, pirms kāds uzdod jautājumu, nolasiet GET /api/ai/routing-policy/effective vārtejā ar personas pašas pilnvaru. Tas atbild ar modeli pierakstītajai organizācijai vai maršrutētāja noraidījumu vārdos, ja tāda nav, un tas nesūta nekādu pieprasījumu modelim.
Maršrutētāja pārraudzība
Rādītāju josla katras lapas apakšā parāda izmantoto modeli ("Model: local"). Enterprise versijā lapa MI komutators, tiešraidē (The AI switchboard, live) zīmē maršrutētāja datplūsmu tās norises brīdī: pieprasījumus no asistenta, darbiem un lietotnēm, kas plūst caur lomām uz pakalpojumu sniedzējiem un atslēgām, atslēgu tās 60 sekunžu atpūtā iezīmējot pelēkā krāsā, izslēgtu atslēgu — sarkanā krāsā, un pāreju uz viesoto pakalpojumu sniedzēju, kad lokālais modelis ir aizņemts. Blakus plūsmai tā attēlo slodzi katram pakalpojumu sniedzējam, pieprasījumus sekundē un gaidīšanas laiku. Tomás to tur atvērtu pirmajā nedēļā pēc jebkurām izmaiņām maršrutēšanas politikā, jo nepareiza lomas piešķiršana tur parādās dažu minūšu laikā kā datplūsma, kas dodas turp, kur neviens to nebija paredzējis.
Community versijā lapā MI modeļi ir poga Test every model (Pārbaudīt katru modeli), kas pārbauda katru konfigurēto modeli un atzīmē, vai tas atbild. Tas ir ātrākais veids, kā pierādīt, ka jauna atslēga darbojas, pirms kāds uz to paļaujas.
Iegulumi
Meklēšana un zināšanu grafs pārvērš tekstu vektoros. Pēc noklusējuma instalācija to dara ar iegulšanas modeli, kas darbojas klastera iekšienē uz procesora, tāpēc neviens teksts neatstāj vietni, lai tiktu iegults, un organizācijai tam nav nepieciešama atslēga. Viesota pakalpojumu sniedzēja izmantošana iegulšanai ir izvēle, ko izdara organizācija; pēc tam tas notiek caur to pašu pūlu un pēc tiem pašiem noteikumiem.
Tikai trīs pakalpojumi drīkst prasīt maršrutētājam iegulšanu vai pārkārtošanu: nexus-graphrag, nexus-skills-engine un nexus-workflows. GraphRAG veic iegulšanu kā organizācija, kurai pieder saturs, ar šīs organizācijas iestatījumiem, un tam nav savas pakalpojumu sniedzēja atslēgas. Kad organizācija maina savu iegulšanas modeli, nexus-workflows izpilda atkārtotas iegulšanas darbu šīs organizācijas krātuvēm.
Individuālie akreditācijas dati paliek personīgi
Daži akreditācijas dati pieder vienai personai. Biežākais gadījums ir Claude Max abonements, kurā pierakstās caur šīs personas pašas kontu. Šādi akreditācijas dati nekad nav organizācijas atslēga: pūls tos noraida ar VALIDATION_FAILED, tie nekad netiek uzskaitīti organizācijas atslēgu tabulā, un nevienas citas personas ekrānā tie netiek rādīti.
Modeļu atslēgas arī nekad nenonāk nekur citur. Lapa Ārējo datu atslēgas (External data keys), kurā glabājas atslēgas ārējiem datu avotiem, noraida visu, kas izskatās pēc MI modeļa atslēgas, ar AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Ja failu lasītājs atrod modeļu atslēgas dokumentā vai konfigurācijā, kur tām nevajadzētu būt, tas reģistrē CREDENTIALS_IN_WRONG_PLACE, un administrators tās noņem un nomaina.
Skripti, REST un MCP
Nexus ir trīs publiskie resursdatori. Harrow tie ir console.harrow.example konsolei, api.harrow.example vārtejai un auth.harrow.example pierakstīšanās procesam. Skripti un rīki izmanto otro un trešo.
Atslēgas skriptiem
Skripts pierakstās ar atslēgu, kas izveidota sadaļā Iestatījumi, Atslēgas skriptiem (Settings, Keys for scripts). Katrai atslēgai ir nosaukums, tvērums (piemēram, "Start Drone yard count only"), persona, kas to izveidoja, un beigu datums; organizācija var noteikt garāko atslēgas darbības laiku. Noslēpums tiek parādīts vienu reizi, kad atslēga tiek izveidota. Iekopējiet to skripta noslēpumu krātuvē, jo Nexus saglabā tikai tā pēdējās četras rakstzīmes. Atslēga tiek atsaukta, nekad netiek noņemta: tā apstājas nekavējoties un paliek sarakstā ar katru izsaukumu, ko tā veikusi. Rotācija piešķir atslēgai jaunu noslēpumu un parāda to vienu reizi.
Katrai atslēgai ir sava lapa ar izsaukumiem dienā, izsaukumiem pēc pakalpojuma un darbību žurnālu ar laiku, adresi, pakalpojumu un rezultātu. Izsaukums ārpus atslēgas tvēruma tiek noraidīts un parādās žurnālā.
nexus-auth apkalpo tās pašas atslēgas pierakstītai personai adresē https://auth.harrow.example/api-keys: izveidot un uzskaitīt, pēc tam nolasīt, mainīt, atsaukt vai rotēt vienu atslēgu pēc tās ID.
REST caur vārteju
Sūtiet REST izsaukumus uz https://api.harrow.example ar Authorization: Bearer <token-or-key>. Katrai atslēgai ir jāpieder organizācijai. Atslēgu, kurai tās nav, ar TOKEN_ORG_MISSING (403) noraida katrs pakalpojums, kas pārbauda atslēgas caur nexus-auth.
Izsaucējam, kurš jautā pārāk bieži, tiek atbildēts 429 ar RATE_LIMITED, Retry-After galveni, kā arī limitu un logu pamattekstā. Uzgaidiet tajā norādīto sekunžu skaitu. Enterprise versijā administratori iestata limitus katrai atslēgai, katrai lietotnei un katrai vienībai sadaļā Iestatījumi, Intensitātes limiti (Settings, Rate limits) (skatiet 2.16. nodaļu, Drošība un tīklošana).
MCP MI rīkiem
MI rīki, kas atbalsta Modeļa konteksta protokolu, pieslēdzas pie https://api.harrow.example/mcp. Tie pierakstās caur OAuth 2.1 serveri (OAuth ir atvērtais standarts deleģētai autorizācijai) adresē https://auth.harrow.example, kas atbalsta klienta reģistrāciju, ko veic pats rīks, tāpēc tāds rīks kā Claude Code vai Cursor pats sevi reģistrē un atver personas pārlūkprogrammu, lai pierakstītos. Pēc tam savienojums darbojas šīs vienas personas vārdā, ar šīs personas tiesībām un neko vairāk. Pierakstījusies persona var iegūt gatavu konfigurāciju komandrindas rīkam no https://auth.harrow.example/api/v1/mcp/cli-config.
Rīku izsaukumi, kuriem nepieciešams modelis, iet caur maršrutētāju tāpat kā viss pārējais, zem personas organizācijas.




