Intermediário 12 minPlano diário

Open WebUI: sincronizar uma pasta com oikb

Um notebook aberto ilumina uma mesa escura com luz verde.

Importar documentos manualmente para uma base de conhecimento do Open WebUI funciona enquanto a pasta não muda. Assim que ela passa a evoluir (procedimentos atualizados, notas adicionadas, arquivos removidos), a base se desatualiza e o modelo responde com base em versões obsoletas. Sincronizar uma pasta com o Open WebUI por meio do oikb, a ferramenta apresentada na seção Ecosystem da documentação oficial, busca corrigir essa defasagem. Este guia explica o princípio da sincronização incremental, o que ela pode excluir e um procedimento cauteloso: backup, escopo restrito, base de teste. Ele não foi testado pela redação.

Por Mohamed Meguedmi·Atualização 2026-11-18·Testado no Windows, macOS e Linux
!
Este guia não reproduz nenhum comando do oikb
A página oficial docs.openwebui.com/ecosystem/knowledge-base-sync/ foi consultada pela redação em 30/10/2026, mas não pôde ser relida no momento da escrita (18/11/2026). Em vez de reproduzir de memória uma sintaxe que pode ter mudado, este guia remete a essa página para a instalação e as opções exatas do oikb. Os comandos apresentados aqui tratam do backup, do escopo e das verificações, que não dependem da ferramenta.

#Por que sincronizar uma pasta com o Open WebUI

Uma base de conhecimento (Knowledge) do Open WebUI é uma coleção de arquivos divididos em trechos e indexados na forma de embeddings. Quando você vincula essa base a um modelo ou a menciona com # no chat, o Open WebUI busca os trechos próximos da pergunta e os adiciona ao contexto. O guia « RAG local com Ollama sem programar » detalha esse funcionamento na interface.

O problema aparece com o tempo. Um arquivo modificado no disco não é modificado na base: o Open WebUI mantém a versão importada. Um arquivo excluído da pasta continua podendo ser consultado. Um arquivo novo não existe enquanto ninguém o importar. Em uma pasta com poucos documentos, dá para resolver reimportando. Em uma pasta de procedimentos internos ou de notas que muda toda semana, a reimportação manual acaba esquecida, e o assistente cita com segurança um procedimento abandonado.

Uma ferramenta de sincronização automatiza esse trabalho: ela compara a pasta com o que já foi enviado e transmite apenas a diferença. É o que se chama de sincronização incremental. A contrapartida é que uma ferramenta que adiciona e substitui automaticamente também pode remover automaticamente. Esse é o ponto que exige mais atenção.

#Sincronização incremental: origem, destino, estado

O kit completo para criar o seu próprio assistente de IA.

Aproveite a nossa experiência e um percurso guiado para criar o seu assistente local e usar a sua IA no dia a dia.

  • Espaço online vitalício
  • PDF + arquivos
  • Reembolsado em 30 dias

Seja qual for a ferramenta, uma sincronização desse tipo se baseia em três elementos. Entendê-los permite ler a documentação do oikb com as perguntas certas em mente.

A origem
A pasta local (ou montada) cujo conteúdo é a referência oficial. Tudo o que estiver nela, dentro do escopo definido, tende a ir parar na base. Por isso é ela que precisa ser delimitada com cuidado: uma subpasta pessoal esquecida ali será indexada e poderá ser consultada por todos que têm acesso à base.
O destino
Uma base de conhecimento específica do Open WebUI, em uma instância específica (URL). Um erro no identificador da base pode misturar dois corpus ou, pior, fazer com que exclusões sejam aplicadas à base errada.
L'authentification
A ferramenta atua por meio da API do Open WebUI com uma chave vinculada a uma conta. Ela herda as permissões dessa conta: tudo o que a conta pode ler, modificar ou excluir, a ferramenta também pode.
O estado
Para saber o que mudou, a ferramenta precisa manter um registro do que já enviou (hashes de conteúdo, datas de modificação, correspondência entre arquivos locais e arquivos no Open WebUI) ou reconstruí-lo consultando a base. Se esse estado for perdido ou ficar dessincronizado, a ferramenta pode reenviar tudo, criar duplicatas ou interpretar mal as ausências.

Com esses elementos, cada execução classifica os arquivos em quatro casos: novo (a enviar), modificado (a substituir), inalterado (a ignorar), removido da origem (a retirar da base, ou a manter, conforme a configuração). Antes de executar o oikb, procure na documentação dele a resposta para quatro perguntas: como ele detecta uma modificação, onde armazena seu estado, se remove os arquivos que sumiram e com qual opção, e se oferece um modo de simulação que exibe as ações sem executá-las.

#O verdadeiro risco: as exclusões espelhadas

Uma sincronização que remove da base os arquivos ausentes na origem é útil: é ela que faz desaparecer o procedimento abandonado. Mas ela transforma qualquer erro na origem em perda na base. Alguns cenários realistas:

