Open WebUI: sincronizzare una cartella con oikb

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.
#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
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
- 011. Fare il backup dell'istanzaArresta 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.
- 022. Delimitare il perimetroNon 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.
- 033. Creare una base di prova e una chiaveIn 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.
- 044. Primo passaggio sulla base di provaInstalla 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.
- 055. Mettere alla prova i casi limite, poi passare alla base realeSulla 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.
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.
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.
#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.
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.
#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).
Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.