Zum Inhalt

LLM Gateway

Basiert auf LiteLLM

Das KIVA LLM-Gateway ist ein Fork von LiteLLM, einem Open-Source Proxy für Large Language Models. Der Fork fokussiert sich auf die Anforderungen der öffentlichen Verwaltung mit erweiterten Compliance- und Sicherheitsfunktionen.

Überblick

Das LLM Gateway ist die zentrale Schnittstelle der KIVA-Plattform für den Zugriff auf Large Language Models. Es abstrahiert verschiedene LLM-Provider hinter einer einheitlichen OpenAI-kompatiblen API und bietet umfassende Management-, Monitoring- und Governance-Funktionen.

Hauptfunktionen

Das Gateway ermöglicht:

  • Einheitliche API für alle LLM-Provider (OpenAI, Azure, Anthropic, lokale Modelle)
  • Service Account Management mit API-Key-Verwaltung und Authentifizierung
  • Token-basiertes Rate Limiting und Quotas pro Team/Nutzer
  • Vollständiges Audit Logging für Compliance und Nachvollziehbarkeit
  • Monitoring & Observability mit Prometheus-Metriken und OpenTelemetry-Support
  • Load Balancing und Fallback zwischen mehreren Modellen
  • Cost Tracking zur Kostenkontrolle und Budgetverwaltung

Kernfunktionen

1. Multi-Provider Support

Das Gateway unterstützt zahlreiche LLM-Provider über eine einheitliche Schnittstelle:

Cloud Provider:

  • OpenAI (GPT-5, GPT-4o, o4)
  • Anthropic (Claude 4.5 Sonnet, Claude 4.1 Opus)
  • Azure OpenAI Service
  • Google Vertex AI (Gemini)
  • AWS Bedrock

Lokale/Open-Source:

  • vLLM (empfohlen für KIVA)
  • Ollama
  • LM Studio
  • Text Generation Inference (TGI)

Einheitliche API für alle: 

# Gleicher Code funktioniert für alle Provider
from openai import OpenAI

client = OpenAI(
    base_url="https://llm-gateway.example.com/v1",
    api_key="sk-your-api-key"
)

# GPT-4, Claude oder lokales Llama - gleiche API
response = client.chat.completions.create(
    model="gpt-4o",  # oder: "claude-3-5-sonnet", "llama-3-70b"
    messages=[{"role": "user", "content": "Hallo KIVA!"}]
)

2. Service Account Management

Verwaltung von API-Keys und Berechtigungen über das Web-Dashboard oder Admin-API:

Features:

  • Team-basierte API-Keys mit individuellen Limits
  • Granulare Berechtigungen (Modellzugriff, Rate Limits)
  • Key-Rotation und automatische Ablauf-Zeiten
  • Budget-Limits pro Key
  • Tag-basierte Kostenallokation

Beispiel: Service Account erstellen 

curl -X POST https://llm-gateway.example.com/key/generate \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "verwaltung-team-1",
    "max_budget": 1000.0,
    "models": ["gpt-4o", "llama-3-70b"],
    "tpm_limit": 10000,
    "rpm_limit": 100,
    "metadata": {
      "department": "Bürgerservice",
      "cost_center": "CC-12345"
    }
  }'

3. Rate Limiting & Quotas

Mehrschichtiges Rate Limiting für faire Ressourcennutzung:

Limit-Typen:

  • TPM (Tokens per Minute): Token-basierte Limits
  • RPM (Requests per Minute): Anfragen pro Minute
  • Budget: Kosten-basierte Limits in EUR
  • Max Parallel Requests: Gleichzeitige Anfragen

Konfiguration: 

# Per Team/Key
rate_limit:
  tpm_limit: 100000
  rpm_limit: 1000
  max_parallel_requests: 50

budget:
  max_budget: 5000.0  # EUR
  budget_duration: "30d"
  reset: true

4. Audit Logging & Compliance

Vollständige Protokollierung aller Anfragen für Compliance und Nachvollziehbarkeit:

Gespeicherte Informationen:

  • Timestamp und Nutzer/Team-ID
  • Verwendetes Modell und Token-Verbrauch
  • Request/Response (optional konfigurierbar)
  • Kosten und Latenz
  • Fehler und Status-Codes

