Versione 1.0.0-alpha.1ultima
Capitolo 2.14
Fornitori e modelli di IA
Come il Provider Router dell'intelligenza artificiale (IA) seleziona un modello dal pool di chiavi dell'organizzazione e come gli script e gli strumenti di IA raggiungono Nexus dall'esterno.
Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

Harrow Port Authority gestisce due installazioni. Quella sulla sua rete operativa air-gapped (capitolo 2.10, Installazione air-gapped) non ha alcun provider in hosting. Sull'installazione aziendale connessa, seguita in questo capitolo, la maggior parte delle domande riceve risposta da un modello in esecuzione su due nodi GPU (graphics processing unit) nella sala server del porto stesso. Una chiave Google Gemini, pagata da Harrow, assorbe il traffico in eccesso quando il modello locale è occupato, e Aoife Brennan ha vincolato il traffico di intelligenza artificiale (IA) dell'organizzazione all'UE. Nessuno presso Harrow ha configurato un modello all'interno di un servizio o di un plugin. Hanno indicato a un singolo componente ciò che Harrow possiede, ed è quel componente a decidere per ogni chiamata.
Questo capitolo tratta tale componente, l'AI Provider Router, che nella Parte 1 e nella console viene chiamato centralino IA, e il pool di chiavi a cui attinge. Si conclude con i modi in cui gli script e gli strumenti di IA raggiungono Nexus dall'esterno: chiavi per script, l'API (application programming interface) REST (representational state transfer) e il Model Context Protocol (MCP).
L'AI Provider Router
Il router viene eseguito all'interno del gateway, nexus-gateway. È l'unico servizio che detiene le credenziali dei modelli di un'organizzazione e prende la decisione finale su quale provider e quale modello rispondano a ciascuna richiesta. Ogni altra parte di Nexus si rivolge a esso. Un passaggio del flusso di lavoro indica ciò che desidera e il router decide.
Solo pochi servizi possono effettuare richieste e ciascun elenco è fissato dal chart:
| Cosa viene richiesto | Chi può richiedere |
|---|---|
Un completamento (/internal/ai/chat e il relativo stream) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Chiamate agli strumenti e le altre rotte IA interne | nexus-orchestrator, nexus-workflows |
| Embedding e reranking | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Ciascuna rotta interna verifica due elementi in sequenza: la chiave di servizio interna del chiamante e l'identità del chiamante rispetto all'elenco precedente. Una richiesta senza la chiave viene rifiutata con MISSING_SERVICE_KEY (401), una chiave errata con INVALID_SERVICE_KEY (403), una richiesta che non specifica chi sta chiamando con MISSING_CALLER_IDENTITY (403) e un chiamante non presente nell'elenco con UNAUTHORIZED_CALLER (403). Nessuna di queste richieste viene ritentata, poiché non si tratta di errori temporanei.
Le app e i plugin non compaiono mai in quell'elenco. Un plugin dichiara le proprie preferenze nelle competenze che registra e invia tramite UNO, il motore del flusso di lavoro. L'orchestratore si rivolge quindi al router per conto del plugin. Ecco perché il segreto compromesso di un plugin può agire come tale plugin, ma non può consumare il budget per i modelli di nessuno.
Il pool di chiavi dell'organizzazione
Le chiavi dei modelli appartengono all'organizzazione. Ciascuna organizzazione utilizza il proprio account del provider e paga la propria fattura, e la chiave risiede nel pool dell'organizzazione, crittografata in nexus-auth. Non esiste alcuna chiave di piattaforma condivisa dietro un'organizzazione, pertanto nessuna organizzazione consuma mai il budget di un'altra. Il prezzo di questa regola è chiaro: un'organizzazione senza chiavi nel proprio pool non ottiene risposte dall'IA. L'assistente mostra MODEL_NOT_CONNECTED (503) e indica chi può collegarne una.
È possibile aggiungere una chiave al pool per quattro provider:
| ID provider | Mostrato come |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Un server di modelli proprio
Un'organizzazione può anche utilizzare qualsiasi server gestito in proprio che comunichi tramite l'API compatibile con OpenAI, come il modello sui nodi GPU di Harrow. L'installatore lo specifica nel file dei 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 indirizza l'adattatore compatibile con OpenAI del gateway al vostro server. In un'installazione, lo slot scaleway del pool raggiunge tale server, quindi la chiave che aggiungete per scaleway è la chiave che il vostro server si aspetta.
ai.installationHosts elenca i nomi host interni all'installazione, oltre al dominio di servizio della release stessa e ai tre host pubblici. Ciascuna voce è un nome host, un .suffix, un indirizzo IP o un intervallo CIDR (Classless Inter-Domain Routing) IPv4. Il router utilizza l'elenco per distinguere una chiamata che rimane in sede da una che esce, ovvero ciò che segnala il controllo "Nulla esce da questa sede" nella pagina Collega un modello sul tuo hardware.
La policy di rete è importante quanto il router. Il namespace nega tutto il traffico in uscita per impostazione predefinita, quindi il gateway può raggiungere un server di modelli esterno al namespace solo quando il suo intervallo è presente in networkPolicy.externalEgressCIDRs. Lo stesso vale per un provider in hosting: se Harrow desidera che la sua chiave Gemini risponda, anche gli intervalli di indirizzi del provider devono essere elencati lì, altrimenti la chiamata non esce mai dal cluster. Il capitolo 2.16, Sicurezza e rete, illustra la policy in dettaglio.
Aggiungere e ritirare le chiavi
I proprietari e gli amministratori di un'organizzazione gestiscono il relativo pool. Chiunque altro non può vedere le chiavi né modificarle, e una sua richiesta viene rifiutata con AUTHORITY_EXCEEDED.
Nella console
In Enterprise il pool è conservato nel centralino IA, sotto i motori. In Community le stesse chiavi sono conservate in Impostazioni, Modelli IA. Quella pagina è il router di base, in cui si aggiungono le chiavi e l'indirizzo di un modello locale e si sceglie quale modello svolge quale incarico. Entrambe mostrano ciascuna chiave indicando chi l'ha impostata e quando ("Impostata da Aoife, 3 set") e tramite un suggerimento mascherato composto al massimo dagli ultimi quattro caratteri, ad esempio ••••7f2q. La chiave stessa non viene mai più mostrata dopo essere stata aggiunta.
Tramite l'API BFF
Il backend for frontend (BFF) della console serve tre rotte per il pool. Chiamatele con il token di accesso personale di un utente: l'organizzazione viene ricavata dal token, mai dalla richiesta.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET restituisce i provider nel pool, se ciascuno è in grado di rispondere, ogni chiave identificata dal relativo suggerimento e i provider per i quali è possibile aggiungere una chiave. L'aggiunta di una chiave richiede un corpo JSON con due campi obbligatori e uno facoltativo:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }La chiave viaggia una sola volta. nexus-auth la crittografa e lo comunica al router, mentre la risposta contiene solo il suggerimento. La risposta è 201 con l'ID della nuova chiave e la relativa riga: "Aggiunta. La chiave Google Gemini ••••7f2q è nel pool IA dell'organizzazione e l'AI Provider Router può ora instradare il traffico verso di essa." Un'etichetta ha una lunghezza massima di 100 caratteri e una chiave è un'unica stringa senza spazi di massimo 4.096 caratteri. Qualsiasi altro campo nel corpo, o un campo che indichi un'organizzazione o una persona, viene rifiutato.
Il ritiro richiede un corpo vuoto. Il router interrompe immediatamente l'instradamento verso la chiave e nexus-auth la conserva, elencata come ritirata, in modo che la sua cronologia rimanga. Nulla nel pool viene mai eliminato.
| Rifiuto | HTTP | Quando |
|---|---|---|
VALIDATION_FAILED |
400 | Un corpo che non è {provider, api_key, label?}, un provider sconosciuto o l'abbonamento personale di un individuo offerto come chiave dell'organizzazione |
AUTHORITY_EXCEEDED |
403 | Il chiamante non è un proprietario o un amministratore dell'organizzazione |
RECORD_NOT_FOUND |
404 | Nessuna chiave con quell'ID è presente nel pool dell'organizzazione |
TRANSITION_NOT_PERMITTED |
409 | La chiave è già stata ritirata |
TENANT_NOT_A_PARAMETER |
403 | Il corpo o la query ha specificato un'organizzazione |
Stati delle chiavi
Ciascuna chiave nel pool si trova in uno di sei stati. Solo una chiave in uso risponde a una chat.
| Stato | Cosa significa |
|---|---|
in_use |
La chiave risponde fino alla sua data di scadenza, se ne ha una. |
resting |
Il router l'ha messa in pausa dopo alcuni errori, fino a un orario stabilito. Nel frattempo le richieste passano alla chiave successiva. |
exhausted |
Ha esaurito il suo limite presso il fornitore. |
invalid |
Il fornitore non la accetta più. |
expired |
È scaduta alla sua data di scadenza. |
withdrawn |
Un amministratore l'ha ritirata. Rimane in elenco come storico. |
Una chiave che fallisce resta in pausa per 60 secondi. Dopo 5 errori consecutivi il router la disattiva, sposta la sua quota sulle altre chiavi e registra l'avviso PROVIDER_KEY_SWITCHED_OFF. Nessuno viene respinto finché un'altra chiave può rispondere.
Quando un fornitore non ha alcuna chiave in uso, il pool ne indica il motivo ("Nessuna chiave in uso: 1 ritirata, 1 scaduta"). Quando nessun fornitore nel pool ha una chiave in uso, una chat viene rifiutata con NO_PROVIDER_FOR_ROLE (422) e il rimedio: un proprietario o un amministratore aggiunge una chiave dell'organizzazione. Questo è uno stato di configurazione e rimane sullo schermo finché qualcuno non lo risolve.
Ruoli, criteri e preferenze
Il router ragiona per ruoli. Ogni richiesta è destinata a uno dei cinque: default, fast, reasoning, code o long_context. Ogni modello appartiene anche a una fascia, frontier, standard o fast, e si preferisce una fascia superiore quando il ruolo lo consente. L'organizzazione decide quale fornitore serve ciascun ruolo (le sue assegnazioni di ruolo) e l'ordine di ripiego quando un fornitore fallisce (la sua scala di criteri di instradamento). Gli amministratori impostano entrambi nel centralino IA. Anche nexus-auth li espone in /auth/org/<organisation-id>/settings/ai-provider/role-assignments e /auth/org/<organisation-id>/settings/ai-provider/routing-policy per una chiave amministratore dotata di ai_provider:manage.
I chiamanti possono esprimere le proprie preferenze. Una riga di competenza può contenere un fornitore preferito e un modello preferito, oltre a un profilo di capacità. Il router tratta ciascuno di essi in modo diverso:
- Un fornitore preferito viene rispettato solo quando l'organizzazione ha abilitato tale fornitore e dispone di una chiave per esso. Altrimenti il router lo sostituisce.
- Un modello preferito viene rispettato quando è presente nel catalogo di quel fornitore e corrisponde al profilo.
- Un profilo di capacità è un filtro che non effettua mai selezioni. Può richiedere una finestra di contesto minima, l'uso di strumenti, visione, embedding, contesto lungo o una residenza dei dati. Tutto ciò che non soddisfa il filtro non è idoneo.
Il router sceglie seguendo un ordine fisso. Rispetta la preferenza quando può, poi prova un altro modello dello stesso fornitore, quindi l'assegnazione di ruolo e qualsiasi altro fornitore con una chiave il cui catalogo sia idoneo. Se è stato indicato un profilo e nessun catalogo vi corrisponde, la richiesta viene rifiutata con MODEL_CAPABILITY_UNAVAILABLE (422). Se non c'è nulla di assegnato e nulla corrisponde, restituisce NO_PROVIDER_FOR_ROLE (422). Non esiste un modello predefinito di ultima istanza. Un ruolo non configurato genera un errore esplicito, con il router stesso che indica cosa impostare.
La residenza dei dati è l'unico vincolo che non può essere aggirato tramite sostituzione. Un profilo con eu_only viene servito da un fornitore UE oppure viene rifiutato. Harrow imposta questo blocco per l'intera organizzazione e il centralino mostra come disattivato il secondo fornitore in hosting, che risiede in una regione degli Stati Uniti.
Una competenza può anche fissare un modello esatto quando ne ha bisogno per funzionare. Anche in quel caso il router utilizza la chiave dell'organizzazione per quel modello e, in sua assenza, nulla risponde. Un chiamante non può mai indurre Nexus a usare un fornitore che l'organizzazione non ha configurato.
Una volta scelto un fornitore, il failover è una questione separata. Un errore 429, 5xx o un guasto di rete sposta la richiesta lungo la scala verso il fornitore successivo. Un errore 400, 401, 403 o 404 interrompe immediatamente il processo, poiché le credenziali e la struttura delle richieste non si trasferiscono tra fornitori e un nuovo tentativo consumerebbe quota per giungere allo stesso errore.
Per vedere cosa sceglierebbe il router prima che qualcuno ponga una domanda, consulti GET /api/ai/routing-policy/effective sul gateway con il token personale di un utente. Risponde indicando il modello per l'organizzazione connessa, oppure il rifiuto espresso a parole dal router quando non ce n'è alcuno, senza inviare alcuna richiesta a un modello.
Monitorare il router
La striscia dei dati in fondo a ogni pagina mostra il modello in uso ("Modello: locale"). Nella versione Enterprise, Il centralino IA, in tempo reale disegna il traffico del router mentre si svolge: le richieste dall'assistente, dai processi e dalle app che fluiscono attraverso i ruoli verso fornitori e chiavi, una chiave nella sua pausa di 60 secondi disegnata in grigio, una chiave disattivata disegnata in rosso e un ripiego sul fornitore in hosting quando il modello locale è occupato. Accanto al flusso traccia il carico per fornitore, le richieste al secondo e il tempo di attesa. Tomás lo tiene aperto durante la prima settimana successiva a qualsiasi modifica ai criteri di instradamento, perché un'assegnazione di ruolo errata si manifesta lì in pochi minuti sotto forma di traffico diretto dove nessuno intendeva mandarlo.
Nella versione Community, la pagina Modelli IA presenta un pulsante Testa ogni modello che verifica ciascun modello configurato e indica se risponde. È il modo più rapido per dimostrare che una nuova chiave funziona prima che qualcuno vi faccia affidamento.
Embedding
La ricerca e il grafo della conoscenza trasformano il testo in vettori. Per impostazione predefinita, l'installazione esegue questa operazione con un modello di embedding che gira all'interno del cluster sul processore, cosicché nessun testo lascia il sito per l'embedding e all'organizzazione non serve alcuna chiave. L'utilizzo di un fornitore in hosting per gli embedding è una scelta dell'organizzazione; in tal caso passa attraverso lo stesso pool e le stesse regole.
Solo tre servizi possono richiedere al router operazioni di embedding o reranking: nexus-graphrag, nexus-skills-engine e nexus-workflows. GraphRAG genera gli embedding a nome dell'organizzazione a cui appartiene il contenuto, con le impostazioni di tale organizzazione, e non detiene alcuna chiave del fornitore propria. Quando un'organizzazione cambia il proprio modello di embedding, nexus-workflows esegue il processo di rigenerazione degli embedding per gli archivi di quell'organizzazione.
Le credenziali individuali restano personali
Alcune credenziali appartengono a una singola persona. Un abbonamento Claude Max, a cui si accede tramite l'account personale dell'utente, è il caso più comune. Una credenziale di questo tipo non è mai una chiave dell'organizzazione: il pool la rifiuta con VALIDATION_FAILED, non viene mai elencata nella tabella delle chiavi dell'organizzazione e nessuna schermata di un altro utente la mostra.
Inoltre, le chiavi dei modelli non finiscono mai altrove. La pagina Chiavi dati esterni, che conserva le chiavi per le fonti di dati esterne, rifiuta qualsiasi elemento che somigli a una chiave di modello IA con AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Se il lettore di file trova chiavi di modelli all'interno di un documento o di una configurazione a cui non appartengono, registra CREDENTIALS_IN_WRONG_PLACE e un amministratore provvede a rimuoverle e sostituirle.
Script, REST e MCP
Nexus ha tre host pubblici. Presso Harrow sono console.harrow.example per la console, api.harrow.example per il gateway e auth.harrow.example per l'accesso. Gli script e gli strumenti utilizzano il secondo e il terzo.
Chiavi per gli script
Uno script effettua l'accesso con una chiave creata in Impostazioni, Chiavi per gli script. Ogni chiave ha un nome, un ambito di validità (ad esempio, "Avvia solo il conteggio piazzale con droni"), la persona che l'ha creata e una data di fine; un'organizzazione può bloccare la durata massima consentita per una chiave. Il segreto viene mostrato una sola volta al momento della creazione della chiave. Lo copi nell'archivio dei segreti dello script, poiché Nexus ne conserva solo gli ultimi quattro caratteri. Una chiave viene ritirata, mai rimossa: cessa subito di funzionare e rimane in elenco con tutte le chiamate effettuate. La rotazione assegna alla chiave un nuovo segreto e lo mostra una sola volta.
Ogni chiave ha la propria pagina con le chiamate giornaliere, le chiamate per servizio e un registro delle attività con orario, indirizzo, servizio ed esito. Una chiamata al di fuori dell'ambito di validità della chiave viene rifiutata e compare nel registro.
nexus-auth espone le stesse chiavi a un utente connesso all'indirizzo https://auth.harrow.example/api-keys: creazione ed elenco, quindi lettura, modifica, revoca o rotazione di una chiave tramite il suo id.
REST attraverso il gateway
Invii le chiamate REST a https://api.harrow.example con Authorization: Bearer <token-or-key>. Ogni chiave deve appartenere a un'organizzazione. Una chiave priva di organizzazione viene rifiutata con TOKEN_ORG_MISSING (403) da tutti i servizi che verificano le chiavi tramite nexus-auth.
A un chiamante che effettua richieste troppo frequenti viene risposto 429 con RATE_LIMITED, un'intestazione Retry-After e il limite e la finestra temporale nel corpo del messaggio. Attenda il numero di secondi indicato. Nella versione Enterprise, gli amministratori impostano i limiti per chiave, per app e per unità in Impostazioni, Limiti di frequenza (vedere capitolo 2.16, Sicurezza e rete).
MCP per gli strumenti IA
Gli strumenti IA che utilizzano il Model Context Protocol si connettono a https://api.harrow.example/mcp. Effettuano l'accesso tramite il server OAuth 2.1 (OAuth è lo standard aperto per l'autorizzazione delegata) all'indirizzo https://auth.harrow.example, che supporta la registrazione del client da parte dello strumento stesso; pertanto uno strumento come Claude Code o Cursor si registra autonomamente e apre il browser dell'utente per l'accesso. La connessione agisce quindi per conto di quella singola persona, con i suoi diritti e nient'altro. Un utente connesso può recuperare una configurazione pronta all'uso per uno strumento a riga di comando da https://auth.harrow.example/api/v1/mcp/cli-config.
Le chiamate degli strumenti che necessitano di un modello passano attraverso il router come tutto il resto, sotto l'organizzazione della persona.




