المُسرِّع

لمحة سريعة

يُفرِّغ المُسرِّع إعادة ضغط الصور الدُّفعية، وتحليل ⁨PDF⁩، وتضمين النص إلى خدمة مرافِقة معالِجة (⁨CPU⁩) مُشترَكة الموقع. وعندما تتعذّر الوصول إلى الخدمة المرافِقة، تتراجع كل عملية إلى مسار ⁨PHP⁩ داخل العملية، فيلاحظ المستدعون النتائج نفسها في الحالتين.

التوفّر والترخيص

تُشحَن هذه الميزة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص على مستوى ⁨Pro⁩. لا يُحمِّل النشر الذي يفتقر إلى ذلك الاستحقاق أصناف الميزة. قارِن الإصدارات واحصل على ترخيص.

لا يملك المُسرِّع علمًا منفصلًا لكل ميزة. يُختار المسار المُسرَّع في وقت التشغيل بفحص إمكانية الوصول إلى الخدمة المرافِقة (ProAcceleratorProvider::isAvailable())؛ وعندما تتعذّر الوصول إلى الخدمة المرافِقة، يعمل مسار ⁨PHP⁩ داخل العملية بدلًا منها.

التثبيت

composer require nextpdf/pro:^3

تثبّت حزمة ⁨Premium⁩ شيفرة nextpdf/pro تحت فضاء الاسم NextPDF\Pro\Accelerator. كما تثبّت الحزمة الفوقية nextpdf/premium قدرات ⁨Enterprise⁩؛ والمُسرِّع نفسه ميزة على مستوى ⁨Pro⁩.

نظرة مفاهيمية عامة

‏ProAcceleratorProvider هو نقطة الدخول. يُنشئ بتكاسل أربع خدمات:

• مُحسِّن مُسرَّع يلفّ PdfOptimizer في ⁨Pro⁩ ويُفرِّغ عمل الصور الدُّفعي إلى الخدمة المرافِقة.
• مُقارِن مُسرَّع يلفّ PdfDiffer في ⁨Pro⁩؛ توازي الخدمة المرافِقة تحليل البنية بينما تعمل خوارزمية المقارنة نفسها في ⁨PHP⁩.
• خدمة تضمين معالِجة (⁨CPU⁩) تُعيد متّجهات بـ 384 بُعدًا باستخدام نموذج ⁨all-MiniLM-L6-v2 ONNX⁩ تستضيفه الخدمة المرافِقة.
• فهرس متّجهات معالِج (⁨CPU⁩) يبني فهرس ⁨HNSW⁩ في الذاكرة ويبحث فيه مُفتَّحًا بمعرّف مجموعة.

يُبقي التصميم منطق المجال في ⁨PHP⁩. تؤدّي الخدمة المرافِقة العمل القابل للتوازي والمُقيَّد بالمعالِج (تحويل ترميز الصور، وتحليل المستندات المتعدّدة، واستدلال ⁨ONNX⁩، والبحث المتّجهي). لكل مسار مُسرَّع احتياط ⁨PHP⁩ حتمي يُنتج نتائج مكافئة.

لماذا يعمل بهذه الطريقة

القرار الحامل هو أن الصحة لا تعتمد أبدًا على الخدمة المرافِقة. يبقى منطق المجال في ⁨PHP⁩؛ ولا تؤدّي الخدمة المرافِقة إلا العمل القابل للتوازي والمُقيَّد بالمعالِج. يحتفظ المُحسِّن والمُقارِن (AcceleratedOptimizer، AcceleratedDiffer) باحتياط ⁨PHP⁩ حتمي، فيغيّر غياب الخدمة المرافِقة التوقيت لا النتائج. العمليتان الوحيدتان بلا مكافئ في ⁨PHP⁩ — CpuEmbeddingService وCpuVectorIndex — تفشلان مغلقتين بدلًا من خفض الدرجة. فالجواب الخاطئ الصامت هناك أسوأ من خطأ صريح. يتيح هذا الفصل توسّع الإنتاجية مع أنوية الخدمة المرافِقة بينما يحتفظ المستدعون بمسار شيفرة واحد وحدّ ثقة واحد.

خلفية التصميم: توليد المستندات عالي الحجم.

عقد السلوك

