Accelerator — глубокий справочник

Краткий обзор

Эта страница — глубокий справочник по публичной поверхности ускорения NextPDF\Pro\Accelerator. Она охватывает фабрику провайдера, ускоренный пакетный оптимизатор, обёртку differ и CPU-службы sidecar для встраивания и векторного поиска. Здесь описаны параметры, значения по умолчанию, режимы сбоев и семантика отката. Сначала прочитайте страницу возможности Accelerator для руководства по рабочим процессам.

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

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

У Accelerator нет пофункционального лицензионного флага. Код поставляется с редакцией Pro; ускоренный путь оптимизатора выбирается во время выполнения зондом доступности sidecar. У службы встраивания и векторного индекса нет резервного варианта на PHP, и при недоступности sidecar они отказывают в закрытое состояние.

Публичная поверхность API

composer require nextpdf/pro:^3

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается ошибкой	Примечания
ProAcceleratorProvider::__construct	SpectrumClient $client	Привязывает провайдер к клиенту sidecar из Core	ProAcceleratorProvider	Ничего не объявлено	Вызывающая сторона создаёт и передаёт клиент
ProAcceleratorProvider::isAvailable	нет	Проверяет доступность sidecar через клиент	bool	Ничего не объявлено	Только доступность; конечные точки проверяются при каждом вызове
ProAcceleratorProvider::embedding	нет	Возвращает мемоизированную службу встраивания	EmbeddingServiceInterface	Ничего не объявлено	Один экземпляр CpuEmbeddingService на провайдер
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Возвращает новый дескриптор индекса, привязанный к коллекции	VectorIndexInterface	Ничего не объявлено	Не мемоизируется; один дескриптор на вызов
ProAcceleratorProvider::optimizer	нет	Возвращает мемоизированный ускоренный оптимизатор	AcceleratedOptimizer	Ничего не объявлено	Создаётся с клиентом провайдера
ProAcceleratorProvider::differ	нет	Возвращает мемоизированную обёртку differ	AcceleratedDiffer	Ничего не объявлено	Создаётся с клиентом провайдера
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Оборачивает PHP-PdfOptimizer на заданном уровне	AcceleratedOptimizer	Ничего не объявлено	Клиент null выбирает путь PHP; логгер null выбирает NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Анализирует каждый документ; при доступности sidecar передаёт работу с изображениями ему	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) при превышении лимита пакета; маркеры ошибок по элементам в резервном результате	Ошибки транспорта после допуска деградируют до пути PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Сохраняет необязательный клиент для будущей совместимости	AcceleratedDiffer	Ничего не объявлено	В этом выпуске клиент не используется
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Полностью сравнивает два документа в PHP	DiffResult	Как у Pro-PdfDiffer	В этом выпуске запрос к sidecar не отправляется
AcceleratedDiffer::isSpectrumWired	нет	Сообщает, был ли внедрён клиент sidecar	bool	Ничего не объявлено	Только состояние привязки; запрос не отправляется
CpuEmbeddingService::embed	string $text	Делегирует batchEmbed и возвращает нулевой элемент	list<float>	Как batchEmbed	Вектор размерности 384
CpuEmbeddingService::batchEmbed	array $texts	Встраивает пакет на sidecar	list<list<float>>	InvalidArgumentException при пустом пакете; SpectrumNotAvailableException при недоступности; SpectrumApiException при неуспешном, некорректном ответе или несоответствии количества	Никогда не возвращает частичные результаты
CpuEmbeddingService::getDimension	нет	Возвращает 384	int	Ничего не объявлено	Константа
CpuEmbeddingService::getModelName	нет	Возвращает all-MiniLM-L6-v2	string	Ничего не объявлено	Константа
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Привязывает дескриптор к одной коллекции	CpuVectorIndex	Ничего не объявлено	Один дескриптор на идентификатор коллекции
CpuVectorIndex::build	array $vectors, array $ids	Строит индекс коллекции на sidecar	void	InvalidArgumentException при несоответствии длины; SpectrumNotAvailableException при недоступности	Пустой вход возвращается без обращения к sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Ранжированный поиск ближайших соседей	list<VectorSearchResult>	SpectrumNotAvailableException при недоступности; SpectrumApiException при внутриполосном конверте ошибки; JsonException при некорректном теле	Ранг каждого попадания в метаданных результата
CpuVectorIndex::delete	array $ids	Всегда отклоняет	void (объявлено)	Всегда: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	В HNSW нет удаления отдельных векторов; выполните перестроение
CpuVectorIndex::count	нет	Читает общее число коллекции через зонд с размерностью	int	SpectrumNotAvailableException при недоступности; SpectrumApiException при ошибке или некорректном ответе с числом	Возвращает 0 только для подтверждённо пустого индекса
CpuVectorIndex::INDEX_DIMENSION	—	Публичная константа 384	int	—	Совпадает с размерностью встраивания

