Versioon 1.0.0-alpha.1uusim
Peatükk 2.14
AI-pakkujad ja mudelid
Kuidas tehisintellekti (AI) Provider Router valib mudeli organisatsiooni enda võtmekogumist ning kuidas skriptid ja AI-tööriistad jõuavad Nexuseni väljastpoolt.
Selle lehe tõlkis AI ingliskeelsest originaalist. Kui miski jääb ebaselgeks, võtke aluseks ingliskeelne leht. Lugege seda lehte inglise keeles

Harrow Port Authority käitab kahte paigaldust. Nende eraldatud operatiivvõrgus oleval paigaldusel (peatükk 2.10, „Eraldatud võrgu paigaldus”) puudub majutatud teenusepakkuja täielikult. Ühendatud ettevõttepaigaldusel, mida käesolev peatükk jälgib, vastab enamikule küsimustele mudel, mis töötab sadama enda serveriruumis kahel graafikaprotsessori (GPU) sõlmel. Harrow' makstav Google Gemini võti võtab üle koormuse ülejäägi, kui kohalik mudel on hõivatud, ning Aoife Brennan on lukustanud organisatsiooni tehisintellekti (AI) liikluse EL-i piiresse. Mitte keegi Harrow's ei seadistanud mudelit teenuse ega pistikprogrammi sees. Nad ütlesid ühele komponendile, mis Harrow'le kuulub, ja see komponent otsustab iga päringu üle.
See peatükk käsitleb seda komponenti – AI teenusepakkujate ruuterit (AI Provider Router), mida 1. osas ja konsoolis nimetatakse AI kommutaatoriks – ning võtmete kogumit, mida see kasutab. Peatükk lõpeb viisidega, kuidas skriptid ja AI-tööriistad väljastpoolt Nexuseni jõuavad: skriptide võtmed, REST (esindusliku olekusiirde) rakendusliides (API) ja mudeli konteksti protokoll (Model Context Protocol, MCP).
AI Provider Router
Ruuter töötab lüüsi nexus-gateway sees. See on ainus teenus, mis hoiab organisatsiooni mudeli mandaate, ning see teeb lõpliku otsuse, milline teenusepakkuja ja milline mudel igale päringule vastab. Kõik teised Nexuse osad küsivad temalt. Töövoo etapp ütleb, mida ta sooviks, ja ruuter otsustab.
Küsida võivad vaid üksikud teenused ning iga nimekiri on määratud Helmi chart'iga:
| Mida küsitakse | Kes võib küsida |
|---|---|
Lõpetamine (/internal/ai/chat ja selle voog) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Tööriistakutsed ja muud sisemised AI marsruudid | nexus-orchestrator, nexus-workflows |
| Manused ja ümberjärjestamine | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Iga sisemine marsruut kontrollib kordamööda kahte asja: kutsuja sisemist teenusevõtit ja kutsuja identiteeti võrreldes ülaltoodud nimekirjaga. Ilma võtmeta päring lükatakse tagasi veaga MISSING_SERVICE_KEY (401), vale võtmega päring veaga INVALID_SERVICE_KEY (403), päring, mis ei ütle, kes kutsub, veaga MISSING_CALLER_IDENTITY (403), ning nimekirjaväline kutsuja veaga UNAUTHORIZED_CALLER (403). Ühtegi neist ei proovita uuesti, sest ükski neist pole mööduv tõrge.
Rakendused ja pistikprogrammid ei ole kunagi selles nimekirjas. Pistikprogramm deklareerib oma soovid oskustes, mille ta registreerib ja edastab töövoomootori UNO kaudu. Seejärel küsib orkestraator pistikprogrammi nimel ruuterilt. Seetõttu saab üks lekkinud pistikprogrammi saladus toimida küll selle pistikprogrammina, kuid ei saa kulutada kellegi mudeli eelarvet.
Organisatsiooni võtmekogum
Mudeli võtmed kuuluvad organisatsioonile. Iga organisatsioon toob kaasa oma teenusepakkuja konto ja maksab oma arve ise ning võti asub organisatsiooni kogumis, krüpteerituna teenuses nexus-auth. Organisatsiooni taga ei ole jagatud platvormivõtit, nii et ükski organisatsioon ei kuluta kunagi teise eelarvet. Selle reegli hind on selge: organisatsioon, mille kogumis pole ühtegi võtit, ei saa AI vastuseid. Assistent kuvab teate MODEL_NOT_CONNECTED (503) ja ütleb, kes saab võtme ühendada.
Kogumisse saab võtme lisada nelja teenusepakkuja jaoks:
| Teenusepakkuja ID | Kuvatakse kui |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Teie enda mudeliserver
Organisatsioon saab kasutada ka mis tahes enda käitatavat serverit, mis räägib OpenAI-ga ühilduvat API-t, nagu näiteks mudel Harrow' GPU-sõlmedel. Paigaldaja nimetab selle väärtuste failis:
# 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 suunab lüüsi OpenAI-ga ühilduva adapteri teie serverile. Paigalduses jõuab kogumi scaleway pesa sellesse serverisse, nii et võti, mille lisate scaleway jaoks, on võti, mida teie enda server ootab.
ai.installationHosts loetleb hostinimed, mis asuvad paigalduse sees, lisaks väljalaske enda teenusedomeenile ja kolmele avalikule hostile. Iga kirje on hostinimi, .suffix, IP-aadress või IPv4 klassideta domeenidevahelise marsruutimise (CIDR) vahemik. Ruuter kasutab seda nimekirja, et eristada kohapeale jäävat kutset kutsest, mis sealt väljub; seda kajastabki kontroll „Midagi ei lahku siit asukohast” lehel „Ühendage mudel oma riistvaral”.
Võrgupoliitika on sama oluline kui ruuter. Nimeruum keelab vaikimisi kogu väljuva liikluse, nii et lüüs pääseb nimeruumist väljaspool asuvale mudeliserverile ligi ainult siis, kui selle vahemik on nimekirjas networkPolicy.externalEgressCIDRs. Sama kehtib majutatud teenusepakkuja kohta: kui Harrow soovib, et nende Gemini võti vastaks, peavad ka teenusepakkuja aadressivahemikud seal loetletud olema, muidu ei välju kutse kunagi klastrist. Peatükk 2.16, „Turvalisus ja võrgundus”, käsitleb seda poliitikat täies mahus.
Võtmete lisamine ja tagasivõtmine
Organisatsiooni kogumit haldavad selle omanikud ja administraatorid. Keegi teine ei näe võtmeid ega saa neid muuta ning nende päring lükatakse tagasi veaga AUTHORITY_EXCEEDED.
Konsoolis
Enterprise-versioonis hoitakse kogumit AI kommutaatoris mootorite all. Community-versioonis hoitakse samu võtmeid lehel Seaded, AI mudelid. See leht on baasruuter, kuhu lisate võtmed ja kohaliku mudeli aadressi ning valite, milline mudel millist tööd teeb. Mõlemad näitavad iga võtme juures, kes ja millal selle määras („Määras Aoife, 3. sept”) ning maskeeritud vihjet selle viimasest kuni neljast tähemärgist, näiteks ••••7f2q. Võtit ennast pärast lisamist enam kunagi ei näidata.
Läbi BFF API
Konsooli kasutajaliidese tagarakendus (BFF) teenindab kogumi jaoks kolme marsruuti. Kutsuge neid välja isiku enda juurdepääsutõendiga: organisatsioon tuleb tõendist, mitte kunagi päringust.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET tagastab kogumis olevad teenusepakkujad, kas igaüks neist saab vastata, iga võtme selle vihje kaudu ja teenusepakkujad, millele saab võtme lisada. Võtme lisamine nõuab JSON-keha kahe kohustusliku ja ühe valikulise väljaga:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Võti liigub vaid korra. nexus-auth krüpteerib selle ja teavitab ruuterit ning vastus sisaldab ainult vihjet. Vastus on 201 koos uue võtme ID ja selle reaga: „Lisatud. Google Gemini võti ••••7f2q on organisatsiooni AI kogumis ja AI teenusepakkujate ruuter saab nüüd sellele suunata.” Silt on kuni 100 tähemärki pikk ja võti on üks ilma tühikuteta string pikkusega kuni 4096 tähemärki. Mis tahes muu väli kehas või väli, mis nimetab organisatsiooni või isikut, lükatakse tagasi.
Tagasivõtmine nõuab tühja keha. Ruuter lõpetab kohe võtmele suunamise ja nexus-auth säilitab selle tagasivõetuna märgitult, nii et selle ajalugu jääb alles. Kogumis ei kustutata kunagi midagi.
| Keeldumine | HTTP | Millal |
|---|---|---|
VALIDATION_FAILED |
400 | Keha, mis ei ole {provider, api_key, label?}, tundmatu teenusepakkuja või isiku enda tellimus, mida pakutakse organisatsiooni võtmena |
AUTHORITY_EXCEEDED |
403 | Kutsuja ei ole organisatsiooni omanik ega administraator |
RECORD_NOT_FOUND |
404 | Organisatsiooni kogumis ei ole selle ID-ga võtit |
TRANSITION_NOT_PERMITTED |
409 | Võti on juba tagasi võetud |
TENANT_NOT_A_PARAMETER |
403 | Keha või päring nimetas organisatsiooni |
Võtmete olekud
Iga kogumis olev võti on ühes kuuest olekust. Vestlusele vastab ainult kasutuses olev võti.
| Olek | Mida see tähendab |
|---|---|
in_use |
Võti vastab kuni oma aegumiskuupäevani, kui see on olemas. |
resting |
Ruuter pani selle pärast tõrkeid määratud ajani puhkama. Päringud lähevad seni järgmisele võtmele. |
exhausted |
See kasutas oma limiidi teenusepakkuja juures ära. |
invalid |
Teenusepakkuja ei aktsepteeri seda enam. |
expired |
See aegus oma aegumiskuupäeval. |
withdrawn |
Administraator võttis selle tagasi. See jääb ajaloona nimekirja. |
Tõrkuv võti puhkab 60 sekundit. Pärast 5 järjestikust tõrget lülitab ruuter selle välja, suunab selle osa teistele võtmetele ja salvestab teate PROVIDER_KEY_SWITCHED_OFF. Kedagi ei lükata tagasi, kuni mõni teine võti saab vastata.
Kui teenusepakkujal pole ühtegi võtit kasutuses, ütleb kogum põhjuse („Ühtegi võtit pole kasutuses: 1 tagasi võetud, 1 aegunud”). Kui ühelgi kogumi teenusepakkujal pole võtit kasutuses, lükatakse vestlus tagasi veaga NO_PROVIDER_FOR_ROLE (422) ja lahendusega: omanik või administraator lisab organisatsiooni võtme. See on seadistusolek ja see jääb ekraanile, kuni keegi selle parandab.
Rollid, reeglid ja eelistused
Ruuter mõtleb rollides. Iga päring on mõeldud ühele viiest: default, fast, reasoning, code või long_context. Iga mudel kuulub ka tasemele frontier, standard või fast, ning kõrgemat taset eelistatakse, kui roll seda võimaldab. Organisatsioon otsustab, milline teenusepakkuja iga rolli teenindab (rollimäärangud) ja millises järjekorras teenusepakkuja tõrke korral varuvariandile lülituda (marsruutimispoliitika redel). Administraatorid määravad mõlemad AI kommutaatoris. nexus-auth teenindab neid ka aadressidel /auth/org/<organisation-id>/settings/ai-provider/role-assignments ja /auth/org/<organisation-id>/settings/ai-provider/routing-policy administraatorivõtmele, millel on õigus ai_provider:manage.
Kutsujad saavad öelda, mida nad sooviksid. Oskuse rida võib sisaldada eelistatud teenusepakkujat ja eelistatud mudelit ning lisaks võimekuse profiili. Ruuter kohtleb igaüht erinevalt:
- Eelistatud teenusepakkujat arvestatakse ainult siis, kui organisatsioonil on see teenusepakkuja lubatud ja selle jaoks on olemas võti. Vastasel juhul kasutab ruuter asendust.
- Eelistatud mudelit arvestatakse siis, kui see on selle teenusepakkuja kataloogis ja sobib profiiliga.
- Võimekuse profiil on filter, mis ise ei vali midagi. See võib nõuda minimaalset kontekstiakent, tööriistakasutust, nägemisvõimekust, manuseid, pikka konteksti või andmete asukohta. Kõik, mis sellele ei vasta, on abikõlbmatu.
Ruuter valib kindlas järjekorras. Võimaluse korral arvestab ta sooviga, seejärel proovib sama teenusepakkuja teist mudelit, seejärel rollimäärangut ja mis tahes muud võtmega teenusepakkujat, mille kataloog sobib. Kui profiil oli antud ja ükski kataloog sellega ei sobi, lükatakse päring tagasi veaga MODEL_CAPABILITY_UNAVAILABLE (422). Kui midagi pole määratud ja miski ei sobi, on tulemuseks NO_PROVIDER_FOR_ROLE (422). Viimase abinõuna kasutatavat vaikemudelit ei ole. Roll, mida te pole seadistanud, ebaõnnestub häälekalt ning ruuter ütleb oma sõnadega, mida tuleb määrata.
Andmete asukoht on ainus piirang, millest ei saa asendamisega mööda minna. Profiili, millel on eu_only, teenindab EL-i teenusepakkuja või see lükatakse tagasi. Harrow määrab selle luku kogu organisatsioonile ja kommutaator kuvab teise majutatud teenusepakkuja, mis asub USA piirkonnas, väljalülitatuna.
Oskus saab ka kinnitada ühe kindla mudeli, kui oskus vajab töötamiseks just seda mudelit. Isegi siis kasutab ruuter selle jaoks organisatsiooni enda võtit ning ilma selleta ei vasta miski. Kutsuja ei saa kunagi panna Nexust kasutama teenusepakkujat, mida organisatsioon pole seadistanud.
Kui teenusepakkuja on valitud, on tõrkesiire eraldi küsimus. 429, 5xx või võrgutõrge viib päringu redelit mööda alla järgmise teenusepakkujani. 400, 401, 403 või 404 peatab protsessi kohe, sest mandaadid ja päringu kujud ei kandu teenusepakkujate vahel üle ning uuesti proovimine vaid raiskaks kvooti, jõudes sama tõrkeni.
Et näha, mida ruuter valiks enne, kui keegi küsimuse esitab, lugege lüüsis isiku enda tõendiga aadressi GET /api/ai/routing-policy/effective. See tagastab sisselogitud organisatsiooni mudeli või selle puudumisel ruuteri sõnalise keeldumise, ega saada mudelile ühtegi päringut.
Ruuteri jälgimine
Iga lehe allosas olev näitajate riba näitab kasutatavat mudelit („Mudel: kohalik”). Enterprise-versioonis joonistab vaade „AI kommutaator, reaalajas” ruuteri liikluse selle toimumise hetkel: assistendilt, töödelt ja rakendustelt tulevad päringud, mis voolavad läbi rollide teenusepakkujate ja võtmeteni, 60-sekundilisel puhkusel olev võti on joonistatud hallina, väljalülitatud võti punasena ning varulülitus majutatud teenusepakkujale, kui kohalik mudel on hõivatud. Voo kõrval kujutab see graafiliselt koormust teenusepakkuja kohta, päringuid sekundis ja ooteaega. Tomás hoiab seda avatuna esimesel nädalal pärast mis tahes muudatust marsruutimispoliitikas, sest vale rollimäärang ilmub seal minutitega nähtavale liiklusena, mis läheb kuhugi, kuhu keegi seda ei plaaninud.
Community-versioonis on AI mudelite lehel nupp „Testi kõiki mudeleid”, mis kontrollib iga seadistatud mudelit ja märgib, kas see vastab. See on kiireim viis tõestada, et uus võti töötab, enne kui keegi sellele toetub.
Vektoriseeringud (embeddings)
Otsing ja teadmusgraaf muudavad teksti vektoriteks. Vaikimisi teeb paigaldus seda manustamismudeliga, mis töötab klastri sees protsessoril, nii et ükski tekst ei lahku manustamiseks asukohast ja organisatsioon ei vaja selleks võtit. Majutatud teenusepakkuja kasutamine manuste jaoks on valik, mille organisatsioon teeb; seejärel läbib see sama kogumi ja samad reeglid.
Ainult kolm teenust võivad ruuterilt manuseid või ümberjärjestamist küsida: nexus-graphrag, nexus-skills-engine ja nexus-workflows. GraphRAG loob manuseid selle organisatsioonina, kelle sisu see on, kasutades selle organisatsiooni seadeid, ega oma ühtegi enda teenusepakkuja võtit. Kui organisatsioon muudab oma manustamismudelit, käivitab nexus-workflows selle organisatsiooni hoidlate jaoks uuesti manustamise töö.
Isiklikud mandaadid jäävad isiklikuks
Mõned mandaadid kuuluvad ühele isikule. Isiku enda konto kaudu sisse logitud Claude Max tellimus on tavaline näide. Selline mandaat ei ole kunagi organisatsiooni võti: kogum lükkab selle tagasi veaga VALIDATION_FAILED, seda ei loetleta kunagi organisatsiooni võtmete tabelis ja ühegi teise isiku ekraan seda ei näita.
Mudeli võtmed ei lähe ka kunagi kuhugi mujale. Leht „Väliste andmete võtmed”, mis hoiab võtmeid väliste andmeallikate jaoks, lükkab kõik, mis näeb välja nagu AI mudeli võti, tagasi veaga AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Kui faililugeja leiab dokumendist või konfiguratsioonist mudeli võtmed, kuhu need ei kuulu, salvestab see teate CREDENTIALS_IN_WRONG_PLACE ning administraator eemaldab ja asendab need.
Skriptid, REST ja MCP
Nexuses on kolm avalikku hosti. Harrow's on need console.harrow.example konsooli jaoks, api.harrow.example lüüsi jaoks ja auth.harrow.example sisselogimise jaoks. Skriptid ja tööriistad kasutavad teist ja kolmandat.
Skriptide võtmed
Skript logib sisse võtmega, mis on loodud lehel Seaded, Skriptide võtmed. Igal võtmel on nimi, ulatus (näiteks „Käivita ainult drooniplatsi loendus”), selle loonud isik ja lõppkuupäev; organisatsioon saab lukustada pikima eluea, mis võtmel võib olla. Saladust näidatakse üks kord võtme loomisel. Kopeerige see skripti saladuste hoidlasse, sest Nexus säilitab ainult selle viimased neli tähemärki. Võti võetakse tagasi, seda ei eemaldata kunagi: see peatub kohe ja jääb nimekirja koos iga tehtud kutsega. Roteerimine annab võtmele uue saladuse ja näitab seda üks kord.
Igal võtmel on oma leht, kus on kutsed päeva lõikes, kutsed teenuse lõikes ning tegevuslogi aja, aadressi, teenuse ja tulemusega. Võtme ulatusest väljapoole jääv kutse lükatakse tagasi ja kuvatakse logis.
nexus-auth teenindab samu võtmeid sisselogitud isikule aadressil https://auth.harrow.example/api-keys: looge ja loetlege, seejärel lugege, muutke, tühistage või roteerige ühte võtit selle ID järgi.
REST läbi lüüsi
Saatke REST-kutsed aadressile https://api.harrow.example päisega Authorization: Bearer <token-or-key>. Iga võti peab kuuluma organisatsioonile. Ilma organisatsioonita võtme lükkab iga teenus, mis kontrollib võtmeid läbi teenuse nexus-auth, tagasi veaga TOKEN_ORG_MISSING (403).
Liiga sageli küsivale kutsujale vastatakse koodiga 429 ja teatega RATE_LIMITED, päisega Retry-After ning limiidi ja ajaaknaga kehas. Oodake vastuses antud arv sekundeid. Enterprise-versioonis määravad administraatorid limiidid võtme, rakenduse ja üksuse kohta lehel Seaded, Kiiruspiirangud (vt peatükk 2.16, „Turvalisus ja võrgundus”).
MCP AI-tööriistadele
AI-tööriistad, mis räägivad mudeli konteksti protokolli (Model Context Protocol), ühenduvad aadressiga https://api.harrow.example/mcp. Nad logivad sisse läbi OAuth 2.1 serveri (OAuth on delegeeritud autoriseerimise avatud standard) aadressil https://auth.harrow.example, mis toetab kliendi registreerimist tööriista enda poolt, nii et tööriist nagu Claude Code või Cursor registreerib end ise ja avab sisselogimiseks isiku brauseri. Ühendus toimib seejärel selle ühe isiku nimel, selle isiku õigustega ja mitte millegi enamaga. Sisselogitud isik saab käsureatööriista jaoks valmis konfiguratsiooni hankida aadressilt https://auth.harrow.example/api/v1/mcp/cli-config.
Mudelit vajavad tööriistakutsed läbivad ruuteri nagu kõik muugi, isiku organisatsiooni alt.




