Intermédiaire 12 minPlan quotidien

Open WebUI : synchroniser un dossier avec oikb

Un ordinateur portable ouvert éclaire un bureau sombre d’une lumière verte.

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.

Par Mohamed Meguedmi·Màj 2026-11-18·Testé sur Windows, macOS, Linux
!
Ce guide ne recopie aucune commande oikb
La page officielle docs.openwebui.com/ecosystem/knowledge-base-sync/ a été consultée par la rédaction le 30/10/2026, mais n'a pas pu être relue au moment d'écrire (18/11/2026). Plutôt que de reproduire de mémoire une syntaxe qui a pu changer, ce guide renvoie à cette page pour l'installation et les options exactes d'oikb. Les commandes données ici concernent la sauvegarde, le périmètre et les contrôles, qui ne dépendent pas de l'outil.

#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

Le kit complet pour créer ton propre assistant IA.

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

  1. 01
    1. Sauvegarder l'instance
    Arrê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.
  2. 02
    2. Délimiter le périmètre
    Ne 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.
  3. 03
    3. 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.
  4. 04
    4. Premier passage sur la base d'essai
    Installez 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.
  5. 05
    5. Éprouver les cas limites, puis basculer
    Sur 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.

Terminal — étape 2 : dossier de publication et inventaire
# Dossier de travail (à adapter) et dossier réservé à la synchronisation
SOURCE=~/Documents/procedures/
PUBLI=~/oikb-publication/
mkdir -p "$PUBLI"

# Simulation d'abord (-n), puis relancer sans -n
rsync -avn --prune-empty-dirs \
  --include='*/' --include='*.md' --include='*.pdf' --exclude='*' \
  "$SOURCE" "$PUBLI"

# Inventaire daté avec empreintes, à garder avec la sauvegarde
cd "$PUBLI" && find . -type f -print0 | sort -z | xargs -0 sha256sum \
  > ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt
wc -l ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt

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.

Terminal — étape 3 : clé hors historique et test en lecture
# Clé dans un fichier privé, pas dans l'historique du shell
install -m 600 /dev/null ~/.config/oikb-cle
${EDITOR:-nano} ~/.config/oikb-cle

U=http://localhost:3000
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $(cat ~/.config/oikb-cle)" \
  "$U/api/models"

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.

→
Une base par source
Associez un dossier de publication à une seule base, et nommez les deux de la même façon (« procedures-qualite » pour le dossier et la base). En cas de doute sur la destination d'un passage, le nom suffit à repérer l'erreur avant qu'elle ne se propage.

#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.
Terminal — garde-fou avant passage
#!/usr/bin/env bash
set -euo pipefail
PUBLI=~/oikb-publication
MIN=10   # seuil à adapter : en dessous, on refuse

N=$(find "$PUBLI" -type f | wc -l)
if [ "$N" -lt "$MIN" ]; then
  echo "$(date -Is) source suspecte : $N fichiers, passage annulé" >&2
  exit 1
fi

# Lancer ici la commande oikb indiquée par la documentation officielle,
# en redirigeant sa sortie vers un journal daté.

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.

i
Mot-clé et données de recherche
Le sujet a été retenu le 30/10/2026 sur la requête « open webui synchroniser dossier ». L'outil de relevé (DataForSEO, Google Ads, France) n'a renvoyé aucune valeur de volume : l'intérêt de la requête n'est ni confirmé ni chiffré.

#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).
Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.