Open WebUI avec Hivenet Router : guide pour les équipes

Open WebUI peut offrir à une équipe une interface de conversation dans le navigateur pour les modèles accessibles via Hivenet Router. Chaque composant a un rôle distinct : Open WebUI gère la conversation, Router choisit une destination admissible et le moteur d’inférence génère la réponse.

Commencez avec un seul modèle de conversation autorisé et une clé client Router dédiée. Vérifiez cette connexion avant d’ajouter des modèles ou des fonctionnalités facultatives. Ce guide couvre la connexion gérée côté serveur, les accès partagés, les requêtes en arrière-plan et les vérifications à effectuer avant d’accueillir une équipe.

Les instructions ont été vérifiées à partir du code d’Open WebUI 0.13.3 et de la documentation Router disponible le 11 novembre 2026. Elles n’ont pas été validées sur un déploiement Open WebUI connecté à Router en fonctionnement. Les vérifications ci-dessous restent donc à réaliser dans votre environnement ; ce ne sont pas des résultats de tests déjà exécutés.

Décider où chaque composant s’exécute

Une requête passe généralement du navigateur au serveur Open WebUI, puis par Router et l’agent sélectionné, avant d’atteindre le moteur d’inférence. Hivenet Router assure le routage et l’application des règles ; il ne charge pas les poids du modèle et ne réalise pas l’inférence.

Une VM CPU peut héberger l’interface et les services de routage lorsque l’inférence s’effectue ailleurs. Dimensionnez-la selon les services présents, les sessions simultanées, le stockage et les traitements facultatifs. Afficher les réponses d’un modèle distant ne nécessite pas à lui seul un GPU, mais des traitements locaux de vectorisation, de voix ou d’inférence changent les besoins. Une mesure de mémoire au repos ne constitue pas une estimation de capacité en production.

Avant de configurer l’interface, prévoyez une adresse Router accessible, une clé client, un agent admissible doté de la capacité llm et un moteur compatible avec Chat Completions. Consultez le guide d’installation d’Open WebUI, en anglais, pour l’application elle-même. Fixez la version déployée et conservez son répertoire de données. Cet article commence à la connexion entre les services, sans supposer qu’une VM vierge les contient déjà.

Vérifier Router avant d’ajouter l’interface

Effectuez les premières vérifications depuis le réseau où le serveur Open WebUI sera exécuté. Un accès réussi depuis votre ordinateur ne prouve pas qu’un conteneur peut résoudre le même nom, valider son certificat ou traverser le pare-feu.

Avec la clé client prévue, appelez GET /v1/models et relevez l’identifiant exact d’un modèle de conversation autorisé. La référence du catalogue Router, en anglais, décrit les informations de capacité. Le catalogue peut aussi contenir des modèles de vectorisation et de reclassement ; ils ne remplacent pas un LLM sur le point d’accès de conversation.

Envoyez ensuite une courte requête textuelle à POST /v1/chat/completions avec cet identifiant. Recommencez en activant le streaming et vérifiez que la réponse arrive progressivement, puis se termine. La référence Chat Completions, en anglais, décrit le chemin de la requête et sa transmission. La découverte des modèles ne prouve pas qu’un moteur peut terminer une requête.

Utilisez une consigne sans données sensibles, par exemple demander trois noms de couleurs. Conservez le statut et l’identifiant de requête sans copier la clé dans un ticket ou une capture d’écran. Si ces vérifications directes échouent, résolvez d’abord le problème de Router, de clé, de réseau ou de moteur avant d’examiner l’interface du navigateur.

Ajouter la connexion gérée côté serveur

Dans Open WebUI, ouvrez Settings → Admin → Connections, puis ajoutez une connexion compatible OpenAI. Ces réglages s’appliquent à toute l’instance. Les connexions personnelles directes constituent une autre fonctionnalité, hors du périmètre de ce guide ; la documentation des réglages, en anglais, explique la distinction.

Le nom d’hôte ci-dessus est un exemple à remplacer par celui de votre déploiement, pas l’adresse d’un service public Hivenet. Saisissez la clé client brute dans le champ prévu ; Open WebUI ajoute l’en-tête d’autorisation Bearer. N’utilisez pas un identifiant d’administration Router.

Le guide officiel d’intégration Router, en anglais, demande d’utiliser Chat Completions. Router n’expose pas actuellement /v1/responses : choisir le type d’API Responses dirige donc la requête vers une route non prise en charge.

Utilisez le bouton Verify Connection, enregistrez, puis vérifiez le sélecteur de modèles. Le guide de connexion aux fournisseurs, en anglais, distingue vérification et enregistrement : la vérification appelle le point d’accès des modèles, tandis qu’enregistrer la connexion ne teste pas l’inférence. Limitez la configuration initiale à un LLM pour repérer facilement une erreur de sélection.

Utiliser une adresse accessible depuis le serveur

Dans un conteneur, localhost désigne ce conteneur. Si Router est un service séparé sur le même réseau Compose, utilisez son nom de service et son port interne réels. S’il tourne sur l’hôte, utilisez une adresse d’hôte prise en charge ; sous Linux, une association host-gateway peut être nécessaire. Si Router est distant, utilisez son nom HTTPS accessible.

L’URL de base se termine normalement par /v1. N’y collez pas le point d’accès complet de conversation : le client ajoute lui-même le chemin. Un préfixe de version manquant peut aussi envoyer la requête vers une mauvaise route. En cas de 404, examinez le chemin effectivement demandé avant de modifier les identifiants.

