Funk-lab/admin/k8s/open-webui.md

Open WebUI — Interface de chat IA

Open WebUI est l'interface web de chat connectée à LiteLLM. Elle permet d'accéder à tous les modèles du lab depuis un navigateur, avec historique persistant et gestion multi-utilisateurs.

---

Accès

URL	http://openwebui.lab.local
Namespace k8s	ai
Port interne	8080
Backend LLM	LiteLLM http://192.168.10.1:4000/v1

Modèles disponibles (via LiteLLM) :

• hermes-default — Qwen3-8B sur gpu-01, profil principal (~35 tok/s)
• qwen3-8b — alias direct gpu-01
• claude-sonnet-4-6 — Claude API Anthropic (facturé)
• claude-opus-4-7 — Claude API Anthropic (facturé)

---

Architecture

Navigateur
    │
    ▼
Traefik (openwebui.lab.local)
    │
    ▼
Open WebUI pod (namespace ai)
    │  OPENAI_API_BASE_URL=http://192.168.10.1:4000/v1
    ▼
LiteLLM (storage-01 :4000)
    │
    ├── hermes-default → llama-server gpu-01 :1234
    └── claude-*       → Anthropic API

Base de données : PostgreSQL sur storage-01 (openwebui DB). Les conversations, utilisateurs et paramètres sont persistés.

---

Déploiement (ArgoCD)

Manifests dans k8s/apps/open-webui/ :

• deployment.yaml — pod Open WebUI
• service.yaml — ClusterIP :8080
• ingress.yaml — IngressRoute Traefik
• pvc.yaml — données applicatives (NFS)
• secret.yaml — secrets (non commité, à créer manuellement)

Application ArgoCD : k8s/apps-of-apps/apps/open-webui.yaml

Créer le secret (première installation)

kubectl create secret generic open-webui-secret -n ai \
  --from-literal=litellm-api-key="lm-studio" \
  --from-literal=database-url="postgresql://openwebui:PASSWORD@192.168.10.1:5432/openwebui" \
  --from-literal=webui-secret-key="$(openssl rand -hex 32)"

Le mot de passe PostgreSQL est dans le vault Ansible (vault_pg_openwebui_password).

---

Premier démarrage

1. Naviguer sur http://openwebui.lab.local
2. Créer un compte administrateur (premier compte = admin automatiquement)
3. Sélectionner un modèle dans le dropdown en haut
4. Commencer à discuter

Note : au premier démarrage, Open WebUI télécharge des modèles sentence-transformer (~500 MB) pour le RAG local. Le pod peut sembler lent pendant 2-3 minutes — c'est normal.

---

Différence avec Hermes TUI

	Open WebUI	Hermes TUI
Accès	Navigateur (réseau local)	SSH + hermes chat
Contexte Funk	✗ LLM générique	✅ Skills RAG, monitoring, agent
Historique	✅ Persistant (PostgreSQL)	✗ Session uniquement
Multi-utilisateurs	✅	✗
Upload fichiers	✅	✗
Usage	Chat général, documents	Admin lab, debug infra

---

Variables d'environnement clés

Variable	Valeur	Rôle
OPENAI_API_BASE_URL	http://192.168.10.1:4000/v1	Backend LiteLLM
OPENAI_API_KEY	lm-studio	Clé LiteLLM master key
DATABASE_URL	postgresql://...	Persistance PostgreSQL
ENABLE_OLLAMA_API	false	Désactiver Ollama
WEBUI_NAME	Funk AI	Nom affiché

---

Dépannage

Symptôme	Cause	Action
"Aucun modèle disponible"	LiteLLM inaccessible	Vérifier curl http://192.168.10.1:4000/v1/models -H 'Authorization: Bearer lm-studio' depuis un pod
Pod OOMKilled	RAM insuffisante au 1er boot	Attendre le rechargement ou augmenter la limit mémoire
Connexion refusée	Pod pas encore prêt	kubectl get pods -n ai — attendre readiness probe
Erreur DB migrations	PostgreSQL inaccessible	kubectl logs deploy/open-webui -n ai

# Logs
kubectl logs deploy/open-webui -n ai -f

# Redémarrer
kubectl rollout restart deploy/open-webui -n ai

# Vérifier connectivité LiteLLM depuis le pod
kubectl exec -n ai deploy/open-webui -- curl -s http://192.168.10.1:4000/v1/models \
  -H 'Authorization: Bearer lm-studio'