Pro редакция

Accelerator

Кратко

Accelerator выгружает пакетную повторную компрессию изображений, разбор PDF и встраивание текста в совмещённый sidecar-сервис на CPU. Когда sidecar недоступен, каждая операция возвращается к внутрипроцессному пути PHP, поэтому вызывающий код в любом случае наблюдает одинаковые результаты.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без такого права не загружает классы возможности. Сравните редакции и получите лицензию.

У Accelerator нет отдельного флага для каждой функции. Ускоренный путь выбирается во время выполнения проверкой доступности sidecar (ProAcceleratorProvider::isAvailable()); когда sidecar недоступен, вместо него выполняется внутрипроцессный путь PHP.

Установка

composer require nextpdf/pro:^3

Пакет Premium устанавливает код nextpdf/pro в пространстве имён NextPDF\Pro\Accelerator. Метапакет nextpdf/premium также устанавливает возможности Enterprise; сам Accelerator — это возможность уровня Pro.

Концептуальный обзор

ProAcceleratorProvider — это точка входа. Он лениво конструирует четыре сервиса:

Ускоренный оптимизатор, который оборачивает Pro PdfOptimizer и выгружает пакетную работу с изображениями в sidecar.
Ускоренный дифер, который оборачивает Pro PdfDiffer; sidecar распараллеливает разбор структуры, тогда как сам алгоритм сравнения выполняется в PHP.
Сервис встраивания на CPU, возвращающий 384-мерные векторы с использованием модели ONNX all-MiniLM-L6-v2, размещённой sidecar.
Векторный индекс на CPU, который строит и ищет индекс HNSW в памяти по идентификатору коллекции.

Дизайн сохраняет доменную логику в PHP. Sidecar выполняет распараллеливаемую, ограниченную CPU работу (транскодирование изображений, разбор множества документов, вывод ONNX, векторный поиск). Каждый ускоренный путь имеет детерминированный резервный путь PHP, который даёт эквивалентные результаты.

Почему это работает именно так

Несущее решение состоит в том, что корректность никогда не зависит от sidecar. Доменная логика остаётся в PHP; sidecar лишь выполняет распараллеливаемую, ограниченную CPU работу. Оптимизатор и дифер (AcceleratedOptimizer, AcceleratedDiffer) сохраняют детерминированный резервный путь PHP, поэтому отсутствующий sidecar меняет время, а не результаты. Только две операции без эквивалента PHP — CpuEmbeddingService и CpuVectorIndex — отказывают закрыто, а не понижают уровень. Молчаливый неверный ответ там был бы хуже явной ошибки. Такое разделение позволяет пропускной способности масштабироваться с числом ядер sidecar, тогда как вызывающий код сохраняет один путь кода и одну границу доверия.

Дизайн-контекст: Генерация документов большого объёма.

Контракт поведения

ProAcceleratorProvider::isAvailable() возвращает, отвечает ли sidecar. Вызывающий код может ветвиться по этому значению, но не обязан: оптимизатор и дифер возвращаются к резервному пути автоматически.
embedding()->embed() возвращает один 384-элементный вектор; batchEmbed() возвращает по одному вектору на вход и отклоняет пустой список входов с InvalidArgumentException.
vectorIndex($collectionId)->build() требует, чтобы vectors и ids были одинаковой длины, и рассматривает пустой вход как холостую операцию.
vectorIndex()->search($queryVector, $topK) возвращает ранжированные результаты; delete() не поддерживается для индекса HNSW и отклоняет вызов — вместо этого вызывающий код перестраивает индекс.
Сервис встраивания и векторный индекс требуют sidecar; они вызывают ошибку «недоступно», а не понижают уровень молча, потому что нет эквивалента PHP для вывода ONNX или поиска HNSW.
Оптимизатор и дифер никогда не вызывают ошибку при сбое sidecar; они прозрачно понижаются до пути PHP.

Пример кода — быстрый старт

Следующее отражает документированный публичный API (ProAcceleratorProvider). Репозиторий не поставляет запускаемого примера для этого модуля.

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

Пример кода — продакшен

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

Подключите ProAcceleratorProvider через ваш контейнер как singleton, чтобы экземпляры оптимизатора и дифера повторно использовались. Рассматривайте вызовы встраивания и векторного индекса как требующие sidecar.

Граничные случаи и подводные камни

Векторный индекс живёт в памяти процесса sidecar и индексируется по идентификатору коллекции. Перезапуск sidecar очищает все индексы; перестройте после перезапуска.
count() на векторном индексе возвращает 0, когда sidecar недоступен, а не вызывает ошибку.
Ускорение оптимизатора и дифера — по принципу «как получится»; ошибка sidecar в середине пакета приводит к молчаливому возврату к резервному пути для этого вызова, поэтому варьируется время, а не корректность.

Производительность

Ускорение нацелено на ограниченную CPU пакетную работу: параллельное транскодирование изображений, разбор множества документов и векторный поиск. NextPDF не публикует здесь фиксированный множитель пропускной способности; выигрыш зависит от состава документов, плотности изображений, числа ядер sidecar и размера пакета. Измеряйте в своей среде, прежде чем полагаться на конкретное число. Резервный путь PHP однопоточен по замыслу.

Замечания по безопасности

Этот модуль отправляет документы и векторы в совмещённый sidecar по его настроенному транспорту. Рассматривайте sidecar как часть вашей границы доверия и развёртывайте его на том же хосте или в частном сетевом сегменте. Модуль проверяет размер и форму входа перед отправкой. Он не записывает в журнал содержимое документа.

Соответствие

Этот модуль сам не выполняет работы по соответствию формату; он делегирует оптимизацию и сравнение модулям Pro Optimizer и Diff. См. эти модули для ссылок ISO 32000-2. Доказательства соответствия для этой страницы взяты из документированных публичных контрактов классов и их модульных тестов; корпус RAG был недоступен на момент написания, поэтому здесь не заявляются внешние идентификаторы пунктов.

Примечание о границе Enterprise

Enterprise не меняет поведение Accelerator. Enterprise добавляет возможности более высокого уровня по соответствию, архивированию и жизненному циклу подписи, документированные отдельно; они выходят за рамки этого модуля и не требуются для использования Accelerator.

Резервный вариант / альтернатива Core

Без Pro используйте внутрипроцессную оптимизацию и сравнение NextPDF Core. Ускоренные пути в этом модуле сводятся к тому же поведению PHP, когда sidecar отсутствует.

Граница публикации

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