• يُعيد ProAcceleratorProvider::isAvailable() ما إذا كانت الخدمة المرافِقة تستجيب. يمكن للمستدعين التفرّع على هذا، لكنهم ليسوا مضطرّين: يتراجع المُحسِّن والمُقارِن تلقائيًا.
• يُعيد embedding()->embed() متّجهًا واحدًا من 384 عنصرًا؛ ويُعيد batchEmbed() متّجهًا واحدًا لكل مُدخَل ويرفض قائمة مُدخَل فارغة بـ InvalidArgumentException.
• يتطلّب vectorIndex($collectionId)->build() أن يكون vectors وids بالطول نفسه ويعامل مُدخَلًا فارغًا كعملية بلا أثر.
• يُعيد vectorIndex()->search($queryVector, $topK) نتائج مُرتَّبة؛ وdelete() غير مدعوم لفهرس ⁨HNSW⁩ ويرفض الاستدعاء — يعيد المستدعون بناء الفهرس بدلًا منه.
• تتطلّب خدمة التضمين وفهرس المتّجهات الخدمة المرافِقة؛ وتثيران خطأ «غير متاح» بدلًا من خفض الدرجة بصمت، لأنه لا يوجد مكافئ في ⁨PHP⁩ لاستدلال ⁨ONNX⁩ أو بحث ⁨HNSW⁩.
• لا يثير المُحسِّن والمُقارِن أبدًا عند إخفاق الخدمة المرافِقة؛ بل يتراجعان إلى مسار ⁨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 عند تعذّر الوصول إلى الخدمة المرافِقة بدلًا من الإثارة.
• تسريع المُحسِّن والمُقارِن أفضل جهد ممكن؛ ويسبّب خطأ الخدمة المرافِقة في منتصف الدُّفعة تراجعًا صامتًا لذلك الاستدعاء، لذا يتغيّر التوقيت — لا الصحة.

الأداء

يستهدف التسريع العمل الدُّفعي المُقيَّد بالمعالِج: تحويل ترميز الصور المتوازي، وتحليل المستندات المتعدّدة، والبحث المتّجهي. لا ينشر ⁨NextPDF⁩ هنا مُضاعِف إنتاجية ثابتًا؛ وتعتمد المكاسب على مزيج المستندات، وكثافة الصور، وعدد أنوية الخدمة المرافِقة، وحجم الدُّفعة. قِس في بيئتك قبل الاعتماد على رقم محدَّد. احتياط ⁨PHP⁩ أحادي الخيط بالتصميم.

ملاحظات أمنية

ترسل هذه الوحدة المستندات والمتّجهات إلى الخدمة المرافِقة مُشترَكة الموقع عبر نقلها المُهيَّأ. عامِل الخدمة المرافِقة كجزء من حدّ ثقتك وانشرها على المضيف نفسه أو على قطعة شبكية خاصة. تتحقّق الوحدة من حجم المُدخَل وشكله قبل الإرسال. ولا تسجّل أي محتوى مستند.

المطابقة

لا تؤدّي هذه الوحدة أي عمل مطابقة تنسيق بنفسها؛ بل تفوّض التحسين والمقارنة إلى وحدتَي المُحسِّن والمقارنة في ⁨Pro⁩. راجع تلك الوحدات لأجل مراجع ⁨ISO 32000-2⁩. مصدر دليل المطابقة لهذه الصفحة هو عقود الأصناف العامة الموثَّقة واختباراتها الوحدوية؛ ولم تتوفّر مادة ⁨RAG⁩ وقت التأليف، لذا لا تُؤكَّد هنا أي معرّفات بنود خارجية.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك المُسرِّع. يضيف ⁨Enterprise⁩ ميزات أعلى مستوى للامتثال، والأرشفة، ودورة حياة التوقيع موثَّقة في موضع آخر؛ وتلك خارجة عن نطاق هذه الوحدة وغير مطلوبة لاستخدام المُسرِّع.

احتياط / بديل ⁨Core⁩

بدون ⁨Pro⁩، استخدم التحسين والمقارنة داخل العملية في ⁨NextPDF Core⁩. تتراجع المسارات المُسرَّعة في هذه الوحدة إلى سلوك ⁨PHP⁩ نفسه عند غياب الخدمة المرافِقة.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا والسطح العام المدعوم للـ ⁨API⁩ فقط. أما مسارات فضاء الاسم الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر فخارجة عن النطاق.

انظر أيضًا

• المُسرِّع — المرجع المفصَّل
• المُحسِّن
• المقارنة
• مسار الإخراج