238 lines
8.8 KiB
Markdown
238 lines
8.8 KiB
Markdown
---
|
|
title: AI Magic Edits (Ops Runbook)
|
|
sidebar_label: AI Magic Edits
|
|
---
|
|
|
|
Dieses Runbook beschreibt den operativen Betrieb von AI Magic Edits (AI Styling) inklusive Entitlements, Provider-Betrieb, Monitoring, Recovery und Incident-Handling.
|
|
|
|
## 1. Scope und aktueller Stand
|
|
|
|
- Feature-Name im System: `ai_styling` (User-facing: "AI Magic Edits"/"AI-Styling").
|
|
- Architektur ist provider-agnostisch umgesetzt (`AiImageProvider` Interface), aktuell ist `runware.ai` als erster Provider aktiv.
|
|
- Das Guest-PWA-Rollout ist derzeit clientseitig hinter einem Flag deaktiviert:
|
|
- `resources/js/guest-v2/lib/featureFlags.ts` → `GUEST_AI_MAGIC_EDITS_ENABLED = false`.
|
|
- Im Event Admin Control Room wird der AI-Bereich nur angezeigt, wenn das Event das Capability `ai_styling` hat.
|
|
|
|
## 2. Entitlements und Freischaltung
|
|
|
|
### 2.1 Paket-/Addon-Logik
|
|
|
|
- Erforderliches Paket-Feature: `ai_styling` (`config/ai-editing.php`).
|
|
- Standard-Addon-Key: `ai_styling_unlock` (`config/ai-editing.php`, `config/package-addons.php`).
|
|
- Entitlement wird event-spezifisch aufgelöst über:
|
|
- aktives Event-Paket (`eventPackage.package.features`, Tabelle `event_packages`)
|
|
- aktive, abgeschlossene Addons (`eventPackage.addons`, Tabelle `event_package_addons`, `status=completed`, optionales Ablaufdatum in `metadata`).
|
|
- Quelle der Berechtigung:
|
|
- `granted_by=package` (Feature im Paket enthalten, z.B. Premium)
|
|
- `granted_by=addon` (Addon für Event aktiv)
|
|
- sonst gesperrt (`feature_locked`).
|
|
|
|
### 2.2 Superadmin-Konfiguration
|
|
|
|
- Paket-Feature-Verwaltung erfolgt über die bestehende Package-Resource (Feature `ai_styling` setzen).
|
|
- Addon-Katalog:
|
|
- Key `ai_styling_unlock` in `config/package-addons.php`
|
|
- kaufbar nur, wenn im Checkout-Katalog ein valider Preis hinterlegt ist.
|
|
|
|
## 3. Runtime-Steuerung (Superadmin)
|
|
|
|
Die zentrale Laufzeitsteuerung liegt in `AI Editing Settings` (Rare Admin Cluster):
|
|
|
|
- `is_enabled`: Globaler Kill-Switch.
|
|
- `status_message`: Text bei globaler Deaktivierung (`feature_disabled`).
|
|
- `default_provider`: aktuell `runware`.
|
|
- `fallback_provider`: reserviert für späteres Failover.
|
|
- `runware_mode`: `live` oder `fake`.
|
|
- `queue_auto_dispatch`: automatische Queue-Dispatches direkt nach Request-Erstellung.
|
|
- `queue_name`: Ziel-Queue für AI Jobs.
|
|
- `queue_max_polls`: maximale Poll-Versuche für Provider-Status.
|
|
- `blocked_terms`: globale Prompt-Blockliste.
|
|
|
|
Wichtiger Betriebsaspekt:
|
|
- Standard ist `queue_auto_dispatch=false`. In diesem Modus werden neue Requests zwar erstellt, aber nicht automatisch verarbeitet.
|
|
- Für Live-Betrieb muss entweder `queue_auto_dispatch=true` gesetzt oder ein separater Dispatch-Prozess etabliert sein.
|
|
|
|
## 4. Styles und Event-Policy
|
|
|
|
### 4.1 Globale Styles
|
|
|
|
- Verwaltung über `AI Styles` Resource.
|
|
- Styles definieren u.a.:
|
|
- `provider`/`provider_model`
|
|
- `prompt_template`/`negative_prompt_template`
|
|
- `is_active`, `is_premium`
|
|
- optionales Entitlement-Metadatenprofil (`metadata.entitlements.*`).
|
|
|
|
### 4.2 Event-spezifische Policy
|
|
|
|
Event-Settings unter `settings.ai_editing` unterstützen:
|
|
|
|
- `enabled` (Feature pro Event an/aus)
|
|
- `allow_custom_prompt`
|
|
- `allowed_style_keys` (leer = alle erlaubten Styles)
|
|
- `policy_message` (Rückmeldung bei Blockierung/Deaktivierung)
|
|
|
|
## 5. API/Queue-Verarbeitung
|
|
|
|
### 5.1 Endpunkte
|
|
|
|
- Guest:
|
|
- `POST /api/v1/events/{token}/photos/{photo}/ai-edits`
|
|
- `GET /api/v1/events/{token}/ai-edits/{requestId}`
|
|
- `GET /api/v1/events/{token}/ai-styles`
|
|
- Tenant:
|
|
- `GET /api/v1/tenant/events/{eventSlug}/ai-edits`
|
|
- `GET /api/v1/tenant/events/{eventSlug}/ai-edits/summary`
|
|
- `POST /api/v1/tenant/events/{eventSlug}/ai-edits`
|
|
- `GET /api/v1/tenant/events/{eventSlug}/ai-edits/{aiEditRequest}`
|
|
- `GET /api/v1/tenant/events/{eventSlug}/ai-styles`
|
|
|
|
### 5.2 Schutzschichten pro Request
|
|
|
|
Reihenfolge der Kernprüfungen:
|
|
|
|
1. Global aktiviert (`is_enabled`)
|
|
2. Entitlement vorhanden (Paket/Addon)
|
|
3. Event-Policy erlaubt Request
|
|
4. Budget erlaubt Request (Soft/Hard Cap)
|
|
5. Style-Zulässigkeit
|
|
6. Prompt-Safety (blocked terms)
|
|
7. Queue/Provider-Verarbeitung
|
|
|
|
### 5.3 Queue-Jobs
|
|
|
|
- `ProcessAiEditRequest`: Provider-Submit und ggf. Übergang in Polling.
|
|
- `PollAiEditRequest`: Provider-Statusabfrage bis `queue_max_polls`.
|
|
- Terminalstatus:
|
|
- `succeeded`
|
|
- `failed`
|
|
- `blocked`
|
|
|
|
### 5.4 Output-Speicherung und Wasserzeichen
|
|
|
|
- Bei erfolgreichem Provider-Result versucht das Backend, den Output lokal zu persistieren:
|
|
- Download von `provider_url`
|
|
- Speicherung unter Event-Pfad (`events/{eventSlug}/ai-edits/...`)
|
|
- Watermark-Anwendung über dieselbe Logik wie normale Uploads (`WatermarkConfigResolver` + `ImageHelper`).
|
|
- Primäre Auslieferung erfolgt über lokale `storage_path`/`url`; `provider_url` bleibt als Fallback erhalten.
|
|
- Backfill für Alt-Daten ohne lokale Pfade:
|
|
- `php artisan ai-edits:backfill-storage`
|
|
|
|
## 6. Provider-Betrieb (Runware)
|
|
|
|
### 6.1 Erforderliche ENV/Config
|
|
|
|
- `RUNWARE_API_KEY`
|
|
- `RUNWARE_BASE_URL` (Default `https://api.runware.ai/v1`)
|
|
- `RUNWARE_TIMEOUT` (Sekunden)
|
|
- `AI_EDITING_DEFAULT_PROVIDER` (Default `runware`)
|
|
- `AI_EDITING_RUNWARE_MODE` (`live` oder `fake`)
|
|
|
|
### 6.2 Fake-Mode
|
|
|
|
- `runware_mode=fake` liefert synthetische Antworten ohne externen API-Call.
|
|
- Geeignet für interne Validierung von Flow/UI/Queue-Logik.
|
|
- Nicht für Kosten- oder Qualitätsaussagen nutzen.
|
|
|
|
## 7. Monitoring und Alerts
|
|
|
|
### 7.1 Wichtige Kennzahlen
|
|
|
|
- Request-Statusverteilung je Event (`queued`, `processing`, `succeeded`, `failed`, `blocked`)
|
|
- Failure-Rate
|
|
- Moderation-Hit-Rate
|
|
- Provider-Failure-Rate
|
|
- durchschnittliche Provider-Latenz
|
|
- Monatsausgaben (`ai_usage_ledgers`)
|
|
|
|
Das Tenant-Summary-Endpoint liefert diese Daten inkl. Alert-Flags:
|
|
- `observability.alerts.failure_rate_threshold_reached`
|
|
- `observability.alerts.latency_threshold_reached`
|
|
|
|
### 7.2 Schwellenwerte aus Config
|
|
|
|
- `ai-editing.observability.failure_rate_alert_threshold` (Default `0.35`)
|
|
- `ai-editing.observability.failure_rate_min_samples` (Default `10`)
|
|
- `ai-editing.observability.latency_warning_ms` (Default `15000`)
|
|
- Budget-Alert-Cooldown: `ai-editing.billing.budget.alert_cooldown_minutes` (Default `30`)
|
|
- Abuse-Eskalation: `ai-editing.abuse.escalation_threshold_per_hour` (Default `25`)
|
|
|
|
### 7.3 Relevante Log-Signale
|
|
|
|
- `AI provider latency warning`
|
|
- `AI failure-rate alert threshold reached`
|
|
- `AI budget threshold reached`
|
|
- `AI abuse escalation threshold reached`
|
|
|
|
## 8. Betriebs-Kommandos
|
|
|
|
### 8.1 Stuck Requests analysieren/recovern
|
|
|
|
- Dry-run:
|
|
- `php artisan ai-edits:recover-stuck --minutes=30`
|
|
- Requeue:
|
|
- `php artisan ai-edits:recover-stuck --minutes=30 --requeue`
|
|
- Hart auf failed setzen:
|
|
- `php artisan ai-edits:recover-stuck --minutes=30 --fail`
|
|
|
|
### 8.2 Retention-Pruning
|
|
|
|
- Dry-run:
|
|
- `php artisan ai-edits:prune --pretend`
|
|
- Ausführen (mit optionalen Overrides):
|
|
- `php artisan ai-edits:prune --request-days=90 --ledger-days=365`
|
|
|
|
Retention Defaults:
|
|
- Requests: `AI_EDITING_REQUEST_RETENTION_DAYS` (90)
|
|
- Ledger: `AI_EDITING_USAGE_LEDGER_RETENTION_DAYS` (365)
|
|
|
|
Hinweis:
|
|
- `ai-edits:prune` läuft täglich per Scheduler (`02:30`), kann aber bei Bedarf manuell ausgeführt werden.
|
|
|
|
### 8.3 Backfill lokaler AI-Outputs
|
|
|
|
- Dry-run:
|
|
- `php artisan ai-edits:backfill-storage --pretend`
|
|
- Ausführen:
|
|
- `php artisan ai-edits:backfill-storage --limit=200`
|
|
- Für einzelne Request-ID:
|
|
- `php artisan ai-edits:backfill-storage --request-id=123`
|
|
|
|
## 9. Incident-Playbooks
|
|
|
|
### 9.1 Provider-Ausfall / hohe Failure-Rate
|
|
|
|
1. `is_enabled=false` als Kill-Switch setzen (optional mit `status_message`).
|
|
2. `runware_mode=fake` nur für interne Funktionstests aktivieren.
|
|
3. Queue-Backlog prüfen, ggf. `ai-edits:recover-stuck --requeue` nach Stabilisierung.
|
|
4. Fehlerraten im Summary pro Event kontrollieren.
|
|
|
|
### 9.2 Kostenanstieg / Budget-Hard-Cap
|
|
|
|
1. Budget-Alerts (`ai_budget_soft_cap`/`ai_budget_hard_cap`) prüfen.
|
|
2. Tenant-Budget in `tenant.settings.ai_editing.budget.*` validieren.
|
|
3. Bei Bedarf zeitweises Override `override_until` setzen.
|
|
4. Bei Missbrauchsspitzen zusätzlich Abuse-Signale prüfen.
|
|
|
|
### 9.3 Safety-/Abuse-Spike
|
|
|
|
1. `blocked_terms` nachschärfen.
|
|
2. Event-Policy enger setzen (`allow_custom_prompt=false`, `allowed_style_keys` einschränken).
|
|
3. Warn-Logs mit `scope_hash`, `event_id`, `tenant_id` korrelieren.
|
|
|
|
## 10. Datenschutz und Datenhaltung
|
|
|
|
- Keine Secrets in Logs/Docs schreiben (`RUNWARE_API_KEY`, `.env`).
|
|
- Prompt-/Negativprompt-Inhalte liegen in `ai_edit_requests`; mit PII vorsichtig umgehen.
|
|
- Nur notwendige Aufbewahrungsdauer halten; Pruning regelmäßig durchführen.
|
|
- Keine Erweiterung der Retention ohne abgestimmte Privacy-Änderung.
|
|
|
|
## 11. Go-Live-Checkliste
|
|
|
|
1. Paket-/Addon-Freischaltung verifiziert (`ai_styling`, `ai_styling_unlock`).
|
|
2. `RUNWARE_API_KEY` gesetzt und Provider-Erreichbarkeit geprüft.
|
|
3. `queue_auto_dispatch=true` und Worker auf korrekter Queue aktiv.
|
|
4. Budget-Limits und Alerting pro Tenant geprüft.
|
|
5. Safety-Baseline (`blocked_terms`) gesetzt.
|
|
6. Recovery- und Prune-Commands in Ops-Routine aufgenommen.
|