Accelerator — مرجع متعمّق (‏⁨GPU sidecar⁩، مصنع موفّري ⁨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	RuntimeException عندما يفتقر local إلى encryption_key غير فارغ، أو عند اسم غير معروف	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 محرفًا سِتّ‑عشريًا (32 بايت)	LocalKmsProvider	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 ويُعيد العنصر صفر	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	مفتاح رئيسي مُرمَّز سِتّ‑عشريًا؛ لا يقلّ عن 64 محرفًا سِتّ‑عشريًا (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⁩ عند توفّرها، ويرجع إلى ⁨CPU⁩ خلاف ذلك، مع وسم البيانات الوصفية للاستجابة بأنها متدنّية عن ⁨GPU⁩. وشكل المتجه متطابق في الحالتين. ويُنزَّل النموذج (نحو ⁨1.3⁩ GB) ويُحمَّل بتكاسل عند أوّل طلب. ودلالة الدفعة إمّا الكلّ أو لا شيء: فأيّ فشل في عنصر، أو متجه مشوّه، أو عدم تطابق في العدد يُطلق خطأً مُنمَّطًا بدلًا من إعادة نتائج جزئية.

البحث المتجهي على ⁨GPU⁩

يُنفّذ GpuVectorIndex عقد الفهرس المتجهي في ⁨Core⁩ ويربط مِقبضًا واحدًا بمُعرِّف مجموعة واحد. ويبني build الفهرس على الوصيف؛ ويستخدم الوصيف فهرس ⁨GPU⁩ عند توفّرها، وفهرس ⁨CPU⁩ خلاف ذلك. والفهرس غير قابل للتغيير بمجرّد بنائه: إذ يرفض delete دائمًا بخطأ مُنمَّط ”غير مُنفَّذ“، وتتطلّب الإزالة إعادة بناء. ويُعيد search النتائج المرتّبة مع رتبة تبدأ من واحد في البيانات الوصفية لكلّ نتيجة. ويطلب count من الوصيف إجمالي المجموعة، ويُبلّغ عن 0 عند أيّ فشل بدلًا من الإطلاق.

الحالات الحدّية وأنماط الفشل

• يجب أن يُفكَّ ترميز المفتاح الرئيسي من السِّتّ‑عشري إلى 32 بايت على الأقل. وأيّ قيمة أقصر أو غير سِتّ‑عشرية تُطلق InvalidArgumentException عند الإنشاء، قبل أيّ استدعاء للوصيف.
• متغيّر المُحدِّد غير المُعيَّن أو الفارغ يُحلّ إلى local؛ ولا يُخمّن المصنع مطلقًا موفّرًا آخر.
• يُطلق fromEnvironment على مسار local دون متغيّر المفتاح الرئيسي خطأً مُنمَّطًا يذكر المتغيّر المفقود.
• يُطلق create('local', [...]) دون مُدخَل encryption_key غير فارغ خطأً مُنمَّطًا يذكر المُدخَل المفقود.
• حالة إصدار المفتاح داخل العملية وخاصّة بكلّ نسخة موفّر. وتُلاحظ العملية الجديدة الإصدار 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 — تسلسل استثناءات الوصيف ورموز الأخطاء.
• الأمان — المرجع التفصيلي
• Accelerator — المرجع التفصيلي لـ‏⁨NextPDF Pro⁩