Сигнатуры точек входа

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService implements EmbeddingServiceInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function embed(string $text): array

    public function batchEmbed(array $texts): array

    public function getDimension(): int

    public function getModelName(): string
}

final class CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly string $collectionId = 'default',
    )

    public function build(array $vectors, array $ids): void

    public function search(array $queryVector, int $topK = 10): array

    public function delete(array $ids): void

    public function count(): int
}

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

Провайдер

ProAcceleratorProvider — точка входа. embedding(), optimizer() и differ() мемоизируют свои экземпляры. vectorIndex($collectionId) возвращает новый дескриптор на каждый вызов, привязанный к заданному идентификатору коллекции. isAvailable() проверяет доступность sidecar через внедрённый Core-SpectrumClient.

Пакетная оптимизация

optimizeBatch возвращает результат пакета с ключами по идентификаторам документов вызывающей стороны. Когда sidecar доступен, совокупная полезная нагрузка проверяется по бюджету клиента до какой-либо буферизации или загрузки. Пакет с превышением лимита отказывает в закрытое состояние с SpectrumApiException SPEC-SEC-001 (HTTP 413) и никогда не деградирует до пути PHP. Допущенный пакет отправляется на sidecar для параллельной работы с изображениями.

Ошибка транспорта, аутентификации или разбора ответа после допуска деградирует до PHP-оптимизатора, который анализирует каждый документ последовательно. Деградацию можно наблюдать дважды: метаданные результата сообщают движок php_fallback со сводным оборудованием cpu, а предупреждение PSR-3 выдаётся под именем события spectrum.optimize.fallback. Предупреждение несёт только класс исключения и число документов; байты документов не логируются. В резервном результате сбой анализа отдельного документа даёт элемент со статусом ошибки и кодом SPEC-PARSE-001; остальные документы пакета всё равно завершаются.

Уровень оптимизации по умолчанию — Balanced. Поля результата по элементам: original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent и processing_time_ms.

Сравнение документов

compare выполняется полностью в PHP через Pro-PdfDiffer: разбор структуры, извлечение текста и алгоритм сравнения. В этом выпуске запрос к sidecar не отправляется. Контракт differ принимает только сырые строки PDF, поэтому результат разбора от sidecar использовать нельзя; передача работы дала бы затраты без выгоды. Внедрённый клиент сохраняется для будущей возможности передачи разбора. isSpectrumWired() раскрывает состояние привязки, не отправляя запрос.

CPU-встраивание

embed делегирует batchEmbed([$text]) и возвращает нулевой элемент. batchEmbed([]) выбрасывает InvalidArgumentException до обращения к sidecar. Недоступный sidecar выбрасывает SpectrumNotAvailableException. Семантика пакета — всё или ничего: сбой отдельного элемента, отсутствующий или некорректный вектор либо несоответствие количества выбрасывает SpectrumApiException (сбои формы протокола несут SPEC-IO-001) вместо возврата частичных векторов. Нечисловой компонент внутри возвращённого вектора приводится к 0.0. getDimension возвращает 384; getModelName возвращает all-MiniLM-L6-v2. Sidecar загружает и подгружает модель ONNX лениво при первом запросе.

Векторный поиск на CPU

