Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.14
Furnizori și modele de IA
Cum alege Ruterul pentru furnizori de inteligență artificială (IA) un model din rezerva proprie de chei a organizației și cum accesează scripturile și instrumentele de IA sistemul Nexus din exterior.
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Harrow Port Authority rulează două instalări. Cea de pe rețeaua sa operațională izolată (air-gapped) (capitolul 2.10, Instalarea izolată (air-gapped)) nu are deloc un furnizor găzduit. Pe instalarea corporativă conectată, pe care o urmărește acest capitol, majoritatea întrebărilor primesc răspuns de la un model care rulează pe două noduri cu unități de procesare grafică (GPU) în propria cameră a serverelor din port. O cheie Google Gemini, plătită de Harrow, preia surplusul atunci când modelul local este ocupat, iar Aoife Brennan a blocat traficul de inteligență artificială (IA) al organizației în UE. Nimeni de la Harrow nu a configurat vreun model în interiorul unui serviciu sau al unui plugin. Au indicat unei singure componente ce deține Harrow, iar acea componentă decide fiecare apel.
Acest capitol tratează acea componentă, AI Provider Router, pe care Partea 1 și consola o numesc centrala IA, precum și rezerva de chei pe care o utilizează. Se încheie cu modurile în care scripturile și instrumentele IA accesează Nexus din exterior: chei pentru scripturi, interfața de programare a aplicațiilor (API) REST (transfer de stare reprezentațională) și Model Context Protocol (MCP).
Ruterul pentru furnizori de IA
Routerul rulează în interiorul gateway-ului, nexus-gateway. Este singurul serviciu care deține acreditările de model ale unei organizații și ia decizia finală cu privire la furnizorul și modelul care răspund fiecărei cereri. Toate celelalte componente din Nexus îl interoghează. Un pas din fluxul de lucru indică ce ar dori, iar routerul decide.
Doar câteva servicii pot solicita acest lucru, iar fiecare listă este fixată prin chart:
| Ce se solicită | Cine poate solicita |
|---|---|
O completare (/internal/ai/chat și fluxul său) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Apeluri de instrumente și celelalte rute IA interne | nexus-orchestrator, nexus-workflows |
| Embedding-uri și reclasificare (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Fiecare rută internă verifică pe rând două lucruri: cheia de serviciu internă a apelantului și identitatea apelantului în raport cu lista de mai sus. O cerere fără cheie este refuzată cu MISSING_SERVICE_KEY (401), o cheie greșită cu INVALID_SERVICE_KEY (403), o cerere care nu specifică cine apelează cu MISSING_CALLER_IDENTITY (403), iar un apelant din afara listei cu UNAUTHORIZED_CALLER (403). Niciuna dintre acestea nu este reîncercată, deoarece niciuna nu reprezintă o eroare trecătoare.
Aplicațiile și pluginurile nu apar niciodată pe acea listă. Un plugin își declară preferințele în competențele (skills) pe care le înregistrează și le transmite prin UNO, motorul de fluxuri de lucru. Orchestratorul solicită apoi routerului în numele pluginului. Acesta este motivul pentru care un secret de plugin compromis poate acționa ca acel plugin, dar nu poate cheltui bugetul de model al nimănui.
Rezerva de chei a organizației
Cheile de model aparțin organizației. Fiecare organizație vine cu propriul cont de furnizor și își plătește propria factură, iar cheia se află în rezerva organizației, criptată în nexus-auth. Nu există o cheie de platformă partajată în spatele unei organizații, astfel încât nicio organizație nu cheltuiește vreodată bugetul alteia. Costul acestei reguli este clar: o organizație fără nicio cheie în rezervă nu primește răspunsuri IA. Asistentul afișează MODEL_NOT_CONNECTED (503) și indică cine poate conecta una.
O cheie poate fi adăugată în rezervă pentru patru furnizori:
| ID furnizor | Afișat ca |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Un server de model propriu
O organizație poate utiliza, de asemenea, orice server pe care îl rulează și care comunică prin API-ul compatibil cu OpenAI, cum ar fi modelul de pe nodurile GPU ale Harrow. Instalatorul îl numește în fișierul de valori:
# 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 direcționează adaptorul compatibil cu OpenAI al gateway-ului către serverul dumneavoastră. Într-o instalare, slotul scaleway al rezervei accesează acel server, astfel încât cheia pe care o adăugați pentru scaleway este cheia pe care o așteaptă propriul dumneavoastră server.
ai.installationHosts listează numele de gazde care se află în interiorul instalării, pe lângă domeniul de serviciu propriu al versiunii (release) și cele trei gazde publice. Fiecare intrare este un nume de gazdă, un .suffix, o adresă IP sau un interval IPv4 Classless Inter-Domain Routing (CIDR). Routerul folosește lista pentru a deosebi un apel care rămâne în locație de unul care o părăsește, ceea ce raportează verificarea „Nimic nu părăsește această locație” de pe pagina Conectați un model pe propriul hardware.
Politica de rețea contează la fel de mult ca routerul. Spațiul de nume (namespace) interzice implicit tot traficul de ieșire (egress), astfel încât gateway-ul poate accesa un server de model din afara spațiului de nume doar atunci când intervalul acestuia se află în networkPolicy.externalEgressCIDRs. Același lucru este valabil și pentru un furnizor găzduit: dacă Harrow dorește ca cheia sa Gemini să răspundă, intervalele de adrese ale furnizorului trebuie să fie listate și ele acolo, altfel apelul nu părăsește niciodată clusterul. Capitolul 2.16, Securitate și rețelistică, acoperă politica în întregime.
Adăugarea și retragerea cheilor
Proprietarii și administratorii unei organizații gestionează rezerva acesteia. Nimeni altcineva nu poate vedea cheile și nu le poate modifica, iar o cerere din partea lor este refuzată cu AUTHORITY_EXCEEDED.
În consolă
În ediția Enterprise, rezerva este păstrată în centrala IA, sub motoare. În ediția Community, aceleași chei sunt păstrate în Setări, Modele IA. Acea pagină reprezintă routerul de bază, unde adăugați chei și o adresă de model local și alegeți ce model îndeplinește fiecare sarcină. Ambele afișează fiecare cheie în funcție de cine a configurat-o și când („Configurat de Aoife, 3 sept.”) și printr-un indiciu mascat format din cel mult ultimele patru caractere, cum ar fi ••••7f2q. Cheia în sine nu mai este afișată niciodată după ce o adăugați.
Prin API-ul BFF
Componenta backend for frontend (BFF) a consolei deservește trei rute pentru rezervă. Apelați-le cu tokenul de acces propriu al unei persoane: organizația provine din token, niciodată din cerere.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET returnează furnizorii din rezervă, dacă fiecare poate răspunde, fiecare cheie după indiciul său și furnizorii pentru care poate fi adăugată o cheie. Adăugarea unei chei necesită un corp JSON cu două câmpuri obligatorii și unul opțional:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Cheia circulă o singură dată. nexus-auth o criptează și informează routerul, iar răspunsul conține doar indiciul. Răspunsul este 201 cu ID-ul noii chei și rândul acesteia: „Adăugată. Cheia Google Gemini ••••7f2q se află în rezerva IA a organizației, iar AI Provider Router poate direcționa către ea acum.” O etichetă are cel mult 100 de caractere, iar o cheie este un șir fără spații de cel mult 4.096 de caractere. Orice alt câmp din corp sau un câmp care numește o organizație ori o persoană este refuzat.
Retragerea necesită un corp gol. Routerul oprește imediat direcționarea către cheie, iar nexus-auth o păstrează, listată ca retrasă, astfel încât istoricul ei rămâne. Nimic din rezervă nu este șters vreodată.
| Refuz | HTTP | Când |
|---|---|---|
VALIDATION_FAILED |
400 | Un corp care nu este {provider, api_key, label?}, un furnizor necunoscut sau abonamentul propriu al unei persoane oferit drept cheie de organizație |
AUTHORITY_EXCEEDED |
403 | Apelantul nu este proprietar sau administrator al organizației |
RECORD_NOT_FOUND |
404 | Nicio cheie cu acel ID nu se află în rezerva organizației |
TRANSITION_NOT_PERMITTED |
409 | Cheia este deja retrasă |
TENANT_NOT_A_PARAMETER |
403 | Corpul sau interogarea a numit o organizație |
Stările cheilor
Fiecare cheie din rezervă se află într-una din șase stări. Doar o cheie în uz răspunde la o conversație.
| Stare | Ce înseamnă |
|---|---|
in_use |
Cheia răspunde, până la data de expirare, dacă are una. |
resting |
Routerul a pus-o în repaus după erori, până la o oră stabilită. Între timp, cererile merg la cheia următoare. |
exhausted |
Și-a epuizat limita la furnizor. |
invalid |
Furnizorul nu o mai acceptă. |
expired |
A expirat la data sa de expirare. |
withdrawn |
Un administrator a retras-o. Rămâne listată ca istoric. |
O cheie care eșuează intră în repaus timp de 60 de secunde. După 5 erori consecutive, routerul o dezactivează, îi mută cota către celelalte chei și înregistrează notificarea PROVIDER_KEY_SWITCHED_OFF. Nimeni nu este refuzat cât timp o altă cheie poate răspunde.
Când un furnizor nu are nicio cheie în uz, rezerva indică motivul („Nicio cheie în uz: 1 retrasă, 1 expirată”). Când niciun furnizor din rezervă nu are o cheie în uz, o conversație este refuzată cu NO_PROVIDER_FOR_ROLE (422) și soluția: un proprietar sau administrator adaugă o cheie de organizație. Aceasta este o stare de configurare și rămâne pe ecran până când cineva o remediază.
Roluri, politici și preferințe
Routerul gândește în roluri. Fiecare cerere este pentru unul din cinci: default, fast, reasoning, code sau long_context. Fiecare model se află, de asemenea, pe un nivel, frontier, standard sau fast, iar un nivel superior este preferat atunci când rolul o permite. Organizația decide ce furnizor deservește fiecare rol (alocările sale de roluri) și ordinea de rezervă atunci când un furnizor eșuează (scara sa de politici de rutare). Administratorii le configurează pe ambele în centrala IA. De asemenea, nexus-auth le deservește la /auth/org/<organisation-id>/settings/ai-provider/role-assignments și /auth/org/<organisation-id>/settings/ai-provider/routing-policy pentru o cheie de administrator care deține ai_provider:manage.
Apelanții pot indica ce ar dori. Un rând de competență (skill) poate conține un furnizor preferat și un model preferat, plus un profil de capabilități. Routerul le tratează diferit pe fiecare:
- Un furnizor preferat este onorat doar atunci când organizația are acel furnizor activat și deține o cheie pentru acesta. În caz contrar, routerul îl substituie.
- Un model preferat este onorat atunci când se află în catalogul acelui furnizor și se potrivește profilului.
- Un profil de capabilități este un filtru care nu selectează niciodată. Poate solicita o fereastră de context minimă, utilizarea de instrumente, viziune, embedding-uri, context lung sau o rezidență a datelor. Orice nu îndeplinește aceste cerințe nu este eligibil.
Routerul alege într-o ordine fixă. Onorează preferința atunci când poate, apoi încearcă un alt model al aceluiași furnizor, apoi alocarea rolului și orice alt furnizor cu o cheie al cărui catalog se potrivește. Dacă a fost indicat un profil și niciun catalog nu i se potrivește, cererea este refuzată cu MODEL_CAPABILITY_UNAVAILABLE (422). Dacă nimic nu este alocat și nimic nu se potrivește, răspunsul este NO_PROVIDER_FOR_ROLE (422). Nu există un model implicit de ultimă instanță. Un rol pe care nu l-ați configurat eșuează vizibil, routerul indicând explicit ce trebuie configurat.
Rezidența datelor este singura constrângere care nu poate fi ocolită prin substituire. Un profil cu eu_only este deservit de un furnizor din UE sau este refuzat. Harrow configurează această blocare pentru întreaga organizație, iar centrala afișează al doilea furnizor găzduit, care se află într-o regiune din SUA, ca dezactivat.
O competență (skill) poate, de asemenea, să fixeze un model exact atunci când are nevoie de acel model pentru a funcționa. Chiar și atunci, routerul folosește propria cheie a organizației pentru acesta, iar fără una nimic nu răspunde. Un apelant nu poate determina niciodată Nexus să utilizeze un furnizor pe care organizația nu l-a configurat.
Odată ce un furnizor este ales, comutarea în caz de eroare (failover) este o chestiune separată. O eroare 429, 5xx sau o eroare de rețea mută cererea mai jos pe scară, către următorul furnizor. O eroare 400, 401, 403 sau 404 se oprește imediat, deoarece acreditările și structurile cererilor nu se transferă de la un furnizor la altul, iar o reîncercare ar consuma din cotă pentru a ajunge la același eșec.
Pentru a vedea ce ar alege routerul înainte ca cineva să pună o întrebare, citiți GET /api/ai/routing-policy/effective pe gateway cu tokenul propriu al unei persoane. Acesta returnează modelul pentru organizația autentificată sau refuzul formulat de router atunci când nu există niciunul, fără a trimite vreo cerere către un model.
Monitorizarea ruterului
Banda cu cifre din partea de jos a fiecărei pagini arată modelul în uz („Model: local”). În ediția Enterprise, Centrala IA, în timp real redă traficul routerului pe măsură ce are loc: cereri de la asistent, sarcini și aplicații care curg prin roluri către furnizori și chei, o cheie aflată în repausul său de 60 de secunde afișată în gri, o cheie dezactivată afișată în roșu și o redirecționare de rezervă către furnizorul găzduit atunci când modelul local este ocupat. Alături de flux, afișează grafic încărcarea per furnizor, cererile pe secundă și timpul de așteptare. Tomás o ține deschisă în prima săptămână după orice modificare a politicii de rutare, deoarece o alocare greșită a rolurilor apare acolo în câteva minute ca trafic care merge undeva unde nimeni nu a intenționat.
În ediția Community, pagina Modele IA are un buton Testează fiecare model care verifică fiecare model configurat și marchează dacă acesta răspunde. Este cea mai rapidă modalitate de a demonstra că o cheie nouă funcționează înainte ca cineva să se bazeze pe ea.
Reprezentări vectoriale (embeddings)
Căutarea și graful de cunoștințe transformă textul în vectori. În mod implicit, instalarea face acest lucru cu un model de embedding care rulează în interiorul clusterului pe procesor, astfel încât niciun text nu părăsește locația pentru a i se genera embedding-uri, iar o organizație nu are nevoie de nicio cheie pentru aceasta. Utilizarea unui furnizor găzduit pentru embedding-uri este o alegere pe care o face organizația; aceasta trece apoi prin aceeași rezervă și aceleași reguli.
Doar trei servicii pot solicita routerului embedding-uri sau reclasificare (reranking): nexus-graphrag, nexus-skills-engine și nexus-workflows. GraphRAG generează embedding-uri în numele organizației căreia îi aparține conținutul, cu setările acelei organizații, și nu deține nicio cheie de furnizor proprie. Când o organizație își schimbă modelul de embedding, nexus-workflows rulează sarcina de regenerare a embedding-urilor pentru depozitele de date ale acelei organizații.
Credențialele individuale rămân personale
Unele acreditări aparțin unei singure persoane. Un abonament Claude Max, autentificat prin contul propriu al acelei persoane, este cazul comun. O astfel de acreditare nu este niciodată o cheie de organizație: rezerva o refuză cu VALIDATION_FAILED, nu este niciodată listată în tabelul de chei al organizației și niciun ecran al altei persoane nu o afișează.
De asemenea, cheile de model nu ajung niciodată în altă parte. Pagina Chei de date externe, care păstrează chei pentru surse de date din exterior, refuză orice seamănă cu o cheie de model IA cu AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Dacă cititorul de fișiere găsește chei de model în interiorul unui document sau al unei configurații unde nu își au locul, înregistrează CREDENTIALS_IN_WRONG_PLACE, iar un administrator le elimină și le înlocuiește.
Scripturi, REST și MCP
Nexus are trei gazde publice. La Harrow, acestea sunt console.harrow.example pentru consolă, api.harrow.example pentru gateway și auth.harrow.example pentru autentificare. Scripturile și instrumentele le folosesc pe a doua și pe a treia.
Chei pentru scripturi
Un script se autentifică cu o cheie creată în Setări, Chei pentru scripturi. Fiecare cheie are un nume, o arie de acoperire (de exemplu, „Doar pornire numărare în curte cu drona”), persoana care a creat-o și o dată de sfârșit; o organizație poate bloca durata maximă de viață pe care o poate avea o cheie. Secretul este afișat o singură dată, atunci când cheia este creată. Copiați-l în depozitul de secrete al scriptului, deoarece Nexus păstrează doar ultimele patru caractere ale acestuia. O cheie este retrasă, niciodată eliminată: se oprește imediat și rămâne listată împreună cu fiecare apel pe care l-a efectuat. Rotirea îi oferă cheii un secret nou și îl afișează o singură dată.
Fiecare cheie are propria pagină cu apeluri pe zi, apeluri pe serviciu și un jurnal de activitate cu ora, adresa, serviciul și rezultatul. Un apel în afara ariei de acoperire a cheii este refuzat și apare în jurnal.
nexus-auth deservește aceleași chei unei persoane autentificate la https://auth.harrow.example/api-keys: crearea și listarea, apoi citirea, modificarea, revocarea sau rotirea unei chei după ID-ul său.
REST prin gateway
Trimiteți apeluri REST către https://api.harrow.example cu Authorization: Bearer <token-or-key>. Fiecare cheie trebuie să aparțină unei organizații. O cheie fără organizație este refuzată cu TOKEN_ORG_MISSING (403) de către fiecare serviciu care verifică cheile prin nexus-auth.
Un apelant care face cereri prea des primește răspunsul 429 cu RATE_LIMITED, un antet Retry-After, precum și limita și fereastra în corp. Așteptați numărul de secunde indicat. În ediția Enterprise, administratorii stabilesc limite per cheie, per aplicație și per unitate în Setări, Limite de rată (consultați capitolul 2.16, Securitate și rețelistică).
MCP pentru instrumente IA
Instrumentele IA care comunică prin Model Context Protocol se conectează la https://api.harrow.example/mcp. Acestea se autentifică prin serverul OAuth 2.1 (OAuth este standardul deschis pentru autorizare delegată) la https://auth.harrow.example, care acceptă înregistrarea clientului de către instrumentul însuși, astfel încât un instrument precum Claude Code sau Cursor se înregistrează singur și deschide browserul persoanei pentru autentificare. Conexiunea acționează apoi în numele acelei singure persoane, cu drepturile acelei persoane și nimic mai mult. O persoană autentificată poate prelua o configurație pregătită pentru un instrument în linie de comandă de la https://auth.harrow.example/api/v1/mcp/cli-config.
Apelurile de instrumente care au nevoie de un model trec prin router ca orice altceva, sub organizația persoanei respective.




