Accelerator

한눈에 보기

Accelerator는 배치 이미지 재압축, PDF 파싱, 그리고 텍스트 임베딩을 같은 위치에 배치된 CPU 사이드카로 오프로드합니다. 사이드카에 도달할 수 없을 때는 모든 작업이 인프로세스 PHP 경로로 폴백하므로, 호출자는 어느 쪽이든 동일한 결과를 관찰합니다.

제공 범위 및 라이선스

이 역량은 NextPDF Pro(nextpdf/pro)에 포함되어 제공되며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 엔타이틀먼트가 없는 배포에서는 이 역량의 클래스가 로드되지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

Accelerator에는 별도의 기능별 플래그가 없습니다. 가속 경로는 런타임에 사이드카 도달성 검사(ProAcceleratorProvider::isAvailable())로 선택됩니다. 사이드카에 도달할 수 없을 때는 대신 인프로세스 PHP 경로가 실행됩니다.

설치

composer require nextpdf/pro:^3

Premium 패키지는 nextpdf/pro 코드를 NextPDF\Pro\Accelerator 네임스페이스 아래에 설치합니다. nextpdf/premium 메타패키지는 Enterprise 역량도 설치합니다. Accelerator 자체는 Pro 등급 기능입니다.

개념 개요

ProAcceleratorProvider가 진입점입니다. 네 가지 서비스를 지연(lazily) 구성합니다.

• Pro PdfOptimizer를 감싸고 배치 이미지 작업을 사이드카로 오프로드하는 가속 옵티마이저.
• Pro PdfDiffer를 감싸는 가속 디퍼. 사이드카가 구조 파싱을 병렬화하는 동안 diff 알고리즘 자체는 PHP에서 실행됩니다.
• 사이드카가 호스팅하는 all-MiniLM-L6-v2 ONNX 모델을 사용하여 384차원 벡터를 반환하는 CPU 임베딩 서비스.
• 컬렉션 식별자로 키가 지정된 인메모리 HNSW 인덱스를 빌드하고 검색하는 CPU 벡터 인덱스.

이 설계는 도메인 로직을 PHP에 유지합니다. 사이드카는 병렬화 가능한 CPU 바운드 작업(이미지 트랜스코딩, 다중 문서 파싱, ONNX 추론, 벡터 검색)을 수행합니다. 각 가속 경로에는 동등한 결과를 산출하는 결정적 PHP 폴백이 있습니다.

이렇게 동작하는 이유

핵심을 지탱하는 결정은 정확성이 결코 사이드카에 의존하지 않는다는 것입니다. 도메인 로직은 PHP에 남고, 사이드카는 병렬화 가능한 CPU 바운드 작업만 수행합니다. 옵티마이저와 디퍼(AcceleratedOptimizer, AcceleratedDiffer)는 결정적 PHP 폴백을 유지하므로, 사이드카가 없으면 결과가 아니라 타이밍이 바뀝니다. PHP 등가물이 없는 두 작업 — CpuEmbeddingService와 CpuVectorIndex — 만이 격하되는 대신 실패로 닫힙니다(fail closed). 그 지점에서 조용한 오답은 명시적 오류보다 더 나쁠 것이기 때문입니다. 그 분리 덕분에 처리량은 사이드카 코어에 따라 확장되는 한편, 호출자는 하나의 코드 경로와 하나의 신뢰 경계를 유지합니다.

설계 배경: 대량 문서 생성.

동작 계약

