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

Источник: https://modelium.tech/zhurnal/open-webui-sinhronizaciya-bazy-znaniy/

Для синхронизации локальной папки с Knowledge Base в Open WebUI используйте встроенный Sync directory или официальный клиент oikb: они сравнивают пути и SHA-256 и передают только изменения. Для собственного скрипта есть read-only `/sync/diff` и изменяющий `/sync/cleanup`; загрузка и обработка файлов — отдельные этапы. Проверяйте не только успешный ответ API, но и новый фрагмент в поиске, отсутствие удалённого фрагмента и права пользователя; на чистой тестовой базе это безопаснее, чем сразу менять рабочую.

**По документации и коду на 28 сентября 2026 года:** маршруты зафиксированы по тегу Open WebUI `v0.11.4` (commit `8bd8b4f`), документы — по отдельной ревизии. Ни Open WebUI, ни oikb, ни локальную LLM Modelium не запускал. Ниже — инструкция для вашей **тестовой** базы, а не отчёт о выполненной синхронизации. [s1](#src-s1) [s2](#src-s2)

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

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

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

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

- Установите Open WebUI версии не ниже 0.9.6 и создайте **отдельную тестовую Knowledge Base**. Скопируйте её ID из адреса страницы базы; задайте учётной записи синхронизации право записи именно в эту базу, а тестовому читателю — только требуемый доступ на чтение. Код маршрутов проверяет write access для diff и cleanup; KB-модель хранит отдельные grants чтения и записи. [s1](#src-s1) [s2](#src-s2) [s5](#src-s5) [s7](#src-s7)

- Получите API key через **Settings → Account**, если администратор разрешил выдачу ключей вашему пользователю. Используйте `Authorization: Bearer` и храните ключ в переменной окружения или менеджере секретов, не в коммитах, URI и примерах из рабочих логов. Альтернатива по документации — JWT, но автоматизации удобнее отдельный управляемый ключ с минимальными правами. [s6](#src-s6) [s7](#src-s7)

- В тестовой папке `./docs` создайте выдуманный файл `policy.txt` с фразой `DEMO-REV-A` и второй `keep.txt` с неизменным маркером. Сделайте резервную копию рабочей базы до реального зеркалирования: пустая или неполная папка для sync означает удаление отсутствующих в манифесте файлов. Оставьте один источник на одну тестовую базу; если источников несколько, используйте объединённую конфигурацию oikb, которая передаёт общий manifest, иначе одиночный `oikb sync SOURCE --kb-id ID` видит только свой источник. [s2](#src-s2) [s5](#src-s5)

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

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

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

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

Для небольшого набора файлов можно вместо CLI выбрать **Add Content → Sync directory** в интерфейсе Knowledge Base. Но это операция в браузере; документация рекомендует oikb для тысяч файлов или частых обновлений. Не смешивайте оба способа на рабочей базе, не проверив предварительно список удалений. [s1](#src-s1) [s5](#src-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](#src-s1) [s2](#src-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](#src-s1) [s2](#src-s2) [s3](#src-s3) [s6](#src-s6)

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

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

- После первой синхронизации найдите в Knowledge Base точную строку `DEMO-REV-A` и запишите ID файла и источник найденного фрагмента. Если модель отвечает без обращения к базе или без проверяемого источника, её ответ ничего не доказывает: в режиме Native она должна вызвать knowledge-инструмент. [s1](#src-s1)

- Локально замените маркер в `policy.txt` на `DEMO-REV-B`, удалите `keep.txt` **только в тестовой папке** и добавьте новый `new.txt`. Повторите dry-run: ожидаются одна модификация, одно удаление и одно добавление; это ожидаемый исход **вашего** сценария, не результат прогона Modelium. Убедитесь, что нет неожиданно удаляемых файлов, и синхронизируйте. [s2](#src-s2) [s5](#src-s5)

- Дождитесь `completed` для загруженных файлов, убедитесь, что `policy.txt` и `new.txt` присутствуют в списке базы, а `keep.txt` — нет. Отдельно выполните поиск по `DEMO-REV-B` и старому `DEMO-REV-A`, сравните ID и текст источника. Успех: новый фрагмент доступен, старого нет, неизменённые документы (если есть) не переобрабатывались. Ошибка или задержка поиска — повод проверить extraction/embedding, статус обработки и режим retrieval, а не просто заново заливать весь корпус. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

- Повторите вопрос под тестовой ролью без доступа: проверьте, что ей не открывается эта KB и её файлы. Это проверка прав в вашем экземпляре, а не обещание универсальной изоляции документов внутри разрешённой базы. Для корпоративного разграничения см. [отдельный разбор прав](/zhurnal/korporativnyy-poisk-prava-dostupa/). [s1](#src-s1) [s7](#src-s7)

**Следующий шаг:** по [гайду агентного RAG в Open WebUI](/zhurnal/agentnyy-rag-open-webui/) проверьте трассу вызова поиска на новой версии файла и сверьте цитату с исходником. Если синхронизация успешна, но модель отвечает старой фразой, не принимайте ответ по памяти за найденный документ: отделите состояние базы, индекс и поведение самой модели. [s1](#src-s1) [s3](#src-s3)

## Источники

1. [Open WebUI Docs — Knowledge Bases, incremental sync and API](https://github.com/open-webui/docs/blob/6602effdb92ce647f2abe6dbb61e136b62191d7a/docs/features/workspace/knowledge.mdx) — получено 2026-09-28
2. [Open WebUI v0.11.4 — knowledge router, sync/diff and cleanup](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/routers/knowledge.py) — получено 2026-09-28
3. [Open WebUI v0.11.4 — file upload, hash and process status](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/routers/files.py) — получено 2026-09-28
4. [Open WebUI oikb — official CLI README](https://github.com/open-webui/oikb/blob/5fd27193da73c4cd2459dcc8b1cb5465a0ce4c54/README.md) — получено 2026-09-28
5. [Open WebUI oikb — full guide and multi-source safeguards](https://github.com/open-webui/oikb/blob/5fd27193da73c4cd2459dcc8b1cb5465a0ce4c54/docs/guide.md) — получено 2026-09-28
6. [Open WebUI Docs — REST API authentication and RAG endpoints](https://github.com/open-webui/docs/blob/6602effdb92ce647f2abe6dbb61e136b62191d7a/docs/reference/api-endpoints.md) — получено 2026-09-28
7. [Open WebUI v0.11.4 — Knowledge Base access grants](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/models/knowledge.py) — получено 2026-09-28