Technical Tutorials

Open WebUI s'est rapidement imposé comme l'interface de référence pour les modèles de langage locaux, comblant le fossé entre les commandes brutes du terminal et des expériences de chat intuitives. Bien que l'installation par défaut suffise pour un usage basique, les utilisateurs experts recherchent souvent une personnalisation plus poussée. Dans ce guide, nous explorerons des stratégies de configuration avancées, en mettant l'accent sur la persistance des thèmes, l'architecture des plugins et l'intégration API pour transformer Open WebUI en un moteur de productivité sur mesure.

Configuration persistante via les variables d'environnement

L'un des aspects les plus critiques du déploiement avancé d'Open WebUI est la garantie que vos configurations persistent après les redémarrages des conteneurs. Bien que l'interface web permette de modifier l'interface utilisateur, ces changements sont souvent éphémères à moins d'être explicitement sauvegardés. La méthode robuste pour gérer cela consiste à utiliser les variables d'environnement Docker.

En définissant OAUTH_ROLE_CLAIM ou en activant ENABLE_OAUTH_SIGNUP, vous pouvez sécuriser votre instance. Cependant, pour une personnalisation pure, concentrez-vous sur WEBUI_SECRET_KEY et les définitions de modèles. Voici un extrait robuste de docker-compose.yml démontrant comment monter un répertoire de configuration personnalisé et définir des variables d'environnement persistantes.

version: '3.8'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    restart: unless-stopped
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
      - WEBUI_SECRET_KEY=votre_clé_aléatoire_super_sécurisée_ici
      - ENABLE_OAUTH_SIGNUP=false
    volumes:
      - ./ollama:/root/.ollama # Stockage persistant des modèles
      - ./data/open-webui:/app/backend/data # Données utilisateur et configurations persistantes

Personnalisation approfondie : injection CSS et thèmes

Pour les développeurs souhaitant modifier l'apparence au-delà des modes sombre et clair standards, Open WebUI prend en charge l'injection CSS. Vous pouvez y parvenir en plaçant des feuilles de style personnalisées dans le répertoire monté /app/backend/data. Cette méthode est particulièrement utile pour créer des outils internes marqués ou pour réduire la fatigue oculaire avec des palettes de couleurs spécifiques.

Pour appliquer un thème personnalisé, créez un fichier nommé custom.css dans votre volume de données monté. Open WebUI scanne automatiquement cet emplacement pour les surcharges. Par exemple, pour personnaliser l'arrière-plan de la barre latérale :

/* custom.css */
.sidebar {
    background-color: #1a1b26;
    border-right: 1px solid #24283b;
}

.chat-message {
    font-family: 'Inter', sans-serif;
    line-height: 1.6;
}

Cette méthode exploite la nature open source du projet, vous permettant de forker ou d'étendre les composants frontend si nécessaire. C'est une alternative puissante au simple recours au menu des paramètres, offrant un contrôle granulaire sur chaque pixel.

Extension des fonctionnalités : l'architecture des plugins

Le système de plugins d'Open WebUI est conçu pour étendre les fonctionnalités sans alourdir la base de code principale. Les plugins sont essentiellement des scripts Python qui s'intercalent dans le cycle de vie des requêtes. Un cas d'utilisation courant pour les utilisateurs avancés est l'intégration avec des bases de connaissances externes ou le déclenchement de webhooks.

Pour développer un plugin personnalisé, vous créez généralement un répertoire sous /app/backend/data/plugins. La structure nécessite généralement un fichier __init__.py et un fichier de configuration. Par exemple, un plugin qui enregistre toutes les invites de chat dans un système SIEM (Gestion des informations et événements de sécurité) externe peut être construit en interceptant les événements ChatCompletion.

# plugin_example.py
from open_webui.plugins import register_plugin
import requests

def register():
    register_plugin(
        name="Journal de sécurité",
        description="Enregistre toutes les invites dans un point de terminaison distant",
        version="1.0.0"
    )

def on_chat_completion(request, response):
    # Logique personnalisée pour envoyer des données à une API externe
    requests.post("https://votre-point-de-terminaison-de-journalisation.com/log", json={
        "prompt": request.get('prompt'),
        "timestamp": "maintenant"
    })

Intégration API et utilisation sans tête (headless)

Enfin, Open WebUI n'est pas seulement un client de chat ; c'est un serveur API complet. Les utilisateurs experts peuvent exploiter les points de terminaison /api/v1 pour intégrer Open WebUI dans des flux de travail d'automatisation plus larges. Que vous construisiez un frontend React personnalisé ou que vous intégriez avec n8n, l'API prend en charge l'authentification via l'en-tête Authorization.

Lors de l'utilisation de l'API, assurez-vous de générer des clés API depuis le panneau d'administration d'Open WebUI. Cela vous permet de faire tourner les identifiants sans affecter les utilisateurs de l'interface principale. De plus, vous pouvez configurer les paramètres CORS via des variables d'environnement si vous hébergez le frontend et le backend séparément.

Conclusion

Maîtriser Open WebUI va au-delà de la simple sélection de modèles. En exploitant la configuration persistante, l'injection CSS personnalisée et l'architecture robuste des plugins, vous pouvez adapter l'interface pour qu'elle s'adapte à des flux de travail spécialisés. Que vous sécurisiez l'accès, marquez l'interface utilisateur ou intégriez des sources de données externes, ces techniques avancées vous permettent de tirer le meilleur parti de votre infrastructure d'IA locale.