Feat: Fügt einen headroomlabs-Service für Prompt-Compression hinzu

2026-09-03 18:37:58 +02:00
parent 564f712e03
commit c911577d19
5 changed files with 151 additions and 2 deletions
@@ -29,6 +29,12 @@ GEMINI_API_KEY=
 GROQ_API_KEY=
 MISTRAL_API_KEY=

+# --- Headroom (Prompt-Kompression) ---
+# Standardmäßig läuft der Headroom-Proxy lokal im Docker-Compose-Netzwerk unter http://headroom:8787
+HEADROOM_API_BASE=http://headroom:8787
+# Optional: API-Key falls ein externer/Cloud Headroom-Service genutzt wird (für den lokalen Proxy leer lassen)
+HEADROOM_API_KEY=
+
 # --- Optional ---
 SLACK_WEBHOOK_URL=
 LANGFUSE_PUBLIC_KEY=
@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install build dependencies for native C++ extensions (e.g. hnswlib) and install headroom-ai
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && pip install --no-cache-dir "headroom-ai[all]" \
+    && apt-get purge -y build-essential \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+# Allow requests from other containers in the Docker network
+ENV HEADROOM_COMPRESS_ALLOW_REMOTE=1
+
+EXPOSE 8787
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=5 \
+    CMD python3 -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8787/readyz', timeout=5)" || exit 1
+
+ENTRYPOINT ["headroom", "proxy"]
+CMD ["--host", "0.0.0.0", "--port", "8787"]
@@ -1,3 +1,78 @@
-# litellm
+# LiteLLM Docker Compose Setup

