Technische Beschreibung¶

Dieser Abschnitt beschreibt den technischen Aufbau des Myra AI Workspace, die Verarbeitung einer Anfrage, die Schnittstellen und die Fehlerbehandlung.

Funktionaler Überblick¶

Der Myra AI Workspace ist ein mandantenfähiger Reverse-Proxy zwischen den Anwendungen des Kunden und den Programmierschnittstellen der KI-Anbieter. Der Aufbau kennt zwei Ebenen. Ein Mandant ist das übergeordnete Konto, in der Regel ein Unternehmen, eine Anwendung oder ein Team. Ein Gateway ist eine benannte Installation innerhalb eines Mandanten, zum Beispiel production oder staging. Jedes Gateway führt eigene Anbieterschlüssel, eigene Authentifizierungs-Token, eigene Ratenbegrenzungen und eigene Routing-Regeln, vollständig getrennt von jedem anderen Gateway.

Jede Inferenzanfrage trägt Mandant und Gateway im URL-Pfad, entweder als /v1/{Mandant}/{Gateway}/compat/chat/completions für den vereinheitlichten Endpunkt oder als /v1/{Mandant}/{Gateway}/{Anbieter}/chat/completions für den anbietereigenen Weg. Das Gateway löst beide Kennungen je Anfrage auf und lädt die zugehörige Gateway-Konfiguration. Eine Änderung an der Konfiguration wirkt innerhalb weniger Sekunden.

Jede Anfrage durchläuft drei Phasen. Jede Phase bricht entweder ab und beantwortet die Anfrage sofort, oder sie reicht die Anfrage an den nächsten Schritt weiter:

■ Zugriffsphase: Läuft, bevor der Rumpf der Anfrage gelesen wird, sodass eine Abweisung wenig kostet. Die Zugriffsphase umfasst die Authentifizierung gegen den gespeicherten Token-Hashwert, die Ratenbegrenzung des Gateways und des Tokens über das gleitende Zeitfenster, die Prüfung gegen die Budgets des Tokens, des Mandanten und des Gateways sowie die IP-Zulassungsliste.
■ Inhaltsphase: Läuft mit dem vollständigen Rumpf. Die Inhaltsphase umfasst die Abfrage des Zwischenspeichers, die zweistufige Guardrail-Kette auf der ausgehenden Anfrage, die Auswertung der Routing-Regeln, den Aufruf des Anbieters, die Guardrail-Kette auf der eingehenden Antwort, die Kostenberechnung und die Ablage im Zwischenspeicher.
■ Protokollphase: Läuft, nachdem die Antwort gesendet wurde, sodass ein Fehler an dieser Stelle den Aufrufer nicht mehr betrifft. Sie schreibt den strukturierten Protokolleintrag und die Messwerte.

Die Routing-Regeln werden in der eingerichteten Reihenfolge ausgewertet, und die erste zutreffende Regel gewinnt. Eine Regel überschreibt Anbieter, Modell und Ersatzkette. Trifft keine Regel zu, gelten Anbieter und Modell der Anfrage selbst:

■ Auf einem anbietereigenen Endpunkt stammen beide aus dem URL-Pfad.
■ Auf dem vereinheitlichten Endpunkt leitet das Gateway den Anbieter aus dem Feld model über den Präfix des Modellnamens ab und weicht andernfalls auf OpenRouter aus.

Antwortet der Anbieter mit einem Fehler der Klasse 5xx, wiederholt das Gateway den Aufruf bis zu retry_count Mal und arbeitet anschließend die Ersatzkette ab. Die Vorgabe 2 ergibt drei Versuche insgesamt. Antworten der Klasse 4xx gehen ohne Wiederholung unmittelbar an den Aufrufer zurück.

Systemarchitektur¶

Das Gateway läuft als ein einzelner OpenResty-Prozess, also nginx mit LuaJIT, der die vollständige Richtlinienkette im Worker selbst trägt. Es gibt keinen Sidecar und keinen zusätzlichen Weg über das Netz für Authentifizierung, Ratenbegrenzung, Zwischenspeicher oder die Guardrails der Stufe 1. Das Produkt besteht aus den folgenden Bestandteilen:

