Intermedio 12 minPiano giornaliero

Open WebUI: sincronizzare una cartella con oikb

Un portatile aperto illumina di verde una scrivania scura.

Importare documenti a mano in una knowledge base di Open WebUI funziona finché la cartella non cambia. Appena diventa viva (procedure aggiornate, note aggiunte, file rimossi), la base si disallinea e il modello risponde basandosi su versioni superate. Sincronizzare una cartella con Open WebUI tramite oikb, lo strumento presentato nella sezione Ecosystem della documentazione ufficiale, serve a correggere questo disallineamento. Questa guida spiega il principio della sincronizzazione incrementale, cosa può eliminare e una procedura prudente: backup, perimetro ristretto, base di prova. Non è stata testata dalla redazione.

Di Mohamed Meguedmi·Agg. 2026-11-18·Testato su Windows, macOS e Linux
!
Questa guida non riporta alcun comando di oikb
La pagina ufficiale docs.openwebui.com/ecosystem/knowledge-base-sync/ è stata consultata dalla redazione il 30/10/2026, ma non è stato possibile rileggerla al momento della stesura (18/11/2026). Anziché riprodurre a memoria una sintassi che potrebbe essere cambiata, questa guida rimanda a quella pagina per l'installazione e le opzioni esatte di oikb. I comandi riportati qui riguardano il backup, il perimetro e i controlli, che non dipendono dallo strumento.

#Perché sincronizzare una cartella con Open WebUI

Una base di conoscenza (Knowledge) di Open WebUI è una raccolta di file suddivisi in passaggi e indicizzati sotto forma di embedding. Quando colleghi questa base a un modello o la citi con # nella chat, Open WebUI cerca i passaggi vicini alla domanda e li aggiunge al contesto. La guida « RAG locale con Ollama senza programmare » descrive in dettaglio questo funzionamento lato interfaccia.

Il problema emerge col tempo. Un file modificato sul disco non viene modificato nella base: Open WebUI conserva la versione importata. Un file eliminato dalla cartella resta interrogabile. Un nuovo file non esiste finché qualcuno non lo importa. Con una cartella di pochi documenti, te la cavi reimportando. Con una cartella di procedure interne o di note che cambia ogni settimana, la reimportazione manuale viene dimenticata e l'assistente cita con sicurezza una procedura abbandonata.

Uno strumento di sincronizzazione automatizza questo lavoro: confronta la cartella con ciò che è già stato inviato e trasmette solo la differenza. È quella che si chiama sincronizzazione incrementale. Il rovescio della medaglia è che uno strumento che aggiunge e sostituisce automaticamente può anche rimuovere automaticamente. È il punto che richiede più attenzione.

#Sincronizzazione incrementale: sorgente, destinazione, stato

Il kit completo per creare il tuo assistente IA.

Approfitta della nostra esperienza e di un percorso guidato per creare il tuo assistente locale e usare la tua IA ogni giorno.

  • Spazio online a vita
  • PDF + file
  • Garanzia di rimborso di 30 giorni

Qualunque sia lo strumento, una sincronizzazione di questo tipo si basa su tre elementi. Capirli ti permette di leggere la documentazione di oikb con le domande giuste in mente.

La sorgente
La cartella locale (o montata) il cui contenuto fa fede. Tutto ciò che contiene, entro il perimetro scelto, è destinato a finire nella base. È quindi lei che va delimitata con cura: una sottocartella personale dimenticata al suo interno verrà indicizzata e diventerà interrogabile da chiunque abbia accesso alla base.
La destinazione
Una specifica base di conoscenza di Open WebUI, su una specifica istanza (URL). Un errore nell'identificativo della base può mescolare due corpus o, peggio, far applicare eliminazioni alla base sbagliata.
L'authentification
Lo strumento agisce tramite l'API di Open WebUI con una chiave legata a un account. Ne eredita i permessi: ciò che l'account può leggere, modificare o eliminare, può farlo anche lo strumento.
Lo stato
Per sapere cosa è cambiato, lo strumento deve tenere traccia di ciò che ha già inviato (impronte del contenuto, date di modifica, corrispondenza tra file locali e file lato Open WebUI), oppure ricostruirla interrogando la base. Se questo stato va perso o si disallinea, lo strumento può reinviare tutto, creare duplicati o interpretare male le assenze.

