Enterprise 에디션

Accelerator — 심층 참조 (GPU 사이드카, KMS 공급자 팩토리)

한눈에 보기

이 페이지는 NextPDF\Enterprise\Accelerator의 공개 가속 표면에 대한 심층 참조입니다. KMS 공급자 스택 — 팩토리, 공급자 계약, 로컬 공급자, 키 메타데이터 결과 — 와 임베딩 및 벡터 검색을 위한 GPU 사이드카 서비스를 다룹니다. 매개변수, 기본값, 실패 모드, 그리고 키 보관 입장을 명시합니다. 워크플로 안내는 먼저 Accelerator 기능 페이지를 읽으십시오. 동일한 네임스페이스의 다른 심볼은 다른 기능에 속하며 이 페이지의 범위 밖입니다.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되어 제공되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

KMS 공급자는 런타임에 선택됩니다. 호출 코드는 구체적인 공급자가 아니라 공급자 계약에 의존합니다. 임베딩 및 벡터 인덱스 서비스는 Core EmbeddingServiceInterface 및 VectorIndexInterface 계약을 구현합니다.

공개 API 표면

composer require nextpdf/enterprise:^3

심볼	매개변수	기본 동작	반환	발생 예외 또는 실패	비고
`KmsProviderFactory::fromEnvironment`	없음	선택자 변수가 지정한 공급자를 구축함; 미설정 또는 빈 값은 `local`을 선택	`KmsProviderInterface`	마스터 키 누락, 사용 불가한 클라우드 공급자, 또는 알 수 없는 이름에 대해 `RuntimeException`	정적 진입점
`KmsProviderFactory::create`	`string $providerType`, `array $config = []`	명시적 구성으로부터 지정된 공급자를 구축함	`KmsProviderInterface`	`local`에 비어 있지 않은 `encryption_key`가 없거나 알 수 없는 이름일 때 `RuntimeException`	이 릴리스에서 구축 가능한 이름은 `local`뿐임
`KmsProviderInterface::getEncryptionKey`	`string $collectionId`	컬렉션의 현재 키 메타데이터를 반환함	`EncryptionKeyResult`	공급자에 연결할 수 없거나 잘못 구성된 경우 `RuntimeException`(계약)	메타데이터만; 원시 키 바이트는 절대 없음
`KmsProviderInterface::rotateKey`	`string $collectionId`	키 버전을 진전시킴	`EncryptionKeyResult`	회전이 실패할 때 `RuntimeException`(계약)	회전은 호출자에 대한 재암호화 신호임
`KmsProviderInterface::providerName`	없음	정규 공급자 이름을 보고함	`string`	선언된 것 없음	`local`, `aws`, `gcp`, `azure`, `vault`
`LocalKmsProvider::__construct`	`string $encryptionKey` (민감)	최소 64개의 16진 문자(32바이트)인 16진 마스터 키를 검증함	`LocalKmsProvider`	짧거나 16진이 아닌 값에 대해 `InvalidArgumentException`	빠른 실패 가드; 자체적으로 도출을 수행하지 않음
`LocalKmsProvider::getEncryptionKey`	`string $collectionId`	`local:{collectionId}:v{version}`를 발행함; 버전 기본값은 1	`EncryptionKeyResult`	선언된 것 없음	알고리즘 레이블 `AES-256-GCM`
`LocalKmsProvider::rotateKey`	`string $collectionId`	인프로세스 버전 카운터를 증가시킴	`EncryptionKeyResult`	선언된 것 없음	버전 상태는 인스턴스별임
`EncryptionKeyResult::__construct`	`string $keyId`, `int $keyVersion`, `string $algorithm = 'AES-256-GCM'`, `string $provider = 'local'`	불변 메타데이터 값 객체	`EncryptionKeyResult`	선언된 것 없음	키 자료를 절대 지니지 않음
`GpuEmbeddingService::embed`	`string $text`	`batchEmbed`에 위임하고 0번째 요소를 반환함	`list<float>`	`batchEmbed`와 동일	1024차원 벡터
`GpuEmbeddingService::batchEmbed`	`array $texts`	사이드카에서 배치를 임베딩함	`list<list<float>>`	빈 배치에 대해 `InvalidArgumentException`; 사이드카에 연결할 수 없을 때 `SpectrumNotAvailableException`; 실패했거나 형식이 잘못되었거나 개수가 일치하지 않는 응답에 대해 `SpectrumApiException`	부분 결과를 절대 반환하지 않음
`GpuEmbeddingService::getDimension`	없음	`1024`를 반환함	`int`	선언된 것 없음	상수
`GpuEmbeddingService::getModelName`	없음	`multilingual-e5-large`를 반환함	`string`	선언된 것 없음	상수
`GpuVectorIndex::__construct`	`SpectrumClient $client`, `string $collectionId = 'default'`	핸들을 하나의 컬렉션에 바인딩함	`GpuVectorIndex`	선언된 것 없음	컬렉션 식별자당 하나의 핸들
`GpuVectorIndex::build`	`array $vectors`, `array $ids`	사이드카에서 컬렉션 인덱스를 구축함	`void`	빈 배치 또는 길이 불일치에 대해 `InvalidArgumentException`; 연결할 수 없을 때 `SpectrumNotAvailableException`; 예상치 못한 구축 응답에 대해 `SpectrumApiException`	재구축은 인덱스를 대체함
`GpuVectorIndex::search`	`array $queryVector`, `int $topK = 10`	순위가 매겨진 최근접 이웃 검색	`list<VectorSearchResult>`	연결할 수 없을 때 `SpectrumNotAvailableException`; 형식이 잘못된 응답 본문에 대해 `JsonException`	결과 메타데이터의 히트별 순위
`GpuVectorIndex::delete`	`array $ids`	항상 거부함	`void` (선언됨)	항상: `SpectrumApiException` (구현되지 않음)	구축된 인덱스는 불변임; 대신 재구축
`GpuVectorIndex::count`	없음	사이드카에서 컬렉션 총계를 읽음	`int`	예외를 던지지 않음; 어떤 실패든 `0`을 반환	`0`은 모호함: 비어 있거나 연결 불가

