Коннекторы и синхронизация
Какие источники подключаются к базе знаний автоматически, как хранятся учётные данные и OAuth, что такое полная загрузка и интервал опроса, пауза и возобновление, удаления в источнике, особенности SharePoint и типовые ошибки.
Коннектор наполняет базу знаний из внешней системы без ручной загрузки: сначала выполняет полную загрузку, затем по расписанию подхватывает изменения. Эта статья описывает каталог коннекторов, их жизненный цикл и то, на что обратить внимание при настройке.
Каталог источников
Коннекторы создаются в настройках учётной записи в разделе «Коннекторы» кнопкой «Новый коннектор». Создавать и изменять их могут владелец и администраторы организации.
| Группа | Коннекторы |
|---|---|
| Файловые хранилища | Google Drive, OneDrive, SharePoint (файлы и списки), SMB-ресурс (сетевая папка), Яндекс Диск |
| Документация и задачи | Confluence, Jira, Azure DevOps (репозитории, вики, рабочие элементы, pull request), GitHub и GitLab (код репозиториев) |
| Почта и переписка | Outlook, Email (IMAP), Microsoft Teams, Zulip, Bitrix24 Открытые линии |
| Учётные системы | 1С:Предприятие (справочники, документы и регистры через OData) |
| Отраслевые и внешние базы | БДУ ФСТЭК (база уязвимостей), legis.md (правовые акты Молдовы), instante.justice.md (судебные решения Молдовы) |
| Приём и обработка данных | Bluedot (записи звонков через webhook), Generic (JSON-конфигурация и токен приёма), Нормализация МТР (справочник из Excel) |
Коннектор привязан к одной базе знаний. При создании можно создать новую базу («Создать датасет», название подставляется автоматически) или оставить коннектор без базы. Часть коннекторов пишет содержимое прямо в индекс и не создаёт файлов: на странице такой базы вместо списка документов показано состояние синхронизации, а содержимое проверяется на вкладке «Тестирование поиска».
Учётные данные
Способ входа зависит от источника:
- токен или логин с паролем: Confluence, Jira (API-токен Atlassian либо сервисный аккаунт OAuth 2.0), GitHub и GitLab (персональный токен; публичные репозитории доступны без него, но с ограничением частоты запросов), Azure DevOps, SMB, IMAP, Zulip, 1С;
- OAuth 2.0: Google Drive («Войти через Google» либо Client ID, Client Secret и Refresh Token, либо JSON сервисного аккаунта), Яндекс Диск (OAuth-токен);
- приложение Microsoft Entra: OneDrive, SharePoint, Outlook, Teams. Используется «Войти через Microsoft» или ручной ввод Client ID, Client Secret, Tenant ID и Refresh Token. Приложению нужны разрешения под задачу: сайты для SharePoint, чтение почты для Outlook, сообщения каналов и файлы для Teams.
Секреты хранятся в зашифрованном хранилище с привязкой к организации и не возвращаются в интерфейс; при редактировании поле секрета оставляют пустым, чтобы сохранить текущее значение. Кнопка «Проверить подключение» выполняет пробный запрос до сохранения. Для каждого источника заводите отдельную служебную учётную запись только на чтение.
Полная загрузка и расписание
После сохранения коннектор переходит из состояния «Новый» в «Синхронизация»: запускается полная загрузка всего разрешённого содержимого. У многих источников есть поле «Загрузить с», ограничивающее глубину истории датой. По завершении состояние становится «Активен», в карточке появляются «Последняя синхронизация» и счётчики загруженного, пропущенного и ошибок.
Дальше коннектор работает по опросу с периодом «Интервал опроса (сек)»; значение по умолчанию зависит от типа. Zulip дополнительно поддерживает режим событий в реальном времени, а webhook-коннекторы (Bluedot, Generic) данные не опрашивают, а принимают по токену приёма. Неизменившиеся объекты пропускаются по версии (eTag, дата изменения), поэтому повторные проходы дешёвые. Кнопка «Полная загрузка» запускает обход заново, не удаляя уже загруженное.
На странице базы блок состояния показывает фазу: «Актуально», «Идёт синхронизация», «Инициализация» (с шагами, например «Подключение», «Загрузка страниц», «Нарезка и индексация»), «На паузе», «Ошибка», «Новый» или «Завис». «Завис» означает, что задачу не держит ни один исполнитель; кнопка «Почистить и перезапустить» снимает осиротевшие блокировки и продолжает с сохранённого места.
Пауза, возобновление, удаление коннектора
«Пауза» останавливает опрос, данные в базе остаются. «Продолжить» возвращает коннектор в работу с сохранённой позиции, а не с начала. «Перезапуск» нужен после смены учётных данных или фильтров. Удаление коннектора удаляет его секреты и служебный индекс; база знаний с документами по умолчанию сохраняется. Создание и удаление коннекторов попадают в журнал аудита.
Удаления в источнике
Поведение зависит от коннектора, и это стоит проверить до запуска:
- SMB имеет переключатель «Удалять из базы знаний исчезнувшие файлы»; он выключен по умолчанию, очистка выполняется только после полного успешного обхода.
- OneDrive получает признак удаления из ленты изменений и убирает документ из базы.
- SharePoint и 1С удаления не отслеживают: удалённый в источнике файл или запись остаются в базе, пока их не удалят вручную.
- У чатов и Confluence есть настройка «Обрабатывать удаления».
Если удаления не отслеживаются, назначьте ответственного за сверку базы с источником.
Особенности SharePoint
В разделе содержимого указываются «URL сайтов» вида https://company.sharepoint.com/sites/my-site, «Библиотеки документов» (список названий; пусто означает все библиотеки сайта), «Списки» (названия списков SharePoint) и переключатель «Включить подсайты». Файлы библиотек обрабатываются как обычные документы методом, заданным в коннекторе; файлы больше «Макс. размер файла (МБ)» пропускаются и учитываются в счётчике. Изменения файлов читаются из ленты изменений сайта, а элементы списков превращаются в текстовые документы с заголовком и полями элемента и обходятся целиком на каждом проходе.
Ошибки, которые стоит ожидать
| Сообщение или состояние | Причина | Что сделать |
|---|---|---|
| «Ошибка подключения», «Нет соединения» | Неверные учётные данные, истёкший токен, нет разрешений у приложения | Повторить «Проверить подключение», обновить секрет, проверить разрешения в источнике |
| «Ошибка инициализации», состояние «Ошибка» после создания | Не найден ни один сайт, проект или папка из настроек | Сверить адреса и названия, проверить права служебной записи |
| Уведомление «Ошибка синхронизации коннектора» | Сбой очередного прохода | Открыть «Последняя ошибка» в карточке; после исправления нажать «Продолжить» |
| «Завис» | Исполнитель остановлен во время прохода | «Почистить и перезапустить» |
| Счётчик пропущенных растёт | Файлы больше лимита или изображения без модели распознавания | Поднять лимит, настроить модель или осознанно включить «Пропускать изображения без vision-модели» |
Коннекторы и 1С
Коннектор 1С устроен иначе, чем файловые источники. Его основная задача дать ассистентам и агентам инструменты живого чтения базы через OData: остатки, обороты, карточки контрагентов и произвольные запросы выполняются в момент вопроса, а не по копии. Дополнительно он может индексировать выбранные наборы сущностей в базу знаний по расписанию. Подготовка публикации, пользователь 1С и разбор ошибок описаны в статье Подключение базы 1С через OData.
Изменения, которые коннекторы замечают при очередном проходе, доступны автоматизациям как события; как на них реагировать агентом, см. Агенты на холсте.
Спросить Сему