Token-Budget & Kosten¶

Das Budget-System kontrolliert den Token-Verbrauch pro User und berechnet die anfallenden Kosten auf Basis eines konfigurierbaren Token-Preises.

Budget-Konfiguration im Admin-Backend¶

Zuweisungsworkflow¶

Admin öffnet User-Edit → Tab Budget
Limits setzen (alle optional, leer = unlimitiert):
Tägliches Limit (Tokens/Tag, Reset täglich um Mitternacht UTC)
Monatliches Limit (Tokens/Monat, Reset am 1. des Monats UTC)
Gesamt-Limit (kumulativ, kein automatischer Reset)
Budget-Typ wählen:
Abo (Subscription): Tages- und Monatslimits werden automatisch zurückgesetzt
Einmalig: Nur total_limit relevant, kein Reset
Budget speichern → schreibt in SQLite + synct Redis

Budget-Typen¶

Typ	Reset	Empfohlene Limits
`subscription`	Täglich + Monatlich	`daily_limit` + `monthly_limit`
`onetime`	Kein Reset	Nur `total_limit`

Token-Zählung¶

Was wird gezählt?¶

Jede API-Anfrage zählt sowohl Prompt-Tokens (Eingabe) als auch Completion-Tokens (Ausgabe):

total_tokens = prompt_tokens + completion_tokens

Kostenfaktor¶

Dem tatsächlichen Token-Verbrauch kann ein Kostenfaktor aufgeschlagen werden:

effektive_tokens = round(total_tokens × cost_factor)

Quelle	Feld	Standard
User-Template	`cost_factor` (REAL)	`1.0`
Inferenz-Server	`cost_factor` (REAL)	`1.0`

Der Kostenfaktor wird aus dem aktiven Expert-Template des Users und/oder dem verwendeten Inferenz-Server berechnet und für 24 Stunden in Redis gecacht:

user:{user_id}:cost_factor  →  STRING  "1.5"   TTL 86400s

Beispiel:

Rohe Tokens	Kostenfaktor	Effektive Tokens
1.000	1.0	1.000
1.000	1.5	1.500
1.000	0.8	800

Redis-Counter (Real-Time)¶

Alle Budget-Zähler laufen in Redis für minimale Latenz:

user:{id}:tokens:daily:{YYYY-MM-DD}    →  INCRBY  TTL 48h
user:{id}:tokens:monthly:{YYYY-MM}    →  INCRBY  TTL 35d
user:{id}:tokens:total                →  INCRBY

Budget-Überschreitung wird beim nächsten API-Request erkannt. Die Anfrage wird mit HTTP 429 abgewiesen.

Kostenberechnung (EUR)¶

Token-Preis konfigurieren¶

Der globale Token-Preis wird im Admin-Dashboard unter Token-Preis gesetzt:

Admin Dashboard → "Token-Preis (EUR pro Token)" → Speichern

Standard: 0.00002 EUR pro Token (= 0,02 EUR pro 1.000 Tokens).

Der Wert wird in der .env-Datei als TOKEN_PRICE_EUR gespeichert.

Kostenformel¶

kosten_eur = effektive_tokens × TOKEN_PRICE_EUR
           = (rohe_tokens × cost_factor) × TOKEN_PRICE_EUR

Beispiel (Standard-Konfiguration):

Tokens	Kostenfaktor	Effektiv	Preis/Token	Kosten
10.000	1.0	10.000	0,00002 €	0,20 €
10.000	1.5	15.000	0,00002 €	0,30 €
50.000	1.0	50.000	0,00002 €	1,00 €

Wo wird der Preis angezeigt?¶

Admin → User-Edit → Tab Budget: Aktueller Verbrauch mit ≈ €X.XX unter jedem Zähler
User-Portal → Abrechnung: Vollständige Aufschlüsselung nach Periode und Modell
User-Portal → Dashboard: Kompakte Budget-Karten mit Prozentanzeige

Budget-Alerts¶

User können automatische E-Mail-Benachrichtigungen bei Budgetausschöpfung konfigurieren.

Konfiguration (durch User im Portal)¶

Feld	Beschreibung	Standard
Alert aktiviert	Ein/Aus-Toggle	Aus
Schwellenwert	Ab welchem % wird gewarnt	80%
E-Mail-Adresse	Empfänger (Standard: Account-E-Mail)	–

Verhalten¶

Hintergrundtask läuft stündlich
Prüft: Wurde der Schwellenwert in einer Periode überschritten?
Max. 1 Alert pro User pro 24 Stunden (Rate-Limiting per last_alert_sent_at)
Periodenabdeckung: Täglich UND Monatlich UND Gesamt
Sprache: Deutsch

Alert-E-Mail-Inhalt¶

Betreff: Budget-Warnung: Tägliches Limit zu 85% ausgeschöpft

Ihr tägliches Token-Budget ist zu 85% ausgeschöpft.
Verbrauch: 85.000 / 100.000 Tokens
Verbleibend: 15.000 Tokens
Reset: in 6 Stunden

Nutzungsprotokoll (Usage Log)¶

Jede API-Anfrage wird in der SQLite-Datenbank protokolliert:

CREATE TABLE usage_log (
    id                TEXT PRIMARY KEY,
    user_id           TEXT NOT NULL,
    api_key_id        TEXT,
    request_id        TEXT NOT NULL,
    model             TEXT NOT NULL,
    moe_mode          TEXT NOT NULL,
    prompt_tokens     INTEGER DEFAULT 0,
    completion_tokens INTEGER DEFAULT 0,
    total_tokens      INTEGER DEFAULT 0,
    status            TEXT DEFAULT 'ok',  -- 'ok' oder Fehlercode
    requested_at      TEXT NOT NULL,       -- ISO-8601 UTC
    notes             TEXT                 -- User-editierbare Notiz
);

Verbrauchsabfrage (Admin)¶

GET /api/users/{user_id}/usage?days=30

Gibt JSON mit allen Einträgen der letzten N Tage zurück, inkl. Key-Label und Key-Prefix.

Zusammenfassung: Weg eines Tokens¶

1. User sendet API-Request
        │
2. Orchestrator validiert API-Key (Redis, TTL 5min)
        │
3. Budget-Prüfung: user:{id}:tokens:daily  ≤  daily_limit?
        │  └─ Überschreitung → HTTP 429
        │
4. LLM-Inferenz läuft durch
        │
5. Token-Zählung: prompt_tokens + completion_tokens
        │
6. Kostenfaktor abrufen (Redis user:{id}:cost_factor)
        │
7. Effektive Tokens = raw × cost_factor
        │
8. Redis-Counter inkrementieren (daily + monthly + total)
        │
9. usage_log → SQLite (fire & forget, async)
        │
10. Prometheus-Counter inkrementieren (moe_tokens_total)