Verze 1.0.0-alpha.1nejnovější
Kapitola 2.14
Poskytovatelé a modely AI
Jak směrovač poskytovatelů umělé inteligence (AI) vybírá model z vlastního fondu klíčů organizace a jak skripty a nástroje AI přistupují k systému Nexus zvenčí.
Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

Harrow Port Authority provozuje dvě instalace. Ta v provozní síti typu air-gapped (kapitola 2.10, Instalace v prostředí air-gapped) nemá vůbec žádného hostovaného poskytovatele. V připojené podnikové instalaci, které se věnuje tato kapitola, na většinu dotazů odpovídá model běžící na dvou uzlech s grafickými procesory (GPU) ve vlastní serverovně přístavu. Klíč pro Google Gemini, který hradí Harrow, přebírá přetok dotazů, když je lokální model vytížený, a Aoife Brennan uzamkla provoz umělé inteligence (AI) organizace do EU. Nikdo v Harrow nenakonfiguroval model uvnitř služby ani pluginu. Sdělovali jediné komponentě, co Harrow vlastní, a tato komponenta rozhoduje o každém volání.
Tato kapitola se věnuje právě této komponentě – AI Provider Routeru, který 1. část a konzole označují jako ústřednu AI – a fondu klíčů, ze kterého čerpá. V závěru popisuje způsoby, jakými skripty a nástroje AI přistupují k systému Nexus zvenčí: klíče pro skripty, aplikační programové rozhraní (API) typu REST (representational state transfer) a protokol Model Context Protocol (MCP).
Směrovač poskytovatelů AI
Router běží uvnitř brány nexus-gateway. Je to jediná služba, která uchovává přístupové údaje k modelům organizace, a činí konečné rozhodnutí o tom, který poskytovatel a který model odpoví na každý požadavek. Všechny ostatní části systému Nexus se dotazují právě jí. Krok pracovního postupu sdělí, co by potřeboval, a router rozhodne.
Dotazovat se může pouze několik služeb a každý seznam je pevně dán chartem:
| O co se žádá | Kdo se může dotazovat |
|---|---|
Generování odpovědi (/internal/ai/chat a její stream) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Volání nástrojů a ostatní interní trasy AI | nexus-orchestrator, nexus-workflows |
| Vektorové reprezentace (embeddings) a přeuspořádání (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Každá interní trasa postupně kontroluje dvě věci: interní klíč služby volajícího a identitu volajícího oproti výše uvedenému seznamu. Požadavek bez klíče je odmítnut s kódem MISSING_SERVICE_KEY (401), nesprávný klíč s INVALID_SERVICE_KEY (403), požadavek, který neuvádí, kdo volá, s MISSING_CALLER_IDENTITY (403), a volající mimo seznam s UNAUTHORIZED_CALLER (403). Žádný z těchto požadavků se neopakuje, protože v žádném z případů nejde o přechodnou chybu.
Aplikace a pluginy se na tomto seznamu nikdy neobjevují. Plugin deklaruje své požadavky u dovedností, které registruje, a odesílá je prostřednictvím UNO, enginu pro pracovní postupy. Orchestrátor se pak dotazuje routeru jménem pluginu. Proto uniklý tajný klíč pluginu sice může jednat jako daný plugin, ale nemůže čerpat ničí rozpočet na modely.
Fond klíčů organizace
Klíče k modelům patří organizaci. Každá organizace si přináší vlastní účet u poskytovatele a platí vlastní účty a klíč je uložen ve fondu organizace, zašifrovaný ve službě nexus-auth. Za organizací nestojí žádný sdílený klíč platformy, takže žádná organizace nikdy nečerpá rozpočet jiné organizace. Daň za toto pravidlo je zřejmá: organizace, která nemá ve svém fondu žádný klíč, nedostane žádné odpovědi od AI. Asistent zobrazí MODEL_NOT_CONNECTED (503) a uvede, kdo může klíč připojit.
Klíč lze do fondu přidat pro čtyři poskytovatele:
| ID poskytovatele | Zobrazeno jako |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Vlastní modelový server
Organizace může také použít jakýkoli server, který provozuje a který komunikuje přes API kompatibilní s OpenAI, jako je například model na uzlech GPU v Harrow. Instalátor jej uvede v souboru hodnot (values):
# 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 nasměruje adaptér brány kompatibilní s OpenAI na váš server. V instalaci se na tento server připojuje slot scaleway ve fondu, takže klíč, který přidáte pro scaleway, je klíč, který očekává váš vlastní server.
ai.installationHosts uvádí názvy hostitelů, které se nacházejí uvnitř instalace, kromě vlastní domény služeb daného vydání (release) a tří veřejných hostitelů. Každá položka je název hostitele, .suffix, IP adresa nebo rozsah IPv4 Classless Inter-Domain Routing (CIDR). Router pomocí tohoto seznamu rozlišuje volání, které zůstává v lokalitě, od volání, které ji opouští, což je údaj, který hlásí kontrola „Nothing leaves this site“ (Nic neopouští tuto lokalitu) na stránce Connect a model on your own hardware (Připojení modelu na vlastním hardwaru).
Síťová politika je stejně důležitá jako router. Jmenný prostor (namespace) ve výchozím nastavení zakazuje veškerý odchozí provoz (egress), takže brána se může spojit s modelovým serverem mimo jmenný prostor pouze tehdy, když je jeho rozsah uveden v networkPolicy.externalEgressCIDRs. Totéž platí pro hostovaného poskytovatele: pokud chce Harrow, aby odpovídal jeho klíč Gemini, musí tam být uvedeny i rozsahy adres poskytovatele, jinak volání nikdy neopustí cluster. Kapitola 2.16, Zabezpečení a sítě, popisuje tuto politiku v plném rozsahu.
Přidávání a odebírání klíčů
Fond organizace spravují její vlastníci a administrátoři. Nikdo jiný klíče nevidí ani je nemůže měnit a požadavek od takových uživatelů je odmítnut s kódem AUTHORITY_EXCEEDED.
V konzoli
V edici Enterprise je fond uložen v ústředně AI pod příslušnými enginy. V edici Community jsou stejné klíče uloženy v části Nastavení, Modely AI. Tato stránka představuje základní router, kde přidáváte klíče a adresu lokálního modelu a vybíráte, který model vykonává kterou úlohu. Obě edice u každého klíče zobrazují, kdo a kdy jej nastavil („Nastavila Aoife, 3. září“), a maskovanou nápovědu obsahující nejvýše poslední čtyři znaky, například ••••7f2q. Samotný klíč se po přidání již nikdy znovu nezobrazí.
Prostřednictvím BFF API
Služba backend for frontend (BFF) konzole obsluhuje tři trasy pro tento fond. Volejte je pomocí vlastního přístupového tokenu uživatele: organizace se určuje z tokenu, nikdy ze samotného požadavku.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vrací poskytovatele ve fondu, informaci, zda každý z nich může odpovídat, každý klíč podle jeho nápovědy a poskytovatele, pro které lze klíč přidat. Přidání klíče vyžaduje tělo ve formátu JSON se dvěma povinnými poli a jedním volitelným:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Klíč putuje po síti pouze jednou. Služba nexus-auth jej zašifruje a předá informaci routeru, přičemž odpověď obsahuje pouze nápovědu. Odpovědí je 201 s ID nového klíče a jeho řádkem: „Added. The Google Gemini key ••••7f2q is in the organisation's AI pool, and the AI Provider Router can route to it now.“ (Přidáno. Klíč Google Gemini ••••7f2q je ve fondu AI organizace a AI Provider Router na něj nyní může směrovat.) Štítek může mít nejvýše 100 znaků a klíč je jeden řetězec bez mezer o délce nejvýše 4 096 znaků. Jakékoli jiné pole v těle nebo pole uvádějící organizaci či osobu je odmítnuto.
Stažení klíče vyžaduje prázdné tělo. Router okamžitě přestane na klíč směrovat a služba nexus-auth si jej ponechá označený jako stažený, takže jeho historie zůstane zachována. Nic ve fondu se nikdy nemaže.
| Odmítnutí | HTTP | Kdy |
|---|---|---|
VALIDATION_FAILED |
400 | Tělo, které není {provider, api_key, label?}, neznámý poskytovatel nebo vlastní předplatné uživatele nabídnuté jako klíč organizace |
AUTHORITY_EXCEEDED |
403 | Volající není vlastníkem ani administrátorem organizace |
RECORD_NOT_FOUND |
404 | Ve fondu organizace není žádný klíč s tímto ID |
TRANSITION_NOT_PERMITTED |
409 | Klíč je již stažen |
TENANT_NOT_A_PARAMETER |
403 | Tělo nebo dotaz uváděl organizaci |
Stavy klíčů
Každý klíč ve fondu se nachází v jednom ze šesti stavů. Na chat odpovídá pouze klíč, který je právě používán.
| Stav | Co to znamená |
|---|---|
in_use |
Klíč odpovídá, a to až do data vypršení platnosti, pokud nějaké má. |
resting |
Směrovač jej po selháních odstavil do stanoveného času. Požadavky mezitím směřují na další klíč. |
exhausted |
Vyčerpal svůj limit u poskytovatele. |
invalid |
Poskytovatel jej již nepřijímá. |
expired |
Vypršela mu platnost k datu exspirace. |
withdrawn |
Správce jej stáhl. Zůstává uveden v historii. |
Klíč, který selže, odpočívá 60 sekund. Po 5 selháních v řadě jej směrovač vypne, přesune jeho podíl na ostatní klíče a zaznamená upozornění PROVIDER_KEY_SWITCHED_OFF. Nikdo není odmítnut, dokud může odpovědět jiný klíč.
Když poskytovatel nemá žádný používaný klíč, fond uvede důvod („Žádný používaný klíč: 1 stažen, 1 s vypršelou platností“). Když žádný poskytovatel ve fondu nemá používaný klíč, chat je odmítnut s chybou NO_PROVIDER_FOR_ROLE (422) a řešením: vlastník nebo správce přidá klíč organizace. Jedná se o stav konfigurace, který zůstává na obrazovce, dokud jej někdo neopraví.
Role, zásady a přání
Směrovač uvažuje v rolích. Každý požadavek je určen pro jednu z pěti: default, fast, reasoning, code nebo long_context. Každý model je také zařazen do úrovně frontier, standard nebo fast, přičemž vyšší úroveň je upřednostňována, pokud to role umožňuje. Organizace rozhoduje, který poskytovatel obsluhuje jednotlivé role (její přiřazení rolí) a v jakém pořadí se má přepínat při selhání poskytovatele (její žebříček zásad směrování). Správci nastavují obojí v ústředně AI. Služba nexus-auth je také poskytuje na /auth/org/<organisation-id>/settings/ai-provider/role-assignments a /auth/org/<organisation-id>/settings/ai-provider/routing-policy pro klíč správce s oprávněním ai_provider:manage.
Volající mohou vyjádřit svá přání. Řádek dovednosti může obsahovat preferovaného poskytovatele a preferovaný model a navíc profil schopností. Směrovač s každým z nich zachází jinak:
- Preferovaný poskytovatel je respektován pouze tehdy, když má organizace tohoto poskytovatele povoleného a má pro něj klíč. V opačném případě směrovač použije náhradu.
- Preferovaný model je respektován, pokud je v katalogu daného poskytovatele a odpovídá profilu.
- Profil schopností je filtr, který nikdy sám nevybírá. Může vyžadovat minimální kontextové okno, použití nástrojů, počítačové vidění, vektorová zobrazení (embeddings), dlouhý kontext nebo umístění dat (data residency). Cokoli, co těmto požadavkům nevyhoví, není způsobilé.
Směrovač vybírá v pevně daném pořadí. Pokud může, vyhoví přání, poté zkusí jiný model stejného poskytovatele, následně přiřazení role a jakéhokoli jiného poskytovatele s klíčem, jehož katalog vyhovuje. Pokud byl zadán profil a žádný katalog mu neodpovídá, je požadavek odmítnut s chybou MODEL_CAPABILITY_UNAVAILABLE (422). Pokud není nic přiřazeno a nic neodpovídá, výsledkem je NO_PROVIDER_FOR_ROLE (422). Neexistuje žádný výchozí model poslední záchrany. Role, kterou jste nenakonfigurovali, hlasitě selže a směrovač vlastními slovy uvede, co je třeba nastavit.
Umístění dat je jediné omezení, které nelze obejít náhradou. Profil s eu_only je obsloužen poskytovatelem z EU, nebo je odmítnut. Harrow nastavuje tento zámek pro celou organizaci a ústředna vykreslí druhého hostovaného poskytovatele, který sídlí v regionu USA, jako vypnutého.
Dovednost může také připnout jeden konkrétní model, pokud jej potřebuje ke svému fungování. I v takovém případě pro něj směrovač použije vlastní klíč organizace, a pokud žádný neexistuje, nic neodpoví. Volající nemůže nikdy přimět Nexus použít poskytovatele, kterého organizace nenakonfigurovala.
Jakmile je poskytovatel vybrán, přepnutí při selhání (failover) je samostatnou záležitostí. Chyba 429, 5xx nebo selhání sítě posune požadavek po žebříčku dolů k dalšímu poskytovateli. Chyba 400, 401, 403 nebo 404 proces okamžitě zastaví, protože přihlašovací údaje a tvary požadavků se mezi poskytovateli nepřenášejí a opakovaný pokus by jen vyčerpal kvótu se stejným neúspěšným výsledkem.
Chcete-li zjistit, co by směrovač vybral, ještě než kdokoli položí otázku, přečtěte GET /api/ai/routing-policy/effective na bráně pomocí vlastního tokenu uživatele. Odpovědí bude model pro přihlášenou organizaci, nebo slovní odmítnutí směrovače, pokud žádný model neexistuje, přičemž se modelu neodešle žádný požadavek.
Sledování směrovače
Pruh s údaji ve spodní části každé stránky ukazuje používaný model („Model: lokální“). V edici Enterprise vykresluje stránka Ústředna AI, živě provoz směrovače v reálném čase: požadavky od asistenta, úloh a aplikací plynoucí přes role k poskytovatelům a klíčům, klíč v 60sekundovém odpočinku vykreslený šedě, vypnutý klíč vykreslený červeně a záložní přepnutí na hostovaného poskytovatele, když je lokální model zaneprázdněn. Vedle toku zobrazuje graf zatížení jednotlivých poskytovatelů, počet požadavků za sekundu a dobu čekání. Tomás ji nechává otevřenou během prvního týdne po jakékoli změně zásad směrování, protože chybné přiřazení role se tam během několika minut projeví jako provoz směřující tam, kam nikdo nezamýšlel.
V edici Community má stránka Modely AI tlačítko Otestovat každý model, které zkontroluje každý nakonfigurovaný model a označí, zda odpovídá. Je to nejrychlejší způsob, jak ověřit, že nový klíč funguje, než se na něj kdokoli spolehne.
Vektorové reprezentace (embeddings)
Vyhledávání a znalostní graf převádějí text na vektory. Ve výchozím nastavení to instalace provádí pomocí modelu pro vektorová zobrazení (embedding), který běží uvnitř clusteru na procesoru, takže žádný text neopouští lokalitu za účelem vytvoření vektorů a organizace pro to nepotřebuje žádný klíč. Použití hostovaného poskytovatele pro vektorová zobrazení je volbou organizace; proces pak prochází stejným fondem a podléhá stejným pravidlům.
O vektorová zobrazení nebo změnu pořadí (reranking) mohou směrovač požádat pouze tři služby: nexus-graphrag, nexus-skills-engine a nexus-workflows. GraphRAG vytváří vektorová zobrazení jménem organizace, které obsah patří, s nastavením této organizace, a nedrží žádný vlastní klíč poskytovatele. Když organizace změní svůj model pro vektorová zobrazení, služba nexus-workflows spustí úlohu opětovného vytvoření vektorů pro úložiště dané organizace.
Osobní přihlašovací údaje zůstávají osobní
Některé přihlašovací údaje patří jedné osobě. Běžným případem je předplatné Claude Max, ke kterému je uživatel přihlášen přes svůj vlastní účet. Takový přihlašovací údaj není nikdy klíčem organizace: fond jej odmítne s chybou VALIDATION_FAILED, nikdy není uveden v tabulce klíčů organizace a nezobrazuje se na obrazovce žádné jiné osoby.
Klíče modelů se také nikdy nedostanou nikam jinam. Stránka Klíče externích dat, která uchovává klíče pro externí datové zdroje, odmítne cokoli, co vypadá jako klíč modelu AI, s chybou AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Pokud čtečka souborů najde klíče modelů uvnitř dokumentu nebo konfigurace, kam nepatří, zaznamená CREDENTIALS_IN_WRONG_PLACE a správce je odstraní a nahradí.
Skripty, REST a MCP
Nexus má tři veřejné hostitele. V organizaci Harrow jsou to console.harrow.example pro konzoli, api.harrow.example pro bránu a auth.harrow.example pro přihlašování. Skripty a nástroje používají druhého a třetího z nich.
Klíče pro skripty
Skript se přihlašuje pomocí klíče vytvořeného na stránce Nastavení, Klíče pro skripty. Každý klíč má název, dosah (například „Pouze spustit sčítání dronů na dvoře“), osobu, která jej vytvořila, a datum ukončení platnosti; organizace může uzamknout maximální dobu životnosti, kterou klíč může mít. Tajný kód (secret) se zobrazí pouze jednou při vytvoření klíče. Zkopírujte jej do úložiště tajných kódů skriptu, protože Nexus uchovává pouze jeho poslední čtyři znaky. Klíč se stahuje, nikdy se neodstraňuje: okamžitě přestane fungovat a zůstane uveden v seznamu se všemi voláními, která provedl. Rotace přidělí klíči nový tajný kód a ten se opět zobrazí pouze jednou.
Každý klíč má svou vlastní stránku s počtem volání za den, voláními podle služeb a protokolem aktivit obsahujícím čas, adresu, službu a výsledek. Volání mimo dosah klíče je odmítnuto a zobrazí se v protokolu.
Služba nexus-auth poskytuje stejné klíče přihlášené osobě na adrese https://auth.harrow.example/api-keys: umožňuje vytvoření a výpis, a následně čtení, změnu, odvolání nebo rotaci jednoho klíče podle jeho id.
REST přes bránu
Volání REST posílejte na https://api.harrow.example s Authorization: Bearer <token-or-key>. Každý klíč musí patřit nějaké organizaci. Klíč, který žádné nepatří, je odmítnut s chybou TOKEN_ORG_MISSING (403) každou službou, která kontroluje klíče prostřednictvím nexus-auth.
Volajícímu, který se dotazuje příliš často, je vrácena odpověď 429 s RATE_LIMITED, hlavičkou Retry-After a limitem a časovým oknem v těle zprávy. Počkejte počet sekund, který je v odpovědi uveden. V edici Enterprise nastavují správci limity na klíč, na aplikaci a na jednotku na stránce Nastavení, Limity frekvence požadavků (viz kapitola 2.16, Zabezpečení a sítě).
MCP pro nástroje AI
Nástroje AI, které komunikují pomocí protokolu Model Context Protocol, se připojují k https://api.harrow.example/mcp. Přihlašují se přes server OAuth 2.1 (OAuth je otevřený standard pro delegovanou autorizaci) na adrese https://auth.harrow.example, který podporuje registraci klienta samotným nástrojem, takže nástroj jako Claude Code nebo Cursor se sám zaregistruje a otevře prohlížeč uživatele pro přihlášení. Připojení pak jedná jménem této jedné osoby, s jejími právy a ničím víc. Přihlášená osoba si může stáhnout připravenou konfiguraci pro nástroj příkazového řádku z https://auth.harrow.example/api/v1/mcp/cli-config.
Volání nástrojů, která potřebují model, procházejí přes směrovač jako cokoli jiného, a to pod organizací dané osoby.