■ Gateway-Prozess (nginx/OpenResty, Lua): Der mandantenfähige Reverse-Proxy. Der Reverse-Proxy hängt sich in die drei nginx-Phasen Zugriff, Inhalt und Protokoll ein und durchläuft eine geordnete Middleware-Kette, in der jeder Schritt die Anfrage entweder sofort beantwortet oder ein Kontextobjekt je Anfrage für den nächsten Schritt anreichert. Ein Prozess bedient viele Mandanten und Gateways bei harter Trennung untereinander.
■ Weboberfläche (React, TypeScript, Vite): Die Oberfläche für die tägliche Arbeit und für die Verwaltung. Die Navigationsleiste kennt zwei Zustände. Im Arbeitsbereich trägt die Navigationsleiste die Gruppe Workspace mit den Einträgen Chat, Projekte, Workflows, Agenten und Playground sowie die Gruppe Übersicht mit den Einträgen Übersicht und Letzte Chats. Über das Benutzermenü wechselt die Navigationsleiste in einen der vier Bereiche Einstellungen, Benutzerverwaltung, Konto und Meine Zugriffsrechte. Die Navigationsleiste zeigt dann ausschließlich die Einträge dieses Bereichs und den Eintrag Zurück zum Workspace. Welche Einträge erscheinen, hängt von den Berechtigungen des Kontos ab. Die Navigationsleiste blendet Einträge lediglich aus. Jede Ansicht und jede Schnittstelle prüft die Berechtigung auf dem Server erneut.
■ Konfigurations- und Protokolldatenbank (MySQL/MariaDB): Hält die dauerhafte Konfiguration sowie das strukturierte Anfrageprotokoll. Die Konfiguration umfasst Mandanten, Gateways, Anbieterschlüssel, Authentifizierungs-Token, Routing-Regeln, Nutzende, Rollen und Modellpreise. Die Konfiguration eines Gateways wird aus der Datenbank gelesen und für die Dauer von config_cache_ttl im gemeinsamen Speicher gehalten, sodass eine Anfrage keinen eigenen Datenbankzugriff benötigt.
■ Gemeinsamer Speicher (nginx Shared Dictionaries): Der heiße Zustand des Prozesses: Antwort-Zwischenspeicher, Zähler des gleitenden Zeitfensters der Ratenbegrenzung, Gateway-Konfiguration, entschlüsselte Anbieterschlüssel mit einer Lebensdauer von 60 Sekunden und die Zähler für die Messwerte.
■ myrapod (LiteLLM-Proxy vor dem GPU-Cluster von Myra): Bedient jede Anfrage an den Anbieter myra und beherbergt die Dienste der Stufe 2: den Presidio-Analysator und -Anonymisierer für die Erkennung personenbezogener Daten, die Llama-Guard-3-Klassifikation für Prompt Guard und die Dokumentwandlung. Jedes von Myra betriebene Modell ist ausschließlich über diesen Weg erreichbar.
■ Dateispeicher: Ein Speicher je Eigentümer auf dem Host, in den Anhänge, Wissensdateien, Uploads und erzeugte Bilder aus der Datenbank ausgelagert werden.
■ Begleitende Dienste: Ein SMTP-Relay für die Einmalcodes der Anmeldung, die Push-Dienste für die mobilen Anwendungen, eine Suchschnittstelle für die Websuche, ein OpenTelemetry-Collector für das Tracing und das SIEM-Ziel des Kunden.
■ Vorgelagerte Anbieter: Die angebundenen KI-Anbieter, die während der Inhaltsphase über HTTPS aufgerufen werden.

Die Produktivumgebung ist unter den folgenden Adressen erreichbar:

Adresse	Bedeutung
`ai.myra.eu`	Weboberfläche
`ai-api.myra.eu`	Inferenzschnittstelle unter `/v1/`
`ai-api-admin.myra.eu`	Verwaltungsschnittstelle unter `/admin/`
`ai-docs.myra.eu`	Dokumentation

Technische Details¶

