Open WebUI : synchroniser un dossier avec oikb

Importer des documents à la main dans une base de connaissances Open WebUI fonctionne tant que le dossier ne bouge pas. Dès qu'il vit (procédures mises à jour, notes ajoutées, fichiers retirés), la base dérive et le modèle répond sur des versions périmées. Synchroniser un dossier avec Open WebUI via oikb, l'outil présenté dans la rubrique Ecosystem de la documentation officielle, vise à corriger cette dérive. Ce guide explique le principe de la synchronisation incrémentale, ce qu'elle peut supprimer, et une procédure prudente : sauvegarde, périmètre restreint, base d'essai. Il n'a pas été testé par la rédaction.
#Pourquoi synchroniser un dossier avec Open WebUI
Une base de connaissances (Knowledge) d'Open WebUI est une collection de fichiers découpés en passages et indexés sous forme d'embeddings. Quand vous rattachez cette base à un modèle ou que vous la citez avec # dans le chat, Open WebUI va chercher les passages proches de la question et les ajoute au contexte. Le guide « RAG local avec Ollama sans coder » détaille ce fonctionnement côté interface.
Le problème apparaît avec le temps. Un fichier modifié sur le disque n'est pas modifié dans la base : Open WebUI conserve la version importée. Un fichier supprimé du dossier reste interrogeable. Un nouveau fichier n'existe pas tant que personne ne l'importe. Sur un dossier de quelques documents, on s'en sort en réimportant. Sur un dossier de procédures internes ou de notes qui change chaque semaine, la réimportation manuelle est oubliée, et l'assistant cite avec assurance une procédure abandonnée.
Un outil de synchronisation automatise ce travail : il compare le dossier à ce qui a déjà été envoyé et ne transmet que la différence. C'est ce qu'on appelle une synchronisation incrémentale. La contrepartie est qu'un outil qui ajoute et remplace automatiquement peut aussi retirer automatiquement. C'est le point qui demande le plus d'attention.
#Synchronisation incrémentale : source, destination, état
Profite de notre expérience et d’un parcours guidé pour créer ton assistant local et utiliser ton IA au quotidien.
- Espace en ligne à vie
- PDF + fichiers
- Remboursé 30 j
Quel que soit l'outil, une synchronisation de ce type repose sur trois éléments. Les comprendre permet de lire la documentation d'oikb avec les bonnes questions en tête.
- La source
- Le dossier local (ou monté) dont le contenu fait foi. Tout ce qui s'y trouve, dans le périmètre retenu, a vocation à finir dans la base. C'est donc lui qu'il faut délimiter avec soin : un sous-dossier personnel oublié dedans sera indexé et deviendra interrogeable par tous ceux qui ont accès à la base.
- La destination
- Une base de connaissances précise d'Open WebUI, sur une instance précise (URL). Une erreur d'identifiant de base peut mélanger deux corpus, ou pire, faire appliquer des suppressions à la mauvaise base.
- L'authentification
- L'outil agit à travers l'API d'Open WebUI avec une clé liée à un compte. Il hérite des droits de ce compte : ce que le compte peut lire, modifier ou supprimer, l'outil le peut aussi.
- L'état
- Pour savoir ce qui a changé, l'outil doit garder une trace de ce qu'il a déjà envoyé (empreintes de contenu, dates de modification, correspondance entre fichiers locaux et fichiers côté Open WebUI), ou la reconstruire en interrogeant la base. Si cet état est perdu ou désaligné, l'outil peut tout renvoyer, créer des doublons ou mal interpréter des absences.
Avec ces éléments, chaque passage classe les fichiers en quatre cas : nouveau (à envoyer), modifié (à remplacer), inchangé (à ignorer), disparu de la source (à retirer de la base, ou à laisser, selon le réglage). Avant de lancer oikb, cherchez dans sa documentation la réponse à quatre questions : comment il détecte une modification, où il stocke son état, s'il retire les fichiers disparus et sous quelle option, et s'il propose un mode de simulation qui affiche les actions sans les exécuter.
#Le vrai risque : les suppressions en miroir
Une synchronisation qui retire de la base les fichiers absents de la source est utile : c'est elle qui fait disparaître la procédure abandonnée. Mais elle transforme toute erreur côté source en perte côté base. Quelques scénarios réalistes :
- Disque non monté
- Le dossier pointe vers un partage réseau ou un disque externe absent au moment du passage. Le point de montage est vide : pour l'outil, tous les fichiers ont disparu.
- Mauvais chemin
- Une faute de frappe ou un changement de répertoire de travail fait pointer la source vers un dossier vide ou différent.
- Réorganisation
- Renommer ou déplacer des sous-dossiers peut être vu comme « tout supprimer puis tout recréer ». Le résultat final peut être correct, mais la base est réindexée entièrement et les liens éventuels vers les anciens fichiers sont perdus.
- Base partagée
- Si d'autres personnes ont ajouté des fichiers à la main dans la même base, un outil en miroir strict peut considérer ces fichiers comme étrangers à la source et les retirer. Vérifiez dans la documentation si oikb ne touche que les fichiers qu'il a lui-même envoyés.
Deux règles en découlent. D'abord, une base synchronisée doit être réservée à la synchronisation : pas d'ajouts manuels dedans. Ensuite, tant que vous n'avez pas observé le comportement de l'outil sur une base d'essai, n'activez pas la suppression sur la base utilisée au quotidien.
#Prérequis
- Open WebUI fonctionnel
- Une instance à jour connectée à Ollama (par défaut sur http://localhost:11434), avec un modèle d'embeddings configuré. Le guide « Open WebUI avec Ollama : guide complet » couvre l'installation.
- Un compte dédié
- Idéalement un compte utilisateur créé pour la synchronisation, propriétaire de la base, plutôt que le compte administrateur. Le périmètre de la clé se limite alors à ce dont ce compte a besoin.
- Les clés d'API autorisées
- Selon les versions, l'administrateur doit activer les clés d'API dans les réglages d'administration avant qu'un utilisateur puisse en générer une depuis Réglages > Compte. Les intitulés exacts varient : reportez-vous à votre version.
- Une sauvegarde récente
- Une archive du volume Docker d'Open WebUI, vérifiée. C'est le seul vrai retour arrière si la base est vidée par erreur.
- Les prérequis propres à oikb
- Langage, version et méthode d'installation sont indiqués sur la page officielle. Ne pas les supposer.
#Synchroniser un dossier avec Open WebUI : la procédure en 5 étapes
- 011. Sauvegarder l'instanceArrêtez le conteneur, archivez le volume, redémarrez, calculez une empreinte. La procédure complète, avec la restauration, est dans le guide « Restaurer Open WebUI et Ollama après une panne ». Une sauvegarde jamais restaurée reste une hypothèse : testez-la au moins une fois sur une instance de contrôle.
- 022. Délimiter le périmètreNe pointez pas oikb sur votre dossier Documents entier. Préparez un dossier de publication qui ne contient que les fichiers destinés à la base, avec des formats qu'Open WebUI sait extraire (texte, Markdown, PDF texte, etc.). Inventoriez-le : c'est votre référence pour vérifier ensuite ce qui est arrivé dans la base.
- 033. Créer une base d'essai et une cléDans Espace de travail > Connaissances, créez une base nommée par exemple « essai-sync ». Son identifiant apparaît dans l'adresse de la page de la base. Générez la clé d'API du compte de synchronisation, stockez-la dans un fichier lisible par vous seul, et vérifiez qu'elle fonctionne avec un appel simple.
- 044. Premier passage sur la base d'essaiInstallez oikb et lancez-le selon la page officielle, avec pour destination la base d'essai, sans suppression, et en mode simulation si l'outil en propose un. Lisez la liste des actions annoncées avant de lancer le passage réel. Comparez ensuite le nombre de fichiers dans la base avec votre inventaire.
- 055. Éprouver les cas limites, puis basculerSur la base d'essai : modifiez un fichier, ajoutez-en un, supprimez-en un, relancez. Vérifiez que seul le fichier modifié est remplacé et que le fichier supprimé est traité comme la documentation l'annonce. Videz ensuite temporairement la source (renommez le dossier) et observez ce que l'outil prévoit de faire : c'est le test du disque non monté. Seulement après, pointez oikb sur la base réelle.
L'étape 2 peut s'appuyer sur rsync pour construire le dossier de publication à partir d'un dossier de travail, en ne gardant que certaines extensions. L'exemple ci-dessous copie les fichiers Markdown et PDF, conserve l'arborescence et ignore tout le reste. Il n'utilise pas --delete : un fichier retiré du dossier de travail reste dans le dossier de publication jusqu'à ce que vous le retiriez, ce qui laisse une décision humaine avant toute suppression côté base.
Pour l'étape 3, la clé se teste sans rien modifier. L'API d'Open WebUI accepte une clé en en-tête Authorization: Bearer ; l'appel ci-dessous liste les modèles visibles par le compte. Une réponse JSON confirme que l'URL et la clé sont bonnes ; une erreur 401 ou 403 indique une clé invalide ou des clés d'API non autorisées par l'administrateur.
Le port 3000 correspond à la commande Docker la plus courante (-p 3000:8080) ; adaptez-le à votre installation. La manière dont oikb lit la clé (variable d'environnement, option, fichier de configuration) est décrite dans sa documentation : préférez une variable ou un fichier aux options de ligne de commande, qui restent visibles dans la liste des processus et l'historique.
#Automatiser la synchronisation sans s'exposer
Une fois le comportement observé sur la base d'essai, la tentation est de planifier le passage toutes les heures. Avant cela, ajoutez quelques garde-fous qui ne dépendent pas de l'outil.
- Vérifier la source avant chaque passage
- Un script qui refuse de lancer la synchronisation si le dossier de publication est vide ou si son nombre de fichiers chute brutalement par rapport au dernier inventaire. C'est la protection la plus simple contre le disque non monté.
- Garder un journal
- Rediriger la sortie de chaque passage vers un fichier daté. En cas de réponse surprenante de l'assistant, le journal indique quand un fichier est entré ou sorti de la base.
- Espacer les passages
- Pour des documents qui changent quelques fois par semaine, un passage quotidien suffit et réduit la charge d'indexation sur la machine qui calcule les embeddings.
- Sauvegarder avant, pas seulement après
- Une sauvegarde régulière du volume, indépendante de la synchronisation. Si un passage vide la base, la restauration remet aussi les embeddings sans tout réindexer.
Ce script ne contient volontairement pas la commande oikb : reprenez-la depuis la page officielle et collez-la à l'endroit indiqué. Le seuil MIN est arbitraire ; un contrôle plus fin compare le nombre de fichiers au dernier inventaire et refuse une baisse de plus d'une certaine proportion.
#Dépannage
- 401 ou 403 sur l'API
- Clé expirée, révoquée ou copiée avec un espace. Vérifiez aussi que l'administrateur autorise les clés d'API et que le compte a accès à la base visée.
- Fichiers envoyés mais introuvables dans le chat
- L'envoi et l'indexation sont deux étapes. Un PDF scanné sans couche texte peut être accepté sans produire de passages exploitables. Ouvrez le fichier dans la base pour voir le texte extrait ; passez les scans par un OCR avant de les publier.
- Doublons dans la base
- Signe fréquent d'un état perdu ou d'un premier passage lancé sur une base qui contenait déjà les mêmes fichiers importés à la main. Repartez d'une base vide réservée à la synchronisation.
- Réindexation longue
- Changer de modèle d'embeddings dans les réglages d'Open WebUI impose de réindexer les documents. Évitez de modifier ce réglage et la synchronisation en même temps : vous ne sauriez plus laquelle a causé un écart.
- Réponses toujours anciennes
- Vérifiez dans la base que l'ancienne version a bien été remplacée et non ajoutée à côté. Ouvrez une nouvelle conversation : les passages déjà cités dans une conversation existante restent dans son historique.
#Ce qui a été vérifié, et ce qui ne l'a pas été
Aucun essai d'oikb n'a été réalisé pour ce guide : pas d'installation, pas de passage, pas de mesure de durée ou de volume. La page de documentation officielle a été consultée le 30/10/2026 lors de la préparation du sujet, puis n'a pas pu être relue le 18/11/2026. Les commandes de sauvegarde reprennent celles du guide de restauration du site ; le test de clé utilise l'en-tête Bearer et la route /api/models de l'API d'Open WebUI, à confirmer sur votre version. Les questions à poser à la documentation (détection des changements, état, suppressions, simulation) sont des critères généraux, pas une description du fonctionnement d'oikb.
#Pour aller plus loin
- RAG local avec Ollama sans coder
- Comment fonctionnent les bases de connaissances d'Open WebUI côté interface, et quand préférer AnythingLLM : https://quelllm.fr/guide/rag-local-ollama-sans-coder
- Restaurer Open WebUI et Ollama après une panne
- Sauvegarde du volume, restauration et instance de contrôle, prérequis de l'étape 1 : https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
- Open WebUI avec Ollama : guide complet
- Installation et réglages de base de l'interface : https://quelllm.fr/guide/open-webui-ollama-tutoriel
- Source primaire
- Open WebUI, documentation Ecosystem, Knowledge Base Sync : https://docs.openwebui.com/ecosystem/knowledge-base-sync/ (consultée le 30/10/2026, non relue le 18/11/2026).
Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.