أداة التسريع — مرجع متعمّق

لمحة سريعة

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

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

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

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

سطح الواجهة البرمجية العام

composer require nextpdf/pro:^3

تُثبِّت الحزمة الوصفية nextpdf/premium شيفرة nextpdf/pro؛ وتقع هذه الوحدة ضمن فضاء الأسماء NextPDF\Pro\Accelerator.

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يُثير أو يفشل بـ	ملاحظات
ProAcceleratorProvider::__construct	SpectrumClient $client	يربط المزوّد بعميل مُرافِق من ⁨Core⁩	ProAcceleratorProvider	لا شيء مُعلَن	يُنشئ المُستدعِي العميل ويُوفِّره
ProAcceleratorProvider::isAvailable	لا شيء	يتحقّق من إمكان الوصول إلى المُرافِق عبر العميل	bool	لا شيء مُعلَن	إمكان الوصول فقط؛ تُفحَص نقاط النهاية لكل استدعاء
ProAcceleratorProvider::embedding	لا شيء	يعيد خدمة التضمين المُذكَّرة	EmbeddingServiceInterface	لا شيء مُعلَن	نسخة CpuEmbeddingService واحدة لكل مزوّد
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	يعيد مقبض فهرس جديدًا مربوطًا بالمجموعة	VectorIndexInterface	لا شيء مُعلَن	غير مُذكَّر؛ مقبض واحد لكل استدعاء
ProAcceleratorProvider::optimizer	لا شيء	يعيد أداة التحسين المُسرَّعة المُذكَّرة	AcceleratedOptimizer	لا شيء مُعلَن	تُنشَأ بعميل المزوّد
ProAcceleratorProvider::differ	لا شيء	يعيد غلاف أداة الفروق المُذكَّر	AcceleratedDiffer	لا شيء مُعلَن	يُنشَأ بعميل المزوّد
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null، OptimizationLevel $level = OptimizationLevel::Balanced، ?LoggerInterface $logger = null	يغلّف PdfOptimizer في ⁨PHP⁩ عند المستوى المُعطى	AcceleratedOptimizer	لا شيء مُعلَن	عميل فارغ يختار مسار ⁨PHP⁩؛ ومُسجِّل فارغ يختار NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	يحلّل كل مستند؛ ويُفرِّغ عمل الصور إلى المُرافِق عند إمكان الوصول	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) على دُفعة تتجاوز الحدّ؛ وعلامات خطأ لكل عنصر في نتيجة الرجوع الاحتياطي	إخفاقات النقل بعد القبول تتدهور إلى مسار ⁨PHP⁩
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	يحتفظ بالعميل الاختياري للتوافق المستقبلي	AcceleratedDiffer	لا شيء مُعلَن	العميل غير مُستخدَم في هذا الإصدار
AcceleratedDiffer::compare	string $sourcePdf، string $targetPdf	يقارن مستندين بالكامل في ⁨PHP⁩	DiffResult	كما في PdfDiffer بإصدار ⁨Pro⁩	لا يُصدَر أي طلب مُرافِق في هذا الإصدار
AcceleratedDiffer::isSpectrumWired	لا شيء	يُبلِّغ عمّا إذا حُقِن عميل مُرافِق	bool	لا شيء مُعلَن	حالة التوصيل فقط؛ لا يُصدر أي طلب
CpuEmbeddingService::embed	string $text	يفوّض إلى batchEmbed ويعيد العنصر صفر	list<float>	كما في batchEmbed	متّجه بـ384 بُعدًا
CpuEmbeddingService::batchEmbed	array $texts	يُضمِّن الدُّفعة على المُرافِق	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	يبني فهرس المجموعة على المُرافِق	void	InvalidArgumentException على عدم تطابق الأطوال؛ وSpectrumNotAvailableException عند تعذّر الوصول	المدخل الفارغ يعود من دون الاتصال بالمُرافِق
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
}

عقد السلوك

المزوّد

ProAcceleratorProvider هو نقطة الدخول. وتُذكِّر embedding() وoptimizer() وdiffer() نُسَخها. ويعيد vectorIndex($collectionId) مقبضًا جديدًا لكل استدعاء مربوطًا بمُعرِّف المجموعة المُعطى. ويتحقّق isAvailable() من إمكان الوصول إلى المُرافِق عبر SpectrumClient المحقون من ⁨Core⁩.

تحسين الدُّفعات