Con questi elementi, ogni passaggio classifica i file in quattro casi: nuovo (da inviare), modificato (da sostituire), invariato (da ignorare), sparito dalla sorgente (da rimuovere dalla base, o da lasciare, a seconda dell'impostazione). Prima di lanciare oikb, cerca nella sua documentazione la risposta a quattro domande: come rileva una modifica, dove salva il suo stato, se rimuove i file spariti e con quale opzione, e se offre una modalità di simulazione che mostra le azioni senza eseguirle.

#Il vero rischio: le eliminazioni a specchio

Una sincronizzazione che rimuove dalla base i file assenti dalla sorgente è utile: è proprio lei a far sparire la procedura abbandonata. Ma trasforma qualsiasi errore lato sorgente in una perdita lato base. Alcuni scenari realistici:

Disco non montato
La cartella punta a una condivisione di rete o a un disco esterno assente al momento dell'esecuzione. Il punto di montaggio è vuoto: per lo strumento, tutti i file sono scomparsi.
Percorso errato
Un errore di battitura o un cambio della directory di lavoro fa puntare la sorgente a una cartella vuota o diversa.
Riorganizzazione
Rinominare o spostare sottocartelle può essere interpretato come « eliminare tutto e poi ricreare tutto ». Il risultato finale può essere corretto, ma la base viene reindicizzata interamente e gli eventuali link ai vecchi file vanno persi.
Base condivisa
Se altre persone hanno aggiunto file a mano nella stessa base, uno strumento a specchio rigoroso può considerare quei file estranei alla sorgente e rimuoverli. Verifica nella documentazione se oikb tocca solo i file che ha inviato lui stesso.

Ne derivano due regole. Innanzitutto, una base sincronizzata deve essere riservata alla sincronizzazione: niente aggiunte manuali al suo interno. In secondo luogo, finché non hai osservato il comportamento dello strumento su una base di prova, non attivare l'eliminazione sulla base che usi quotidianamente.

#Prerequisiti

Open WebUI funzionante
Un'istanza aggiornata collegata a Ollama (per impostazione predefinita su http://localhost:11434), con un modello di embedding configurato. La guida « Open WebUI avec Ollama: guide complet » tratta l'installazione.
Un account dedicato
Idealmente un account utente creato per la sincronizzazione, proprietario della base, anziché l'account amministratore. Il perimetro della chiave si limita così a ciò di cui questo account ha bisogno.
Le chiavi API autorizzate
A seconda della versione, l'amministratore deve attivare le chiavi API nelle impostazioni di amministrazione prima che un utente possa generarne una da Impostazioni > Account. Le diciture esatte variano: fai riferimento alla tua versione.
Un backup recente
Un archivio verificato del volume Docker di Open WebUI. È l'unico vero modo per tornare indietro se la base viene svuotata per errore.
I prerequisiti specifici di oikb
Linguaggio, versione e metodo di installazione sono indicati nella pagina ufficiale. Non darli per scontati.

#Sincronizzare una cartella con Open WebUI: la procedura in 5 passi

  1. 01
    1. Fare il backup dell'istanza
    Arresta il container, archivia il volume, riavvia e calcola un hash. La procedura completa, con il ripristino, è nella guida «Ripristinare Open WebUI e Ollama dopo un guasto». Un backup mai ripristinato resta un'ipotesi: testalo almeno una volta su un'istanza di controllo.
  2. 02
    2. Delimitare il perimetro
    Non puntare oikb sull'intera cartella Documenti. Prepara una cartella di pubblicazione che contenga solo i file destinati alla base, in formati che Open WebUI sa estrarre (testo, Markdown, PDF testuali, ecc.). Fanne l'inventario: è il tuo riferimento per verificare poi cosa è arrivato nella base.
  3. 03
    3. Creare una base di prova e una chiave
    In Area di lavoro > Conoscenza, crea una base chiamata ad esempio «essai-sync». Il suo identificativo compare nell'indirizzo della pagina della base. Genera la chiave API dell'account di sincronizzazione, salvala in un file leggibile solo da te e verifica che funzioni con una semplice chiamata.
  4. 04
    4. Primo passaggio sulla base di prova
    Installa oikb e avvialo seguendo la pagina ufficiale, con la base di prova come destinazione, senza eliminazioni e in modalità simulazione se lo strumento ne offre una. Leggi l'elenco delle azioni previste prima di lanciare il passaggio reale. Poi confronta il numero di file nella base con il tuo inventario.
  5. 05
    5. Mettere alla prova i casi limite, poi passare alla base reale
    Sulla base di prova: modifica un file, aggiungine uno, eliminane uno e rilancia. Verifica che venga sostituito solo il file modificato e che il file eliminato venga gestito come indicato nella documentazione. Poi svuota temporaneamente la sorgente (rinomina la cartella) e osserva cosa lo strumento prevede di fare: è il test del disco non montato. Solo dopo, punta oikb sulla base reale.

Il passaggio 2 può appoggiarsi a rsync per costruire la cartella di pubblicazione a partire da una cartella di lavoro, mantenendo solo determinate estensioni. L'esempio qui sotto copia i file Markdown e PDF, conserva la struttura delle cartelle e ignora tutto il resto. Non usa --delete: un file rimosso dalla cartella di lavoro resta nella cartella di pubblicazione finché non lo rimuovi tu, il che lascia una decisione umana prima di qualsiasi eliminazione lato base.

Terminale — passo 2: cartella di pubblicazione e inventario
# 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

Per il passaggio 3, puoi testare la chiave senza modificare nulla. L'API di Open WebUI accetta una chiave nell'header Authorization: Bearer; la chiamata qui sotto elenca i modelli visibili dall'account. Una risposta JSON conferma che l'URL e la chiave sono corretti; un errore 401 o 403 indica una chiave non valida oppure chiavi API non autorizzate dall'amministratore.

Terminale — passo 3: chiave fuori dalla cronologia e test in lettura
# 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"

La porta 3000 corrisponde al comando Docker più comune (-p 3000:8080); adattala alla tua installazione. Il modo in cui oikb legge la chiave (variabile d'ambiente, opzione, file di configurazione) è descritto nella sua documentazione: preferisci una variabile o un file alle opzioni da riga di comando, che restano visibili nell'elenco dei processi e nella cronologia.

→
Una base per ogni sorgente
Associa una cartella di pubblicazione a una sola base e dai a entrambe lo stesso nome («procedures-qualite» per la cartella e per la base). Se hai dubbi sulla destinazione di un passaggio, il nome basta a individuare l'errore prima che si propaghi.

#Automatizzare la sincronizzazione senza esporsi

Una volta osservato il comportamento sulla base di prova, la tentazione è pianificare l'esecuzione ogni ora. Prima di farlo, aggiungi alcune protezioni che non dipendono dallo strumento.

Verificare la sorgente prima di ogni esecuzione
Uno script che si rifiuta di avviare la sincronizzazione se la cartella di pubblicazione è vuota o se il suo numero di file cala bruscamente rispetto all'ultimo inventario. È la protezione più semplice contro il disco non montato.
Tenere un registro
Reindirizzare l'output di ogni esecuzione verso un file datato. In caso di risposta sorprendente dell'assistente, il log indica quando un file è entrato o uscito dalla base.
Distanziare le esecuzioni
Per documenti che cambiano qualche volta alla settimana, un'esecuzione quotidiana è sufficiente e riduce il carico di indicizzazione sulla macchina che calcola gli embedding.
Fare il backup prima, non solo dopo
Un backup regolare del volume, indipendente dalla sincronizzazione. Se un passaggio svuota la base, il ripristino recupera anche gli embedding senza dover reindicizzare tutto.
Terminale — protezione prima dell'esecuzione
#!/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é.

Questo script volutamente non contiene il comando oikb: riprendilo dalla pagina ufficiale e incollalo nel punto indicato. La soglia MIN è arbitraria; un controllo più fine confronta il numero di file con l'ultimo inventario e rifiuta un calo superiore a una certa proporzione.

#Risoluzione dei problemi

401 o 403 sull'API
Chiave scaduta, revocata o copiata con uno spazio. Verifica anche che l'amministratore autorizzi le chiavi API e che l'account abbia accesso alla base interessata.
File inviati ma introvabili nella chat
Invio e indicizzazione sono due fasi distinte. Un PDF scansionato senza livello di testo può essere accettato senza produrre passaggi utilizzabili. Apri il file nella base per vedere il testo estratto; passa le scansioni attraverso un OCR prima di pubblicarle.
Duplicati nella base
Segnale frequente di uno stato perso o di un primo passaggio lanciato su una base che conteneva già gli stessi file importati a mano. Riparti da una base vuota riservata alla sincronizzazione.
Reindicizzazione lunga
Cambiare modello di embedding nelle impostazioni di Open WebUI richiede di reindicizzare i documenti. Evita di modificare questa impostazione e la sincronizzazione contemporaneamente: non sapresti più quale delle due ha causato una discrepanza.
Risposte ancora datate
Verifica nella base che la vecchia versione sia stata effettivamente sostituita e non aggiunta accanto. Apri una nuova conversazione: i passaggi già citati in una conversazione esistente restano nella sua cronologia.

#Cosa è stato verificato e cosa no

Per questa guida non è stata effettuata alcuna prova di oikb: nessuna installazione, nessuna esecuzione, nessuna misurazione di durata o di volume. La pagina di documentazione ufficiale è stata consultata il 30/10/2026 durante la preparazione dell'argomento, poi non è stato possibile rileggerla il 18/11/2026. I comandi di backup riprendono quelli della guida al ripristino del sito; il test della chiave usa l'header Bearer e la route /api/models dell'API di Open WebUI, da confermare sulla tua versione. Le domande da porre alla documentazione (rilevamento delle modifiche, stato, eliminazioni, simulazione) sono criteri generali, non una descrizione del funzionamento di oikb.

i
Parola chiave e dati di ricerca
L'argomento è stato scelto il 30/10/2026 a partire dalla query « open webui synchroniser dossier ». Lo strumento di rilevazione (DataForSEO, Google Ads, Francia) non ha restituito alcun valore di volume: l'interesse per la query non è né confermato né quantificato.

#Per approfondire

RAG locale con Ollama senza scrivere codice
Come funzionano le basi di conoscenza di Open WebUI lato interfaccia, e quando preferire AnythingLLM: https://quelllm.fr/guide/rag-local-ollama-sans-coder
Ripristinare Open WebUI e Ollama dopo un guasto
Backup del volume, ripristino e istanza di controllo, prerequisiti del passo 1: https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
Open WebUI con Ollama: guida completa
Installazione e impostazioni di base dell'interfaccia: https://quelllm.fr/guide/open-webui-ollama-tutoriel
Fonte primaria
Open WebUI, documentazione Ecosystem, Knowledge Base Sync: https://docs.openwebui.com/ecosystem/knowledge-base-sync/ (consultata il 30/10/2026, non riletta il 18/11/2026).
Questa guida ti è stata utile?

Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.