• ProAcceleratorProvider::isAvailable()은 사이드카가 응답하는지 여부를 반환합니다. 호출자는 이를 분기할 수 있지만 그럴 필요는 없습니다. 옵티마이저와 디퍼는 자동으로 폴백합니다.
• embedding()->embed()는 단일 384요소 벡터를 반환합니다. batchEmbed()는 입력당 하나의 벡터를 반환하며 빈 입력 목록을 InvalidArgumentException으로 거부합니다.
• vectorIndex($collectionId)->build()는 vectors와 ids가 같은 길이일 것을 요구하며 빈 입력을 무동작(no-op)으로 취급합니다.
• vectorIndex()->search($queryVector, $topK)는 순위가 매겨진 결과를 반환합니다. delete()는 HNSW 인덱스에서 지원되지 않으며 호출을 거부합니다 — 호출자는 대신 인덱스를 다시 빌드합니다.
• 임베딩 서비스와 벡터 인덱스는 사이드카를 요구합니다. ONNX 추론이나 HNSW 검색에 대한 PHP 등가물이 없으므로, 조용히 격하하는 대신 “사용 불가” 오류를 발생시킵니다.
• 옵티마이저와 디퍼는 사이드카 실패 시 결코 오류를 발생시키지 않습니다. 투명하게 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를 컨테이너를 통해 싱글톤으로 와이어링하십시오. 임베딩 및 벡터 인덱스 호출은 사이드카를 요구하는 것으로 취급하십시오.

엣지 케이스 및 함정

• 벡터 인덱스는 사이드카 프로세스 메모리에 존재하며 컬렉션 식별자로 키가 지정됩니다. 사이드카 재시작은 모든 인덱스를 지웁니다. 재시작 후 다시 빌드하십시오.
• 벡터 인덱스의 count()는 사이드카에 도달할 수 없을 때 오류를 발생시키는 대신 0을 반환합니다.
• 옵티마이저와 디퍼 가속은 최선 노력(best-effort)입니다. 배치 중간의 사이드카 오류는 해당 호출에 대해 조용한 폴백을 유발하므로 정확성이 아니라 타이밍이 달라집니다.

성능

가속은 CPU 바운드 배치 작업을 대상으로 합니다. 즉, 병렬 이미지 트랜스코딩, 다중 문서 파싱, 벡터 검색입니다. NextPDF는 여기에 고정된 처리량 배수를 발행하지 않습니다. 이득은 문서 구성, 이미지 밀도, 사이드카 코어 수, 배치 크기에 따라 달라집니다. 특정 수치에 의존하기 전에 자체 환경에서 측정하십시오. PHP 폴백은 설계상 단일 스레드입니다.

보안 참고 사항

이 모듈은 문서와 벡터를 구성된 전송을 통해 같은 위치에 배치된 사이드카로 전송합니다. 사이드카를 신뢰 경계의 일부로 취급하고 동일한 호스트나 사설 네트워크 세그먼트에 배포하십시오. 이 모듈은 디스패치 전에 입력 크기와 형태를 검증합니다. 어떤 문서 콘텐츠도 로그에 기록하지 않습니다.

적합성

이 모듈은 어떠한 형식 적합성 작업도 자체적으로 수행하지 않습니다. 최적화와 diff를 Pro Optimizer 및 Diff 모듈에 위임합니다. ISO 32000-2 참조는 해당 모듈을 참조하십시오. 이 페이지의 적합성 증거는 문서화된 공개 클래스 계약과 그 단위 테스트에서 비롯됩니다. 작성 시점에 RAG 코퍼스를 사용할 수 없었으므로 여기에서는 어떠한 외부 조항 식별자도 주장하지 않습니다.

Enterprise 경계 참고

Enterprise는 Accelerator 동작을 변경하지 않습니다. Enterprise는 다른 곳에 문서화된 상위 등급의 규정 준수, 아카이브, 서명 수명 주기 기능을 추가합니다. 그것들은 이 모듈의 범위 밖이며 Accelerator를 사용하는 데 필요하지 않습니다.

Core 폴백 / 대안

Pro 없이는 NextPDF Core의 인프로세스 최적화와 diff를 사용하십시오. 이 모듈의 가속 경로는 사이드카가 없을 때 그 동일한 PHP 동작으로 축소됩니다.

발행 경계

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

참고 항목

• Accelerator — 심층 참조
• Optimizer
• Diff
• Output Pipeline