يعيد optimizeBatch نتيجة دُفعة مفهرسة بمُعرِّفات مستندات المُستدعِي. وحين يمكن الوصول إلى المُرافِق، يُتحقَّق من الحمولة الإجمالية مقابل ميزانية العميل قبل أي تخزين مؤقت أو رفع. وتفشل الدُّفعة المتجاوزة للحدّ بإغلاق آمن مع SpectrumApiException SPEC-SEC-001 (⁨HTTP⁩ 413)؛ ولا تتدهور أبدًا إلى مسار ⁨PHP⁩. وتُرسَل الدُّفعة المقبولة إلى المُرافِق لعمل الصور المتوازي.

وأي إخفاق في النقل أو المصادقة أو تحليل الاستجابة بعد القبول يتدهور إلى أداة تحسين ⁨PHP⁩ التي تحلّل كل مستند بالتسلسل. والتدهور قابل للرصد مرتين: تُبلِّغ البيانات الوصفية للنتيجة عن المحرّك php_fallback مع عتاد مُلخَّص cpu، ويُصدَر تحذير ⁨PSR-3⁩ تحت اسم الحدث spectrum.optimize.fallback. ويحمل التحذير صنف الاستثناء وعدد المستندات فقط؛ ولا تُسجَّل أي وحدات بايت من المستندات. وفي نتيجة الرجوع الاحتياطي، يُنتِج إخفاق تحليل مستند عنصرًا بحالة خطأ ورمز SPEC-PARSE-001؛ وتكتمل بقية مستندات الدُّفعة مع ذلك.

ومستوى التحسين الافتراضي هو ⁨Balanced⁩. وحقول نتيجة كل عنصر هي original_bytes وoptimized_bytes وobjects_removed وimages_before وimages_after وsavings_percent وprocessing_time_ms.

فروق المستندات

يعمل compare بالكامل في ⁨PHP⁩ عبر PdfDiffer بإصدار ⁨Pro⁩: تحليل البنية، واستخراج النص، وخوارزمية الفروق. ولا يُصدَر أي طلب مُرافِق في هذا الإصدار. ولا يقبل عقد أداة الفروق إلا سلاسل ⁨PDF⁩ الخام، فلا يمكن استهلاك نتيجة تحليل من المُرافِق؛ ويضيف التفريغ كلفة من دون فائدة. ويُحتفَظ بعميل محقون لميزة تفريغ تحليل مستقبلية. ويكشف isSpectrumWired() حالة التوصيل من دون إصدار طلب.

التضمين على وحدة المعالجة المركزية

يفوّض embed إلى batchEmbed([$text]) ويعيد العنصر صفر. ويثير batchEmbed([]) استثناء InvalidArgumentException قبل الاتصال بالمُرافِق. ويثير المُرافِق المتعذّر الوصول استثناء SpectrumNotAvailableException. ودلالات الدُّفعة هي الكل أو لا شيء: إخفاق عنصر، أو متّجه مفقود أو مشوَّه، أو عدم تطابق العدد يثير SpectrumApiException (تحمل إخفاقات شكل البروتوكول الرمز SPEC-IO-001) بدلًا من إعادة متّجهات جزئية. ويُحوَّل أي مُكوِّن غير عددي داخل متّجه مُعاد إلى 0.0. ويعيد getDimension القيمة 384؛ ويعيد getModelName القيمة all-MiniLM-L6-v2. ويُنزِّل المُرافِق نموذج ⁨ONNX⁩ ويُحمِّله بتكاسل عند الطلب الأول.

البحث المتّجهي على وحدة المعالجة المركزية

يربط كل مقبض مُعرِّف مجموعة واحدًا؛ وتُطابَق كل مجموعة بفهرس ⁨HNSW⁩ منفصل في الذاكرة داخل المُرافِق. ويتطلّب build قائمتَي متّجهات ومُعرِّفات متساويتَي الطول ويثير InvalidArgumentException خلاف ذلك؛ ويعود المدخل الفارغ من دون استدعاء المُرافِق. ويعيد search إصابات مُرتَّبة برتبة تبدأ من واحد في البيانات الوصفية لكل نتيجة. ويثير مظروف خطأ داخل النطاق استثناء SpectrumApiException؛ ويُطابَق المظروف الذي بلا رمز مع SPEC-INDEX-003. ويرفض delete دائمًا مع SpectrumApiException SPEC-INDEX-004 (⁨HTTP⁩ 501، غير قابل لإعادة المحاولة) لأن ⁨HNSW⁩ لا يدعم الحذف لكل متّجه؛ أعِد بناء الفهرس بدلًا من ذلك.

