Version 1.0.0-alpha.1aktuell
Kapitel 2.14
KI-Anbieter und -Modelle
Wie der Provider Router für künstliche Intelligenz (KI) ein Modell aus dem eigenen Schlüsselpool der Organisation auswählt und wie Skripte und KI-Werkzeuge von außen auf Nexus zugreifen.
Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

Die Harrow Port Authority betreibt zwei Installationen. Diejenige in ihrem physisch isolierten (Air-Gapped) Betriebsnetzwerk (Kapitel 2.10, Air-Gapped-Installation) nutzt überhaupt keinen gehosteten Anbieter. Auf der vernetzten Unternehmensinstallation, die in diesem Kapitel begleitet wird, werden die meisten Fragen von einem Modell beantwortet, das auf zwei Grafikprozessor-Knoten (GPU) im eigenen Serverraum des Hafens läuft. Ein von Harrow bezahlter Schlüssel für Google Gemini fängt die Spitzen ab, wenn das lokale Modell ausgelastet ist, und Aoife Brennan hat den Datenverkehr der künstlichen Intelligenz (KI) der Organisation auf die EU beschränkt. Niemand bei Harrow hat ein Modell innerhalb eines Dienstes oder eines Plug-ins konfiguriert. Man hat einer einzigen Komponente mitgeteilt, was Harrow besitzt, und diese Komponente entscheidet über jeden Aufruf.
Dieses Kapitel behandelt diese Komponente, den AI Provider Router, der in Teil 1 und in der Konsole als KI-Schaltzentrale bezeichnet wird, sowie den Schlüsselpool, auf den er zugreift. Es schließt mit den Wegen, über die Skripte und KI-Tools Nexus von außen erreichen: Schlüssel für Skripte, die REST-Programmierschnittstelle (Representational State Transfer Application Programming Interface, API) und das Model Context Protocol (MCP).
Der AI Provider Router
Der Router läuft innerhalb des Gateways, nexus-gateway. Er ist der einzige Dienst, der die Modell-Zugangsdaten einer Organisation verwaltet, und er trifft die endgültige Entscheidung darüber, welcher Anbieter und welches Modell jede Anfrage beantwortet. Jeder andere Teil von Nexus fragt ihn an. Ein Workflow-Schritt gibt an, was er sich wünscht, und der Router entscheidet.
Nur wenige Dienste dürfen anfragen, und jede Liste ist durch das Chart festgelegt:
| Was angefragt wird | Wer anfragen darf |
|---|---|
Eine Vervollständigung (/internal/ai/chat und ihr Stream) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Tool-Aufrufe und die anderen internen KI-Routen | nexus-orchestrator, nexus-workflows |
| Embeddings und Reranking | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Jede interne Route prüft nacheinander zwei Dinge: den internen Dienstschlüssel des Aufrufers und die Identität des Aufrufers anhand der obigen Liste. Eine Anfrage ohne den Schlüssel wird mit MISSING_SERVICE_KEY (401) abgelehnt, ein falscher Schlüssel mit INVALID_SERVICE_KEY (403), eine Anfrage, die nicht angibt, wer aufruft, mit MISSING_CALLER_IDENTITY (403) und ein Aufrufer außerhalb der Liste mit UNAUTHORIZED_CALLER (403). Keiner dieser Fälle wird erneut versucht, da es sich bei keinem um einen vorübergehenden Fehler handelt.
Apps und Plug-ins erscheinen niemals auf dieser Liste. Ein Plug-in deklariert seine Wünsche bei den Skills, die es registriert, und leitet sie über UNO, die Workflow-Engine, weiter. Der Orchestrator fragt dann im Namen des Plug-ins beim Router an. Aus diesem Grund kann ein offengelegtes Plug-in-Geheimnis zwar als dieses Plug-in agieren, aber das Modellbudget von niemandem verbrauchen.
Der Schlüsselpool der Organisation
Modellschlüssel gehören der Organisation. Jede Organisation bringt ihr eigenes Anbieterkonto mit und bezahlt ihre eigene Rechnung, und der Schlüssel liegt im Pool der Organisation, verschlüsselt in nexus-auth. Es gibt keinen gemeinsam genutzten Plattformschlüssel hinter einer Organisation, sodass keine Organisation jemals das Budget einer anderen verbraucht. Der Preis dieser Regel ist klar: Eine Organisation ohne Schlüssel in ihrem Pool erhält keine KI-Antworten. Der Assistent zeigt MODEL_NOT_CONNECTED (503) an und gibt an, wer einen Schlüssel hinterlegen kann.
Für vier Anbieter kann dem Pool ein Schlüssel hinzugefügt werden:
| Anbieter-ID | Angezeigt als |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Ein eigener Modellserver
Eine Organisation kann auch jeden selbst betriebenen Server nutzen, der die OpenAI-kompatible API spricht, wie etwa das Modell auf den GPU-Knoten von Harrow. Das Installationsprogramm benennt ihn in der values-Datei:
# 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 verweist den OpenAI-kompatiblen Adapter des Gateways auf Ihren Server. Bei einer Installation erreicht der Steckplatz scaleway des Pools diesen Server, sodass der Schlüssel, den Sie für scaleway hinzufügen, der Schlüssel ist, den Ihr eigener Server erwartet.
ai.installationHosts listet Hostnamen auf, die sich innerhalb der Installation befinden, neben der eigenen Service-Domäne des Releases und den drei öffentlichen Hosts. Jeder Eintrag ist ein Hostname, ein .suffix, eine IP-Adresse oder ein IPv4-CIDR-Bereich (Classless Inter-Domain Routing). Der Router verwendet die Liste, um einen Aufruf, der am Standort verbleibt, von einem zu unterscheiden, der ihn verlässt; genau das meldet die Prüfung „Nichts verlässt diesen Standort“ auf der Seite „Ein Modell auf eigener Hardware verbinden“.
Die Netzwerkrichtlinie ist ebenso wichtig wie der Router. Der Namespace verweigert standardmäßig jeglichen ausgehenden Datenverkehr (Egress), sodass das Gateway einen Modellserver außerhalb des Namespaces nur erreichen kann, wenn dessen Bereich in networkPolicy.externalEgressCIDRs eingetragen ist. Dasselbe gilt für einen gehosteten Anbieter: Wenn Harrow möchte, dass sein Gemini-Schlüssel antwortet, müssen die Adressbereiche des Anbieters ebenfalls dort aufgeführt sein, andernfalls verlässt der Aufruf niemals den Cluster. Kapitel 2.16, Sicherheit und Netzwerk, behandelt die Richtlinie im Detail.
Hinzufügen und Entfernen von Schlüsseln
Eigentümer und Administratoren einer Organisation verwalten deren Pool. Andere Personen können die Schlüssel weder sehen noch ändern, und eine entsprechende Anfrage von ihnen wird mit AUTHORITY_EXCEEDED abgelehnt.
In der Konsole
In der Enterprise-Edition wird der Pool in der KI-Schaltzentrale unter den Engines verwaltet. In der Community-Edition werden dieselben Schlüssel unter „Einstellungen“, „KI-Modelle“ verwaltet. Diese Seite ist der Basis-Router, über den Sie Schlüssel und eine lokale Modelladresse hinzufügen und auswählen, welches Modell welche Aufgabe übernimmt. Beide zeigen jeden Schlüssel mit der Angabe an, wer ihn wann festgelegt hat („Festgelegt von Aoife, 3. Sept.“), sowie mit einem maskierten Hinweis auf seine höchstens letzten vier Zeichen, wie etwa ••••7f2q. Der Schlüssel selbst wird nach dem Hinzufügen nie wieder angezeigt.
Über die BFF-API
Das Backend-for-Frontend (BFF) der Konsole stellt drei Routen für den Pool bereit. Rufen Sie diese mit dem persönlichen Zugriffstoken einer Person auf: Die Organisation wird aus dem Token ermittelt, niemals aus der Anfrage.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET gibt die Anbieter im Pool zurück, ob jeder einzelne antworten kann, jeden Schlüssel anhand seines Hinweises sowie die Anbieter, für die ein Schlüssel hinzugefügt werden darf. Das Hinzufügen eines Schlüssels erfordert einen JSON-Body mit zwei Pflichtfeldern und einem optionalen Feld:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Der Schlüssel wird nur einmal übertragen. nexus-auth verschlüsselt ihn und informiert den Router, und die Antwort enthält lediglich den Hinweis. Die Antwort lautet 201 mit der ID des neuen Schlüssels und seiner Zeile: „Hinzugefügt. Der Google Gemini-Schlüssel ••••7f2q befindet sich im KI-Pool der Organisation, und der AI Provider Router kann nun dorthin weiterleiten.“ Eine Bezeichnung darf höchstens 100 Zeichen lang sein, und ein Schlüssel ist eine einzelne Zeichenfolge ohne Leerzeichen mit höchstens 4.096 Zeichen. Jedes andere Feld im Body oder ein Feld, das eine Organisation oder eine Person benennt, wird abgelehnt.
Das Zurückziehen erfordert einen leeren Body. Der Router stellt die Weiterleitung an den Schlüssel sofort ein, und nexus-auth behält ihn als zurückgezogen markiert bei, sodass sein Verlauf erhalten bleibt. Nichts im Pool wird jemals gelöscht.
| Ablehnung | HTTP | Wann |
|---|---|---|
VALIDATION_FAILED |
400 | Ein Body, der nicht {provider, api_key, label?} ist, ein unbekannter Anbieter oder ein persönliches Abonnement einer Person, das als Organisationsschlüssel angeboten wird |
AUTHORITY_EXCEEDED |
403 | Der Aufrufer ist weder Eigentümer noch Administrator der Organisation |
RECORD_NOT_FOUND |
404 | Im Pool der Organisation befindet sich kein Schlüssel mit dieser ID |
TRANSITION_NOT_PERMITTED |
409 | Der Schlüssel ist bereits zurückgezogen |
TENANT_NOT_A_PARAMETER |
403 | Der Body oder die Abfrage hat eine Organisation benannt |
Schlüsselstatus
Jeder Schlüssel im Pool befindet sich in einem von sechs Zuständen. Nur ein aktiver Schlüssel (in use) beantwortet einen Chat.
| Zustand | Bedeutung |
|---|---|
in_use |
Der Schlüssel antwortet, und zwar bis zu seinem Ablaufdatum, sofern er eines hat. |
resting |
Der Router hat ihn nach Fehlern bis zu einem festgelegten Zeitpunkt pausiert. Anfragen gehen in der Zwischenzeit an den nächsten Schlüssel. |
exhausted |
Er hat sein Kontingent beim Anbieter ausgeschöpft. |
invalid |
Der Anbieter akzeptiert ihn nicht mehr. |
expired |
Er ist an seinem Ablaufdatum verfallen. |
withdrawn |
Ein Administrator hat ihn zurückgezogen. Er bleibt als Verlaufseintrag aufgelistet. |
Ein Schlüssel, der fehlschlägt, pausiert für 60 Sekunden. Nach 5 Fehlern in Folge schaltet der Router ihn ab, verteilt seinen Anteil auf die anderen Schlüssel und zeichnet den Hinweis PROVIDER_KEY_SWITCHED_OFF auf. Niemand wird abgewiesen, solange ein anderer Schlüssel antworten kann.
Wenn ein Anbieter keinen aktiven Schlüssel hat, nennt der Pool den Grund („Kein Schlüssel aktiv: 1 zurückgezogen, 1 verfallen“). Wenn kein Anbieter im Pool einen aktiven Schlüssel hat, wird ein Chat mit NO_PROVIDER_FOR_ROLE (422) und der Abhilfemaßnahme abgelehnt: Ein Eigentümer oder Administrator fügt einen Organisationsschlüssel hinzu. Das ist ein Konfigurationszustand, und er bleibt auf dem Bildschirm bestehen, bis jemand ihn behebt.
Rollen, Richtlinien und Präferenzen
Der Router denkt in Rollen. Jede Anfrage gilt für eine von fünf Rollen: default, fast, reasoning, code oder long_context. Jedes Modell befindet sich zudem in einer Stufe (Tier), frontier, standard oder fast, und eine höhere Stufe wird bevorzugt, wenn die Rolle dies zulässt. Die Organisation entscheidet, welcher Anbieter welche Rolle bedient (ihre Rollenzuweisungen) und in welcher Reihenfolge bei einem Ausfall eines Anbieters ausgewichen wird (ihre Routing-Richtlinien-Leiter). Administratoren legen beides in der KI-Schaltzentrale fest. nexus-auth stellt sie außerdem unter /auth/org/<organisation-id>/settings/ai-provider/role-assignments und /auth/org/<organisation-id>/settings/ai-provider/routing-policy für einen Admin-Schlüssel bereit, der ai_provider:manage besitzt.
Aufrufer können angeben, was sie sich wünschen. Eine Skill-Zeile kann einen bevorzugten Anbieter und ein bevorzugtes Modell sowie ein Fähigkeitsprofil enthalten. Der Router behandelt jedes dieser Elemente unterschiedlich:
- Ein bevorzugter Anbieter wird nur berücksichtigt, wenn die Organisation diesen Anbieter aktiviert hat und über einen Schlüssel für ihn verfügt. Andernfalls nimmt der Router eine Ersetzung vor.
- Ein bevorzugtes Modell wird berücksichtigt, wenn es im Katalog dieses Anbieters enthalten ist und zum Profil passt.
- Ein Fähigkeitsprofil ist ein Filter, der niemals selbst auswählt. Es kann ein minimales Kontextfenster, Tool-Nutzung, Bildverarbeitung (Vision), Embeddings, langen Kontext oder einen Datenstandort (Data Residency) verlangen. Alles, was diese Anforderungen nicht erfüllt, kommt nicht infrage.
Der Router wählt in einer festen Reihenfolge aus. Er berücksichtigt den Wunsch, wenn er kann, versucht dann ein anderes Modell desselben Anbieters, danach die Rollenzuweisung und schließlich jeden anderen Anbieter mit einem Schlüssel, dessen Katalog passt. Wenn ein Profil angegeben wurde und kein Katalog dazu passt, wird die Anfrage mit MODEL_CAPABILITY_UNAVAILABLE (422) abgelehnt. Wenn nichts zugewiesen ist und nichts passt, lautet der Fehler NO_PROVIDER_FOR_ROLE (422). Es gibt kein Standardmodell als letzten Ausweg. Eine Rolle, die Sie nicht konfiguriert haben, schlägt deutlich sichtbar fehl, wobei der Router in eigenen Worten angibt, was eingestellt werden muss.
Der Datenstandort ist die einzige Einschränkung, die nicht durch eine Ersetzung umgangen werden kann. Ein Profil mit eu_only wird von einem EU-Anbieter bedient oder abgelehnt. Harrow legt diese Sperre für die gesamte Organisation fest, und die Schaltzentrale stellt den zweiten gehosteten Anbieter, der sich in einer US-Region befindet, als ausgeschaltet dar.
Ein Skill kann auch ein exaktes Modell fest vorschreiben (pinnen), wenn der Skill genau dieses Modell benötigt, um zu funktionieren. Selbst dann verwendet der Router dafür den eigenen Schlüssel der Organisation, und ohne einen solchen antwortet nichts. Ein Aufrufer kann Nexus niemals dazu bringen, einen Anbieter zu verwenden, den die Organisation nicht konfiguriert hat.
Sobald ein Anbieter ausgewählt ist, ist das Failover eine separate Angelegenheit. Ein 429-, ein 5xx- oder ein Netzwerkfehler schiebt die Anfrage auf der Leiter weiter nach unten zum nächsten Anbieter. Ein 400-, 401-, 403- oder 404-Fehler stoppt sofort, da Zugangsdaten und Anfrageformate nicht über Anbieter hinweg übertragbar sind und ein erneuter Versuch nur Kontingent verbrennen würde, um denselben Fehler erneut zu erreichen.
Um zu sehen, was der Router auswählen würde, bevor jemand eine Frage stellt, lesen Sie GET /api/ai/routing-policy/effective auf dem Gateway mit dem persönlichen Token einer Person aus. Es gibt das Modell für die angemeldete Organisation zurück oder die Ablehnung des Routers in Worten, wenn keines vorhanden ist, und sendet dabei keine Anfrage an ein Modell.
Überwachung des Routers
Die Zahlenleiste am unteren Rand jeder Seite zeigt das verwendete Modell an („Modell: lokal“). In der Enterprise-Edition zeichnet „Die KI-Schaltzentrale, live“ den Datenverkehr des Routers in Echtzeit auf: Anfragen vom Assistenten, von Jobs und Apps, die über Rollen zu Anbietern und Schlüsseln fließen, wobei ein Schlüssel in seiner 60-sekündigen Pause grau dargestellt wird, ein abgeschalteter Schlüssel rot und ein Fallback auf den gehosteten Anbieter, wenn das lokale Modell ausgelastet ist. Neben dem Datenfluss werden die Last pro Anbieter, die Anfragen pro Sekunde und die Wartezeit in Diagrammen dargestellt. Tomás lässt diese Ansicht in der ersten Woche nach jeder Änderung an der Routing-Richtlinie geöffnet, da eine falsche Rollenzuweisung dort innerhalb von Minuten als Datenverkehr sichtbar wird, der dorthin fließt, wo ihn niemand haben wollte.
In der Community-Edition verfügt die Seite „KI-Modelle“ über eine Schaltfläche „Jedes Modell testen“, die jedes konfigurierte Modell prüft und markiert, ob es antwortet. Das ist der schnellste Weg, um zu beweisen, dass ein neuer Schlüssel funktioniert, bevor sich jemand darauf verlässt.
Embeddings
Die Suche und der Wissensgraph wandeln Text in Vektoren um. Standardmäßig erledigt die Installation dies mit einem Embedding-Modell, das innerhalb des Clusters auf dem Prozessor läuft, sodass kein Text den Standort verlässt, um eingebettet zu werden, und eine Organisation dafür keinen Schlüssel benötigt. Die Nutzung eines gehosteten Anbieters für Embeddings ist eine bewusste Entscheidung einer Organisation; dies läuft dann über denselben Pool und nach denselben Regeln.
Nur drei Dienste dürfen den Router nach Embeddings oder Reranking fragen: nexus-graphrag, nexus-skills-engine und nexus-workflows. GraphRAG erstellt Embeddings im Namen der Organisation, der die Inhalte gehören, und zwar mit den Einstellungen dieser Organisation, und besitzt keinen eigenen Anbieterschlüssel. Wenn eine Organisation ihr Embedding-Modell ändert, führt nexus-workflows den Job zur Neuerstellung der Embeddings für die Speicher dieser Organisation aus.
Persönliche Zugangsdaten bleiben persönlich
Einige Zugangsdaten gehören einer einzelnen Person. Ein Claude Max-Abonnement, bei dem die Anmeldung über das eigene Konto dieser Person erfolgt, ist der gängige Fall. Solche Zugangsdaten sind niemals ein Organisationsschlüssel: Der Pool lehnt sie mit VALIDATION_FAILED ab, sie werden niemals in der Schlüsseltabelle der Organisation aufgeführt, und kein Bildschirm einer anderen Person zeigt sie an.
Modellschlüssel gelangen auch niemals an einen anderen Ort. Die Seite „Schlüssel für externe Daten“, die Schlüssel für externe Datenquellen verwaltet, lehnt alles, was wie ein KI-Modellschlüssel aussieht, mit AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422) ab. Wenn der Dateileser Modellschlüssel innerhalb eines Dokuments oder einer Konfiguration findet, wo sie nicht hingehören, zeichnet er CREDENTIALS_IN_WRONG_PLACE auf, und ein Administrator entfernt und ersetzt sie.
Skripte, REST und MCP
Nexus verfügt über drei öffentliche Hosts. Bei Harrow sind dies console.harrow.example für die Konsole, api.harrow.example für das Gateway und auth.harrow.example für die Anmeldung. Skripte und Tools verwenden den zweiten und dritten.
Schlüssel für Skripte
Ein Skript meldet sich mit einem Schlüssel an, der unter „Einstellungen“, „Schlüssel für Skripte“ erstellt wurde. Jeder Schlüssel hat einen Namen, eine Reichweite (zum Beispiel „Nur Drohnen-Hofzählung starten“), die Person, die ihn erstellt hat, und ein Enddatum; eine Organisation kann die maximale Lebensdauer festlegen, die ein Schlüssel haben darf. Das Geheimnis wird einmalig angezeigt, wenn der Schlüssel erstellt wird. Kopieren Sie es in den Geheimnisspeicher des Skripts, da Nexus nur die letzten vier Zeichen aufbewahrt. Ein Schlüssel wird zurückgezogen, niemals entfernt: Er stoppt sofort und bleibt mit jedem Aufruf, den er getätigt hat, aufgelistet. Beim Rotieren erhält der Schlüssel ein neues Geheimnis, das einmalig angezeigt wird.
Jeder Schlüssel hat seine eigene Seite mit Aufrufen pro Tag, Aufrufen nach Dienst und einem Aktivitätsprotokoll mit Zeit, Adresse, Dienst und Ergebnis. Ein Aufruf außerhalb der Reichweite des Schlüssels wird abgelehnt und im Protokoll angezeigt.
nexus-auth stellt einer angemeldeten Person dieselben Schlüssel unter https://auth.harrow.example/api-keys bereit: zum Erstellen und Auflisten sowie anschließend zum Lesen, Ändern, Widerrufen oder Rotieren eines Schlüssels anhand seiner ID.
REST über das Gateway
Senden Sie REST-Aufrufe an https://api.harrow.example mit Authorization: Bearer <token-or-key>. Jeder Schlüssel muss zu einer Organisation gehören. Ein Schlüssel ohne Organisation wird von jedem Dienst, der Schlüssel über nexus-auth prüft, mit TOKEN_ORG_MISSING (403) abgelehnt.
Ein Aufrufer, der zu häufig anfragt, erhält als Antwort 429 mit RATE_LIMITED, einen Retry-After-Header sowie das Limit und das Zeitfenster im Body. Warten Sie die dort angegebene Anzahl von Sekunden ab. In der Enterprise-Edition legen Administratoren unter „Einstellungen“, „Ratenbegrenzungen“ Limits pro Schlüssel, pro App und pro Einheit fest (siehe Kapitel 2.16, Sicherheit und Netzwerk).
MCP für KI-Tools
KI-Tools, die das Model Context Protocol sprechen, verbinden sich mit https://api.harrow.example/mcp. Sie melden sich über den OAuth 2.1-Server (OAuth ist der offene Standard für delegierte Autorisierung) unter https://auth.harrow.example an, der die Client-Registrierung durch das Tool selbst unterstützt, sodass sich ein Tool wie Claude Code oder Cursor selbst registriert und den Browser der Person zur Anmeldung öffnet. Die Verbindung handelt dann für diese eine Person, mit den Rechten dieser Person und nicht mehr. Eine angemeldete Person kann unter https://auth.harrow.example/api/v1/mcp/cli-config eine fertige Konfiguration für ein Befehlszeilen-Tool abrufen.
Tool-Aufrufe, die ein Modell benötigen, laufen wie alles andere über den Router, und zwar unter der Organisation der jeweiligen Person.




