Intermedio 12 minPlan diario

Open WebUI: sincronizar una carpeta con oikb

Un portátil abierto ilumina con luz verde un escritorio oscuro.

Importar documentos a mano en una base de conocimiento de Open WebUI funciona mientras la carpeta no cambie. En cuanto evoluciona (procedimientos actualizados, notas añadidas, archivos retirados), la base se desfasa y el modelo responde con versiones obsoletas. Sincronizar una carpeta con Open WebUI mediante oikb, la herramienta presentada en la sección Ecosystem de la documentación oficial, busca corregir ese desfase. Esta guía explica el principio de la sincronización incremental, lo que puede eliminar y un procedimiento prudente: copia de seguridad, alcance restringido y base de prueba. La redacción no lo ha probado.

Por Mohamed Meguedmi·Actualización 2026-11-18·Probado en Windows, macOS y Linux
!
Esta guía no reproduce ningún comando de oikb
La redacción consultó la página oficial docs.openwebui.com/ecosystem/knowledge-base-sync/ el 30/10/2026, pero no pudo volver a revisarla en el momento de escribir (18/11/2026). En lugar de reproducir de memoria una sintaxis que puede haber cambiado, esta guía remite a esa página para la instalación y las opciones exactas de oikb. Los comandos que se dan aquí se refieren a la copia de seguridad, el alcance y las comprobaciones, que no dependen de la herramienta.

#Por qué sincronizar una carpeta con Open WebUI

Una base de conocimiento (Knowledge) de Open WebUI es una colección de archivos divididos en fragmentos e indexados en forma de embeddings. Cuando vinculas esta base a un modelo o la mencionas con # en el chat, Open WebUI busca los fragmentos cercanos a la pregunta y los añade al contexto. La guía «RAG local con Ollama sin programar» detalla este funcionamiento desde la interfaz.

El problema aparece con el tiempo. Un archivo modificado en el disco no se modifica en la base: Open WebUI conserva la versión importada. Un archivo eliminado de la carpeta sigue pudiendo consultarse. Un archivo nuevo no existe mientras nadie lo importe. Con una carpeta de pocos documentos, basta con volver a importarlos. Con una carpeta de procedimientos internos o de notas que cambia cada semana, la reimportación manual se olvida y el asistente cita con total seguridad un procedimiento abandonado.

Una herramienta de sincronización automatiza este trabajo: compara la carpeta con lo que ya se ha enviado y solo transmite la diferencia. Es lo que se llama sincronización incremental. La contrapartida es que una herramienta que añade y reemplaza automáticamente también puede retirar automáticamente. Es el punto que exige más atención.

#Sincronización incremental: origen, destino, estado

El kit completo para crear tu propio asistente de IA.

Aprovecha nuestra experiencia y un recorrido guiado para crear tu asistente local y usar tu IA en el día a día.

  • Espacio en línea de por vida
  • PDF + archivos
  • Reembolsado 30 d

Sea cual sea la herramienta, una sincronización de este tipo se basa en tres elementos. Entenderlos te permite leer la documentación de oikb con las preguntas adecuadas en mente.

El origen
La carpeta local (o montada) cuyo contenido es la referencia. Todo lo que contiene, dentro del alcance definido, está destinado a acabar en la base. Por eso es la que hay que delimitar con cuidado: una subcarpeta personal olvidada dentro se indexará y podrá consultarla cualquiera que tenga acceso a la base.
El destino
Una base de conocimiento concreta de Open WebUI, en una instancia concreta (URL). Un error en el identificador de la base puede mezclar dos corpus o, peor aún, hacer que las eliminaciones se apliquen a la base equivocada.
L'authentification
La herramienta actúa a través de la API de Open WebUI con una clave vinculada a una cuenta. Hereda los permisos de esa cuenta: lo que la cuenta puede leer, modificar o eliminar, también puede hacerlo la herramienta.
El estado
Para saber qué ha cambiado, la herramienta debe guardar un registro de lo que ya ha enviado (huellas de contenido, fechas de modificación, correspondencia entre archivos locales y archivos en Open WebUI), o reconstruirlo consultando la base. Si ese estado se pierde o se desalinea, la herramienta puede volver a enviarlo todo, crear duplicados o interpretar mal las ausencias.

Con estos elementos, cada pasada clasifica los archivos en cuatro casos: nuevo (para enviar), modificado (para reemplazar), sin cambios (para ignorar) y desaparecido del origen (para retirar de la base o dejar, según la configuración). Antes de ejecutar oikb, busca en su documentación la respuesta a cuatro preguntas: cómo detecta una modificación, dónde almacena su estado, si retira los archivos desaparecidos y con qué opción, y si ofrece un modo de simulación que muestre las acciones sin ejecutarlas.

#El verdadero riesgo: las eliminaciones en espejo

Una sincronización que elimina de la base los archivos ausentes en el origen es útil: es la que hace desaparecer el procedimiento abandonado. Pero convierte cualquier error en el origen en una pérdida en la base. Algunos escenarios realistas:

Disco no montado
La carpeta apunta a un recurso compartido de red o a un disco externo que no está disponible en el momento de la ejecución. El punto de montaje está vacío: para la herramienta, todos los archivos han desaparecido.
Ruta incorrecta
Un error tipográfico o un cambio de directorio de trabajo hace que el origen apunte a una carpeta vacía o distinta.
Reorganización
Renombrar o mover subcarpetas puede interpretarse como «eliminarlo todo y volver a crearlo todo». El resultado final puede ser correcto, pero la base se reindexa por completo y se pierden los posibles enlaces a los archivos antiguos.
Base compartida
Si otras personas han añadido archivos a mano en la misma base, una herramienta en modo espejo estricto puede considerar esos archivos ajenos a la origen y eliminarlos. Comprueba en la documentación si oikb solo toca los archivos que ella misma ha enviado.

De ahí se derivan dos reglas. Primero, una base sincronizada debe reservarse a la sincronización: nada de añadir archivos manualmente en ella. Segundo, mientras no hayas observado el comportamiento de la herramienta en una base de prueba, no actives la eliminación en la base que usas a diario.

#Prerrequisitos

Open WebUI operativo
Una instancia actualizada conectada a Ollama (por defecto en http://localhost:11434), con un modelo de embeddings configurado. La guía «Open WebUI con Ollama: guía completa» cubre la instalación.
Una cuenta dedicada
Idealmente, una cuenta de usuario creada para la sincronización y propietaria de la base, en lugar de la cuenta de administrador. Así, el alcance de la clave se limita a lo que esa cuenta necesita.
Las claves de API autorizadas
Según la versión, el administrador debe activar las claves de API en los ajustes de administración antes de que un usuario pueda generar una desde Ajustes > Cuenta. Los nombres exactos varían: consulta tu versión.
Una copia de seguridad reciente
Un archivo comprimido del volumen Docker de Open WebUI, verificado. Es la única forma real de dar marcha atrás si la base se vacía por error.
Los requisitos propios de oikb
El lenguaje, la versión y el método de instalación se indican en la página oficial. No los supongas.

#Sincronizar una carpeta con Open WebUI: el procedimiento en 5 pasos

  1. 01
    1. Hacer una copia de seguridad de la instancia
    Detén el contenedor, archiva el volumen, reinicia y calcula una huella. El procedimiento completo, con la restauración, está en la guía «Restaurar Open WebUI y Ollama tras una avería». Una copia de seguridad que nunca se ha restaurado sigue siendo una hipótesis: pruébala al menos una vez en una instancia de control.
  2. 02
    2. Delimitar el alcance
    No apuntes oikb a toda tu carpeta Documentos. Prepara una carpeta de publicación que contenga solo los archivos destinados a la base, en formatos que Open WebUI sepa extraer (texto, Markdown, PDF con texto, etc.). Haz un inventario: es tu referencia para comprobar después lo que ha llegado a la base.
  3. 03
    3. Crear una base de prueba y una clave
    En Espacio de trabajo > Conocimiento, crea una base llamada, por ejemplo, «essai-sync». Su identificador aparece en la dirección de la página de la base. Genera la clave de API de la cuenta de sincronización, guárdala en un archivo que solo tú puedas leer y comprueba que funciona con una llamada sencilla.
  4. 04
    4. Primera pasada sobre la base de prueba
    Instala oikb y ejecútalo según la página oficial, con la base de prueba como destino, sin eliminaciones y en modo de simulación si la herramienta lo ofrece. Lee la lista de acciones anunciadas antes de lanzar la pasada real. Después, compara el número de archivos de la base con tu inventario.
  5. 05
    5. Probar los casos límite y luego hacer el cambio
    En la base de prueba: modifica un archivo, añade otro, elimina otro y vuelve a ejecutar. Comprueba que solo se reemplaza el archivo modificado y que el archivo eliminado se trata como indica la documentación. Después, vacía temporalmente el origen (cambia el nombre de la carpeta) y observa lo que la herramienta prevé hacer: es la prueba del disco no montado. Solo después, apunta oikb a la base real.

El paso 2 puede apoyarse en rsync para construir la carpeta de publicación a partir de una carpeta de trabajo, conservando solo ciertas extensiones. El ejemplo siguiente copia los archivos Markdown y PDF, conserva la estructura de directorios e ignora todo lo demás. No usa --delete: un archivo eliminado de la carpeta de trabajo permanece en la carpeta de publicación hasta que lo quites, lo que deja una decisión humana antes de cualquier eliminación en la base.

Terminal — paso 2: carpeta de publicación 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

Para el paso 3, puedes probar la clave sin modificar nada. La API de Open WebUI acepta una clave en el encabezado Authorization: Bearer; la llamada de abajo lista los modelos visibles para la cuenta. Una respuesta JSON confirma que la URL y la clave son correctas; un error 401 o 403 indica una clave no válida o que el administrador no ha autorizado las claves de API.

Terminal — paso 3: clave fuera del historial y prueba de lectura
# 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"

El puerto 3000 corresponde al comando Docker más habitual (-p 3000:8080); adáptalo a tu instalación. La forma en que oikb lee la clave (variable de entorno, opción, archivo de configuración) se describe en su documentación: es preferible una variable o un archivo antes que las opciones de línea de comandos, que quedan visibles en la lista de procesos y en el historial.

→
Una base por origen
Asocia cada carpeta de publicación a una sola base y ponles el mismo nombre a ambas («procedures-qualite» para la carpeta y la base). Si tienes dudas sobre el destino de una pasada, el nombre basta para detectar el error antes de que se propague.

#Automatizar la sincronización sin exponerse

Una vez observado el comportamiento en la base de prueba, la tentación es programar la ejecución cada hora. Antes de eso, añade algunas salvaguardas que no dependan de la herramienta.

Comprobar el origen antes de cada ejecución
Un script que se niega a lanzar la sincronización si la carpeta de publicación está vacía o si su número de archivos cae bruscamente respecto al último inventario. Es la protección más sencilla contra el disco no montado.
Llevar un registro
Redirigir la salida de cada ejecución a un archivo con fecha. Si el asistente da una respuesta sorprendente, el registro indica cuándo entró o salió un archivo de la base.
Espaciar las ejecuciones
Para documentos que cambian unas pocas veces por semana, basta con una ejecución diaria, lo que reduce la carga de indexación en la máquina que calcula los embeddings.
Hacer la copia de seguridad antes, no solo después
Una copia de seguridad periódica del volumen, independiente de la sincronización. Si una pasada vacía la base, la restauración también recupera los embeddings sin tener que reindexarlo todo.
Terminal — salvaguarda antes de la ejecución
#!/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é.

Este script no incluye a propósito el comando oikb: cópialo de la página oficial y pégalo en el lugar indicado. El umbral MIN es arbitrario; una comprobación más precisa compara el número de archivos con el último inventario y rechaza una disminución superior a cierta proporción.

#Solución de problemas

401 o 403 en la API
Clave caducada, revocada o copiada con un espacio. Comprueba también que el administrador permite las claves de API y que la cuenta tiene acceso a la base en cuestión.
Archivos enviados pero que no aparecen en el chat
El envío y la indexación son dos pasos distintos. Un PDF escaneado sin capa de texto puede aceptarse sin producir fragmentos aprovechables. Abre el archivo en la base para ver el texto extraído; pasa los escaneos por un OCR antes de publicarlos.
Duplicados en la base
Señal frecuente de un estado perdido o de una primera pasada lanzada sobre una base que ya contenía los mismos archivos importados a mano. Vuelve a empezar desde una base vacía reservada a la sincronización.
Reindexación larga
Cambiar el modelo de embeddings en los ajustes de Open WebUI obliga a reindexar los documentos. Evita modificar este ajuste y la sincronización al mismo tiempo: no sabrías cuál de los dos ha causado una discrepancia.
Respuestas siempre desactualizadas
Comprueba en la base que la versión antigua se ha reemplazado de verdad y no se ha añadido junto a la nueva. Abre una conversación nueva: los fragmentos ya citados en una conversación existente permanecen en su historial.

#Lo que se verificó y lo que no

No se ha realizado ninguna prueba de oikb para esta guía: ni instalación, ni ejecución, ni medición de duración o volumen. La página de documentación oficial se consultó el 30/10/2026 durante la preparación del tema y luego no pudo volver a revisarse el 18/11/2026. Los comandos de copia de seguridad retoman los de la guía de restauración del sitio; la prueba de la clave usa el encabezado Bearer y la ruta /api/models de la API de Open WebUI, algo que debes confirmar en tu versión. Las preguntas que hay que plantear a la documentación (detección de cambios, estado, eliminaciones, simulación) son criterios generales, no una descripción del funcionamiento de oikb.

i
Palabra clave y datos de búsqueda
El tema se eligió el 30/10/2026 a partir de la búsqueda «open webui synchroniser dossier». La herramienta de medición (DataForSEO, Google Ads, Francia) no devolvió ningún valor de volumen: el interés de la búsqueda no está ni confirmado ni cuantificado.

#Para ir más allá

RAG local con Ollama sin programar
Cómo funcionan las bases de conocimiento de Open WebUI desde la interfaz y cuándo es preferible AnythingLLM: https://quelllm.fr/guide/rag-local-ollama-sans-coder
Restaurar Open WebUI y Ollama después de una falla
Copia de seguridad del volumen, restauración e instancia de control, requisitos previos del paso 1: https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
Open WebUI con Ollama: guía completa
Instalación y ajustes básicos de la interfaz: https://quelllm.fr/guide/open-webui-ollama-tutoriel
Fuente primaria
Open WebUI, documentación Ecosystem, Knowledge Base Sync: https://docs.openwebui.com/ecosystem/knowledge-base-sync/ (consultada el 30/10/2026, no revisada el 18/11/2026).
¿Esta guía te ha ayudado?

¿Un comentario, un error, una precisión? Avísanos, eso mejora la guía para todos.