Pour une instance distante partagée, proposez un accès HTTPS à Open WebUI et protégez son administration. Gardez la création du premier compte dans un environnement privé, examinez les réglages d’inscription et d’approbation, puis testez avec un utilisateur ordinaire et un administrateur. Limitez l’accès aux personnes prévues avant de partager l’adresse.

Appliquer les règles d’accès aux deux niveaux

Open WebUI détermine quels utilisateurs et groupes peuvent utiliser ses modèles. Router détermine ce que la clé utilisée en amont peut appeler. Masquer un modèle dans une liste ne remplace pas une restriction sur la clé.

Définissez explicitement les modèles de conversation et de tâches autorisés dans Router. La documentation des restrictions, en anglais, distingue models pour les clés statiques, allowed_models pour les clés dynamiques et les quotas stricts par modèle. Une liste vide ne signifie pas « tout interdire » lorsqu’aucun quota strict par modèle n’est configuré. Les identifiants sont sensibles à la casse.

Avec une connexion serveur partagée, les utilisateurs emploient la même clé client configurée. Leurs comptes Open WebUI distincts ne deviennent pas automatiquement des tenants Router séparés ni des quotas Router indépendants. Prévoyez le budget de requêtes et de tokens pour la charge cumulée, en vous appuyant sur la référence des clés API, en anglais.

Si des services ont besoin de budgets ou de droits différents en amont, prévoyez des clés distinctes et contrôlez qui peut utiliser chaque connexion. Des déploiements séparés peuvent être nécessaires lorsque les responsabilités d’exploitation ou le stockage des données doivent aussi être isolés. Transmettre un en-tête d’identité Open WebUI ne suffit pas à faire authentifier cette personne par Router ni à lui attribuer un budget séparé.

Compter aussi les requêtes invisibles dans la conversation

Une conversation peut déclencher la génération d’un titre, d’étiquettes, de suggestions de suivi ou d’autres tâches en arrière-plan. Un message affiché ne correspond donc pas forcément à une seule requête d’inférence. Réduisez les fonctionnalités facultatives lors du premier test, puis activez-les progressivement en observant le trafic.

La référence de configuration d’Open WebUI, en anglais, décrit TASK_MODEL_EXTERNAL pour les tâches utilisant des modèles compatibles OpenAI, ainsi que des contrôles comme ENABLE_TITLE_GENERATION. Si vous choisissez un modèle de tâches distinct, vérifiez son identifiant exact, ses droits d’accès, sa disponibilité et son quota. Une conversation réussie ne garantit pas la réussite d’une requête de génération de titre.

Après un changement de configuration, vérifiez les valeurs effectivement enregistrées. Lorsque la persistance est activée, des valeurs stockées peuvent prendre le pas sur les variables d’environnement aux démarrages suivants. Désactiver cette persistance change la conservation des modifications faites dans l’interface ; ce n’est pas une correction universelle sans conséquence pour un réglage ignoré.

Vérifier le streaming, les erreurs et les données conservées

Testez une réponse courte, puis une réponse plus longue en streaming dans le navigateur. Vérifiez que les tokens arrivent au fil de la réponse, et non tous à la fin. Si le flux direct fonctionne mais que le navigateur attend, examinez la mise en tampon et les délais d’expiration des proxys. Comparez l’action dans l’interface aux journaux d’audit Router pour identifier le modèle choisi et les requêtes supplémentaires.

Effectuez ensuite des vérifications négatives contrôlées dans un environnement de test : une clé invalide doit échouer, un modèle non autorisé doit être refusé et un moteur indisponible doit produire une erreur identifiable. Un statut HTTP 200 au début du flux ne prouve pas que toute la réponse s’est terminée. Notre guide des métriques d’inférence, en anglais, aide à distinguer les temps de réponse du travail achevé.

Enfin, recréez l’application avec son stockage persistant prévu et vérifiez que la connexion approuvée et une conversation de test sans données sensibles sont conservées. Sauvegardez la base réelle, les fichiers importés, la configuration et les secrets nécessaires selon une méthode cohérente. Testez la restauration séparément avant une mise à jour ; revenir à une image précédente n’annule pas une migration de base de données.

Définir ce que signifie une conversation d’équipe privée

Documentez les points d’accès qui reçoivent les consignes et leur contexte, les responsables de l’application et des sauvegardes, ainsi que les données conservées. Héberger soi-même l’interface ne rend pas privé un modèle externe configuré. Les consignes de confidentialité d’Open WebUI, en anglais, distinguent aussi le masquage des conversations dans l’interface d’administration d’une protection contre l’accès des opérateurs privilégiés aux données stockées.

Laissez les outils, l’import de fichiers, la recherche web et les connexions directes hors du premier déploiement, sauf si leurs accès et leurs chemins de données ont été examinés séparément. Gardez désactivé le transfert arbitraire vers l’API OpenAI. La compatibilité d’une conversation textuelle ne garantit pas celle de la recherche documentaire, de la voix, des appels d’outils ou de tous les paramètres propres aux modèles. Notre guide des API compatibles OpenAI, en anglais, propose une liste de vérification plus large.

Invitez l’équipe après avoir vérifié la découverte des modèles, la fin des réponses en streaming, les refus d’accès, l’usage partagé et la récupération. Conservez les versions, le responsable, les modèles autorisés et les preuves avec le déploiement. Ces informations permettent de mieux évaluer le prochain changement de connexion ou de version qu’une simple capture d’écran d’une réponse réussie.