진입점 시그니처

final class KmsProviderFactory
{
    public static function fromEnvironment(): KmsProviderInterface

    public static function create(string $providerType, array $config = []): KmsProviderInterface
}

interface KmsProviderInterface
{
    public function getEncryptionKey(string $collectionId): EncryptionKeyResult;

    public function rotateKey(string $collectionId): EncryptionKeyResult;

    public function providerName(): string;
}

final class LocalKmsProvider implements KmsProviderInterface
{
    public function __construct(
        #[SensitiveParameter]
        private readonly string $encryptionKey,
    )
}

final readonly class EncryptionKeyResult
{
    public function __construct(
        public string $keyId,
        public int $keyVersion,
        public string $algorithm = 'AES-256-GCM',
        public string $provider = 'local',
    )
}

final class GpuEmbeddingService 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 GpuVectorIndex implements VectorIndexInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
        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
}

구성 표면

설정	소비자	의미
`SPECTRUM_KMS_PROVIDER`	`fromEnvironment()`	공급자 선택자. 미설정 또는 빈 값은 `local`로 해석됨.
`SPECTRUM_ENCRYPTION_KEY`	`local` 공급자 경로	16진 인코딩 마스터 키; 최소 64개의 16진 문자(32바이트). 사이드카와 공유됨.
`encryption_key`	`create('local', [...])`	명시적 마스터 키; 동일한 형식과 검증.

동작 계약

공급자 선택

KmsProviderFactory::fromEnvironment는 선택자 변수를 읽고 기본값으로 local을 사용합니다. 클라우드 공급자 이름 aws, gcp, azure, vault는 인식되지만 이 릴리스에서는 구축할 수 없습니다. aws를 선택하면 필요한 aws/aws-sdk-php 패키지를 명시하는 타입 지정된 오류가 발생합니다. 나머지 세 개는 통합이 구현되지 않았다고 보고합니다. 알 수 없는 이름은 지원되는 이름을 나열하는 타입 지정된 오류를 발생시킵니다. KmsProviderFactory::create는 명시적 공급자 이름과 구성 맵을 받습니다. 구축하는 이름은 local뿐입니다.

키 메타데이터와 보관

