Accelerator — 深度参考

速览

本页是 NextPDF\Pro\Accelerator 公共加速接口面的深度参考。它涵盖 provider 工厂、加速批量优化器、differ 包装器，以及用于嵌入与向量搜索的 CPU sidecar 服务。它说明参数、默认值、失败模式与回退语义。请先阅读 Accelerator 能力页面 以获取工作流指引。

可用性与授权

该能力随 NextPDF Pro（nextpdf/pro）发布，并通过 Pro 层级的 license envelope 激活。没有该权益的部署不会加载该能力的类。比较版本并获取授权。

Accelerator 没有逐功能授权标记。代码随 Pro 版本一同发布；加速优化器路径在运行时由一次 sidecar 可达性探测来选择。嵌入服务与向量索引没有 PHP 回退，在 sidecar 不可达时失败即关闭。

公共 API 接口面

composer require nextpdf/pro:^3

nextpdf/premium 元包会安装 nextpdf/pro 代码；本模块位于 NextPDF\Pro\Accelerator 命名空间下。

符号	参数	默认行为	返回	抛出或失败于	备注
ProAcceleratorProvider::__construct	SpectrumClient $client	将 provider 绑定到一个 Core sidecar 客户端	ProAcceleratorProvider	未声明	由调用方构造并提供该客户端
ProAcceleratorProvider::isAvailable	无	通过客户端探测 sidecar 可达性	bool	未声明	仅探测可达性；端点按每次调用探测
ProAcceleratorProvider::embedding	无	返回被缓存的嵌入服务	EmbeddingServiceInterface	未声明	每个 provider 一个 CpuEmbeddingService 实例
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	返回一个绑定到该集合的新索引句柄	VectorIndexInterface	未声明	不缓存；每次调用一个句柄
ProAcceleratorProvider::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 logger 选择 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
}

行为契约

Provider

ProAcceleratorProvider 是入口点。embedding()、optimizer() 与 differ() 会缓存各自的实例。vectorIndex($collectionId) 每次调用返回一个绑定到给定集合标识符的新句柄。isAvailable() 通过注入的 Core SpectrumClient 探测 sidecar 可达性。

批量优化

optimizeBatch 返回一个以调用方文档标识符为键的批处理结果。当 sidecar 可达时，聚合负载会在任何缓冲或上传之前先按客户端预算校验。超限批次以 SpectrumApiException SPEC-SEC-001（HTTP 413）失败即关闭；它绝不降级为 PHP 路径。已准入的批次会被分派给 sidecar 做并行图像工作。

准入之后的传输、认证或响应解析失败会降级为 PHP 优化器，它逐个顺序分析各文档。该降级在两处可观察：结果元数据报告引擎为 php_fallback 且摘要硬件为 cpu，并在事件名 spectrum.optimize.fallback 下发出一条 PSR-3 warning。该 warning 仅携带异常类与文档数量；不记录任何文档字节。在回退结果中，某份文档的分析失败会产生一个带错误状态与代码 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 算法。本版本不发出 sidecar 请求。differ 契约仅接受原始 PDF 字符串，因此无法消费 sidecar 的解析结果；卸载只会增加成本而无收益。注入的客户端为未来的解析卸载功能而保留。isSpectrumWired() 在不发出请求的情况下暴露接线状态。

CPU 嵌入

embed 委派给 batchEmbed([$text]) 并返回第零个元素。batchEmbed([]) 会在联系 sidecar 之前抛出 InvalidArgumentException。不可达的 sidecar 会抛出 SpectrumNotAvailableException。批处理语义是全有或全无：某项失败、缺失或格式不正确的向量、或数量不匹配都会抛出 SpectrumApiException（协议形状失败携带 SPEC-IO-001），而非返回部分向量。返回向量中的非数值分量会被强制转换为 0.0。getDimension 返回 384；getModelName 返回 all-MiniLM-L6-v2。sidecar 在首次请求时惰性下载并加载 ONNX 模型。

CPU 向量搜索

每个句柄绑定一个集合标识符；每个集合映射到 sidecar 中一个独立的内存 HNSW 索引。build 要求向量列表与标识符列表等长，否则抛出 InvalidArgumentException；空输入不调用 sidecar 即返回。search 返回带排名的命中，每个结果的元数据中带有从 1 开始的排名。带内错误信封会抛出 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 集合。请将索引构建视为幂等的，并在重启后重新运行。
• 单个进程内的混合可用性是受支持的：optimizer 逐调用降级；嵌入与向量服务逐调用失败即关闭。
• 超限的 optimizer 批次会在任何上传之前失败即关闭；它不会回退到 PHP 路径。
• optimizer 回退绝不静默失败：请检查结果元数据的引擎标记并监控该 warning 事件。
• 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 深度参考