-Eine einfache docker-compose um LiteLLM zu starten.
+Dieses Projekt stellt ein vollständiges Setup für den **LiteLLM Proxy** mit PostgreSQL-Datenbank (für UI/Key-/Team-Management), Redis (für Caching/Routing), Prometheus (Monitoring) und **Headroom Prompt-Kompression** bereit.
+
+---
+
+## Funktionen
+
+- **LiteLLM Database & Admin UI**: Verwaltung von Modellen, API-Keys, Benutzern, Teams und Guardrails über das Webinterface (`http://localhost:4000/ui`).
+- **Headroom Proxy Service**:
+  - Eigener Headroom Proxy-Container (`http://localhost:8787` bzw. intern `http://headroom:8787`).
+  - Verwendet das offizielle Multi-Arch-Image `ghcr.io/headroomlabs-ai/headroom:main` oder kann alternativ via `Dockerfile.headroom` lokal gebaut werden.
+  - Ermöglicht ML-basierte und strukturelle Prompt-Kompression direkt im lokalen Stack ohne Cloud-Abhängigkeit.
+- **Headroom Prompt-Kompression in LiteLLM**:
+  - Global standardmäßig für alle Anfragen aktiviert (`default_guardrails: ["headroom"]`).
+  - Als Guardrail (`headroom`) definiert, sodass es in der LiteLLM Web-UI sichtbar ist und spezifischen API-Keys, Teams oder Modellen zugewiesen oder angepasst werden kann.
+- **PostgreSQL**: Persistente Speicherung aller Modelle, Spend-Logs, Teams und Guardrail-Zuweisungen.
+- **Redis**: Caching von Antworten und Rate-Limiting.
+- **Prometheus**: Metriken-Erfassung unter `http://localhost:9090`.
+
+---
+
+## Schnellstart
+
+1. **Umgebungsvariablen konfigurieren**:
+   ```bash
+   cp .env.example .env
+   ```
+   Öffne `.env` und trage deine Werte ein:
+   - `LITELLM_MASTER_KEY` & `LITELLM_SALT_KEY`
+   - `UI_USERNAME` & `UI_PASSWORD` (für den Login in die Web-UI)
+   - `HEADROOM_API_KEY` (und optional `HEADROOM_API_BASE`, Standard: `https://api.headroom.ai`)
+   - Deine LLM-Provider API-Keys (z.B. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
+
+2. **Container starten**:
+   ```bash
+   docker compose up -d
+   ```
+
+3. **Web-UI öffnen**:
+   - URL: `http://localhost:4000/ui` (oder `http://<server-ip>:4000/ui`)
+   - Logge dich mit `UI_USERNAME` und `UI_PASSWORD` oder dem `LITELLM_MASTER_KEY` ein.
+
+---
+
+## Headroom-Kompression verwenden & zuweisen
+
+### 1. Globale Standard-Aktivierung ("für alles")
+In `config.yaml` ist Headroom unter `litellm_settings` als Standard-Guardrail hinterlegt:
+```yaml
+litellm_settings:
+  default_guardrails: ["headroom"]
+```
+Dadurch wird Headroom automatisch bei allen eingehenden Anfragen zur Prompt-Kompression angewendet.
+
+### 2. Zuweisung und Verwaltung über die Web-UI
+Da `headroom` in `config.yaml` unter `guardrails:` definiert ist, steht es in der LiteLLM Web-UI an folgenden Stellen zur Verfügung:
+
+- **API-Keys**:
+  - Gehe in der Web-UI auf **API Keys** → **Create New Key** (oder bestehenden Key bearbeiten).
+  - Wähle im Feld **Guardrails** den Eintrag `headroom` aus, um die Kompression für diesen Key zu erzwingen.
+- **Teams**:
+  - Gehe auf **Teams** → **Create Team** (oder bestehendes Team bearbeiten).
+  - Wähle unter **Guardrails** `headroom` aus, damit alle Keys dieses Teams automatisch komprimiert werden.
+- **Modelle**:
+  - Unter **Models** / **Add Model** kann `guardrails: ["headroom"]` direkt an spezifische Modelle gebunden werden.
+- **Guardrails-Übersicht**:
+  - Unter **Guardrails** in der Web-UI siehst du alle registrierten Guardrails inklusive `headroom` und deren Status.
+
+---
+
+## Konfigurationsdateien
+
+- `docker-compose.yaml`: Definiert die Services `litellm`, `headroom`, `db` (Postgres), `redis` und `prometheus`.
+- `Dockerfile.headroom`: Dockerfile zum optionalen lokalen Bauen des Headroom-Proxy-Images.
+- `config.yaml`: LiteLLM Proxy-Konfiguration inklusive Caching, Routing, Logging und Headroom-Guardrail.
+- `.env.example`: Vorlage für Passwörter, Master-Keys und Provider/Headroom-Konfiguration.
+- `prometheus.yaml`: Konfiguration für das Scraping der LiteLLM-Metriken.
@@ -18,6 +18,18 @@ litellm_settings:
  success_callback: ["prometheus", "langfuse"]
  failure_callback: ["prometheus"]

+  # Standard-Guardrails für alle Anfragen (Headroom Prompt-Kompression für alles aktiv)
+  default_guardrails: ["headroom"]
+
+# Guardrail-Definitionen (werden auch in der LiteLLM Web-UI angezeigt und können Keys/Teams/Modellen zugewiesen werden)
+guardrails:
+  - guardrail_name: "headroom"
+    litellm_params:
+      guardrail: "headroom"
+      mode: "pre_call"
+      api_key: os.environ/HEADROOM_API_KEY
+      api_base: os.environ/HEADROOM_API_BASE
+
 general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
@@ -29,6 +29,9 @@ services:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - GROQ_API_KEY=${GROQ_API_KEY}
      - MISTRAL_API_KEY=${MISTRAL_API_KEY}
+      # --- Headroom (Prompt-Kompression) ---
+      - HEADROOM_API_KEY=${HEADROOM_API_KEY:-}
+      - HEADROOM_API_BASE=${HEADROOM_API_BASE:-http://headroom:8787}
      # --- Optionale Alerts / Logging ---
      - SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}
      - LANGFUSE_PUBLIC_KEY=${LANGFUSE_PUBLIC_KEY}
@@ -47,6 +50,8 @@ services:
        condition: service_healthy
      redis:
        condition: service_started
+      headroom:
+        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health/liveliness"]
      interval: 30s
@@ -56,6 +61,34 @@ services:
    networks:
      - litellm-network

+  headroom:
+    image: ghcr.io/headroomlabs-ai/headroom:main
+    # Falls das Image lokal gebaut werden soll (Dockerfile.headroom im Repo vorhanden):
+    # build:
+    #   context: .
+    #   dockerfile: Dockerfile.headroom
+    container_name: litellm-headroom
+    restart: unless-stopped
+    ports:
+      - "8787:8787"
+    environment:
+      # Erlaubt Anfragen von anderen Containern im Docker-Netzwerk an den /v1/compress Endpoint
+      - HEADROOM_COMPRESS_ALLOW_REMOTE=1
+      # Optional: Provider-Keys falls Headroom eigenständig Provider ansteuert
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    volumes:
+      - ./data/headroom:/root/.headroom
+    command: ["--host", "0.0.0.0", "--port", "8787"]
+    healthcheck:
+      test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8787/readyz', timeout=5)\""]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+    networks:
+      - litellm-network
+
  db:
    image: postgres:16-alpine
    container_name: litellm-db