Versio 1.0.0-alpha.1uusin
Luku 2.14
Tekoälytarjoajat ja -mallit
Kuinka tekoälyn (AI) Provider Router valitsee mallin organisaation omasta avainvarannosta, ja kuinka komentosarjat ja tekoälytyökalut tavoittavat Nexuksen ulkopuolelta.
Tämä sivu on käännetty tekoälyllä englanninkielisestä alkuperäistekstistä. Jos jokin kohta on epäselvä, englanninkielinen sivu on ensisijainen lähde. Lue tämä sivu englanniksi

Harrow Port Authoritylla on kaksi asennusta. Ilmavälillä eristetyssä operatiivisessa verkossa olevassa asennuksessa (luku 2.10, Ilmavälillä eristetty asennus) ei ole lainkaan ulkoista palveluntarjoajaa. Verkkoon yhdistetyssä yritysasennuksessa, jota tässä luvussa seurataan, useimpiin kysymyksiin vastaa malli, joka pyörii kahdella grafiikkasuoritinsolmulla (GPU) sataman omassa palvelinhuoneessa. Harrow'n maksama Google Gemini -avain hoitaa ylivuodon, kun paikallinen malli on ruuhkautunut, ja Aoife Brennan on lukinnut organisaation tekoälyliikenteen (AI) EU-alueelle. Kukaan Harrow'lla ei määrittänyt mallia palvelun tai lisäosan sisälle. He kertoivat yhdelle komponentille, mitä Harrow omistaa, ja tuo komponentti päättää jokaisesta kutsusta.
Tämä luku käsittelee kyseistä komponenttia, tekoälypalveluntarjoajien reititintä (AI Provider Router), jota osassa 1 ja konsolissa kutsutaan tekoälyn kytkentäpöydäksi (AI switchboard), sekä sen hyödyntämää avainvarantoa. Luvun lopussa käsitellään tapoja, joilla komentosarjat ja tekoälytyökalut tavoittavat Nexuksen ulkopuolelta: komentosarjojen avaimia, REST-ohjelmointirajapintaa (representational state transfer, API) ja Model Context Protocolia (MCP).
Tekoälyn Provider Router
Reititin toimii yhdyskäytävän, nexus-gatewayn, sisällä. Se on ainoa palvelu, joka säilyttää organisaation mallitunnistetietoja, ja se tekee lopullisen päätöksen siitä, mikä palveluntarjoaja ja mikä malli vastaa kuhunkin pyyntöön. Kaikki muut Nexuksen osat pyytävät siltä. Työnkulun vaihe kertoo, mitä se haluaisi, ja reititin päättää.
Vain harvat palvelut saavat esittää pyyntöjä, ja kukin lista on kiinteästi määritetty kaaviossa:
| Mitä pyydetään | Kuka saa pyytää |
|---|---|
Täydennys (/internal/ai/chat ja sen virta) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Työkalukutsut ja muut sisäiset tekoälyreitit | nexus-orchestrator, nexus-workflows |
| Upotteet ja uudelleenjärjestäminen | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Jokainen sisäinen reitti tarkistaa vuorollaan kaksi asiaa: kutsujan sisäisen palveluavaimen sekä kutsujan identiteetin yllä olevaa listaa vasten. Avaimeton pyyntö hylätään koodilla MISSING_SERVICE_KEY (401), väärä avain koodilla INVALID_SERVICE_KEY (403), pyyntö, josta ei käy ilmi kutsuja, koodilla MISSING_CALLER_IDENTITY (403) ja listan ulkopuolinen kutsuja koodilla UNAUTHORIZED_CALLER (403). Mitään näistä ei yritetä uudelleen, koska mikään niistä ei ole ohimenevä häiriö.
Sovellukset ja lisäosat eivät koskaan esiinny tällä listalla. Lisäosa ilmoittaa toiveensa taidoissa, jotka se rekisteröi ja lähettää työnkulkumoottori UNOn kautta. Orkestroija esittää sitten pyynnön reitittimelle lisäosan puolesta. Tästä syystä yksi vuotanut lisäosan salaisuus voi toimia kyseisenä lisäosana, mutta se ei voi kuluttaa kenenkään mallibudjettia.
Organisaation avainvaranto
Malliavaimet kuuluvat organisaatiolle. Jokainen organisaatio tuo oman palveluntarjoajatilinsä ja maksaa oman laskunsa, ja avain sijaitsee organisaation varannossa salattuna nexus-auth-palvelussa. Organisaation takana ei ole jaettua alusta-avainta, joten mikään organisaatio ei koskaan kuluta toisen budjettia. Tämän säännön hinta on selvä: organisaatio, jonka varannossa ei ole avainta, ei saa tekoälyvastauksia. Avustaja näyttää virheen MODEL_NOT_CONNECTED (503) ja kertoo, kuka voi yhdistää avaimen.
Varantoon voidaan lisätä avain neljälle palveluntarjoajalle:
| Palveluntarjoajan tunnus | Näytetään nimellä |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Oma mallipalvelimesi
Organisaatio voi myös käyttää mitä tahansa ylläpitämäänsä palvelinta, joka tukee OpenAI-yhteensopivaa API-rajapintaa, kuten Harrow'n GPU-solmuilla pyörivää mallia. Asentaja nimeää sen arvotiedostossa:
# 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 ohjaa yhdyskäytävän OpenAI-yhteensopivan sovittimen palvelimellesi. Asennuksessa varannon scaleway-paikka tavoittaa kyseisen palvelimen, joten scaleway-kohtaan lisäämäsi avain on se avain, jota oma palvelimesi odottaa.
ai.installationHosts luettelee asennuksen sisäiset isäntänimet julkaisun oman palvelutoimialueen ja kolmen julkisen isännän lisäksi. Jokainen merkintä on isäntänimi, .suffix, IP-osoite tai IPv4 Classless Inter-Domain Routing (CIDR) -osoitealue. Reititin käyttää listaa erottaakseen toimipisteen sisällä pysyvän kutsun sieltä poistuvasta kutsusta, minkä ”Mitään ei poistu tästä toimipisteestä” -tarkistus Yhdistä malli omalla laitteistollasi -sivulla raportoi.
Verkkokäytäntö on yhtä tärkeä kuin reititin. Nimiavaruus estää oletusarvoisesti kaiken lähtevän liikenteen, joten yhdyskäytävä voi tavoittaa nimiavaruuden ulkopuolisen mallipalvelimen vain, kun sen osoitealue on kohdassa networkPolicy.externalEgressCIDRs. Sama pätee ulkoiseen palveluntarjoajaan: jos Harrow haluaa Gemini-avaimensa vastaavan, myös palveluntarjoajan osoitealueet on listattava siellä, tai kutsu ei koskaan poistu klusterista. Luku 2.16, Tietoturva ja verkko, käsittelee käytäntöä kokonaisuudessaan.
Avainten lisääminen ja poistaminen
Organisaation omistajat ja järjestelmänvalvojat ylläpitävät sen varantoa. Kukaan muu ei voi nähdä avaimia eikä muuttaa niitä, ja heidän tekemänsä pyynnöt hylätään koodilla AUTHORITY_EXCEEDED.
Konsolissa
Enterprise-versiossa varantoa ylläpidetään tekoälyn kytkentäpöydällä, moottoreiden alla. Community-versiossa samat avaimet ovat kohdassa Asetukset, Tekoälymallit. Kyseinen sivu toimii perusreitittimenä, johon voit lisätä avaimia ja paikallisen mallin osoitteen sekä valita, mikä malli tekee minkäkin työn. Molemmat näyttävät jokaisen avaimen kohdalla sen asettajan ja asetusajan (”Asettanut Aoife, 3. syysk.”) sekä peitetyn vihjeen sen enintään neljästä viimeisestä merkistä, kuten ••••7f2q. Itse avainta ei koskaan näytetä uudelleen sen lisäämisen jälkeen.
BFF API -rajapinnan kautta
Konsolin backend for frontend (BFF) tarjoaa kolme reittiä varannolle. Kutsu niitä henkilön omalla käyttöoikeustunnuksella: organisaatio saadaan tunnuksesta, ei koskaan pyynnöstä.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vastaa kertomalla varannossa olevat palveluntarjoajat, pystyykö kukin vastaamaan, jokaisen avaimen sen vihjeen perusteella sekä palveluntarjoajat, joille avain voidaan lisätä. Avaimen lisääminen vaatii JSON-rungon, jossa on kaksi pakollista ja yksi valinnainen kenttä:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Avain kulkee vain kerran. nexus-auth salaa sen ja ilmoittaa reitittimelle, ja vastaus sisältää vain vihjeen. Vastaus on 201 sekä uuden avaimen tunnus ja sen rivi: ”Lisätty. Google Gemini -avain ••••7f2q on organisaation tekoälyvarannossa, ja AI Provider Router voi nyt reitittää siihen.” Tunniste on enintään 100 merkkiä pitkä, ja avain on yksi välilyönnitön merkkijono, jossa on enintään 4 096 merkkiä. Mikä tahansa muu kenttä rungossa tai kenttä, joka nimeää organisaation tai henkilön, hylätään.
Peruuttaminen vaatii tyhjän rungon. Reititin lopettaa reitittämisen avaimeen välittömästi, ja nexus-auth säilyttää sen peruutetuksi merkittynä, jotta sen historia säilyy. Mitään varannossa olevaa ei koskaan poisteta.
| Hylkäys | HTTP | Tilanne |
|---|---|---|
VALIDATION_FAILED |
400 | Runko, joka ei ole {provider, api_key, label?}, tuntematon palveluntarjoaja tai henkilön oma tilaus tarjottuna organisaation avaimeksi |
AUTHORITY_EXCEEDED |
403 | Kutsuja ei ole organisaation omistaja tai järjestelmänvalvoja |
RECORD_NOT_FOUND |
404 | Organisaation varannossa ei ole avainta kyseisellä tunnuksella |
TRANSITION_NOT_PERMITTED |
409 | Avain on jo peruutettu |
TENANT_NOT_A_PARAMETER |
403 | Runko tai kysely nimesi organisaation |
Avainten tilat
Jokainen varannon avain on yhdessä kuudesta tilasta. Vain käytössä oleva avain vastaa keskusteluun.
| Tila | Mitä se tarkoittaa |
|---|---|
in_use |
Avain vastaa vanhenemispäiväänsä asti, jos sillä on sellainen. |
resting |
Reititin asetti sen lepotilaan virheiden jälkeen asetettuun aikaan asti. Pyynnöt ohjataan sillä välin seuraavaan avaimeen. |
exhausted |
Se on käyttänyt kiintiönsä loppuun palveluntarjoajalla. |
invalid |
Palveluntarjoaja ei enää hyväksy sitä. |
expired |
Se on vanhentunut vanhenemispäivänään. |
withdrawn |
Järjestelmänvalvoja on peruuttanut sen. Se säilyy listalla historiatietona. |
Epäonnistunut avain on lepotilassa 60 sekuntia. Kun virheitä on tullut 5 peräkkäin, reititin kytkee sen pois päältä, siirtää sen osuuden muille avaimille ja kirjaa ilmoituksen PROVIDER_KEY_SWITCHED_OFF. Ketään ei käännytetä pois niin kauan kuin jokin toinen avain pystyy vastaamaan.
Kun palveluntarjoajalla ei ole yhtään avainta käytössä, varanto kertoo syyn (”Ei avainta käytössä: 1 peruutettu, 1 vanhentunut”). Kun yhdelläkään varannon palveluntarjoajalla ei ole avainta käytössä, keskustelu hylätään koodilla NO_PROVIDER_FOR_ROLE (422) ja korjausohjeella: omistaja tai järjestelmänvalvoja lisää organisaation avaimen. Kyseessä on määritystila, ja se pysyy näytöllä, kunnes joku korjaa sen.
Roolit, käytännöt ja toiveet
Reititin ajattelee rooleissa. Jokainen pyyntö koskee yhtä viidestä roolista: default, fast, reasoning, code tai long_context. Jokainen malli kuuluu myös tasoon frontier, standard tai fast, ja korkeampaa tasoa suositaan, kun rooli sen sallii. Organisaatio päättää, mikä palveluntarjoaja palvelee mitäkin roolia (sen roolimääritykset) ja missä järjestyksessä varajärjestelmiin siirrytään, kun palveluntarjoaja epäonnistuu (sen reitityskäytännön tikapuut). Järjestelmänvalvojat asettavat molemmat tekoälyn kytkentäpöydällä. nexus-auth tarjoaa ne myös osoitteissa /auth/org/<organisation-id>/settings/ai-provider/role-assignments ja /auth/org/<organisation-id>/settings/ai-provider/routing-policy järjestelmänvalvojan avaimelle, jolla on ai_provider:manage.
Kutsujat voivat kertoa, mitä he haluaisivat. Taitorivi voi sisältää ensisijaisen palveluntarjoajan ja ensisijaisen mallin sekä kyvykkyysprofiilin. Reititin käsittelee kutakin eri tavalla:
- Ensisijaista palveluntarjoajaa noudatetaan vain, kun kyseinen palveluntarjoaja on otettu käyttöön organisaatiossa ja sille on avain. Muussa tapauksessa reititin korvaa sen toisella.
- Ensisijaista mallia noudatetaan, kun se on kyseisen palveluntarjoajan valikoimassa ja sopii profiiliin.
- Kyvykkyysprofiili on suodatin, joka ei koskaan tee valintaa. Se voi vaatia vähimmäiskonteksti-ikkunaa, työkalujen käyttöä, konenäköä, upotteita, pitkää kontekstia tai tietojen sijaintipaikkaa. Mikä tahansa, mikä ei täytä sen vaatimuksia, on kelpaamaton.
Reititin tekee valinnan kiinteässä järjestyksessä. Se toteuttaa toiveen silloin kun pystyy, kokeilee sitten saman palveluntarjoajan toista mallia ja sen jälkeen roolimääritystä sekä mitä tahansa muuta avaimellista palveluntarjoajaa, jonka valikoima sopii. Jos profiili on annettu eikä mikään valikoima sovi siihen, pyyntö hylätään koodilla MODEL_CAPABILITY_UNAVAILABLE (422). Jos mitään ei ole määritetty eikä mikään täsmää, koodi on NO_PROVIDER_FOR_ROLE (422). Viimeisen keinon oletusmallia ei ole. Rooli, jota et ole määrittänyt, epäonnistuu näkyvästi, ja reititin kertoo omin sanoin, mitä tulee asettaa.
Tietojen sijaintipaikka on ainoa rajoite, jota ei voi kiertää korvaamalla. Profiilia, jossa on eu_only, palvelee EU-palveluntarjoaja tai se hylätään. Harrow asettaa tämän lukituksen koko organisaatiolle, ja kytkentäpöytä piirtää toisen, Yhdysvaltain alueella sijaitsevan ulkoisen palveluntarjoajan poissa päältä olevaksi.
Taito voi myös kiinnittää yhden tarkan mallin, kun taito vaatii kyseisen mallin toimiakseen. Silloinkin reititin käyttää siihen organisaation omaa avainta, ja ilman sitä mikään ei vastaa. Kutsuja ei voi koskaan saada Nexusta käyttämään palveluntarjoajaa, jota organisaatio ei ole määrittänyt.
Kun palveluntarjoaja on valittu, vikasietoisuus on erillinen asia. 429-, 5xx- tai verkkovirhe siirtää pyynnön tikapuita pitkin alaspäin seuraavalle palveluntarjoajalle. 400, 401, 403 tai 404 pysäyttää käsittelyn välittömästi, koska tunnistetiedot ja pyyntöjen muodot eivät siirry palveluntarjoajien välillä ja uudelleenyritys vain kuluttaisi kiintiötä päätyen samaan virheeseen.
Jotta näet, minkä valinnan reititin tekisi ennen kuin kukaan esittää kysymystä, lue GET /api/ai/routing-policy/effective yhdyskäytävältä henkilön omalla tunnuksella. Se vastaa kertomalla sisäänkirjautuneen organisaation mallin tai reitittimen sanallisen hylkäyksen, jos mallia ei ole, eikä se lähetä pyyntöä mallille.
Reitittimen seuranta
Jokaisen sivun alareunassa oleva tietopalkki näyttää käytössä olevan mallin (”Malli: paikallinen”). Enterprise-versiossa Tekoälyn kytkentäpöytä, reaaliaikainen piirtää reitittimen liikenteen sen tapahtuessa: pyynnöt avustajalta, töistä ja sovelluksista virtaamassa roolien kautta palveluntarjoajille ja avaimille, 60 sekunnin lepotilassa olevan avaimen harmaana, pois päältä kytketyn avaimen punaisena sekä varasiirtymän ulkoiselle palveluntarjoajalle, kun paikallinen malli on ruuhkautunut. Virran vieressä se esittää kaavioina palveluntarjoajakohtaisen kuorman, pyynnöt sekunnissa ja odotusajan. Tomás pitää sen auki ensimmäisen viikon ajan jokaisen reitityskäytäntöön tehdyn muutoksen jälkeen, koska väärä roolimääritys näkyy siellä muutamassa minuutissa liikenteenä, joka kulkee jonnekin, minne kukaan ei tarkoittanut.
Community-versiossa Tekoälymallit-sivulla on Testaa jokainen malli -painike, joka tarkistaa jokaisen määritetyn mallin ja merkitsee, vastaako se. Se on nopein tapa todistaa uuden avaimen toimivuus ennen kuin kukaan nojautuu siihen.
Upotukset (embeddings)
Haku ja tietograafi muuttavat tekstin vektoreiksi. Oletusarvoisesti asennus tekee tämän upotemallilla, joka toimii klusterin sisällä suorittimella, joten tekstiä ei lähetetä toimipisteen ulkopuolelle upotettavaksi eikä organisaatio tarvitse siihen avainta. Ulkoisen palveluntarjoajan käyttäminen upotteisiin on organisaation oma valinta; tällöin se kulkee saman varannon ja samojen sääntöjen kautta.
Vain kolme palvelua saa pyytää reitittimeltä upotteita tai uudelleenjärjestämistä: nexus-graphrag, nexus-skills-engine ja nexus-workflows. GraphRAG tekee upotteet sen organisaation nimissä, jonka sisällöstä on kyse, kyseisen organisaation asetuksilla, eikä sillä ole omaa palveluntarjoajan avainta. Kun organisaatio vaihtaa upotemalliaan, nexus-workflows ajaa uudelleenupotustyön kyseisen organisaation tietovarastoille.
Henkilökohtaiset tunnistetiedot pysyvät henkilökohtaisina
Jotkin tunnistetiedot kuuluvat yhdelle henkilölle. Henkilön oman tilin kautta kirjautunut Claude Max -tilaus on yleinen tapaus. Tällainen tunnistetieto ei ole koskaan organisaation avain: varanto hylkää sen koodilla VALIDATION_FAILED, sitä ei koskaan luetella organisaation avaintaulussa, eikä se näy kenenkään toisen henkilön näytöllä.
Malliavaimet eivät myöskään koskaan päädy minnekään muualle. Ulkoisten tietojen avaimet -sivu, joka säilyttää ulkopuolisten tietolähteiden avaimia, hylkää kaiken tekoälymallin avaimelta näyttävän koodilla AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Jos tiedostonlukija löytää malliavaimia asiakirjan tai määrityksen sisältä, minne ne eivät kuulu, se kirjaa merkinnän CREDENTIALS_IN_WRONG_PLACE, ja järjestelmänvalvoja poistaa ja korvaa ne.
Komentosarjat, REST ja MCP
Nexuksella on kolme julkista isäntää. Harrow'lla ne ovat console.harrow.example konsolille, api.harrow.example yhdyskäytävälle ja auth.harrow.example sisäänkirjautumiselle. Komentosarjat ja työkalut käyttävät toista ja kolmatta.
Komentosarjojen avaimet
Komentosarja kirjautuu sisään avaimella, joka on luotu kohdassa Asetukset, Komentosarjojen avaimet. Jokaisella avaimella on nimi, ulottuvuus (esimerkiksi ”Käynnistä vain Drone yard count”), sen luonut henkilö ja päättymispäivä; organisaatio voi lukita avaimen enimmäisvoimassaoloajan. Salaisuus näytetään kerran avainta luotaessa. Kopioi se komentosarjan salaisuuksien säilöön, sillä Nexus säilyttää vain sen neljä viimeistä merkkiä. Avain peruutetaan, ei koskaan poisteta: se lakkaa toimimasta välittömästi ja jää listalle kaikkien tekemiensä kutsujen kanssa. Kiertäminen antaa avaimelle uuden salaisuuden ja näyttää sen kerran.
Jokaisella avaimella on oma sivunsa, jolla näkyvät päivittäiset kutsut, palvelukohtaiset kutsut sekä tapahtumaloki, joka sisältää ajan, osoitteen, palvelun ja tuloksen. Avaimen ulottuvuuden ulkopuolinen kutsu hylätään ja näkyy lokissa.
nexus-auth tarjoaa samat avaimet sisäänkirjautuneelle henkilölle osoitteessa https://auth.harrow.example/api-keys: luo ja listaa, sekä lue, muuta, peruuta tai kierrätä yksittäistä avainta sen tunnuksella.
REST yhdyskäytävän kautta
Lähetä REST-kutsut osoitteeseen https://api.harrow.example otsakkeella Authorization: Bearer <token-or-key>. Jokaisen avaimen on kuuluttava jollekin organisaatiolle. Avain, jolla ei ole organisaatiota, hylätään koodilla TOKEN_ORG_MISSING (403) jokaisessa palvelussa, joka tarkistaa avaimet nexus-auth-palvelun kautta.
Liian usein pyyntöjä esittävälle kutsujalle vastataan koodilla 429 ja virheellä RATE_LIMITED, Retry-After-otsakkeella sekä rungossa olevilla raja- ja aikaikkunatiedoilla. Odota vastauksen ilmoittama sekuntimäärä. Enterprise-versiossa järjestelmänvalvojat asettavat avain-, sovellus- ja yksikkökohtaiset rajat kohdassa Asetukset, Nopeusrajoitukset (katso luku 2.16, Tietoturva ja verkko).
MCP tekoälytyökaluille
Tekoälytyökalut, jotka tukevat Model Context Protocolia, yhdistävät osoitteeseen https://api.harrow.example/mcp. Ne kirjautuvat sisään OAuth 2.1 -palvelimen kautta (OAuth on valtuutuksen delegoinnin avoin standardi) osoitteessa https://auth.harrow.example, joka tukee työkalun itsensä tekemää asiakasrekisteröintiä, joten esimerkiksi Claude Code tai Cursor rekisteröi itsensä ja avaa henkilön selaimen sisäänkirjautumista varten. Yhteys toimii sen jälkeen kyseisen yhden henkilön puolesta, kyseisen henkilön oikeuksilla eikä millään muulla. Sisäänkirjautunut henkilö voi noutaa valmiin määrityksen komentorivityökalulle osoitteesta https://auth.harrow.example/api/v1/mcp/cli-config.
Mallia tarvitsevat työkalukutsut kulkevat reitittimen kautta kuten kaikki muukin, henkilön organisaation alaisuudessa.




