InnskráningBóka kynningu

Kafli 2.14

Gervigreindarveitur og líkön

Hvernig veitubeinir gervigreindar (AI) velur líkan úr eigin lyklasafni stofnunarinnar og hvernig skriftur og gervigreindarverkfæri ná til Nexus utan frá.

Þessi síða var þýdd með gervigreind úr enska frumtextanum. Ef eitthvað er óljóst gildir enska síðan til viðmiðunar. Lesa þessa síðu á ensku

16 mínútna lestur

Harrow Port Authority rekur tvær uppsetningar. Sú sem er á einangraða (air-gapped) rekstrarnetinu (kafli 2.10, Einangruð uppsetning) er alls ekki með neina hýsta þjónustuaðila. Á tengdu fyrirtækjauppsetningunni, sem þessi kafli fylgir, er flestum spurningum svarað af líkani sem keyrir á tveimur skjástýringarhnútum (GPU) í eigin netþjónaherbergi hafnarinnar. Google Gemini lykill, sem Harrow greiðir fyrir, tekur við umframálagi þegar staðbundna líkanið er upptekið og Aoife Brennan hefur læst gervigreindarumferð (AI) stofnunarinnar við ESB. Enginn hjá Harrow stillti líkan inni í þjónustu eða viðbót. Þau sögðu einni einingu hvað Harrow á, og sú eining tekur ákvörðun um hvert kall.

Þessi kafli fjallar um þá einingu, AI Provider Router, sem 1. hluti og stjórnborðið kalla gervigreindarskiptiborðið, og lyklasafnið sem hún sækir í. Hann endar á þeim leiðum sem skriftur og gervigreindarverkfæri nota til að ná í Nexus utan frá: lyklar fyrir skriftur, REST (representational state transfer) forritaskil (API) og Model Context Protocol (MCP).

AI Provider Router

Beinirinn keyrir inni í gáttinni, nexus-gateway. Það er eina þjónustan sem geymir auðkenni líkana fyrir stofnun og hún tekur lokaákvörðun um hvaða þjónustuaðili og hvaða líkan svarar hverri beiðni. Allir aðrir hlutar Nexus spyrja hann. Skref í verkferli segir hvað það vill og beinirinn ákveður.

Aðeins fáar þjónustur mega spyrja og hver listi er fastsettur í Helm-pakkanum (chart):

Um hvað er beðið Hver má spyrja
Útfylling (/internal/ai/chat og straumur hennar) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Verkfæraköll og aðrar innri gervigreindarleiðir nexus-orchestrator, nexus-workflows
Vigranir (embeddings) og endurröðun nexus-graphrag, nexus-skills-engine, nexus-workflows

Hver innri leið athugar tvennt, hvort á eftir öðru: innri þjónustulykil kallarans og auðkenni kallarans samanborið við listann hér að ofan. Beiðni án lykilsins er hafnað með MISSING_SERVICE_KEY (401), röngum lykli með INVALID_SERVICE_KEY (403), beiðni sem segir ekki hver kallar með MISSING_CALLER_IDENTITY (403) og kallara utan listans með UNAUTHORIZED_CALLER (403). Ekkert af þessu er reynt aftur, því ekkert af þessu er tímabundin bilun.

Forrit og viðbætur birtast aldrei á þeim lista. Viðbót lýsir óskum sínum varðandi þá færni sem hún skráir og sendir í gegnum UNO, verkferlavélina. Samhæfingareiningin (orchestrator) spyr síðan beininn fyrir hönd viðbótarinnar. Þess vegna getur eitt lekið leyndarmál viðbótar komið fram sem sú viðbót en getur ekki eytt líkanaheimildum neins.

