ملحقات البائع

امتدادات البائعين Neural Networks API (NNAPI) ، التي تم تقديمها في Android 10 ، هي مجموعات من العمليات وأنواع البيانات التي يحددها البائع. على الأجهزة التي تعمل بنظام NN HAL 1.2 أو أعلى ، يمكن أن توفر برامج التشغيل عمليات مخصصة لتسريع الأجهزة من خلال دعم ملحقات البائعين المقابلة. لا تقوم امتدادات البائعين بتعديل سلوك العمليات الحالية.

توفر امتدادات البائعين بديلاً أكثر تنظيماً لعمليات OEM وأنواع البيانات ، والتي تم إهمالها في Android 10. لمزيد من المعلومات ، راجع عمليات OEM وأنواع البيانات .

قائمة السماح باستخدام الإضافات

لا يمكن استخدام امتدادات البائعين إلا من خلال تطبيقات Android المحددة بوضوح وثنائيات أصلية على أقسام /product و /vendor و /odm و /data . لا يمكن للتطبيقات والثنائيات الأصلية الموجودة في قسم /system استخدام ملحقات البائع.

يتم تخزين قائمة بتطبيقات Android والثنائيات المسموح لها باستخدام ملحقات موردي NNAPI في /vendor/etc/nnapi_extensions_app_allowlist . يحتوي كل سطر من الملف على إدخال جديد. يمكن أن يكون الإدخال مسارًا ثنائيًا أصليًا مسبوقًا بشرطة مائلة (/) ، على سبيل المثال ، /data/foo ، أو اسم حزمة تطبيقات Android ، على سبيل المثال ، com.foo.bar .

يتم فرض allowlist من مكتبة وقت تشغيل NNAPI المشتركة. تحمي هذه المكتبة من الاستخدام العرضي ولكن ليس من التحايل المتعمد من قبل أحد التطبيقات مباشرةً باستخدام واجهة HAL لبرنامج تشغيل NNAPI.

تعريف ملحق البائع

يقوم البائع بإنشاء ملف رأس مع تعريف الامتداد والاحتفاظ به. يمكن العثور على مثال كامل لتعريف الامتداد في example/fibonacci/FibonacciExtension.h .

يجب أن يكون لكل امتداد اسم فريد يبدأ باسم المجال العكسي للبائع.

const char EXAMPLE_EXTENSION_NAME[] = "com.example.my_extension";

يعمل الاسم كمساحة اسم للعمليات وأنواع البيانات. يستخدم NNAPI هذا الاسم للتمييز بين ملحقات البائع.

يتم الإعلان عن أنواع العمليات والبيانات بطريقة مشابهة لتلك الموجودة في runtime/include/NeuralNetworks.h .

enum {
    /**
     * A custom scalar type.
     */
    EXAMPLE_SCALAR = 0,

    /**
     * A custom tensor type.
     *
     * Attached to this tensor is {@link ExampleTensorParams}.
     */
    EXAMPLE_TENSOR = 1,
};

enum {
    /**
     * Computes example function.
     *
     * Inputs:
     * * 0: A scalar of {@link EXAMPLE_SCALAR}.
     *
     * Outputs:
     * * 0: A tensor of {@link EXAMPLE_TENSOR}.
     */
    EXAMPLE_FUNCTION = 0,
};

يمكن أن تستخدم عملية الامتداد أي نوع من المعامل ، بما في ذلك أنواع المعامل غير التمديد وأنواع المعامل من الامتدادات الأخرى. عند استخدام نوع معامل من امتداد آخر ، يجب أن يدعم المشغل الامتداد الآخر.

يمكن أن تعلن الإضافات أيضًا عن الهياكل المخصصة لمرافقة معاملات التمديد.

/**
 * Quantization parameters for {@link EXAMPLE_TENSOR}.
 */
typedef struct ExampleTensorParams {
    double scale;
    int64_t zeroPoint;
} ExampleTensorParams;

استخدام ملحقات في عملاء NNAPI

يوفر ملف runtime/include/NeuralNetworksExtensions.h (C API) دعمًا لتمديد وقت التشغيل. يقدم هذا القسم نظرة عامة على C API.

للتحقق مما إذا كان الجهاز يدعم أحد الامتدادات ، استخدم ANeuralNetworksDevice_getExtensionSupport .

bool isExtensionSupported;
CHECK_EQ(ANeuralNetworksDevice_getExtensionSupport(device, EXAMPLE_EXTENSION_NAME,
                                                   &isExtensionSupported),
         ANEURALNETWORKS_NO_ERROR);
if (isExtensionSupported) {
    // The device supports the extension.
    ...
}