Datenschutz:

  • Konfigurierbare PII-Maskierung
  • Opt-out für sensitive Anfragen
  • DSGVO-konforme Datenspeicherung

5. Load Balancing & Fallback

Intelligente Lastverteilung und Ausfallsicherheit:

Features:

  • Round-robin Load Balancing über mehrere Deployments
  • Automatischer Fallback bei Ausfällen
  • Circuit Breaker Pattern
  • Retry-Logic mit Exponential Backoff

Beispiel-Konfiguration: 

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: ${OPENAI_API_KEY}

  # Fallback zu Azure
  - model_name: gpt-4o  # Gleicher Name!
    litellm_params:
      model: azure/gpt-4
      api_key: ${AZURE_API_KEY}
      api_base: ${AZURE_BASE_URL}

6. Monitoring & Observability

Umfassende Einblicke in Nutzung und Performance:

Metriken (Prometheus):

  • Request-Rate und Latenz
  • Token-Verbrauch pro Modell/Team
  • Error-Rate und Fehlertypen
  • Kosten-Tracking
  • Queue-Längen und Throughput

Tracing (OpenTelemetry):

  • End-to-End Request-Tracing
  • Verteilte Traces über Komponenten
  • Integration mit Jaeger/Zipkin

Web-Dashboard:

  • Echtzeit-Monitoring
  • Nutzungsstatistiken
  • Kostenübersicht
  • Team-Management

Installation & Setup

Voraussetzungen

  • Python 3.10, 3.11 oder 3.12
  • Poetry für Dependency Management
  • PostgreSQL 15+ (lokal oder via Docker)
  • Node.js 18+ & npm (für Web-Dashboard)
  • Docker & Docker Compose (optional, empfohlen)

Lokale Entwicklungsumgebung

1. Repository klonen

git clone https://gitlab.opencode.de/baden-wuerttemberg/innenministerium/kiva/kiva-llm-gateway.git
cd kiva-llm-gateway

2. Python Environment einrichten

# Virtual Environment erstellen
python -m venv .venv

# Aktivieren
source .venv/bin/activate  # Linux/macOS
# oder: .venv\Scripts\activate  # Windows

# Dependencies installieren
make install-proxy-dev

3. Konfiguration

Erstellen Sie eine .env Datei:

cp .env.example .env

Minimale Konfiguration:

# Master Key für Admin-Zugriff
LITELLM_MASTER_KEY=sk-your-secure-master-key-here

# Datenbank
DATABASE_URL=postgresql://user:password@localhost:5432/kiva-llm-proxy
STORE_MODEL_IN_DB=True

# LLM Provider (Beispiel: lokales vLLM)
OPENAI_API_KEY=sk-dummy-key
OPENAI_BASE_URL=http://localhost:8000

4. Prisma Client generieren

poetry run prisma generate

5. Datenbank starten & Schema migrieren

Option A: Docker Compose (empfohlen) 

# PostgreSQL Container starten
docker-compose up -d db

# Schema erstellen
poetry run prisma migrate dev --name init

Option B: Lokale PostgreSQL 

# Datenbank erstellen
createdb litellm

# Schema migrieren
poetry run prisma migrate dev --name init

5. Services starten

Backend: 

poetry run uvicorn litellm.proxy.proxy_server:app \
  --host localhost \
  --port 4000 \
  --reload

Web-Dashboard: 

cd ui/litellm-dashboard
npm install
npm run dev

Zugriff:

  • Backend API: http://localhost:4000
  • Web Dashboard: http://localhost:3000
  • API Docs: http://localhost:4000/docs

Verifizierung

# Gateway Health Check
curl http://localhost:4000/health

# Modell-Liste abrufen
curl http://localhost:4000/v1/models \
  -H "Authorization: Bearer sk-your-secure-master-key-here"

# Test Chat Completion
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secure-master-key-here" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hallo KIVA!"}]
  }'

Produktivbetrieb

Für Produktivdeployments auf Kubernetes siehe Installation & Setup.

Weiterführende Dokumentation

  • Sicherheit: Best Practices für Produktivbetrieb

Für Integrationsmöglichkeiten siehe den Abschnitt Integration.