공급자는 불변 키 메타데이터를 반환합니다: 키 식별자, 단조 증가하는 키 버전, 알고리즘 레이블, 그리고 공급자 이름입니다. 원시 키 바이트는 절대 반환하지 않으므로 메타데이터 유출은 키 자료를 노출하지 않습니다. 로컬 공급자는 accelerator 사이드카와 임무를 분담합니다. PHP 클래스는 생성 시 마스터 비밀을 검증하고 local:{collectionId}:v{version} 형식의 안정적이고 컬렉션 범위의 키 신원을 발행합니다. 사이드카는 HKDF-SHA256 도출과 AES-256-GCM 암호화를 수행하며, 컬렉션 식별자와 버전을 도메인 구분자로 사용하여 컬렉션마다 별개의 32바이트 데이터 암호화 키를 도출합니다. 양측은 동일하게 구성된 마스터 비밀을 읽습니다. 외부 KMS 서비스에는 연결하지 않습니다. 키 처리는 배포 내부에 머뭅니다. 키 버전과 라이프사이클 모델은 NIST SP 800-57 Part 1 Rev.5 §4를 따릅니다.

회전 호출은 키 버전을 진전시키고 새 메타데이터를 반환합니다. 호출자는 새 버전으로 컬렉션 데이터를 다시 암호화합니다. 공급자 자체는 아무것도 다시 암호화하지 않습니다.

키 보안은 KMS 또는 마스터 키 비밀, 배포, 그리고 운영자에 따라 달라지며 — NextPDF Enterprise 단독에 달려 있지 않습니다. 운영자는 마스터 키 프로비저닝, 비밀 저장, KMS 구성, 회전 스케줄링을 소유합니다. 키 보호 책임은 NIST SP 800-57 Part 1 Rev.5 §5.5.2를 따릅니다.

GPU 임베딩

GpuEmbeddingService는 Core 임베딩 계약을 구현하고 사이드카에 위임합니다. 사이드카는 GPU가 사용 가능할 때 GPU에서 임베딩 모델을 실행하고, 그렇지 않으면 CPU로 폴백하며, 응답 메타데이터를 GPU에서 저하된 것으로 표시합니다. 벡터 형태는 두 경우 모두 동일합니다. 모델(약 1.3 GB)은 첫 요청 시 지연 방식으로 다운로드되고 로드됩니다. 배치 의미론은 전부 아니면 전무입니다: 항목별 실패, 형식이 잘못된 벡터, 또는 개수 불일치는 부분 결과를 반환하는 대신 타입 지정된 오류를 발생시킵니다.

GPU 벡터 검색

GpuVectorIndex는 Core 벡터 인덱스 계약을 구현하고 하나의 핸들을 하나의 컬렉션 식별자에 바인딩합니다. build는 사이드카에서 인덱스를 구축합니다. 사이드카는 GPU가 사용 가능할 때 GPU 인덱스를 사용하고 그렇지 않으면 CPU 인덱스를 사용합니다. 인덱스는 한번 구축되면 불변입니다: delete는 항상 타입 지정된 미구현 오류로 거부하며, 제거하려면 재구축이 필요합니다. search는 각 결과의 메타데이터에 1 기반 순위와 함께 순위가 매겨진 히트를 반환합니다. count는 사이드카에 컬렉션 총계를 요청하고 어떤 실패에 대해서도 예외를 던지는 대신 0을 보고합니다.

엣지 케이스 및 실패 모드

마스터 키는 16진에서 최소 32바이트로 디코딩되어야 합니다. 더 짧거나 16진이 아닌 값은 어떤 사이드카 호출보다 먼저 생성 시 InvalidArgumentException을 발생시킵니다.
미설정 또는 빈 선택자 변수는 local로 해석됩니다. 팩토리는 다른 공급자를 절대 추측하지 않습니다.
마스터 키 변수 없이 local 경로에서 fromEnvironment를 호출하면 누락된 변수를 명시하는 타입 지정된 오류가 발생합니다.
비어 있지 않은 encryption_key 항목 없이 create('local', [...])를 호출하면 누락된 항목을 명시하는 타입 지정된 오류가 발생합니다.
키 버전 상태는 인프로세스이며 공급자 인스턴스별입니다. 새 프로세스는 회전이 다시 실행될 때까지 버전 1을 관찰합니다. 회전 결과는 공급자 상태를 신뢰하는 것이 아니라 데이터를 다시 암호화하여 영속화하십시오.
빈 임베딩 배치는 InvalidArgumentException을 발생시킵니다. 사이드카에는 연결하지 않습니다.
사이드카 가용성은 호출마다 확인됩니다. 연결할 수 없는 사이드카는 SpectrumNotAvailableException을 발생시킵니다. 서비스는 절대 조용히 실패하지 않습니다.
반환된 임베딩 벡터 내의 숫자가 아닌 구성 요소는 0.0으로 강제 변환됩니다. 누락되었거나 배열이 아닌 벡터는 SpectrumApiException을 발생시킵니다.
첫 임베딩 요청은 일회성 모델 다운로드 및 로드 비용을 치릅니다. 해당 타임아웃은 별도로 산정하십시오.
build와 search는 사이드카 응답을 엄격하게 디코딩합니다. 형식이 잘못된 본문은 JsonException을 발생시킵니다. count는 모든 실패를 삼키고 0을 반환합니다.
식별자나 점수가 누락된 검색 히트는 배치를 실패시키는 대신 빈 문자열과 0.0으로 기본 설정됩니다.
사이드카 오류 코드와 예외 계층은 Accelerator 오류 참조에 정리되어 있습니다.