لإنشاء نموذج بمعامل ملحق ، استخدم ANeuralNetworksModel_getExtensionOperandType للحصول على نوع المعامل واستدعاء ANeuralNetworksModel_addOperand .

int32_t type;
CHECK_EQ(ANeuralNetworksModel_getExtensionOperandType(model, EXAMPLE_EXTENSION_NAME, EXAMPLE_TENSOR, &type),
         ANEURALNETWORKS_NO_ERROR);
ANeuralNetworksOperandType operandType{
        .type = type,
        .dimensionCount = dimensionCount,
        .dimensions = dimensions,
};
CHECK_EQ(ANeuralNetworksModel_addOperand(model, &operandType), ANEURALNETWORKS_NO_ERROR);

اختياريًا ، استخدم ANeuralNetworksModel_setOperandExtensionData لربط بيانات إضافية بمعامل ملحق.

ExampleTensorParams params{
        .scale = 0.5,
        .zeroPoint = 128,
};
CHECK_EQ(ANeuralNetworksModel_setOperandExtensionData(model, operandIndex, &params, sizeof(params)),
         ANEURALNETWORKS_NO_ERROR);

لإنشاء نموذج مع عملية ملحق ، استخدم ANeuralNetworksModel_getExtensionOperationType للحصول على نوع العملية واستدعاء ANeuralNetworksModel_addOperation .

ANeuralNetworksOperationType type;
CHECK_EQ(ANeuralNetworksModel_getExtensionOperationType(model, EXAMPLE_EXTENSION_NAME, EXAMPLE_FUNCTION,
                                                        &type),
         ANEURALNETWORKS_NO_ERROR);
CHECK_EQ(ANeuralNetworksModel_addOperation(model, type, inputCount, inputs, outputCount, outputs),
         ANEURALNETWORKS_NO_ERROR);

إضافة دعم التمديد إلى برنامج تشغيل NNAPI

تبلغ برامج التشغيل عن الامتدادات المدعومة من خلال طريقة IDevice::getSupportedExtensions . يجب أن تحتوي القائمة التي تم إرجاعها على إدخال يصف كل امتداد مدعوم.

Extension {
    .name = EXAMPLE_EXTENSION_NAME,
    .operandTypes = {
        {
            .type = EXAMPLE_SCALAR,
            .isTensor = false,
            .byteSize = 8,
        },
        {
            .type = EXAMPLE_TENSOR,
            .isTensor = true,
            .byteSize = 8,
        },
    },
}

من بين 32 بت تُستخدم لتحديد الأنواع والعمليات ، فإن بتات Model::ExtensionTypeEncoding::HIGH_BITS_PREFIX هي بادئة الامتداد وتمثل بتات Model::ExtensionTypeEncoding::LOW_BITS_TYPE نوع أو عملية الامتداد.

عند التعامل مع عملية أو نوع المعامل ، يجب على السائق التحقق من بادئة التمديد. إذا كانت بادئة الامتداد تحتوي على قيمة غير صفرية ، فإن نوع العملية أو المعامل هو نوع ملحق. إذا كانت القيمة 0 ، فإن نوع العملية أو المعامل ليس نوعًا ملحقًا.

لتعيين البادئة إلى اسم ملحق ، ابحث عنها في model.extensionNameToPrefix . التعيين من البادئة إلى اسم الامتداد هو مراسلة واحد لواحد (حيّز) لنموذج معين. قد تتوافق قيم البادئة المختلفة مع نفس اسم الامتداد في نماذج مختلفة.

يجب أن يتحقق برنامج التشغيل من صحة عمليات الامتداد وأنواع البيانات لأن وقت تشغيل NNAPI لا يمكنه التحقق من عمليات الامتداد وأنواع البيانات المعينة.

يمكن أن تحتوي معاملات الامتداد على بيانات مرتبطة في operand.extraParams.extension ، والتي يتعامل معها وقت التشغيل على أنها كتلة بيانات أولية ذات حجم عشوائي.

أنواع البيانات وعمليات تصنيع المعدات الأصلية

يحتوي NNAPI على عملية OEM وأنواع بيانات OEM للسماح لمصنعي الأجهزة بتوفير وظائف مخصصة خاصة ببرنامج التشغيل. يتم استخدام أنواع البيانات والعمليات هذه بواسطة تطبيقات OEM فقط. دلالات تشغيل OEM وأنواع البيانات خاصة بـ OEM ويمكن تغييرها في أي وقت. يتم ترميز عمليات OEM وأنواع البيانات باستخدام OperationType::OEM_OPERATION و OperandType::OEM و OperandType::TENSOR_OEM_BYTE .