Ru

Смена модели индексации документов#

Эта инструкция помогает сменить модель, которая создаёт векторы для поиска по документам. При смене модели или размерности Sherpa AI Server очищает старые векторы и заново индексирует документы. На время переключения поиск по содержимому может быть недоступен, а до завершения обработки файлов результаты могут быть неполными. Планируйте переключение на подходящее время.

Перед началом#

  • Для изменения настроек нужны права documents:update и ai_models:read. Если модель или её экземпляр ещё нужно создать, дополнительно требуется ai_models:create. Для настройки экземпляра vLLM через API требуется ai_models:update.
  • Узнайте фактическую размерность вектора новой модели. Укажите число, которое она возвращает: целое от 32 до 2000. При переходе с 2.5.0 на 2.5.1 подготовьте индексы 384 и 1024. Если текущая версия ниже 2.5.0, сначала согласуйте путь обновления с сопровождением. Для другой размерности администратор должен заранее подготовить поисковый индекс.
  • У модели типа Индексация или Мультимодальная должен быть ровно один активный экземпляр. Несколько экземпляров одной модели могут возвращать несовместимые векторы.
  • Не меняйте адрес или путь активного экземпляра текущей модели индексации, чтобы направить его на другой источник векторов: система отклонит такое изменение. Создайте отдельную модель с новым экземпляром и затем выберите её в настройках индексации документов.
  • Если в документах есть фрагменты, добавленные только через API и не связанные с исходным файлом, ознакомьтесь с разделом «Если переключение отклонено» ниже. Такие фрагменты нельзя восстановить обычной переиндексацией.

Пример: BGE-M3 через vLLM#

На сервере с GPU запустите отдельный экземпляр vLLM для модели индексации. Пример для vLLM 0.27.1 и модели BAAI/bge-m3 (нужны установленный vLLM и доступ к файлам модели):

vllm serve BAAI/bge-m3 --runner pooling --pooler-config.task embed \
  --hf-overrides '{"architectures":["BgeM3EmbeddingModel"]}' \
  --host 0.0.0.0 --port 8001

На сервере vLLM проверьте, что модель возвращает вектор из 1024 чисел (для команды нужен jq):

curl -fsS http://127.0.0.1:8001/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"BAAI/bge-m3","input":["test"]}' \
  | jq '.data[0].embedding | length'

В Модели создайте новую модель типа Индексация и один активный локальный экземпляр. Укажите путь модели BAAI/bge-m3, порт 8001 и адрес vLLM, доступный из контейнера Sherpa AI Server. Если vLLM работает на другом сервере, используйте его сетевое имя или IP. 127.0.0.1 внутри контейнера Sherpa указывает на сам контейнер. Дополнительный путь API оставьте пустым.

До выбора этой модели для индексации настройте экземпляр через API Sherpa AI Server с правом ai_models:update: выполните GET /api/v1/models/{model_guid}/instances/{instance_guid}, возьмите весь объект data.connection_params, добавьте в него "embed_format": "openai" и передайте полный обновлённый объект в PATCH по тому же адресу как {"connection_params": {…}}. Повторите GET и убедитесь, что data.connection_params.embed_format равен openai. При PATCH объект параметров заменяется целиком, поэтому сохраните все существующие поля подключения и авторизации.

Эта настройка направляет запросы Sherpa к /v1/embeddings. Без неё локальный экземпляр использует /v2/embed с параметром input_type, который BGE-M3 в vLLM 0.27.1 отклоняет. После настройки не сохраняйте этот экземпляр через форму Модели: форма не показывает embed_format и удалит его при сохранении. Проверка соединения в форме проверяет доступность сервера; фактическую выдачу векторов Sherpa проверит при сохранении настроек индексации. Затем выберите новую модель и размерность 1024 по шагам ниже.

Порядок переключения#

  1. Откройте Модели и проверьте доступность нужной модели и её единственного активного экземпляра. Если модель отсутствует и у вас есть право ai_models:create, нажмите Создать в списке моделей, создайте модель типа Индексация или Мультимодальная, затем нажмите Создать в списке экземпляров и добавьте экземпляр. Если права нет, обратитесь к администратору.
  2. Откройте Документы → Настройки → Индексация. Выберите Модель индексации и введите её фактическую Размерность эмбеддинга. Изменение одного только числа не меняет модель.
  3. Нажмите Сохранить один раз. Сервер проверит модель, возвращаемую ею размерность и готовность поискового индекса. После успешной проверки он сохранит новую модель и размерность, очистит старые векторы и поставит документы с автоматической индексацией в очередь. Исходные файлы сохраняются. Отдельно нажимать Удалить все векторы и переиндексировать не нужно. Смена модели при той же размерности тоже запускает переход, если выбрана другая модель.
  4. Дождитесь обработки документов: Ожидает обработки → В обработке → Готов. Если файл получил статус Ожидает ручной индексации, откройте его и нажмите Переиндексировать, затем дождитесь статуса Готов. Файлы со статусом Не индексируется не индексируются. Образцы ответов ассистентов сервер переиндексирует автоматически.
  5. Проверьте поиск по известному документу и убедитесь, что нужные файлы получили статус Готов. Если у файла статус Ошибка, откройте причину и устраните её. После этого нажмите Переиндексировать у этого файла. Для повторной обработки всех файлов отдельно используйте Удалить все векторы и переиндексировать.

Статус перехода ready означает, что переключение настроек завершилось; он не означает, что все файлы получили статус Готов. Если в ответе API показано queued_files, это число файлов, поставленных в очередь, а не число уже обработанных файлов. Проверяйте статус документов и поиск после завершения их индексации.

Примеры#

  • 384 → 1024. Выберите новую модель с вектором размерности 1024, укажите 1024 и нажмите Сохранить. Дождитесь повторной индексации файлов и проверьте поиск.
  • 1024 → 384. Выберите модель с вектором размерности 384, укажите 384 и выполните те же действия.
  • 384 → 384, другая модель. Выберите другую модель, оставьте 384 и нажмите Сохранить. Смена модели запускает повторную индексацию, хотя размерность не изменилась.

Если переключение отклонено или прервалось#

Если предварительная проверка не прошла из-за недоступной модели, неверной размерности или неподготовленного индекса, исправьте причину и повторите сохранение. Если переход отклонён из-за фрагментов, добавленных только через API, прежняя модель, размерность и векторы сохраняются. Сохраните тексты и метаданные таких фрагментов вне системы, затем попросите администратора удалить их или удалите содержащий их файл, если он больше не нужен. После успешной смены модели при необходимости добавьте сохранённые фрагменты через API заново.

Если переход уже начался, но остался в состоянии ожидания или прервался, снова откройте настройки и сохраните ту же модель и ту же размерность. Сервер завершит очистку и постановку файлов в очередь; сама индексация выполняется в фоне. Пока переход не завершён, не выбирайте другую пару модели и размерности.

Если вместе с моделью менялись параметры распознавания PDF, размер чанка или перекрытие чанков, после ошибки снова откройте настройки и проверьте эти поля: они могли сохраниться отдельно. Это не означает, что модель и размерность переключились успешно.

Для администратора: другая размерность#

Для размерности, отличной от 384 и 1024, после миграций версии 2.5.1 и до сохранения новой модели подготовьте индекс для нужного аккаунта. Полный SQL, проверка и команды для стандартной клиентской установки приведены в разделе «Дополнительная размерность после обновления» инструкции по подготовке индексов. Скопируйте SQL оттуда в локальный файл, укажите числовой идентификатор аккаунта и фактическую размерность модели. После успешного выполнения команды пользователь может нажать Сохранить.