Accelerator — 심층 참조

한눈에 보기

이 페이지는 NextPDF\Pro\Accelerator의 공개 가속 표면에 대한 심층 레퍼런스입니다. provider 팩토리, 가속 배치 optimizer, differ 래퍼, 그리고 임베딩과 벡터 검색을 위한 CPU 사이드카 서비스를 다룹니다. 매개변수, 기본값, 실패 모드, 폴백 시맨틱을 명시합니다. 워크플로 안내는 Accelerator 기능 페이지를 먼저 읽으십시오.

제공 여부 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 계층 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 에디션 비교 및 라이선스 받기.

Accelerator에는 기능별 라이선스 플래그가 없습니다. 코드는 Pro 에디션과 함께 제공되며, 가속 optimizer 경로는 사이드카 도달 가능성 프로브로 런타임에 선택됩니다. 임베딩 서비스와 벡터 인덱스에는 PHP 폴백이 없으며 사이드카에 도달할 수 없을 때 실패-차단됩니다.

공개 API 표면

composer require nextpdf/pro:^3

nextpdf/premium 메타패키지가 nextpdf/pro 코드를 설치합니다. 이 모듈은 NextPDF\Pro\Accelerator 네임스페이스 아래에 있습니다.

심볼	매개변수	기본 동작	반환	발생 또는 실패	비고
ProAcceleratorProvider::__construct	SpectrumClient $client	provider를 Core 사이드카 클라이언트에 바인딩	ProAcceleratorProvider	선언된 것 없음	호출자가 클라이언트를 구성하여 공급
ProAcceleratorProvider::isAvailable	없음	클라이언트를 통해 사이드카 도달 가능성을 프로브	bool	선언된 것 없음	도달 가능성만 확인; 엔드포인트는 호출마다 프로브
ProAcceleratorProvider::embedding	없음	메모이즈된 임베딩 서비스를 반환	EmbeddingServiceInterface	선언된 것 없음	provider당 CpuEmbeddingService 인스턴스 하나
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	컬렉션에 바인딩된 새 인덱스 핸들을 반환	VectorIndexInterface	선언된 것 없음	메모이즈되지 않음; 호출마다 핸들 하나
ProAcceleratorProvider::optimizer	없음	메모이즈된 가속 optimizer를 반환	AcceleratedOptimizer	선언된 것 없음	provider의 클라이언트로 구성됨
ProAcceleratorProvider::differ	없음	메모이즈된 differ 래퍼를 반환	AcceleratedDiffer	선언된 것 없음	provider의 클라이언트로 구성됨
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	각 문서를 분석; 도달 가능할 때 이미지 작업을 사이드카로 오프로드	BatchResultInterface	한도 초과 배치에서 SpectrumApiException SPEC-SEC-001 (HTTP 413); 폴백 결과의 항목별 오류 마커	승인 이후의 전송 실패는 PHP 경로로 격하됨
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	향후 호환성을 위해 선택적 클라이언트를 보관	AcceleratedDiffer	선언된 것 없음	이 릴리스에서 클라이언트는 사용되지 않음
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	두 문서를 전적으로 PHP에서 비교	DiffResult	Pro PdfDiffer와 동일	이 릴리스에서 사이드카 요청은 발행되지 않음
AcceleratedDiffer::isSpectrumWired	없음	사이드카 클라이언트가 주입되었는지 보고	bool	선언된 것 없음	배선 상태만; 요청을 발행하지 않음
CpuEmbeddingService::embed	string $text	batchEmbed에 위임하고 요소 0을 반환	list<float>	batchEmbed와 동일	384차원 벡터
CpuEmbeddingService::batchEmbed	array $texts	사이드카에서 배치를 임베딩	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	사이드카에서 컬렉션 인덱스를 빌드	void	길이 불일치에서 InvalidArgumentException; 도달 불가 시 SpectrumNotAvailableException	빈 입력은 사이드카에 접촉하지 않고 반환
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; 오류 또는 잘못된 형식의 count 응답에서 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()은 주입된 Core SpectrumClient를 통해 사이드카 도달 가능성을 프로브합니다.

배치 최적화

optimizeBatch는 호출자의 문서 식별자로 키가 지정된 배치 결과를 반환합니다. 사이드카에 도달할 수 있을 때, 어떠한 버퍼링이나 업로드 이전에 집계 페이로드가 클라이언트 예산 대비 검증됩니다. 한도 초과 배치는 SpectrumApiException SPEC-SEC-001 (HTTP 413)으로 실패-차단되며, PHP 경로로 결코 격하되지 않습니다. 승인된 배치는 병렬 이미지 작업을 위해 사이드카로 디스패치됩니다.

승인 이후의 전송, 인증, 또는 응답 파싱 실패는 각 문서를 순차적으로 분석하는 PHP optimizer로 격하됩니다. 격하는 두 곳에서 관찰 가능합니다. 결과 메타데이터가 요약 하드웨어 cpu와 함께 엔진 php_fallback을 보고하고, 이벤트 이름 spectrum.optimize.fallback 하에 PSR-3 경고가 방출됩니다. 경고는 예외 클래스와 문서 개수만 담으며, 문서 바이트는 로깅되지 않습니다. 폴백 결과에서 문서별 분석 실패는 오류 상태와 코드 SPEC-PARSE-001을 갖는 항목을 산출하며, 배치의 다른 문서는 여전히 완료됩니다.

기본 최적화 레벨은 Balanced입니다. 항목별 결과 필드는 original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent, processing_time_ms입니다.

문서 diff