Schnittstellen. Das Produkt stellt zwei getrennte Schnittstellen bereit. Die Inferenzschnittstelle unter /v1/ trägt die Anfragen an die KI-Anbieter und authentifiziert über ein undurchsichtiges Token je Gateway. Die Verwaltungsschnittstelle unter /admin/v1/ verwaltet Mandanten, Gateways, Nutzende, Tokens, Anbieterschlüssel, Routing-Regeln, Modellpreise, Statistiken, Protokolle und Guardrail-Ereignisse und authentifiziert über eine Browsersitzung im signierten JWT-Cookie aig_admin.

Authentifizierung. Das Gateway nimmt ein Token in drei Kopfzeilen an und verwendet die erste vorhandene:

■ x-aig-token
■ Authorization: Bearer <Token>
■ x-api-key zur Verträglichkeit mit dem SDK von Anthropic

Durch diese Reihenfolge tritt das Gateway ohne Änderung an einer bestehenden Anwendung an die Stelle der Schnittstelle von OpenAI. Ein Token wird vor der Ablage mit SHA-256 gehasht, gilt für genau ein Gateway und trägt wahlweise ein Ablaufdatum, eine eigene Ratenbegrenzung, ein eigenes Budget und eine Bindung an ein Konto. Die Rolle dieses Kontos bestimmt, was das Token darf.

Rollen. Die Plattform kennt die Rollen admin, tenant_admin, ki_manager, member, finance, viewer und demouser. Die Rolle wird während der Authentifizierung durchgesetzt, bevor der Rumpf der Anfrage gelesen wird. Das Löschen eines Kontos macht jedes Authentifizierungs-Token dieses Kontos sofort ungültig.

Anmeldung. Die Weboberfläche authentifiziert ohne Kennwort über einen sechsstelligen Einmalcode per E-Mail. Nach fünf misslungenen Versuchen je Adresse antwortet die Prüfung mit 429. Ein Mandant richtet zusätzlich OpenID Connect oder SAML 2.0 ein. Beide Verfahren melden ausschließlich bestehende Konten an und legen nie eines an. Eine vorübergehende Störung macht eine Sitzung nie ungültig und führt nie zu einer Anmeldung. Die Prüfung scheitert stets zur sicheren Seite mit 503.

Kopfzeilen der Anfrage. Die Protokollierung der Nutzdaten wird je Gateway mit log_payloads: false und je Anfrage mit x-aig-collect-log-payload: false abgeschaltet. Die Kopfzeile x-aig-collect-log: false verwirft den Protokolleintrag vollständig. Die Kopfzeile x-aig-byok-alias wählt einen bestimmten Anbieterschlüssel. Bei einem unbekannten Alias weicht das Gateway nie auf den vorgegebenen Schlüssel aus.

Kopfzeilen der Antwort. Eine Antwort aus dem Zwischenspeicher trägt X-AIG-Cache: HIT. Eine Fehlerantwort trägt den dauerhaften Code in X-AIG-Error. Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining. Eine Abweisung trägt zusätzlich Retry-After.

Datentrennung. Der URL-Präfix {Mandant}/{Gateway} wird je Anfrage aufgelöst, und eine unbekannte Kennung wird mit 404 tenant_not_found beantwortet. Der gesamte innere Zustand ist je Mandant und Gateway getrennt benannt, alle Daten sind auf der Speicherebene streng dem besitzenden Mandanten zugeordnet, und Ratenbegrenzungen und Budgets werden je Gateway geführt und nie geteilt.

Streaming. Mit "stream": true reicht das Gateway die Abschnitte der Antwort weiter, sobald sie eintreffen. Tritt ein Fehler auf, nachdem der Strom geöffnet wurde, lässt sich der HTTP-Status nicht mehr ändern. Die Antwort trägt auf der Leitung den Status 200, und der Fehler kommt als Ereignis im Strom an. Eine Anwendung mit Streaming wertet daher beide Wege aus: den HTTP-Status vor dem ersten Ereignis und das Feld error in den Ereignissen danach. Das Protokoll hält den tatsächlichen Status fest, nicht den Status 200 der Leitung.