وcount مُغلَق عند الإخفاق وغير ملتبس. ويثير المُرافِق المتعذّر الوصول استثناء SpectrumNotAvailableException؛ وتنتشر أخطاء النقل والمُرافِق من دون تغيير. وعلى استجابة ناجحة فيما عدا ذلك، يثير المتن غير ⁨JSON⁩ الرمز SPEC-INDEX-005، ويثير غياب metadata.total_vectors الرمز SPEC-INDEX-006، ويثير الإجمالي غير الصحيح أو السالب الرمز SPEC-INDEX-007. ويعيد count القيمة 0 فقط لفهرس مؤكَّد الفراغ. ويُرسِل تحقّق الحجم متّجهًا صفريًا بأبعاد INDEX_DIMENSION (384) بالضبط مع top_k قيمته 0، فيقبله مُرافِق يتحقّق من الأبعاد.

الحالات الحدّية وأوضاع الإخفاق

• ذاكرة المُرافِق متطايرة: تمحو إعادة التشغيل كل مجموعات ⁨HNSW⁩. عامِل بناء الفهرس معاملة العملية عديمة الأثر التراكمي وأعِد تشغيله بعد إعادة التشغيل.
• يُدعَم التوافر المختلط داخل عملية واحدة: تتدهور أداة التحسين لكل استدعاء؛ وتفشل خدمتا التضمين والمتّجهات بإغلاق آمن لكل استدعاء.
• تفشل دُفعة أداة التحسين المتجاوزة للحدّ بإغلاق آمن قبل أي رفع؛ ولا ترجع إلى مسار ⁨PHP⁩.
• لا يفشل رجوع أداة التحسين الاحتياطي بصمت أبدًا: تحقّق من علامة المحرّك في البيانات الوصفية للنتيجة وراقِب حدث التحذير.
• لا يُبلِّغ count أبدًا عن مُرافِق متعذّر الوصول أو خطأ بروتوكول على أنه 0؛ فتلك تثير استثناءات مُنمَّطة.
• تأخذ إصابة البحث التي يعوزها مُعرِّفها أو درجتها القيمة الافتراضية سلسلةً فارغة و0.0 بدلًا من إخفاق الدُّفعة.
• تُستخدَم قيمة top_k المساوية 0 داخليًا فقط لتحقّق العدّ؛ ومرِّر topK موجبًا للبحوث الحقيقية.
• يدفع طلب التضمين الأول كلفة تنزيل النموذج وتحميله لمرة واحدة؛ فحدِّد مهلة ذلك على حدة.
• تُفهرَس هرمية استثناءات المُرافِق وعائلات رموز الأخطاء في مرجع أخطاء أداة التسريع.
• لا تُجري هذه الوحدة أي عمليات تشفير ولا تحدّد أي سلوك خاصّ بـ⁨FIPS⁩. وتحكم وحدتا التوقيع والامتثال وضعية وضع ⁨FIPS⁩، لا هنا.

المطابقة

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

ملاحظات التطوير

• يحمل مصدر الوحدة @since 2.1.0؛ ويوثّق هذا المرجع السطح كما شُحِن في nextpdf/pro 3.1.0.
• جميع الأصناف final وتستخدم الحقن عبر الباني؛ فأنشئ نُسَخًا جديدة بدلًا من التغيير في مكانها.
• تأتي SpectrumClient وVectorSearchResult وBatchResultInterface وعقدا EmbeddingServiceInterface وVectorIndexInterface من ⁨NextPDF Core⁩؛ ويُنشئ المُستدعِي عميل المُرافِق ويُوفِّره.
• تأتي OptimizationLevel وPdfOptimizer وPdfDiffer من وحدتَي أداة التحسين والفروق في ⁨Pro⁩؛ ودلالاتها موثَّقة في صفحتَي المرجع تلك.
• تتشارك خدمة التضمين وفهرس المتّجهات بُعد 384. فابنِ متّجهات الفهرس على البُعد نفسه للتضمينات التي تستعلمها.
• تبقى تفاصيل الآلية الداخلية في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

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

انظر أيضًا

• أداة التسريع — صفحة القدرة للإرشاد حول سير العمل.
• مرجع أخطاء أداة التسريع — هرمية استثناءات المُرافِق ورموز الأخطاء.
• أداة التحسين — مرجع متعمّق
• الفروق — مرجع متعمّق
• أداة التسريع — مرجع ⁨NextPDF Enterprise⁩ متعمّق