Open WebUI: синхронизация папки с базой знаний через API

Когда нужна именно синхронизация, а не новый RAG-гайд?

Если папка с регламентами меняется, разовая загрузка PDF не отвечает на вопросы «какой файл изменился?» и «остался ли прежний фрагмент доступен?». В Open WebUI действие Add Content → Sync directory сравнивает локальные файлы по относительному пути, имени и SHA-256: новые добавляет, изменённые заменяет, отсутствующие в исходной папке удаляет из базы. Неизменённые не загружает и повторно не индексирует. Для частых или больших обновлений авторы рекомендуют отдельный CLI oikb, который обращается к тем же API. Оба пути требуют Open WebUI не старее 0.9.6. s1 s4

Это задача обновления источника, а не настройки поиска по уже созданной базе. Маршрут решения: локальная папка → манифест → diff → обработка изменённых файлов → очистка старых записей → проверка выдачи на тестовом вопросе. Для ответа локальной модели далее нужен отдельный работающий inference-сервер и корректный режим поиска в Open WebUI; сама синхронизация не проверяет модель или отсутствие облачных вызовов у выбранных extraction/embedding-провайдеров. s1

Что подготовить до первого запуска?

1. Установите Open WebUI версии не ниже 0.9.6 и создайте отдельную тестовую Knowledge Base. Скопируйте её ID из адреса страницы базы; задайте учётной записи синхронизации право записи именно в эту базу, а тестовому читателю — только требуемый доступ на чтение. Код маршрутов проверяет write access для diff и cleanup; KB-модель хранит отдельные grants чтения и записи. s1 s2 s5 s7
2. Получите API key через Settings → Account, если администратор разрешил выдачу ключей вашему пользователю. Используйте Authorization: Bearer и храните ключ в переменной окружения или менеджере секретов, не в коммитах, URI и примерах из рабочих логов. Альтернатива по документации — JWT, но автоматизации удобнее отдельный управляемый ключ с минимальными правами. s6 s7
3. В тестовой папке ./docs создайте выдуманный файл policy.txt с фразой DEMO-REV-A и второй keep.txt с неизменным маркером. Сделайте резервную копию рабочей базы до реального зеркалирования: пустая или неполная папка для sync означает удаление отсутствующих в манифесте файлов. Оставьте один источник на одну тестовую базу; если источников несколько, используйте объединённую конфигурацию oikb, которая передаёт общий manifest, иначе одиночный oikb sync SOURCE --kb-id ID видит только свой источник. s2 s5

Как синхронизировать папку через официальный клиент?

На отдельной машине с Python 3.10+ установите oikb и проверьте версию своего Open WebUI. Для уже работающей тестовой базы пример команд по документации проекта; KB_ID и адрес замените своими, ключ не печатайте в истории команд: s4 s5

python3 -m pip install oikb
export OPEN_WEBUI_URL=http://localhost:3000
# OPEN_WEBUI_API_KEY задайте безопасным способом вне истории команд.
# KB_ID задайте фактическим ID тестовой Knowledge Base.
oikb sync ./docs --kb-id "$KB_ID" --dry-run
oikb sync ./docs --kb-id "$KB_ID"

--dry-run показывает добавления, изменения и удаления, ничего не записывая; перед вторым вызовом сравните его список со своей папкой. Не запускайте sync на папке с неполной выгрузкой данных. По руководству oikb следующий запуск без изменений должен быть инкрементальным. Если у одной базы несколько источников, сначала объедините их в .oikb.yaml под одним kb-id и повторно просмотрите dry-run: отдельный вызов с одним источником может посчитать остальные файлы удалёнными. s4 s5

Для небольшого набора файлов можно вместо CLI выбрать Add Content → Sync directory в интерфейсе Knowledge Base. Но это операция в браузере; документация рекомендует oikb для тысяч файлов или частых обновлений. Не смешивайте оба способа на рабочей базе, не проверив предварительно список удалений. s1 s5

Что делает собственный API-клиент?

Для собственной интеграции формируйте полный manifest локального источника: POST /api/v1/knowledge/{id}/sync/diff принимает {"manifest":[{"path":"","filename":"policy.txt","checksum":"<SHA-256 сырого файла>","size":<байты>}]}. В документации краткая форма перечисляет только путь/имя/хеш, но обработчик v0.11.4 дополнительно требует size. path — относительная директория без имени файла, для корня пустая строка. sync/diff возвращает added, modified со stale_file_id, deleted с file_id, mkdir, rmdir, unmodified_count и directory_map; сам по себе он базу не меняет. Сравнивайте все удаления с исходным набором до записывающих действий. s1 s2

Далее создайте недостающие каталоги и загрузите только added/modified через POST /api/v1/files/, передав knowledge_id, нужный directory_id и file_hash в multipart metadata. Сервер сохраняет хеш и умеет привязать файл к базе; обработка асинхронна, поэтому проверяйте GET /api/v1/files/{id}/process/status до completed и останавливайтесь при failed или timeout. Проверяйте и фактическую связь файла с базой, а не только HTTP 200 загрузки. Затем передавайте в POST /api/v1/knowledge/{id}/sync/cleanup только проверенные устаревшие file_ids и пустые dir_ids: вызов меняет базу и убирает старый векторный контент. Для собственного скрипта рекомендуем очистку после успешных загрузок, как в пошаговом описании Knowledge API; не обещайте атомарной замены на уровне всего корпуса. s1 s2 s3 s6

README oikb кратко перечисляет удаление старых файлов до загрузки новых, а документация ручного API предлагает cleanup после upload. Это разные процедуры с окном несогласованности; не считайте их транзакцией. На критичной базе сначала прогоните сценарий в копии и не подавайте продуктивный корпус без backup и плана восстановления. s1 s4

Как проверить отсутствие устаревшего фрагмента?

1. После первой синхронизации найдите в Knowledge Base точную строку DEMO-REV-A и запишите ID файла и источник найденного фрагмента. Если модель отвечает без обращения к базе или без проверяемого источника, её ответ ничего не доказывает: в режиме Native она должна вызвать knowledge-инструмент. s1
2. Локально замените маркер в policy.txt на DEMO-REV-B, удалите keep.txt только в тестовой папке и добавьте новый new.txt. Повторите dry-run: ожидаются одна модификация, одно удаление и одно добавление; это ожидаемый исход вашего сценария, не результат прогона Modelium. Убедитесь, что нет неожиданно удаляемых файлов, и синхронизируйте. s2 s5
3. Дождитесь completed для загруженных файлов, убедитесь, что policy.txt и new.txt присутствуют в списке базы, а keep.txt — нет. Отдельно выполните поиск по DEMO-REV-B и старому DEMO-REV-A, сравните ID и текст источника. Успех: новый фрагмент доступен, старого нет, неизменённые документы (если есть) не переобрабатывались. Ошибка или задержка поиска — повод проверить extraction/embedding, статус обработки и режим retrieval, а не просто заново заливать весь корпус. s1 s2 s3
4. Повторите вопрос под тестовой ролью без доступа: проверьте, что ей не открывается эта KB и её файлы. Это проверка прав в вашем экземпляре, а не обещание универсальной изоляции документов внутри разрешённой базы. Для корпоративного разграничения см. отдельный разбор прав. s1 s7

Следующий шаг: по гайду агентного RAG в Open WebUI проверьте трассу вызова поиска на новой версии файла и сверьте цитату с исходником. Если синхронизация успешна, но модель отвечает старой фразой, не принимайте ответ по памяти за найденный документ: отделите состояние базы, индекс и поведение самой модели. s1 s3