Kryptografie und Schlüsselhaltung. Ein Anbieterschlüssel wird mit AES-256-CBC verschlüsselt und als Paar aus Initialisierungsvektor und Geheimtext abgelegt. Der Schlüssel wird bei der ersten Verwendung entschlüsselt, 60 Sekunden im gemeinsamen Speicher gehalten und dann in den Aufruf des Anbieters eingesetzt. Der Hauptschlüssel stammt aus der Umgebung des Prozesses. Die Sitzung der Weboberfläche ist ein zustandsloses JSON Web Token mit HMAC-SHA256, gehalten im Cookie aig_admin mit den Merkmalen HttpOnly und SameSite=Strict und einer Lebensdauer von acht Stunden in der Vorgabe.

Ratenbegrenzung und Budget. Die Ratenbegrenzung ist ein gleitendes Zeitfenster über zwei Zähler. Der Zähler des vorangegangenen Fensters wird mit dem noch nicht verstrichenen Anteil des laufenden Fensters gewichtet und zum Zähler des laufenden Fensters addiert. Kosten werden als Mikro-Dollar geführt, vor der Anfrage gegen die Grenze des Tokens, des Mandanten und des Gateways geprüft und nach der Antwort des Anbieters erhöht.

Rollen und Berechtigungen. Eine Rolle ist eine Menge von Berechtigungen, und jede Prüfung wertet eine Berechtigung aus statt eines Rollennamens. Die sieben genannten Rollen sind Systemrollen, die Myra pflegt. Ein Mandant legt zusätzlich eigene Rollen aus derselben Menge von Berechtigungen an. Eine Rolle eines Mandanten trägt nie eine Berechtigung der Plattformklasse, was das Datenmodell selbst durchsetzt. Single Sign-on vergibt die vorgegebene Rolle member und setzt nie die Plattformrolle. Gruppen des Identitätsanbieters werden über eine Zulassungsliste je Mandant auf innere Gruppen abgebildet.

Antwort-Zwischenspeicher. Neben der genauen Übereinstimmung über eine Prüfsumme aus Anbieter, Modell und dem kanonischen Rumpf der Anfrage schaltet ein Gateway wahlweise einen semantischen Zwischenspeicher ein. Bei einem Fehlschlag wird der Prompt eingebettet und mit den abgelegten Einbettungen desselben Gateways und desselben Modells verglichen. Oberhalb der eingerichteten Ähnlichkeit, in der Vorgabe 0,95, wird die abgelegte Antwort mit den Kopfzeilen X-AIG-Cache: SEMANTIC_HIT und X-AIG-Similarity zurückgegeben. Im Strom übertragene Antworten werden nicht semantisch zwischengespeichert.

Fehlerbehandlung¶

Jede Fehlerantwort des Gateways trägt einen HTTP-Status und einen dauerhaften Fehlercode. Der Code benennt die Ursache genau und ändert sich nicht, wenn der Wortlaut der Meldung überarbeitet wird. Eine aufrufende Anwendung wertet daher error.code aus und nie den Text error.message. Der Code steht sowohl im JSON-Rumpf als auch in der Kopfzeile X-AIG-Error. Die Weboberfläche zeigt zu jedem Code eine übersetzte Meldung. Die Fehler gliedern sich in vier Gruppen.

Grenzen und Abrechnung¶

Fehler	Ursache und Abhilfe
`429 rate_limited`	Die Grenze des gleitenden Zeitfensters ist erschöpft. Warten Sie die in `Retry-After` genannte Dauer ab und erhöhen Sie die Grenze des Gateways oder des Tokens.
`429 quota_exceeded`	Ein Budget des Tokens, des Mandanten oder des Gateways ist erreicht. Erhöhen Sie das Budget oder setzen Sie den Zähler zurück.
`402 subscription_inactive`	Das Abonnement ist nicht aktiv. Aktivieren Sie das Abonnement erneut oder hinterlegen Sie eine gültige Zahlungsweise.
`402 trial_expired`	Der Testzeitraum ist abgelaufen. Aktivieren Sie das Abonnement erneut oder hinterlegen Sie eine gültige Zahlungsweise.

Zugriff und Sicherheit¶

