Синхронизация базы знаний с сайтом нужна, чтобы AI-ассистент отвечал по актуальной документации без ручной перезагрузки файлов. Website Knowledge Sync регулярно обходит разрешённые разделы, замечает содержательные изменения и обновляет индекс только после успешной обработки новой версии.
Чем синхронизация отличается от разовой загрузки
Обычная загрузка документа создаёт снимок на конкретный момент. После изменения страницы старый фрагмент продолжает участвовать в поиске, пока команда не загрузит файл заново. Для документации, базы помощи или каталога это быстро превращается в эксплуатационную задачу: нужно находить новые страницы, обновлять изменившиеся и убирать удалённые.
Website Knowledge Sync связывает источник сайта с конкретной базой знаний и ведёт историю запусков. Это не замена проектированию RAG: правила chunking, retrieval и ответа всё равно важны. Но синхронизация закрывает отдельный вопрос свежести. Базовую архитектуру retrieval можно изучить в статье про RAG по документам компании, а возможности готового workflow — на странице Knowledge Sync.
Ограничьте область сайта
Не начинайте с полного домена. Укажите стартовый URL и разрешённые пути, например /docs и /help, а архив, поиск и служебные страницы добавьте в excludePaths. Ограничения maxPages и maxDepth должны соответствовать реальному размеру раздела и бюджету одного обновления.
Хорошая область содержит страницы, которые действительно отвечают на вопросы пользователя. Навигационные фильтры, личные кабинеты, результаты поиска, теги и календарные архивы обычно создают дубли. Проверьте несколько URL вручную и убедитесь, что публичные страницы разрешено обрабатывать. URL также должен проходить защиту от запросов во внутреннюю сеть; общие рекомендации по таким проверкам собраны в OWASP SSRF Prevention Cheat Sheet.
Подключите источник к базе знаний
Когда база уже создана и известен её идентификатор, добавьте источник отдельным запросом. Idempotency-Key защищает создание от дубля при повторной доставке.
curl https://api.llmtokenapi.ru/v1/knowledge-bases/$KNOWLEDGE_BASE_ID/sources \
-H "Authorization: Bearer $LLMTOKENAPI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: docs-source-v1" \
-d '{
"url": "https://example.com/docs",
"name": "Документация продукта",
"includePaths": ["/docs"],
"excludePaths": ["/docs/archive"],
"maxPages": 250,
"maxDepth": 6,
"intervalMinutes": 1440,
"maxSpendKopecks": 5000,
"syncNow": true
}'
intervalMinutes задаёт частоту автоматического запуска, а syncNow определяет, нужно ли сразу поставить первую синхронизацию в очередь. Для осторожного запуска создайте источник с syncNow: false, проверьте настройки и запустите обновление вручную отдельным endpoint.
Понимайте жизненный цикл обновления
Во время запуска страницы дедуплицируются и сортируются по URL. Из их содержимого собирается детерминированный snapshot, для которого вычисляется хэш. Если хэш совпал с последней успешной версией, контент не переиндексируется: задание завершается без новых embeddings и соответствующего списания за неизменившийся материал.
Если содержимое изменилось, новый snapshot проходит существующий ingest-конвейер. Только успешная индексация обновляет сохранённый хэш источника и готовый knowledge file. Это важное свойство: частично загруженная или не прошедшая обработку версия не должна вытеснить рабочую базу знаний.
Разделите первый запуск и регулярный режим
Первый обход проверяйте как миграцию данных. Смотрите число найденных страниц, долю успешных документов, неожиданные URL, объём текста и ответы на контрольные вопросы. Не включайте частое расписание, пока границы источника не стабилизировались.
В регулярном режиме отслеживайте длительность, статус, изменение snapshot и стоимость успешного запуска. Уведомление через сохранённый webhook удобно использовать для обновления внутреннего статуса, но обработчик должен выдерживать повторную доставку. Не запускайте второй обход только потому, что клиент не получил уведомление: сначала проверьте состояние source run.
Проверяйте свежесть на вопросах пользователей
Технически успешная синхронизация ещё не доказывает, что ассистент отвечает лучше. Подготовьте набор вопросов по недавно изменённым страницам и несколько стабильных контрольных вопросов. После обновления проверьте retrieval, текст ответа и ссылку в citation.
Website Sync сохраняет URL страницы рядом с материалом, поэтому ответ может указывать на исходный источник, не раскрывая внутреннее хранилище или маршрут эмбеддингов. Для критичных сценариев показывайте ссылку пользователю и добавляйте дату последней успешной синхронизации в собственный интерфейс.
Обновляйте и удаляйте источник безопасно
При изменении includePaths, глубины или бюджета сначала поставьте источник на паузу, выполните ручной запуск и сравните контрольные ответы. Резкое расширение области может добавить навигационный шум, а слишком узкое правило — убрать нужные инструкции.
Удаление source — это операция над данными, а не просто выключение расписания. После успешного удаления связанный synthetic knowledge file, фрагменты и векторные точки больше не участвуют в поиске и ответах. Если материал нужно временно заморозить, используйте паузу; если его нужно убрать из базы, удалите источник и проверьте контрольным запросом отсутствие старого ответа.
Практический чек-лист запуска
Сначала создайте небольшую базу и ограниченный источник. Затем выполните ручную синхронизацию, проверьте список страниц и несколько вопросов, повторите запуск без изменений и убедитесь, что он распознан как неизменившийся. После этого измените тестовую страницу, дождитесь новой успешной версии и только тогда включайте расписание.
Храните у себя идентификаторы базы, source и последнего job, но не дублируйте исходные snapshot без необходимости. Все актуальные endpoints, scopes и параметры операций сверяйте в документации LLMTOKENAPI. В результате база знаний обновляется предсказуемо: сайт остаётся источником истины, а рабочий индекс меняется только после полностью успешной обработки.