Каждый дескриптор привязывается к одному идентификатору коллекции; каждая коллекция отображается на отдельный HNSW-индекс в памяти sidecar. build требует списки векторов и идентификаторов равной длины и иначе выбрасывает InvalidArgumentException; пустой вход возвращается без вызова sidecar. search возвращает ранжированные попадания с рангом от единицы в метаданных каждого результата. Внутриполосный конверт ошибки выбрасывает SpectrumApiException; конверт без кода отображается на SPEC-INDEX-003. delete всегда отклоняет с SpectrumApiException SPEC-INDEX-004 (HTTP 501, без повторных попыток), потому что HNSW не поддерживает удаление отдельных векторов; вместо этого перестройте индекс.

count работает с отказом в закрытое состояние и однозначно. Недоступный sidecar выбрасывает SpectrumNotAvailableException; ошибки транспорта и sidecar распространяются без изменений. При в остальном успешном ответе тело не в формате JSON выбрасывает SPEC-INDEX-005, отсутствующее metadata.total_vectors выбрасывает SPEC-INDEX-006, а нецелое или отрицательное значение выбрасывает SPEC-INDEX-007. count возвращает 0 только для подтверждённо пустого индекса. Зонд размера отправляет нулевой вектор ровно INDEX_DIMENSION (384) размерностей с top_k, равным 0, поэтому sidecar, проверяющий размерность, принимает его.

Граничные случаи и режимы сбоев

• Память sidecar волатильна: перезапуск очищает все коллекции HNSW. Считайте построение индекса идемпотентным и повторяйте его после перезапуска.
• Смешанная доступность в рамках одного процесса поддерживается: оптимизатор деградирует на каждом вызове; службы встраивания и векторов отказывают в закрытое состояние на каждом вызове.
• Пакет оптимизатора с превышением лимита отказывает в закрытое состояние до какой-либо загрузки; он не откатывается на путь PHP.
• Откат оптимизатора никогда не завершается сбоем молча: проверяйте маркер движка в метаданных результата и отслеживайте событие предупреждения.
• count никогда не сообщает недоступный sidecar или ошибку протокола как 0; они выбрасывают типизированные исключения.
• Попадание поиска без идентификатора или оценки по умолчанию получает пустую строку и 0.0, а не приводит к сбою пакета.
• top_k, равный 0, используется внутренне только для зонда count; для реальных поисков передавайте положительный topK.
• Первый запрос встраивания оплачивает разовую загрузку и подгрузку модели; задавайте этот тайм-аут отдельно.
• Иерархия исключений sidecar и семейства кодов ошибок каталогизированы в справочнике ошибок Accelerator.
• Этот модуль не выполняет криптографических операций и не определяет поведения, специфичного для FIPS. Готовность к режиму FIPS определяется модулями подписания и соответствия требованиям, а не здесь.

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

Accelerator делегирует работу, влияющую на формат, модулям Optimizer и Diff и не утверждает независимого соответствия формату. Соответствие для делегированной работы документировано на справочных страницах Optimizer и Diff. На этой странице не заявляются внешние идентификаторы пунктов; каждое утверждение основано на исходном коде продукта. NextPDF не заявляет о какой-либо сертификации.

Заметки по разработке

• Исходный код модуля несёт @since 2.1.0; этот справочник документирует поверхность в том виде, в каком она поставлена в nextpdf/pro 3.1.0.
• Все классы объявлены final и используют внедрение через конструктор; создавайте новые экземпляры вместо изменения существующих.
• SpectrumClient, VectorSearchResult, BatchResultInterface, а также контракты EmbeddingServiceInterface и VectorIndexInterface происходят из NextPDF Core; вызывающая сторона создаёт и передаёт клиент sidecar.
• OptimizationLevel, PdfOptimizer и PdfDiffer происходят из модулей Pro Optimizer и Diff; их семантика документирована на соответствующих справочных страницах.
• Служба встраивания и векторный индекс используют общую размерность 384. Стройте векторы индекса той же размерности, что и встраивания, которые их запрашивают.
• Детали внутреннего механизма остаются во внутренней документации исходного репозитория и выходят за рамки этого руководства.

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

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

См. также

• Accelerator — страница возможности с руководством по рабочим процессам.
• Справочник ошибок Accelerator — иерархия исключений sidecar и коды ошибок.
• Optimizer — глубокий справочник
• Diff — глубокий справочник
• Accelerator — глубокий справочник NextPDF Enterprise