Fehler	Ursache und Abhilfe
`401 unauthorized`	Das Token fehlt, ist unbekannt, abgelaufen, widerrufen oder gilt für ein anderes Gateway. Der Wortlaut der Meldung unterscheidet die drei Fälle.
`403 forbidden`	Die Quelladresse steht nicht in der IP-Zulassungsliste, oder die Rolle lässt die Aktion nicht zu.
`403 data_residency_blocked`	Das gewählte Modell liefe über einen Anbieter oder eine Region außerhalb der EU. Wählen Sie ein EU-Modell oder ein Gateway ohne scharfgeschalteten Boden.
`400 guardrail_blocked`	Ein Guardrail hat den Inhalt der Antwort abgewiesen. Formulieren Sie den Inhalt um oder passen Sie bei einem Fehlalarm das Muster oder die Aktion des Guardrails an. Eine Sperre in der Anfragephase trägt einen anderen Status, siehe den Abschnitt Gestalt einer gesperrten Antwort.
`403 processing_restricted`	Die Verarbeitung ist für das Konto eingeschränkt, zum Beispiel nach einem Antrag nach Artikel 18 DSGVO.

Anfrage und Modell¶

Fehler	Ursache und Abhilfe
`400 invalid_request`	Der Rumpf ist kein gültiges JSON, oder ein Pflichtfeld fehlt.
`400 context_length_exceeded`	Der Prompt überschreitet das Kontextfenster. Kürzen Sie die Eingabe, schalten Sie die Verdichtung des Kontextes ein oder wechseln Sie auf ein Modell mit größerem Kontextfenster.
`413 context_overflow`	Der Prompt überschreitet das Kontextfenster. Die Antwort trägt `estimated`, `limit`, `suggested_model` und `can_compact_now`.
`413 request_too_large`	Kein Anbieter hat die Anfrage angenommen, meist wegen übergroßer Anhänge.
`400 model_capability_mismatch`	Das gewählte Modell unterstützt die angeforderten Werkzeuge nicht.
`400 web_search_not_supported`	Das gewählte Modell unterstützt die Websuche nicht.
`404 tenant_not_found`	Der Mandant oder das Gateway im Pfad besteht nicht.

Anbieter und Betrieb¶

Fehler	Ursache und Abhilfe
`502 provider_error`	Der Anbieter hat nach jedem Wiederholungsversuch mit einem Serverfehler geantwortet.
`502 all_providers_failed`	Jeder Anbieter der Routing-Kette ist ausgefallen. Prüfen Sie das Anfrageprotokoll, die Statusseiten der Anbieter und die Schlüssel jedes Anbieters der Kette.
`424 provider_key_missing`	Für den aufgelösten Anbieter ist auf diesem Gateway kein Schlüssel hinterlegt.
`504 request_timeout`	Die Anfrage wurde nicht innerhalb des Zeitbudgets fertig. Vereinfachen Sie die Anfrage oder schalten Sie die Websuche ab.
`503 service_starting`	Das Gateway startet. Wiederholen Sie die Anfrage nach der in `Retry-After` genannten Dauer.
`500 configuration_error`	Von Myra Security zu beheben. Der Support benötigt die Anfrage-ID und die Gateway-Kennung aus dem Anfrageprotokoll.
`500 internal_error`	Von Myra Security zu beheben. Der Support benötigt die Anfrage-ID und die Gateway-Kennung aus dem Anfrageprotokoll.

Circuit Breaker. Ist der Circuit Breaker eingeschaltet und erreicht ein Anbieter die eingerichtete Fehlerschwelle innerhalb des eingerichteten Zeitfensters, überspringt das Gateway diesen Anbieter und geht zum nächsten Eintrag der Kette. Nach der Abkühlzeit lässt der Circuit Breaker eine Probeanfrage zu. Erst ein Versuch, der tatsächlich eine Antwort liefert, schließt ihn. Der Zustand je Anbieter wird mit GET /admin/v1/gateways/{id}/circuit-breaker gelesen.

Gestalt einer gesperrten Antwort¶

Ein Guardrail sperrt in zwei Phasen, und die Antwort fällt je Phase verschieden aus:

