Pro 版本

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 是入口点。它惰性地构造四个服务：

一个加速优化器，包裹 Pro 的 PdfOptimizer 并把批量图像工作卸载到边车。
一个加速差异器，包裹 Pro 的 PdfDiffer；边车并行化结构解析，而 diff 算法本身在 PHP 中运行。
一个 CPU 嵌入服务，使用边车托管的一个 all-MiniLM-L6-v2 ONNX 模型返回 384 维向量。
一个 CPU 向量索引，构建并搜索一个以集合标识符为键、保存在内存中的 HNSW 索引。

该设计将领域逻辑保留在 PHP 中。边车执行可并行化、CPU 密集的工作（图像转码、多文件解析、ONNX 推理、向量搜索）。每条加速路径都有一个确定性的 PHP 回退，产出等价的结果。

为什么这样设计

起关键作用的决定是：正确性绝不依赖边车。领域逻辑留在 PHP 中，边车只执行可并行化、CPU 密集的工作。优化器与差异器（AcceleratedOptimizer、AcceleratedDiffer）保有一个确定性的 PHP 回退，因此缺失边车改变的是耗时，而非结果。只有那两个没有 PHP 对应物的操作——CpuEmbeddingService 与 CpuVectorIndex——会失败关闭而不是降级。在那里给出一个静默的错误答案，比一个显式错误更糟。这种划分让吞吐随边车核心数扩展，同时调用方保持单一代码路径与单一信任边界。

设计背景：大批量文件生成。

行为契约

ProAcceleratorProvider::isAvailable() 返回边车是否响应。调用方可以基于此分支处理，但不必如此：优化器与差异器会自动回退。
embedding()->embed() 返回单个 384 元素向量；batchEmbed() 为每个输入返回一个向量，并以 InvalidArgumentException 拒绝空输入列表。
vectorIndex($collectionId)->build() 要求 vectors 与 ids 长度相同，并将空输入视为一个无操作。
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 而非引发错误。
优化器与差异器加速是尽力而为的；批处理中途的一次边车错误会导致该次调用静默回退，因此变化的是耗时——而非正确性。

性能

加速面向 CPU 密集的批量工作：并行图像转码、多文件解析，以及向量搜索。NextPDF 在此不发布一个固定的吞吐倍数；增益取决于文件构成、图像密度、边车核心数与批大小。在依赖某个具体数字之前，请在你的环境中测量。PHP 回退在设计上是单线程的。

安全说明

本模块通过其配置的传输把文件与向量发送到共置的边车。请把边车视为你信任边界的一部分，并将其部署在同一台主机或一个私有网络段上。本模块在分发之前验证输入的大小与形态。它不记录任何文件内容。

符合性

本模块本身不执行任何格式符合性工作；它把优化与差异比对委托给 Pro 的 Optimizer 与 Diff 模块。ISO 32000-2 引用请参阅那些模块。本页的符合性佐证来源于已记录的公开类契约及其单元测试；著作时 RAG 语料库不可用，因此此处不断言任何外部条款标识符。

Enterprise 边界说明

Enterprise 不改变 Accelerator 行为。Enterprise 增加了别处记录的更高层级合规、归档与签名生命周期功能；那些不在本模块范围之内，使用 Accelerator 也不需要它们。

Core 回退 / 替代

在没有 Pro 的情况下，使用 NextPDF Core 的进程内优化与差异比对。当边车缺失时，本模块中的加速路径会退化为同样的 PHP 行为。

发布边界

本页仅记录外部可观察行为以及受支持的公开 API 范围。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀均不在范围之内。