compare는 Pro PdfDiffer를 통해 전적으로 PHP에서 실행됩니다. 구조 파싱, 텍스트 추출, diff 알고리즘이 그렇습니다. 이 릴리스에서 사이드카 요청은 발행되지 않습니다. differ 계약은 원시 PDF 문자열만 받으므로 사이드카 파싱 결과를 소비할 수 없으며, 오프로딩은 이득 없이 비용만 추가하게 됩니다. 주입된 클라이언트는 향후 파싱 오프로드 기능을 위해 보관됩니다. isSpectrumWired()는 요청을 발행하지 않고 배선 상태를 노출합니다.

CPU 임베딩

embed는 batchEmbed([$text])에 위임하고 요소 0을 반환합니다. batchEmbed([])는 사이드카에 접촉하기 전에 InvalidArgumentException을 발생시킵니다. 도달할 수 없는 사이드카는 SpectrumNotAvailableException을 발생시킵니다. 배치 시맨틱은 전부-아니면-전무입니다. 항목별 실패, 누락되거나 잘못된 형식의 벡터, 또는 개수 불일치는 부분 벡터를 반환하는 대신 SpectrumApiException을 발생시킵니다(프로토콜 형태 실패는 SPEC-IO-001을 수반). 반환된 벡터 내의 비수치 성분은 0.0으로 강제 변환됩니다. getDimension은 384를 반환하고, getModelName은 all-MiniLM-L6-v2를 반환합니다. 사이드카는 첫 요청 시 ONNX 모델을 지연 다운로드하여 로드합니다.

CPU 벡터 검색

각 핸들은 하나의 컬렉션 식별자에 바인딩되고, 각 컬렉션은 사이드카의 별도 인메모리 HNSW 인덱스에 매핑됩니다. build는 길이가 같은 벡터와 식별자 리스트를 요구하며 그렇지 않으면 InvalidArgumentException을 발생시킵니다. 빈 입력은 사이드카 호출 없이 반환합니다. search는 각 결과의 메타데이터에 1부터 시작하는 순위를 담아 랭크된 히트를 반환합니다. 인밴드 오류 봉투는 SpectrumApiException을 발생시키며, 코드가 없는 봉투는 SPEC-INDEX-003으로 매핑됩니다. delete는 HNSW가 벡터별 삭제를 지원하지 않으므로 항상 SpectrumApiException SPEC-INDEX-004 (HTTP 501, 재시도 불가)로 거부합니다. 대신 인덱스를 재빌드하십시오.

count는 실패-차단이며 명확합니다. 도달할 수 없는 사이드카는 SpectrumNotAvailableException을 발생시키고, 전송 및 사이드카 오류는 변경 없이 전파됩니다. 그 외에 성공한 응답에서, JSON이 아닌 본문은 SPEC-INDEX-005를, 누락된 metadata.total_vectors는 SPEC-INDEX-006을, 정수가 아니거나 음수인 총계는 SPEC-INDEX-007을 발생시킵니다. count는 확인된 빈 인덱스에 대해서만 0을 반환합니다. 크기 프로브는 정확히 INDEX_DIMENSION(384) 차원의 영 벡터를 top_k 0으로 제출하므로, 차원을 검증하는 사이드카가 이를 수락합니다.

엣지 케이스 및 실패 모드

• 사이드카 메모리는 휘발성입니다. 재시작은 모든 HNSW 컬렉션을 지웁니다. 인덱스 빌드를 멱등적으로 취급하고 재시작 후 다시 실행하십시오.
• 단일 프로세스 내의 혼합 가용성이 지원됩니다. optimizer는 호출마다 격하되고, 임베딩과 벡터 서비스는 호출마다 실패-차단됩니다.
• 한도 초과 optimizer 배치는 어떠한 업로드 이전에 실패-차단됩니다. PHP 경로로 폴백하지 않습니다.
• optimizer 폴백은 결코 조용히 실패하지 않습니다. 결과 메타데이터 엔진 마커를 확인하고 경고 이벤트를 모니터링하십시오.
• count는 도달할 수 없는 사이드카나 프로토콜 오류를 결코 0으로 보고하지 않습니다. 그것들은 타입이 지정된 예외를 발생시킵니다.
• 식별자나 점수가 누락된 검색 히트는 배치를 실패시키는 대신 빈 문자열과 0.0으로 기본 설정됩니다.
• top_k 0은 count 프로브를 위해서만 내부적으로 사용됩니다. 실제 검색에는 양수 topK를 전달하십시오.
• 첫 임베딩 요청은 일회성 모델 다운로드와 로드 비용을 지불합니다. 해당 타임아웃은 별도로 설정하십시오.
• 사이드카 예외 계층과 오류 코드 계열은 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에서 옵니다. 호출자가 사이드카 클라이언트를 구성하여 공급합니다.
• OptimizationLevel, PdfOptimizer, PdfDiffer는 Pro Optimizer 및 Diff 모듈에서 옵니다. 그 시맨틱은 해당 레퍼런스 페이지에 문서화되어 있습니다.
• 임베딩 서비스와 벡터 인덱스는 384 차원을 공유합니다. 인덱스 벡터를 그것을 쿼리하는 임베딩과 동일한 차원으로 빌드하십시오.
• 내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남아 있으며 이 매뉴얼의 범위를 벗어납니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• Accelerator — 워크플로 안내를 위한 기능 페이지.
• Accelerator 오류 레퍼런스 — 사이드카 예외 계층 및 오류 코드.
• Optimizer — 심층 레퍼런스
• Diff — 심층 레퍼런스
• Accelerator — NextPDF Enterprise 심층 레퍼런스