В этом материале
При миграции API ColPali нужно сохранить обработку запросов, изображений, масок и многовекторную оценку до добавления новых возможностей.
Переход ColPali на Sentence Transformers требует проверки паритета скоринга: одной замены импортов недостаточно для сохранения обработки запросов и сходства. Сначала нужно воспроизвести выбор известных страниц, а уже затем менять checkpoint, правила пакетной обработки или численное представление векторов внутри нового рабочего контура.
Начать с поддерживаемого пути миграции
Авторский репозиторий ColPali помечает colpali-engine как устаревший и направляет пользователей к Sentence Transformers. Текущий переход описан в руководстве по миграции. До изменений сохраняют версию старого пакета и ревизию модели. Новый API может успешно загрузиться с другой подготовкой входа, маскированием или нормализацией, поэтому инициализация является лишь первым условием приёмки, а не доказательством совместимости поведения.
Сопоставить операции, а не названия
Прежний процесс отдельно готовил запросы, изображения и оценивал многовекторное сходство. Новый MultiVectorEncoder предлагает кодирование запросов, документов и операции similarity. Каждому старому вызову нужно сопоставить его действительную роль. Знакомое название метода не гарантирует, что он принимает такой же уже подготовленный объект или возвращает массив прежней формы; это проверяют на небольшом сохранённом примере перед переносом всей коллекции.
| Прежняя задача | Проверка при переходе |
|---|---|
| Подготовить запрос | Сохранить инструкцию и роль запроса |
| Подготовить страницы | Сохранить рендеринг и роль документа |
| Оценить многовекторное сходство | Сохранить маски и агрегацию |
| Выбрать лучшие страницы | Сохранить идентификаторы и обработку равенства |
Сохранить небольшой контрольный набор
Выберем страницу руководства со схемой, другую страницу с похожей лексикой и постороннюю страницу. Вопрос должен иметь ответ только на схеме. Сохраним прежнюю матрицу оценок и порядок страниц вместе с идентификаторами. Затем запустим замену на тех же изображениях и вопросах. Набор проверяет и выбор релевантной страницы, и систематическую причину изменения близких оценок, которые иначе легко счесть случайным численным шумом.
Проверить маски и расположение проекции
Дополняющие токены и нетекстовые либо не относящиеся к изображению embeddings обрабатывают по контракту конкретной модели и руководству миграции. Изменённая маска способна добавить ранее исключённые вклады. Упаковка checkpoint также может размещать проекцию или нормализацию внутри модели либо внешней обёртки. Повторное применение любого шага меняет представление даже при визуально правильной итоговой размерности и успешном выполнении всего кода.
Отделить численный дрейф от смены смысла
Небольшие различия вычислений требуют явно выбранного допуска для реализации, а не выдуманного универсального порога. Изменение порядка почти равных результатов рассматривают отдельно от крупного систематического сдвига. Если сдвинулись все оценки, сначала проверяют агрегацию и подготовку входа. Если изменились отдельные страницы, сравнивают их размеры, преобразование изображений и связанные с ними маски, сохраняя исходные файлы для повторного разбора.
Принять переход перед расширением
Итоговый артефакт содержит карту операций, ревизии, контрольные изображения, прежние и новые оценки, а также объяснение принятых различий. Сначала воспроизводят прежнее поведение, затем отдельно испытывают новые возможности. Такой порядок не позволяет смешать миграцию, обновление модели и смену рендеринга документов в одну необъяснимую регрессию релевантности, для которой невозможно выполнить выборочный откат.
Связанные материалы: Embeddings и rerankers: другие задачи для свободного GPU; Воспроизводимый стек инференса: как сохранить результат GPU-пилота.