■ Anfragephase: Das Gateway gibt eine erzeugte Antwort im Drahtformat der Anfrage zurück, mit dem Status 200 und dem Ablehnungstext an der Stelle der Modellantwort. Die aufrufende Anwendung erhält also eine gültig geformte Antwort statt eines Fehlers. Bei "stream": true kommt die Sperre als Ereignis aig_status: "guardrail_blocked" im Strom an.
■ Antwortphase: Ein Aufruf über die Inferenzschnittstelle erhält den Fehler 400 guardrail_blocked.

Eine aufrufende Anwendung wertet daher beide Wege aus.

Guardrail-Dienst nicht erreichbar¶

Ist ein Dienst der Stufe 2 nicht erreichbar, entscheidet die Einstellung Fail-open des betroffenen Guardrails:

■ Eingeschaltet: Die Anfrage läuft ungeprüft durch. Das ist die Vorgabe.
■ Abgeschaltet: Die Anfrage wird gesperrt.

Das Anfrageprotokoll zeigt, ob bei einer durchgelaufenen Anfrage ein Urteil der Stufe 2 fehlt.

Anwendungsfälle¶

Eine öffentliche Einrichtung und ein regulierter Konzern stehen vor demselben Widerspruch. Die leistungsfähigsten Modelle stammen von OpenAI, Anthropic, Google Gemini und AWS Bedrock. Diese Modelle werden von Unternehmen aus den Vereinigten Staaten betrieben, unterliegen dem dortigen Recht und stehen in dortigen Rechenzentren. Schützenswerte Angaben unmittelbar an diese Anbieter zu senden, wirft Fragen nach der DSGVO und nach den Vorgaben der jeweiligen Branche auf:

■ Wer greift auf diese Angaben zu?
■ Nach welchem Recht?
■ Unter wessen Aufsicht?

Zugleich beginnen Teams, denen KI verwehrt wird, eigenständig Verbraucherdienste zu nutzen. Das ist genau der Abfluss, den die Organisation verhindern wollte.

Der Myra AI Workspace stellt die zertifizierte EU-Infrastruktur von Myra Security zwischen die Organisation und jeden dieser Anbieter. Alle Anfragen und Antworten laufen über das Netz von Myra, und ein Anbieter aus den Vereinigten Staaten erhält stets nur das, was die Richtlinien des Kunden ausdrücklich zulassen. Die Dienste, die den Inhalt prüfen und personenbezogene Daten erkennen, laufen innerhalb dieser zertifizierten Infrastruktur, sodass schützenswerte Inhalte innerhalb der EU geprüft, maskiert oder durch Platzhalter ersetzt werden.

Drei typische Fälle veranschaulichen den Einsatz des Produkts:

■ Die Rechtsabteilung eines Versicherers arbeitet mit Verträgen, die personenbezogene Daten enthalten. Die Abteilung nutzt ein Projekt der Zugriffsstufe PII-Schutz erforderlich. Personenbezogene Daten werden durch umkehrbare Platzhalter ersetzt, bevor die Anfrage die EU verlässt, und in der Antwort wieder eingesetzt. Das Budget der Abteilung ist auf 2.000 USD im Monat begrenzt.
■ Ein Entwicklungsteam bindet einen Chatbot für Kunden an. Die Anwendung meldet sich mit einem eigenen Token am Gateway production an und bekommt einen Anbieterschlüssel nie zu sehen. Das Token trägt ein Budget von 50 USD im Monat und eine eigene Ratenbegrenzung. Eine Ersatzkette und der Circuit Breaker halten den Chatbot antwortfähig, wenn ein Anbieter ausfällt.
■ Die Regelkonformitätsbeauftragte beantwortet nach einem Sicherheitsvorfall die Frage einer Prüfstelle: Was hat das Modell erhalten, und was hat es geantwortet? Das Anfrageprotokoll hält die Identität, das Routing, die Zahl der Token, die Kosten, die Laufzeit je Phase, das Urteil jedes Guardrails und die Residenzzone jedes Abschnitts fest, durch eine Kette aus Prüfsummen gegen Änderung versiegelt.