FIPS 모드 동작

로컬 키 경로는 도출에 HKDF-SHA256을, 암호화에 AES-256-GCM을 사용합니다. 사이드카가 두 가지를 모두 실행합니다. 키 메타데이터에 기록되는 알고리즘 레이블은 AES-256-GCM입니다. 배포가 FIPS 검증 암호화 공급자에 대해 실행되면, 해당 프리미티브는 그 검증된 경계 내에서 실행됩니다. AES-GCM 사용에는 NIST SP 800-38D §5에 따라 키마다 고유한 초기화 벡터가 필요합니다.

NextPDF Enterprise는 FIPS 검증 암호화 모듈이 아니며 FIPS 인증 주장을 하지 않습니다. FIPS 검증 암호화 공급자 또는 FIPS 검증 KMS로 구성된 경우에만 FIPS 호환 모드로 작동합니다. 이 저장소에는 FIPS 인증 아티팩트가 존재하지 않습니다.

적합성

주장	표준	조항
키 버전과 라이프사이클 모델은 키 상태 지침을 따릅니다.	NIST SP 800-57 Part 1 Rev.5	§4
키 보호 및 보관 책임은 키 소유자와 운영자에게 있습니다.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM은 키마다 고유한 초기화 벡터를 요구합니다.	NIST SP 800-38D	§5

모든 조항은 의역된 것이며 NextPDF는 규범 텍스트를 재현하지 않습니다. NextPDF는 인증 주장을 하지 않습니다. 인용된 조항과의 정렬은 기능 진술이며 인증이 아닙니다. 이 페이지는 키 관리를 다룹니다. FIPS 모드 진술은 호환성 진술이며 법률 의견이 아닙니다. 자체 준수 및 법률 자문에게 문의하십시오.

개발 참고 사항

모듈 소스는 @since 2.1.0을 지닙니다. 이 참조는 nextpdf/enterprise 3.1.0에 포함되어 제공된 표면을 문서화합니다.
모든 클래스는 final입니다. EncryptionKeyResult는 final readonly입니다. 변경하는 대신 새 인스턴스를 생성하십시오.
마스터 키는 민감한 생성자 매개변수(#[SensitiveParameter])입니다. PHP는 스택 트레이스에서 이를 삭제합니다. 애플리케이션 로그와 구성 덤프에서 제외하십시오.
SpectrumClient, VectorSearchResult, 그리고 EmbeddingServiceInterface 및 VectorIndexInterface 계약은 NextPDF Core에서 옵니다. 호출자가 사이드카 클라이언트를 생성하고 제공합니다.
NextPDF\Enterprise\Accelerator 네임스페이스는 배치 오프로드 엔진과 검색 컬렉션 및 OCR 추출 스택도 지니고 있습니다. 해당 표면은 이 페이지의 범위 밖입니다.
내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남으며 이 매뉴얼의 범위 밖입니다.

발행 경계

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

함께 보기

Accelerator — GPU 사이드카 및 KMS 공급자 팩토리 — 워크플로 및 보관 안내를 위한 기능 페이지.
Accelerator 오류 참조 — 사이드카 예외 계층과 오류 코드.
Security — 심층 참조
Accelerator — NextPDF Pro 심층 참조