Funktionen¶

Der Funktionsumfang gliedert sich in Hardware- und GPU-Verwaltung, Modell-Verwaltung, Routing und API-Bereitstellung, Schlüssel-Management, qualitätssichernde Funktionen sowie Monitoring und Energie-Tracking. Die Bedienung erfolgt über eine tabbasierte Web-Oberfläche.

Anwendungsszenarien¶

Chat-, Vision- und Embedding-Modelle für Forschungsgruppen. Auf einem Server mit mehreren NVIDIA-GPUs werden parallel ein größeres Chat-Modell (über mehrere GPUs per Tensor-Parallel) und ein kleineres Embedding-Modell (auf einer MIG-Instanz) bereitgestellt. Mitglieder der Gruppe greifen über Virtual Keys mit individuellen Rate-Limits und Modell-Einschränkungen zu.
Spracherkennung und Sprachsynthese als interne Dienste. Speech-to-Text- und Text-to-Speech-Modelle laufen auf MIG-Instanzen oder kleineren GPUs und werden über die direkten Endpunkte /models/<n>/v1/* an interne Anwendungen — etwa Transkriptions-Tools oder Vorlese-Funktionen — angebunden.
Bildgenerierung als interner Dienst. Bildgenerierungs-Modelle werden auf einer dedizierten GPU bereitgestellt und über einen Direkt-Routen-Key an eine interne Anwendung gebunden, ohne dass diese am Virtual-Key-System teilnimmt.
Multi-Tenant-Betrieb mit Verbrauchsabrechnung. Mehrere Arbeitsgruppen nutzen denselben Server. Pro Gruppe oder Person wird ein Virtual Key mit RPM-Limit, Modell-Einschränkungen und Spend-Tracking erzeugt; die Verbrauchsdaten lassen sich über die LiteLLM-Management-API auswerten.
Bereitstellung im Hochschulnetz ohne Schlüsselverteilung. In firewall-geschützten Netzen werden ausgewählte Chat-, Vision- und Embedding-Modelle über die Open-Access-Route /open/<n>/v1/* mit beliebigem Bearer-Token erreichbar gemacht. Die Zugriffskontrolle erfolgt durch die vorgelagerte Firewall; ein Kill-Switch deaktiviert alle Open-Access-Routen sofort.
Performance-Vergleich vor Modell-Auswahl. Vor der Übernahme eines Modells in den Regelbetrieb werden TTFT-Perzentile (P50/P95/P99), Gesamtlatenz und Throughput direkt am vLLM-Container gemessen — ohne Proxy-Overhead. Mehrere Modelle lassen sich nacheinander unter denselben Bedingungen testen.

Auf einen Blick¶

Automatische Erkennung aller NVIDIA-GPUs (Anzahl, Typ, VRAM, NVLink, MIG-Status) und Persistenz der MIG-Konfiguration über Reboots hinweg.
Sieben Modell-Typen mit typspezifischen Defaults für Docker-Image, Argumente, Routing und Endpunkte.
Zwei API-Routing-Pfade (LiteLLM-vermittelt und direkt) hinter einem gemeinsamen HTTPS-Reverse-Proxy.
Dreistufiges API-Key-System (Master, Direkt-Routen-Keys, Virtual Keys) mit getrennten Geltungsbereichen.
Replicas mit transparentem Load Balancing und Live-Statusanzeige (z.B. 4/4, 3/4 bei Teilausfall).
Zweisprachige Oberfläche (Deutsch/Englisch) mit Umschalter in der Kopfzeile.
Pro Modell wählbare vLLM-Version — mehrere Versionslinien laufen parallel auf derselben Maschine, neue Modelle starten unabhängig vom Bestand.
LiteLLM-Aliase: ein Modell unter mehreren API-Namen mit fest hinterlegten Parameter-Bündeln (Sampling, Reasoning-Stufen).
Integriertes Prometheus- und Grafana-Monitoring sowie ein eigener Energie-Monitor mit CSV-Export.
Wiederherstellung des vorherigen Betriebszustands nach Reboot über einen einzigen Bedienschritt.

Hardware- und GPU-Verwaltung¶

Beim Start werden alle NVIDIA-GPUs erkannt und in der Oberfläche aufgeführt — inklusive VRAM, NVLink- und NVSwitch-Verbindungen sowie MIG-Status. Heterogene Konstellationen (z.B. eine A100 neben mehreren H100) werden unterstützt. Über den MIG-Bereich lassen sich GPUs in isolierte Instanzen partitionieren (Profile von 1g.45gb bis 4g.180gb, bis zu sieben Instanzen pro GPU); kleine Modelle laufen auf MIG-Instanzen, große Modelle belegen ganze GPUs. Die MIG-Konfiguration wird in einer eigenen Datei persistiert und nach einem Reboot automatisch wiederhergestellt.

Ein integrierter GPU-Speicher-Kalkulator schätzt anhand von Parameteranzahl, Quantisierung, Kontextlänge und Architekturdetails den VRAM-Bedarf (Modellgewichte, KV-Cache, Aktivierungen, Overhead) und schlägt eine zur NVLink-Topologie passende Tensor-Parallel-Konstellation vor.

Modell-Verwaltung¶

Modelle werden über die Hugging-Face-ID hinzugefügt; Modell-Typ, GPU- bzw. MIG-Zuweisung, Quantisierung (auto, fp8, awq, gptq, bitsandbytes), maximale Kontextlänge sowie zusätzliche vLLM-Argumente und Umgebungsvariablen lassen sich pro Modell setzen. Jedes Modell läuft in einem eigenen Docker-Container; Container-Logs sind direkt aus der Oberfläche einsehbar. Optional lassen sich pro Modell ein eigenes Jinja2-Chat-Template, eine eigene vLLM- bzw. vLLM-Omni-Version, ein abweichendes Docker-Image und mehrere Replicas (1–8) konfigurieren. Modelle ohne eigene Versionsangabe folgen der global konfigurierten Version; damit lassen sich einzelne Modelle auf einer anderen vLLM-Linie betreiben als der übrige Bestand, und die Modell-Tabelle weist die jeweils wirksame Version aus. Bei Replicas > 1 erstellt LLM-Manager identische Container auf den zugewiesenen GPUs; die Validierung verlangt eine durch die Replica-Anzahl teilbare GPU-Anzahl.

Ein eingebauter Vorab-Download über die Hugging-Face-CLI lädt Modelle ohne GPU-Belegung in den lokalen Cache, sodass auch sehr große Modelle ausserhalb der eigentlichen Inbetriebnahme bereitgestellt werden können. Eine Cache-Übersicht zeigt heruntergeladene Modelle mit Größe und erlaubt selektives Bereinigen.

Konnektoren und externe Dienste¶

Hugging Face Hub — Bezugsquelle aller Modelle. Der Zugriff erfolgt über die offizielle Hugging-Face-CLI in einem temporären Container; ein Hugging-Face-Token kann für geschützte Modelle hinterlegt werden. Heruntergeladene Modelle liegen in einem geteilten Cache und werden in alle vLLM-Container als Volume eingebunden.
Docker Hub — Bezugsquelle für die offiziellen vLLM-Images, das PostgreSQL-Image, das Caddy-Image, das Prometheus-Image und das Grafana-Image.
GitHub Container Registry (ghcr.io) — Bezugsquelle für die LiteLLM-Images (Standard-Variante und Database-Variante mit Prisma).
ACME-Server (Let's Encrypt oder eigener Server) — Bezugsquelle für TLS-Zertifikate, die Caddy automatisch bezieht und verlängert. Endpunkt und E-Mail-Adresse sind konfigurierbar.

Routing und API-Bereitstellung¶

Zwei Routing-Pfade decken alle Modell-Typen ab. Chat-, Vision- und Embedding-Modelle werden unter /v1/chat/completions, /v1/embeddings und /v1/models über LiteLLM gebündelt; LiteLLM authentifiziert per Master-Key oder Virtual Key und routet intern an den jeweiligen vLLM-Container. Spracherkennungs-, Sprachsynthese- und Bildgenerierungs-Modelle werden direkt unter /models/<n>/v1/* an den vLLM-Container geleitet; Caddy entfernt das Präfix und prüft den Authorization-Header per Expression-Matcher gegen den Master-Key sowie alle eingetragenen Direkt-Routen-Keys.

Optional lässt sich pro chat-, vision- oder embedding-fähigem Modell der Open-Access-Modus aktivieren, der eine Route /open/<n>/v1/* mit beliebigem Bearer-Token freischaltet. Caddy ersetzt den Token durch den echten Master-Key und reicht die Anfrage an LiteLLM weiter. Ein Kill-Switch im HTTPS-Bereich deaktiviert alle Open-Access-Routen gleichzeitig.

Pro Modell lassen sich zusätzlich LiteLLM-Aliase definieren: weitere API-Modellnamen, an die feste Parameter-Bündel gebunden sind — Sampling-Werte sowie Template-Einstellungen wie Reasoning-Stufen über chat_template_kwargs. Clients wählen damit ein Verhalten statt einzelner Parameter (etwa modell, modell-low, modell-med, modell-xhigh). Aliase folgen dem Modellstatus, erben Replicas samt Load Balancing und erscheinen in der generierten LiteLLM-Konfiguration als eigenständige Einträge; ein Alias mit dem Namen des Modells ersetzt dessen Standard-Eintrag, sodass auch der Basisname ein definiertes Bündel trägt.

Die Modell-Tabelle zeigt pro Modell die vollständige Client-URL, sodass sich Endpunkte direkt entnehmen lassen.

API-Key-Management¶

Drei Schlüsseltypen mit unterschiedlichem Geltungsbereich:

Master-Key — gilt für alle Routen, wird in der Konfigurationsdatei abgelegt und sowohl von LiteLLM als auch von Caddy akzeptiert.
Direkt-Routen-Keys — beliebig viele Schlüssel, die ausschließlich für /models/<n>/v1/* gelten und für interne Anwendungen vorgesehen sind. Sie werden über einen Caddy-Expression-Matcher validiert.
Virtual Keys — über die LiteLLM-Management-API erzeugt, in PostgreSQL persistiert; zu jedem Schlüssel lassen sich RPM-Limits, Modell-Einschränkungen und Spend-Tracking hinterlegen. PostgreSQL wird beim ersten Virtual Key automatisch eingerichtet — kein eigener Konfigurationsschritt.

Qualitätssichernde Funktionen¶

Mehrere Mechanismen sichern Konsistenz, Robustheit und Nachvollziehbarkeit ab:

Validierung der Konfiguration. Replicas erfordern eine durch ihre Anzahl teilbare GPU-Anzahl; reservierte Modellnamen (open, models, v1) werden abgelehnt; MIG-Änderungen sind nur möglich, wenn keine Container auf der betroffenen GPU laufen; Alias-Namen werden über alle Modelle hinweg auf Eindeutigkeit geprüft. Beim Speichern warnen Regeln vor veralteten oder unbekannten vLLM-Argumenten.
Konsistenzprüfung. Ein eigener Bereich vergleicht laufende Container gegen die Konfiguration — Image und Version, Argumente, GPU-/MIG-Zuweisung und Umgebungsvariablen, bei Replicas je Replica einzeln — und weist Abweichungen typisiert aus. Soll- und Ist-Zustand entstehen aus derselben Aufbaulogik wie der Container-Start.
Selektive Aktualisierung. Ein Image- oder Versionswechsel startet nur die Container neu, deren Ziel-Image sich tatsächlich ändert; alle übrigen laufen unberührt weiter.
Sichere Container-Operationen. Der Stop-Vorgang von PostgreSQL entfernt nie den Container und nie das Volume; der Neustart von LiteLLM hält drei Sekunden zwischen Stop und Start ein und berührt PostgreSQL und Caddy nicht; Health-Checks gewähren bei Datenbank-Migrationen 60 Sekunden Anlaufzeit.
Persistenz und Wiederherstellung. Modell- und MIG-Konfiguration werden in lokalen Dateien gespeichert; ein Restore-Vorgang stellt nach einem Reboot in fünf Schritten den vorherigen Betriebszustand her — MIG-Partitionen, PostgreSQL, Modelle, LiteLLM, Caddy. Optional folgt der Monitoring-Stack als sechster Schritt.
Live-Logs und Live-Status. Container-Logs sind direkt aus der Oberfläche einsehbar; der Status laufender Modelle wird einschließlich Replica-Zähler in der Modell-Tabelle dargestellt.
Reproduzierbare Image-Auswahl. Die Image-Auswahl folgt einer festen Priorität (Override, Rezept-Image, vLLM-Omni-Image, Standard-vLLM-Image); Rezept-Images für Spracherkennungs-Modelle werden definiert reproduzierbar gebaut.
Benchmark-Funktion. Leistungsmessungen direkt am vLLM-Container — ohne Proxy-Overhead — mit konfigurierbarer Request-Anzahl, Concurrency und Prompt-Länge. Ausgewertet werden TTFT-Perzentile (P50/P95/P99), Gesamtlatenz, Tokens pro Sekunde und Requests pro Sekunde, jeweils nach einem Warmup-Request.

Monitoring und Energie-Tracking¶

Prometheus, Grafana und der NVIDIA DCGM Exporter werden als zusätzliche Container über die Oberfläche gestartet, gestoppt und konfiguriert. Prometheus-Scrape-Targets werden bei jedem Modell-Start oder -Stopp automatisch aktualisiert; die Retention ist zwischen 30 und 365 Tagen einstellbar. Grafana ist über https://host/grafana/ mit IP-Whitelist oder per SSH-Tunnel über Port 3000 erreichbar.

Vier vorkonfigurierte Dashboards stehen bereit: ein Übersichts-Dashboard (Token-Nutzung, Throughput, TTFT-P95, GPU-Power, KV-Cache, Requests pro Sekunde), ein Pro-Modell-Detail-Dashboard (Latenz-Perzentile, Queue-Wartezeit, Prefix-Cache-Hitrate), ein Vergleichs-Dashboard (Multi-Select über Modelle) und ein Energie- und GPU-Dashboard (GPU-Leistung, Temperatur, VRAM, Effizienz in Wh / 1000 Tokens). Labels model_name und model_type auf allen Metriken erlauben Aggregation über Modellwechsel hinweg; Modelle der Omni-Runtime (Sprachsynthese, Bildgenerierung) werden über ihre eigenen Metriknamen in die Dashboards einbezogen.

Unabhängig vom Grafana-Stack misst ein leichtgewichtiger Energie-Monitor pro GPU die Leistungsaufnahme (über nvidia-smi, alle zwei Sekunden) und ordnet sie Sitzungen zu. Sitzungs-Token-Zählung und Effizienzkennzahlen lassen sich als CSV exportieren.

Konfiguration und Betrieb¶

Die Konfiguration wird in einer einzigen JSON-Datei gehalten; LiteLLM-Konfiguration, Caddyfile, Prometheus-Konfiguration und Grafana-Provisioning werden aus dieser zentralen Datei generiert und beim Modell- oder Routen-Wechsel aktualisiert. Die Web-Oberfläche bindet ausschließlich auf 127.0.0.1:7860; der Zugriff erfolgt vom Server selbst oder über einen SSH-Tunnel. Externe Erreichbarkeit ist nur über Caddy auf Port 443 möglich; das Admin-UI lässt sich zusätzlich per IP-Whitelist absichern.

Import- und Exportformate¶

Modell-Import: Hugging-Face-IDs (öffentlich oder mit Token); Modelle werden in einen geteilten Hugging-Face-Cache geladen und von allen Containern als Volume eingebunden.
Konfigurations-Import und -Export: Backup und Wiederherstellung über das Konfigurationsverzeichnis (z.B. per tar); MIG-Konfiguration und Modell-Definitionen werden mitgesichert. Die zentrale config.json ist die einzige relevante Datei.
Energie-Export: CSV pro Sitzung mit Zeitstempel, GPU-Leistung, Token-Anzahl und Effizienz.
Generierte Konfigurationen: litellm-config.yaml, Caddyfile, prometheus.yml sowie Grafana-Dashboard- und -Datasource-JSONs werden bei jeder Änderung neu erzeugt und dienen gleichzeitig als nachvollziehbare Snapshots des Routings.