Vinstri: þrír kassar í stafla, „Aðstoðarmaður“, „Skref í verkferli“, „Færni“, hver með ör inn í kassa „UNO sending (nexus-orchestrator)“. Ör merkt „óskir: æskilegur þjónustuaðili, æskilegt líkan, getusnið“ fer til hægri inn í stóran kassa „AI Provider Router (nexus-gateway)“. Inni í beiniskassanum eru þrír litlir kassar í röð: „Hlutverk“, „Safn stofnunar“, „Beiningarstefna“. Frá beininum fara þrjár örvar til hægri í „Staðbundið líkan (ai.localProvider.baseUrl)“, „Lykill hýsts þjónustuaðila A“, „Lykill hýsts þjónustuaðila B“. Undir beininum er aðskilinn kassi „nexus-auth: lyklasafn stofnunarinnar (dulkóðað)“ með brotinni ör upp í beininn merktri „lyklar, leystir fyrir hvert kall“.
Hvernig beiðni nær til líkans.

Lyklasafn stofnunarinnar

Líkanalyklar tilheyra stofnuninni. Hver stofnun kemur með sinn eigin aðgang hjá þjónustuaðila og greiðir sinn eigin reikning, og lykillinn lifir í safni stofnunarinnar, dulkóðaður í nexus-auth. Það er enginn sameiginlegur kerfislykill á bak við stofnun, þannig að engin stofnun eyðir nokkru sinni fjárheimildum annarrar. Kostnaðurinn við þá reglu er einfaldur: stofnun sem er ekki með neinn lykil í safni sínu fær engin gervigreindarsvör. Aðstoðarmaðurinn sýnir MODEL_NOT_CONNECTED (503) og segir hver getur tengt lykil.

Hægt er að bæta lykli í safnið fyrir fjóra þjónustuaðila:

Auðkenni þjónustuaðila Birt sem
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

Þinn eigin líkananetþjónn