Disco não montado
A pasta aponta para um compartilhamento de rede ou um disco externo ausente no momento da execução. O ponto de montagem está vazio: para a ferramenta, todos os arquivos desapareceram.
Caminho errado
Um erro de digitação ou uma mudança de diretório de trabalho faz a origem apontar para uma pasta vazia ou diferente.
Reorganização
Renomear ou mover subpastas pode ser interpretado como « excluir tudo e depois recriar tudo ». O resultado final pode estar correto, mas a base é totalmente reindexada e eventuais links para os arquivos antigos são perdidos.
Base compartilhada
Se outras pessoas tiverem adicionado arquivos manualmente à mesma base, uma ferramenta de espelhamento estrito pode considerar esses arquivos como estranhos à origem e removê-los. Verifique na documentação se o oikb mexe apenas nos arquivos que ele mesmo enviou.

Daí decorrem duas regras. Primeiro, uma base sincronizada deve ser reservada à sincronização: nada de adições manuais nela. Depois, enquanto você não tiver observado o comportamento da ferramenta em uma base de teste, não ative a exclusão na base usada no dia a dia.

#Pré-requisitos

Open WebUI funcionando
Uma instância atualizada conectada ao Ollama (por padrão em http://localhost:11434), com um modelo de embeddings configurado. O guia « Open WebUI com Ollama: guia completo » cobre a instalação.
Uma conta dedicada
Idealmente, uma conta de usuário criada para a sincronização, proprietária da base, em vez da conta de administrador. O escopo da chave fica então limitado ao que essa conta precisa.
As chaves de API autorizadas
Dependendo da versão, o administrador precisa ativar as chaves de API nas configurações de administração antes que um usuário possa gerar uma em Configurações > Conta. Os nomes exatos variam: consulte a sua versão.
Um backup recente
Um arquivo do volume Docker do Open WebUI, verificado. É a única forma real de voltar atrás se a base for esvaziada por engano.
Os pré-requisitos específicos do oikb
A linguagem, a versão e o método de instalação estão indicados na página oficial. Não os presuma.

#Sincronizar uma pasta com o Open WebUI: o procedimento em 5 etapas

  1. 01
    1. Fazer backup da instância
    Pare o contêiner, arquive o volume, reinicie e calcule um hash. O procedimento completo, incluindo a restauração, está no guia "Restaurer Open WebUI et Ollama après une panne". Um backup nunca restaurado continua sendo uma hipótese: teste-o pelo menos uma vez em uma instância de controle.
  2. 02
    2. Delimitar o escopo
    Não aponte o oikb para a sua pasta Documentos inteira. Prepare uma pasta de publicação que contenha apenas os arquivos destinados à base, em formatos que o Open WebUI consiga extrair (texto, Markdown, PDF com texto etc.). Faça um inventário dela: é a sua referência para verificar depois o que chegou à base.
  3. 03
    3. Criar uma base de teste e uma chave
    Em Espaço de trabalho > Conhecimento, crie uma base chamada, por exemplo, "essai-sync". O identificador dela aparece no endereço da página da base. Gere a chave de API da conta de sincronização, armazene-a em um arquivo que só você possa ler e verifique se ela funciona com uma chamada simples.
  4. 04
    4. Primeira execução na base de teste
    Instale o oikb e execute-o conforme a página oficial, tendo como destino a base de teste, sem exclusão e em modo de simulação, se a ferramenta oferecer um. Leia a lista de ações anunciadas antes de iniciar a execução real. Depois, compare o número de arquivos na base com o seu inventário.
  5. 05
    5. Testar os casos-limite e depois fazer a virada
    Na base de teste: modifique um arquivo, adicione outro, exclua outro e execute novamente. Verifique se apenas o arquivo modificado é substituído e se o arquivo excluído é tratado como a documentação informa. Em seguida, esvazie temporariamente a origem (renomeie a pasta) e observe o que a ferramenta pretende fazer: esse é o teste do disco não montado. Só depois aponte o oikb para a base real.

A etapa 2 pode usar o rsync para montar a pasta de publicação a partir de uma pasta de trabalho, mantendo apenas determinadas extensões. O exemplo abaixo copia os arquivos Markdown e PDF, preserva a estrutura de diretórios e ignora todo o resto. Ele não usa --delete: um arquivo removido da pasta de trabalho permanece na pasta de publicação até que você o remova, o que garante uma decisão humana antes de qualquer exclusão na base.

Terminal — etapa 2: pasta de publicação e inventário
# 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

Na etapa 3, você pode testar a chave sem alterar nada. A API do Open WebUI aceita uma chave no cabeçalho Authorization: Bearer; a chamada abaixo lista os modelos visíveis para a conta. Uma resposta JSON confirma que a URL e a chave estão corretas; um erro 401 ou 403 indica uma chave inválida ou que as chaves de API não foram autorizadas pelo administrador.

Terminal — etapa 3: chave fora do histórico e teste de leitura
# 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"

A porta 3000 corresponde ao comando Docker mais comum (-p 3000:8080); adapte-a à sua instalação. A forma como o oikb lê a chave (variável de ambiente, opção, arquivo de configuração) está descrita na documentação dele: prefira uma variável ou um arquivo às opções de linha de comando, que ficam visíveis na lista de processos e no histórico.

→
Uma base por origem
Associe uma pasta de publicação a uma única base e dê o mesmo nome às duas ("procedures-qualite" para a pasta e para a base). Em caso de dúvida sobre o destino de uma execução, o nome basta para identificar o erro antes que ele se propague.

#Automatizar a sincronização sem se expor

Depois de observar o comportamento na base de teste, a tentação é agendar a execução a cada hora. Antes disso, adicione algumas salvaguardas que não dependam da ferramenta.

Verificar a origem antes de cada execução
Um script que se recusa a iniciar a sincronização se a pasta de publicação estiver vazia ou se o número de arquivos dela cair bruscamente em relação ao último inventário. É a proteção mais simples contra o disco não montado.
Manter um registro
Redirecionar a saída de cada execução para um arquivo com data. Se o assistente der uma resposta surpreendente, o log indica quando um arquivo entrou na base ou saiu dela.
Espaçar as execuções
Para documentos que mudam algumas vezes por semana, uma execução diária basta e reduz a carga de indexação na máquina que calcula os embeddings.
Fazer backup antes, não apenas depois
Um backup regular do volume, independente da sincronização. Se uma execução esvaziar a base, a restauração também recupera os embeddings sem precisar reindexar tudo.
Terminal — salvaguarda antes da execução
#!/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 intencionalmente não contém o comando oikb: copie-o da página oficial e cole-o no local indicado. O limite MIN é arbitrário; uma verificação mais precisa compara o número de arquivos com o último inventário e se recusa a seguir com uma queda superior a uma certa proporção.

#Solução de problemas

401 ou 403 na API
Chave expirada, revogada ou copiada com um espaço. Verifique também se o administrador permite chaves de API e se a conta tem acesso à base em questão.
Arquivos enviados, mas não encontrados no chat
O envio e a indexação são duas etapas. Um PDF digitalizado sem camada de texto pode ser aceito sem gerar trechos aproveitáveis. Abra o arquivo na base para ver o texto extraído; passe as digitalizações por um OCR antes de publicá-las.
Duplicatas na base
Sinal frequente de um estado perdido ou de uma primeira execução feita em uma base que já continha os mesmos arquivos importados manualmente. Recomece a partir de uma base vazia reservada à sincronização.
Reindexação demorada
Trocar o modelo de embeddings nas configurações do Open WebUI exige reindexar os documentos. Evite alterar essa configuração e a sincronização ao mesmo tempo: você não saberia mais qual das duas causou uma divergência.
Respostas ainda desatualizadas
Verifique na base se a versão antiga foi de fato substituída, e não adicionada ao lado. Abra uma nova conversa: os trechos já citados em uma conversa existente permanecem no histórico dela.

#O que foi verificado e o que não foi

Nenhum teste do oikb foi realizado para este guia: nenhuma instalação, nenhuma execução, nenhuma medição de duração ou de volume. A página de documentação oficial foi consultada em 30/10/2026 durante a preparação do tema e depois não pôde ser relida em 18/11/2026. Os comandos de backup são os mesmos do guia de restauração do site; o teste da chave usa o cabeçalho Bearer e a rota /api/models da API do Open WebUI, o que deve ser confirmado na sua versão. As perguntas a fazer à documentação (detecção de mudanças, estado, exclusões, simulação) são critérios gerais, e não uma descrição do funcionamento do oikb.

i
Palavra-chave e dados de pesquisa
O tema foi escolhido em 30/10/2026 a partir da consulta « open webui synchroniser dossier ». A ferramenta de levantamento (DataForSEO, Google Ads, França) não retornou nenhum valor de volume: o interesse pela consulta não está confirmado nem quantificado.

#Para se aprofundar

RAG local com Ollama sem programar
Como funcionam as bases de conhecimento do Open WebUI na interface e quando preferir o AnythingLLM: https://quelllm.fr/guide/rag-local-ollama-sans-coder
Restaurar Open WebUI e Ollama após uma falha
Backup do volume, restauração e instância de controle, pré-requisitos da etapa 1: https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
Open WebUI com Ollama: guia completo
Instalação e configurações básicas da interface: https://quelllm.fr/guide/open-webui-ollama-tutoriel
Fonte primária
Open WebUI, documentação Ecosystem, Knowledge Base Sync: https://docs.openwebui.com/ecosystem/knowledge-base-sync/ (consultada em 30/10/2026, não revisada em 18/11/2026).
Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.