Stofnun getur einnig notað hvaða netþjón sem er sem hún rekur og talar OpenAI-samhæfð forritaskil (API), svo sem líkanið á GPU-hnútum Harrow. Uppsetningarforritið nefnir hann í gildisskránni (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 beinir OpenAI-samhæfða millistykki gáttarinnar að netþjóninum þínum. Í uppsetningu nær scaleway hólf safnsins til þess netþjóns, þannig að lykillinn sem þú bætir við fyrir scaleway er lykillinn sem þinn eigin netþjónn býst við.

ai.installationHosts telur upp vélarheiti sem eru innan uppsetningarinnar, auk eigin þjónustuléns útgáfunnar og opinberu vélanna þriggja. Hver færsla er vélarheiti, .suffix, IP-tala eða IPv4 Classless Inter-Domain Routing (CIDR) bil. Beinirinn notar listann til að þekkja í sundur kall sem helst á staðnum frá kalli sem fer út fyrir hann, sem er það sem athugunin „Ekkert fer út fyrir þennan stað“ á síðunni Tengdu líkan á þínum eigin vélbúnaði gefur skýrslu um.

Netstefnan skiptir jafn miklu máli og beinirinn. Nafnarýmið hafnar allri útumferð (egress) sjálfgefið, þannig að gáttin nær aðeins til líkananetþjóns utan nafnarýmisins þegar bil hans er í networkPolicy.externalEgressCIDRs. Hið sama gildir um hýstan þjónustuaðila: ef Harrow vill að Gemini-lykillinn sinn svari verða vistfangabil þjónustuaðilans einnig að vera skráð þar, annars fer kallið aldrei út fyrir klasann. Kafli 2.16, Öryggi og netkerfi, fjallar ítarlega um stefnuna.

Tengdu líkan á þínum eigin vélbúnaði
Tengdu líkan á þínum eigin vélbúnaði
Líkan tengt á þínum eigin vélbúnaði. Síðan telur upp þau líkön sem netþjónninn tilkynnir um, hlutverkið sem hvert þeirra gegnir og staðfestir að ekkert fari út fyrir staðinn.

Lyklum bætt við og þeir afturkallaðir

Eigendur og kerfisstjórar stofnunar halda utan um safn hennar. Aðrir geta hvorki séð lyklana né breytt þeim, og beiðni frá þeim er hafnað með AUTHORITY_EXCEEDED.

Í stjórnborðinu

Í Enterprise er safnið geymt í gervigreindarskiptiborðinu, undir vélunum. Í Community eru sömu lyklar geymdir undir Stillingar, Gervigreindarlíkön. Sú síða er grunnbeinirinn, þar sem þú bætir við lyklum og vistfangi staðbundins líkans og velur hvaða líkan vinnur hvaða verk. Báðar sýna hvern lykil eftir því hver setti hann inn og hvenær („Sett af Aoife, 3. sept.“) og með falinni vísbendingu um síðustu fjóra stafi hans í mesta lagi, svo sem ••••7f2q. Lykillinn sjálfur er aldrei sýndur aftur eftir að þú bætir honum við.

Skiptiborð gervigreindar
Skiptiborð gervigreindar
Gervigreindarskiptiborðið telur upp hvern þjónustuaðila ásamt því hver setti lykilinn hans og hvaða verk hann vinnur. Einn lykill hvílir sig eftir bilanir, slökkt hefur verið á öðrum og síðan segir hvert gögn mega fara.
Gervigreindarlíkön
Gervigreindarlíkön
Grunnbeinirinn í Community: stofnanalýkill, staðbundið líkan á eigin vél stofnunarinnar og hvaða líkan vinnur hvaða verk.

Í gegnum BFF API

Bakendi fyrir framenda (BFF) stjórnborðsins þjónustar þrjár leiðir fyrir safnið. Kallaðu á þær með eigin aðgangstákni (access token) einstaklings: stofnunin kemur úr tákninu, aldrei úr beiðninni.

GET  /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw

GET svarar með þjónustuaðilunum í safninu, hvort hver þeirra geti svarað, hverjum lykli með vísbendingu sinni og þeim þjónustuaðilum sem hægt er að bæta við lykli fyrir. Að bæta við lykli tekur JSON-meginmál með tveimur nauðsynlegum reitum og einum valfrjálsum:

{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }

Lykillinn ferðast einu sinni. nexus-auth dulkóðar hann og lætur beininn vita, og svarið ber aðeins vísbendinguna. Svarið er 201 með auðkenni nýja lykilsins og línu hans: „Bætt við. Google Gemini lykillinn ••••7f2q er í gervigreindarsafni stofnunarinnar og AI Provider Router getur beint til hans núna.“ Merki er í mesta lagi 100 stafir og lykill er einn strengur án bila sem er í mesta lagi 4.096 stafir. Öllum öðrum reitum í meginmálinu, eða reit sem nefnir stofnun eða einstakling, er hafnað.

Afturköllun tekur tómt meginmál. Beinirinn hættir strax að beina til lykilsins og nexus-auth geymir hann, skráðan sem afturkallaðan, svo ferill hans haldist. Engu í safninu er nokkru sinni eytt.

Höfnun HTTP Hvenær
VALIDATION_FAILED 400 Meginmál sem er ekki {provider, api_key, label?}, óþekktur þjónustuaðili eða eigin áskrift einstaklings boðin fram sem stofnanalýkill
AUTHORITY_EXCEEDED 403 Kallarinn er hvorki eigandi né kerfisstjóri stofnunarinnar
RECORD_NOT_FOUND 404 Enginn lykill með þessu auðkenni er í safni stofnunarinnar
TRANSITION_NOT_PERMITTED 409 Lykillinn er þegar afturkallaður
TENANT_NOT_A_PARAMETER 403 Meginmálið eða fyrirspurnin nefndi stofnun

Stöður lykla

Hver lykill í safninu er í einni af sex stöðum. Aðeins lykill í notkun svarar spjalli.

Staða Hvað það þýðir
in_use Lykillinn svarar, fram að gildistíma sínum ef hann hefur slíkan.
resting Beinirinn hvíldi hann eftir bilanir, fram að ákveðnum tíma. Beiðnir fara á næsta lykil á meðan.
exhausted Hann kláraði heimild sína hjá þjónustuaðilanum.
invalid Þjónustuaðilinn samþykkir hann ekki lengur.
expired Hann rann út á gildistíma sínum.
withdrawn Kerfisstjóri afturkallaði hann. Hann helst skráður sem ferill.

Lykill sem bilar hvílist í 60 sekúndur. Eftir 5 bilanir í röð slekkur beinirinn á honum, færir hlutdeild hans yfir á hina lyklana og skráir tilkynninguna PROVIDER_KEY_SWITCHED_OFF. Engum er hafnað á meðan annar lykill getur svarað.

Þegar þjónustuaðili er ekki með neinn lykil í notkun segir safnið hvers vegna („Enginn lykill í notkun: 1 afturkallaður, 1 útrunninn“). Þegar enginn þjónustuaðili í safninu er með lykil í notkun er spjalli hafnað með NO_PROVIDER_FOR_ROLE (422) og úrræðinu: eigandi eða kerfisstjóri bætir við stofnanalýkli. Það er stillingarstaða og hún helst á skjánum þar til einhver lagar hana.

Hlutverk, stefnur og óskir

Beinirinn hugsar í hlutverkum. Hver beiðni er fyrir eitt af fimm: default, fast, reasoning, code eða long_context. Hvert líkan er einnig í þrepi, frontier, standard eða fast, og hærra þrep er tekið fram yfir þegar hlutverkið leyfir það. Stofnunin ákveður hvaða þjónustuaðili þjónustar hvert hlutverk (hlutverkaskipan hennar) og í hvaða röð á að grípa til varaleiða þegar þjónustuaðili bilar (beiningarstefnustigi hennar). Kerfisstjórar stilla hvort tveggja í gervigreindarskiptiborðinu. nexus-auth þjónustar þetta einnig á /auth/org/<organisation-id>/settings/ai-provider/role-assignments og /auth/org/<organisation-id>/settings/ai-provider/routing-policy fyrir kerfisstjóralykil sem hefur ai_provider:manage.

Kallarar geta sagt hvað þeir vilja. Færnilína getur borið æskilegan þjónustuaðila og æskilegt líkan, auk getusniðs. Beinirinn meðhöndlar hvert þeirra á ólíkan hátt:

  • Æskilegur þjónustuaðili er aðeins virtur þegar stofnunin hefur virkjað þann þjónustuaðila og á lykil fyrir hann. Annars velur beinirinn staðgengil.
  • Æskilegt líkan er virt þegar það er í vörulista þess þjónustuaðila og passar við sniðið.
  • Getusnið er sía sem velur aldrei. Hún getur beðið um lágmarks samhengisglugga, verkfæranotkun, sjón, vigranir, langt samhengi eða gagnastaðsetningu. Allt sem stenst hana ekki kemur ekki til greina.

Beinirinn velur í fastri röð. Hann virðir óskina þegar hann getur, reynir síðan annað líkan hjá sama þjónustuaðila, því næst hlutverkaskipanina og hvaða annan þjónustuaðila sem er með lykil þar sem vörulistinn passar. Ef snið var gefið upp og enginn vörulisti passar við það er beiðninni hafnað með MODEL_CAPABILITY_UNAVAILABLE (422). Ef ekkert er úthlutað og ekkert passar er það NO_PROVIDER_FOR_ROLE (422). Það er ekkert sjálfgefið líkan til þrautavara. Hlutverk sem þú hefur ekki stillt bilar áberandi, þar sem eigin orð beinisins segja hvað á að stilla.

Gagnastaðsetning er eina skorðan sem ekki er hægt að skipta út. Snið með eu_only er þjónustað af ESB-þjónustuaðila eða hafnað. Harrow setur þennan lás fyrir alla stofnunina og skiptiborðið teiknar annan hýsta þjónustuaðilann, sem er á svæði í Bandaríkjunum, sem óvirkan.

Færni getur einnig fest eitt nákvæmt líkan þegar færnin þarf á því líkani að halda til að virka. Jafnvel þá notar beinirinn eigin lykil stofnunarinnar fyrir það, og án hans svarar ekkert. Kallari getur aldrei látið Nexus nota þjónustuaðila sem stofnunin hefur ekki stillt.

Þegar þjónustuaðili hefur verið valinn er varaleið (failover) sérstakt mál. 429, 5xx eða netbilun færir beiðnina niður stigann á næsta þjónustuaðila. 400, 401, 403 eða 404 stöðvast samstundis, vegna þess að auðkenni og lögun beiðna flytjast ekki á milli þjónustuaðila og endurtekning myndi brenna kvóta til að komast að sömu bilun.

Til að sjá hvað beinirinn myndi velja áður en nokkur spyr spurningar skaltu lesa GET /api/ai/routing-policy/effective á gáttinni með eigin tákni einstaklings. Það svarar með líkaninu fyrir innskráðu stofnunina, eða höfnun beinisins í orðum þegar ekkert er til staðar, og það sendir enga beiðni til líkans.

Fylgst með beininum

Töluröndin neðst á hverri síðu sýnir líkanið sem er í notkun („Líkan: staðbundið“). Í Enterprise teiknar Gervigreindarskiptiborðið, í beinni umferð beinisins jafnóðum og hún á sér stað: beiðnir frá aðstoðarmanninum, verkum og forritum sem flæða í gegnum hlutverk til þjónustuaðila og lykla, lykill í 60 sekúndna hvíld sinni teiknaður grár, lykill sem slökkt er á teiknaður rauður og varaleið á hýsta þjónustuaðilann þegar staðbundna líkanið er upptekið. Við hlið flæðisins teiknar það upp álag á hvern þjónustuaðila, beiðnir á sekúndu og biðtíma. Tomás hefur það opið fyrstu vikuna eftir allar breytingar á beiningarstefnunni, vegna þess að röng hlutverkaskipan birtist þar innan nokkurra mínútna sem umferð sem fer eitthvert sem enginn ætlaði henni að fara.

Í Community er síðan Gervigreindarlíkön með hnappinn Prófa öll líkön sem athugar hvert stillt líkan og merkir hvort það svari. Það er fljótlegasta leiðin til að sanna að nýr lykill virki áður en nokkur treystir á hann.

Gervigreindarskiptiborðið, í beinni
Gervigreindarskiptiborðið, í beinni
Beinirinn í beinni. Umferð flæðir frá aðstoðarmanninum og verkum í gegnum hlutverk til staðbundins líkans og hýstra lykla; einn lykill hvílist, slökkt er á einum og gullnir punktar sýna varaleið á meðan staðbundna líkanið er upptekið.

Vigranir

Leit og þekkingarnetið breyta texta í vigra. Sjálfgefið gerir uppsetningin þetta með vigrunarlíkani (embedding model) sem keyrir inni í klasanum á örgjörvanum, þannig að enginn texti fer út fyrir staðinn til að verða vigraður og stofnun þarf engan lykil fyrir það. Að nota hýstan þjónustuaðila fyrir vigranir er val sem stofnun tekur; það fer þá í gegnum sama safn og sömu reglur.

Aðeins þrjár þjónustur mega biðja beininn um vigranir eða endurröðun: nexus-graphrag, nexus-skills-engine og nexus-workflows. GraphRAG vigrar sem sú stofnun sem á efnið, með stillingum þeirrar stofnunar, og geymir engan eigin lykil þjónustuaðila. Þegar stofnun breytir vigrunarlíkani sínu keyrir nexus-workflows endurvigrunarverkið fyrir gagnageymslur þeirrar stofnunar.

Persónuleg auðkenni haldast persónuleg

Sum auðkenni tilheyra einum einstaklingi. Claude Max áskrift, skráð inn í gegnum eigin aðgang þess einstaklings, er algengasta tilfellið. Slíkt auðkenni er aldrei stofnanalýkill: safnið hafnar því með VALIDATION_FAILED, það er aldrei skráð í lyklatöflu stofnunarinnar og enginn skjár annars einstaklings sýnir það.

Líkanalyklar fara heldur aldrei neitt annað. Síðan Lyklar fyrir ytri gögn, sem geymir lykla fyrir ytri gagnagjafa, hafnar öllu sem lítur út eins og lykill fyrir gervigreindarlíkan með AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Ef skráarlesarinn finnur líkanalykla inni í skjali eða stillingu þar sem þeir eiga ekki heima skráir hann CREDENTIALS_IN_WRONG_PLACE og kerfisstjóri fjarlægir þá og skiptir þeim út.

Skriftur, REST og MCP

Nexus er með þrjár opinberar vélar. Hjá Harrow eru þær console.harrow.example fyrir stjórnborðið, api.harrow.example fyrir gáttina og auth.harrow.example fyrir innskráningu. Skriftur og verkfæri nota þá aðra og þriðju.

Lyklar fyrir skriftur

Skrifta skráir sig inn með lykli sem búinn er til undir Stillingar, Lyklar fyrir skriftur. Hver lykill hefur nafn, umfang (til dæmis „Hefja eingöngu drónatalningu á svæði“), einstaklinginn sem bjó hann til og lokadagsetningu; stofnun getur læst mesta líftíma sem lykill má hafa. Leyndarmálið er sýnt einu sinni þegar lykillinn er búinn til. Afritaðu það í leyndarmálageymslu skriftunnar, því Nexus geymir aðeins síðustu fjóra stafi þess. Lykill er afturkallaður, aldrei fjarlægður: hann stöðvast samstundis og helst skráður með hverju kalli sem hann gerði. Endurnýjun (rotating) gefur lyklinum nýtt leyndarmál og sýnir það einu sinni.

Hver lykill hefur sína eigin síðu með köllum á dag, köllum eftir þjónustu og virkniskrá yfir tíma, vistfang, þjónustu og niðurstöðu. Kalli utan umfangs lykilsins er hafnað og það birtist í skránni.

nexus-auth þjónustar sömu lykla fyrir innskráðan einstakling á https://auth.harrow.example/api-keys: búa til og lista, síðan lesa, breyta, afturkalla eða endurnýja einn lykil eftir auðkenni hans.

Einn lykill fyrir skriftur
Einn lykill fyrir skriftur
Einn lykill fyrir skriftur. Síðan sýnir umfang lykilsins, hver bjó hann til, lokadagsetningu hans, köll eftir degi og eftir þjónustu, og niðurstöðu hvers kalls; leyndarmálið endar á …7QK2 og er aldrei sýnt aftur.

REST í gegnum gáttina

Sendu REST-köll á https://api.harrow.example með Authorization: Bearer <token-or-key>. Hver lykill verður að tilheyra stofnun. Lykli sem tilheyrir engri er hafnað með TOKEN_ORG_MISSING (403) af hverri þjónustu sem athugar lykla í gegnum nexus-auth.

Kallara sem spyr of oft er svarað 429 með RATE_LIMITED, Retry-After haus og mörkunum og tímarammanum í meginmálinu. Bíddu í þann fjölda sekúndna sem hann gefur upp. Í Enterprise stilla kerfisstjórar mörk á hvern lykil, á hvert forrit og á hverja einingu undir Stillingar, Hraðatakmarkanir (sjá kafla 2.16, Öryggi og netkerfi).

MCP fyrir gervigreindarverkfæri

Gervigreindarverkfæri sem tala Model Context Protocol tengjast við https://api.harrow.example/mcp. Þau skrá sig inn í gegnum OAuth 2.1 netþjóninn (OAuth er opni staðallinn fyrir framselda heimild) á https://auth.harrow.example, sem styður skráningu biðlara af verkfærinu sjálfu, þannig að verkfæri eins og Claude Code eða Cursor skráir sig sjálft og opnar vafra einstaklingsins til að skrá sig inn. Tengigin starfar þá fyrir þann eina einstakling, með réttindum þess einstaklings og engu meira. Innskráður einstaklingur getur sótt tilbúna stillingu fyrir skipanalínuverkfæri frá https://auth.harrow.example/api/v1/mcp/cli-config.

Verkfæraköll sem þurfa á líkani að halda fara í gegnum beininn eins og allt annað, undir stofnun einstaklingsins.