منصة Play المخصّصة للذكاء الاصطناعي على الجهاز فقط (إصدار تجريبي)

مقدمة

تتيح لك خدمة Play for On-device AI الاستفادة من مزايا مجموعة حزمات تطبيق Android وخدمة التسليم من Google Play في توزيع نماذج تعلُّم الآلة المخصّصة، ما يتيح لك تحسين أداء النماذج مع تقليل تعقيد منظومة الأجهزة المتكاملة بدون أي تكلفة إضافية. تتيح لك هذه الميزة نشر ملف واحد على Google Play يحتوي على الرموز البرمجية ومواد العرض ونماذج تعلُّم الآلة، كما تتيح لك الاختيار من بين عدد من أوضاع العرض وخيارات الاستهداف.

المزايا

  • يمكنك تحميل ملف واحد للنشر على Google Play وتفويض Google Play باستضافة التطبيق وتسليمه وتحديثه واستهدافه بدون أي تكلفة إضافية.
  • يمكنك تقديم نماذج تعلُّم الآلة أثناء التثبيت أو تنزيلها فور اكتمال التثبيت أو عند الطلب.
    • يمكن أن يضمن التسليم عند التثبيت توفُّر نموذج كبير جدًا عند فتح تطبيقك. سيتم تثبيت النموذج كملف APK.
    • يتم التنزيل فور اكتمال التثبيت تلقائيًا في الخلفية بعد تثبيت تطبيقك. قد يفتح المستخدمون تطبيقك قبل تنزيل النموذج بالكامل. سيتم تنزيل النموذج إلى مساحة التخزين الداخلية لتطبيقك.
    • يتيح لك التسليم عند الطلب طلب النموذج في وقت التشغيل، وهو أمر مفيد إذا كان النموذج مطلوبًا فقط لمسارات مستخدمين معيّنة. سيتم تنزيل النموذج إلى مساحة التخزين الداخلية لتطبيقك.
  • يمكنك تقديم نُسخ من نماذج تعلُّم الآلة التي تستهدف أجهزة معيّنة بناءً على طراز الجهاز أو خصائص النظام أو ذاكرة الوصول العشوائي (RAM).
  • يمكنك الحفاظ على صغر حجم تحديثات التطبيق وتحسينها باستخدام ميزة التصحيح التلقائي في Google Play، ما يعني أنّه يجب تنزيل الاختلافات في الملفات فقط.

الاعتبارات

  • يعني استخدامك لبرنامج "Play للذكاء الاصطناعي على الأجهزة" موافقتك على البنود الواردة في اتفاقية المطوّرين للنشر على Google Play و بنود خدمة حزمة تطوير البرامج (SDK) لمكتبة Play الأساسية.
  • يجب ألا تستخدم تطبيقاتك سوى النماذج التي نزّلتها خدمة Play للذكاء الاصطناعي على الجهاز فقط. يجب عدم تقديم النماذج إلى تطبيقات أخرى.
  • يمكن أن يصل حجم حزم الذكاء الاصطناعي الفردية إلى 1.5 غيغابايت، استنادًا إلى أحجامها المضغوطة عند التنزيل. الحد الأقصى للحجم التراكمي لأي إصدار من تطبيقك يتم إنشاؤه من حزمة التطبيق هو 4 غيغابايت.
  • يجب أن تضبط التطبيقات التي يزيد حجمها عن 1 غيغابايت الحدّ الأدنى لمستوى حزمة تطوير البرامج (SDK) على 21 أو أعلى.

كيفية استخدام Play للذكاء الاصطناعي على الجهاز فقط

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

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

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

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

استخدام LiteRT وMediaPipe مع حزم الذكاء الاصطناعي

يمكنك استخدام LiteRT وMediaPipe مع حِزم الذكاء الاصطناعي. يمكنك تجميع نموذجك في حزمة ذكاء اصطناعي ثم الوصول إليه باستخدام تعليمات حِزم وقت التثبيت أو حِزم المتابعة السريعة وحِزم عند الطلب.

قراءات إضافية:

بدء استخدام حزم الذكاء الاصطناعي

في ما يلي نظرة عامة على كيفية بدء استخدام Play for On-device AI:

  1. يمكنك تجميع نماذجك في حِزم ذكاء اصطناعي ضمن مجموعة حزمات تطبيق Android وتحديد كيفية تسليم حِزم الذكاء الاصطناعي.
  2. [اختياري] إذا أردت تقديم نماذج مختلفة لأجهزة مختلفة، يمكنك ضبط استهداف الأجهزة لحِزم الذكاء الاصطناعي. على سبيل المثال، يمكنك إرسال حزمة الذكاء الاصطناعي "أ" إلى طراز جهاز معيّن، وحزمة الذكاء الاصطناعي "ب" إلى الأجهزة التي تحتوي على ذاكرة وصول عشوائي (RAM) بسعة 6 غيغابايت على الأقل، وقد لا تتلقّى جميع الأجهزة الأخرى أي نموذج.
  3. [اختياري] إذا كنت تستخدم ميزة العرض عند الطلب أو العرض السريع، يمكنك دمج مكتبة Play AI Delivery في تطبيقك لتنزيل حِزم الذكاء الاصطناعي حسب الحاجة.
  4. اختبِر حِزمة تطبيقك واطرحها على Google Play.

التحقّق من إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android

لاستخدام حِزم الذكاء الاصطناعي، تأكَّد من أنّ إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP) هو 8.8 على الأقل. يتم تجميع هذا الإصدار مع استوديو Android Ladybug 2.

استخراج النموذج إلى حزمة ذكاء اصطناعي

لا يلزم استخدام Android Studio لتنفيذ الخطوات التالية.

  1. في دليل المستوى الأعلى لمشروعك، أنشئ دليلاً لحزمة الذكاء الاصطناعي. يُستخدم اسم الدليل هذا كاسم حزمة الذكاء الاصطناعي. يجب أن تبدأ أسماء حِزم الذكاء الاصطناعي بحرف، ويمكن أن تحتوي على أحرف وأرقام وشرطات سفلية فقط.
  2. في دليل حزمة الذكاء الاصطناعي، أنشِئ ملف build.gradle وأضِف الرمز التالي. تأكَّد من تحديد اسم حزمة الذكاء الاصطناعي ونوع تسليم واحد فقط:

    // In the AI pack's build.gradle file:
    plugins {
      id 'com.android.ai-pack'
    }
    
    aiPack {
        packName = "ai-pack-name" // Directory name for the AI pack
        dynamicDelivery {
            deliveryType = "[ install-time | fast-follow | on-demand ]"
        }
    }
    
  3. في ملف build.gradle الخاص بتطبيق المشروع، أضِف اسم كل حزمة ذكاء اصطناعي في مشروعك كما هو موضّح أدناه:

    // In the app build.gradle file:
    android {
        ...
        assetPacks = [":ai-pack-name", ":ai-pack2-name"]
    }
    
  4. في ملف settings.gradle الخاص بالمشروع، أدرِج جميع حزم الذكاء الاصطناعي في مشروعك كما هو موضّح أدناه:

    // In the settings.gradle file:
    include ':app'
    include ':ai-pack-name'
    include ':ai-pack2-name'
    
  5. داخل حزمة الذكاء الاصطناعي، أنشِئ دليل src/main/assets/.

  6. ضَع نماذجك في الدليل src/main/assets. يمكنك إنشاء أدلة فرعية هنا أيضًا. يجب أن تبدو بنية الدليل لتطبيقك الآن على النحو التالي:

    • build.gradle
    • settings.gradle
    • app/
    • ai-pack-name/build.gradle
    • ai-pack-name/src/main/assets/your-model-directories
  7. أضِف رمزًا برمجيًا لتحميل النماذج وتشغيلها. ستعتمد كيفية القيام بذلك على وضع تسليم حزم الذكاء الاصطناعي. اطّلِع على تعليمات التثبيت و المتابعة السريعة/عند الطلب أدناه.

  8. [اختياري] اضبط استهداف الأجهزة لتقديم نماذج مختلفة لأجهزة مختلفة.

  9. إنشاء مجموعة حزمات تطبيق Android باستخدام Gradle في حِزمة التطبيق التي تم إنشاؤها، يتضمّن الدليل على مستوى الجذر الآن ما يلي:

    • ai-pack-name/manifest/AndroidManifest.xml: لضبط معرّف حزمة الذكاء الاصطناعي ووضع التسليم
    • ‫ai-pack-name/assets/your-model-directories: المجلد الذي يحتوي على جميع مواد العرض التي تم إرسالها كجزء من حزمة الذكاء الاصطناعي

    ينشئ Gradle ملف البيان لكل حزمة AI وينتج دليل assets/ لك.

ضبط ميزة "التسليم عند التثبيت"

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

import android.content.res.AssetManager;
...
Context context = createPackageContext("com.example.app", 0);
AssetManager assetManager = context.getAssets();
InputStream is = assetManager.open("model-name");

ضبط إعدادات ميزتَي "المتابعة السريعة" و"التسليم عند الطلب"

لتنزيل حزم الذكاء الاصطناعي باستخدام ميزة "التنزيل السريع" أو "التسليم عند الطلب"، استخدِم Play AI Delivery Library.

الإعلان عن الاعتماد على Play AI Delivery Library

في ملف build.gradle الخاص بتطبيقك، أعلِن عن تبعية لمكتبة Play AI Delivery:

dependencies {
  ...
  implementation "com.google.android.play:ai-delivery:0.1.1-alpha01"
}

التحقّق من الحالة

يتم تخزين كل حزمة ذكاء اصطناعي في مجلد منفصل في مساحة التخزين الداخلية للتطبيق. استخدِم الطريقة getPackLocation() لتحديد المجلد الجذر لحزمة الذكاء الاصطناعي. تعرض هذه الطريقة القيم التالية:

عرض القيمة الحالة
عنصر AiPackLocation صالح المجلد الرئيسي لحزمة الذكاء الاصطناعي جاهز للوصول الفوري على الرابط assetsPath()
null حزمة الذكاء الاصطناعي غير معروفة أو حزم الذكاء الاصطناعي غير متاحة

الحصول على معلومات تنزيل حزم الذكاء الاصطناعي

استخدِم طريقة getPackStates() لتحديد حجم عملية التنزيل ومعرفة ما إذا كان قد بدأ تنزيل الحزمة.

Task<AiPackStates> getPackStates(List<String> packNames)

‫getPackStates() هي طريقة غير متزامنة تعرض Task<AiPackStates>. يعرض الإجراء packStates() لعنصر AiPackStates قيمة Map<String, AiPackState>. تحتوي هذه الخريطة على حالة كل حزمة ذكاء اصطناعي مطلوبة، مرتبطة باسمها:

Map<String, AiPackState> AiPackStates#packStates()

يظهر الطلب النهائي على النحو التالي:

final String aiPackName = "myAiPackName";

aiPackManager
    .getPackStates(Collections.singletonList(aiPackName))
    .addOnCompleteListener(new OnCompleteListener<AiPackStates>() {
        @Override
        public void onComplete(Task<AiPackStates> task) {
            AiPackStates aiPackStates;
            try {
                aiPackStates = task.getResult();
                AiPackState aiPackState =
                    aiPackStates.packStates().get(aiPackName);
            } catch (RuntimeExecutionException e) {
                Log.d("MainActivity", e.getMessage());
                return;
            });

توفّر طرق AiPackState التالية حجم حزمة الذكاء الاصطناعي، والكمية التي تم تنزيلها حتى الآن (إذا تم طلبها)، والكمية التي تم نقلها إلى التطبيق:

لمعرفة حالة حزمة الذكاء الاصطناعي، استخدِم طريقة status() التي تعرض الحالة كرقم صحيح يتوافق مع حقل ثابت في فئة AiPackStatus. إذا لم يتم تثبيت حزمة الذكاء الاصطناعي بعد، ستظهر الحالة AiPackStatus.NOT_INSTALLED.

إذا تعذّر تنفيذ طلب، استخدِم طريقة errorCode() التي تتوافق قيمة عرضها مع حقل ثابت في فئة AiPackErrorCode.

تثبيت

استخدِم طريقة fetch() لتنزيل حزمة ذكاء اصطناعي لأول مرة أو اطلب اكتمال تحديث حزمة الذكاء الاصطناعي:

Task<AiPackStates> fetch(List<String> packNames)

تعرض هذه الطريقة عنصر AiPackStates يحتوي على قائمة بالحزم وحالات وأحجام التنزيل الأولية. إذا كانت حزمة الذكاء الاصطناعي المطلوبة باستخدام fetch() قيد التنزيل، يتم عرض حالة التنزيل ولا يتم بدء أي عملية تنزيل إضافية.

مراقبة حالات التنزيل

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

void registerListener(AiPackStateUpdateListener listener)
void unregisterListener(AiPackStateUpdateListener listener)
عمليات تنزيل كبيرة

إذا كان حجم الملف الذي يتم تنزيله أكبر من 200 ميغابايت ولم يكن المستخدم متصلاً بشبكة Wi-Fi، لن يبدأ التنزيل إلا بعد أن يمنح المستخدم موافقته الصريحة على المتابعة باستخدام اتصال بيانات الجوّال. وبالمثل، إذا كان حجم التنزيل كبيرًا وانقطع اتصال المستخدم بشبكة Wi-Fi، يتم إيقاف التنزيل مؤقتًا ويجب الحصول على موافقة صريحة للمتابعة باستخدام اتصال بيانات الجوّال. تكون حالة الحزمة المتوقفة مؤقتًا WAITING_FOR_WIFI. لتشغيل مسار واجهة المستخدم من أجل طلب موافقة المستخدم، استخدِم طريقة showConfirmationDialog().

يُرجى العِلم أنّه إذا لم يستدعِ التطبيق هذه الطريقة، فسيتم إيقاف عملية التنزيل مؤقتًا ولن يتم استئنافها تلقائيًا إلا عندما يعود المستخدم إلى الاتصال بشبكة Wi-Fi.

تأكيد المستخدم مطلوب

إذا كانت الحزمة بالحالة REQUIRES_USER_CONFIRMATION، لن تتم عملية التنزيل إلى أن يقبل المستخدم مربّع الحوار الذي يظهر مع showConfirmationDialog(). يمكن أن تظهر هذه الحالة عندما لا يتعرّف Play على التطبيق، مثلاً إذا تم تثبيت التطبيق من مصدر غير معروف. يُرجى العِلم أنّ استدعاء showConfirmationDialog() في هذه الحالة سيؤدي إلى تحديث التطبيق. بعد التحديث، عليك طلب حِزم الذكاء الاصطناعي مرة أخرى.

في ما يلي مثال على تنفيذ أداة استماع:

AiPackStateUpdateListener aiPackStateUpdateListener = new AiPackStateUpdateListener() {
    private final ActivityResultLauncher<IntentSenderRequest> activityResultLauncher =
      registerForActivityResult(
          new ActivityResultContracts.StartIntentSenderForResult(),
          new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
              if (result.getResultCode() == RESULT_OK) {
                Log.d(TAG, "Confirmation dialog has been accepted.");
              } else if (result.getResultCode() == RESULT_CANCELED) {
                Log.d(TAG, "Confirmation dialog has been denied by the user.");
              }
            }
          });

    @Override
    public void onStateUpdate(AiPackState aiPackState) {
      switch (aiPackState.status()) {
        case AiPackStatus.PENDING:
          Log.i(TAG, "Pending");
          break;

        case AiPackStatus.DOWNLOADING:
          long downloaded = aiPackState.bytesDownloaded();
          long totalSize = aiPackState.totalBytesToDownload();
          double percent = 100.0 * downloaded / totalSize;

          Log.i(TAG, "PercentDone=" + String.format("%.2f", percent));
          break;

        case AiPackStatus.TRANSFERRING:
          // 100% downloaded and assets are being transferred.
          // Notify user to wait until transfer is complete.
          break;

        case AiPackStatus.COMPLETED:
          // AI pack is ready to use. Run the model.
          break;

        case AiPackStatus.FAILED:
          // Request failed. Notify user.
          Log.e(TAG, aiPackState.errorCode());
          break;

        case AiPackStatus.CANCELED:
          // Request canceled. Notify user.
          break;

        case AiPackStatus.WAITING_FOR_WIFI:
        case AiPackStatus.REQUIRES_USER_CONFIRMATION:
          if (!confirmationDialogShown) {
            aiPackManager.showConfirmationDialog(activityResultLauncher);
            confirmationDialogShown = true;
          }
          break;

        case AiPackStatus.NOT_INSTALLED:
          // AI pack is not downloaded yet.
          break;
        case AiPackStatus.UNKNOWN:
          Log.wtf(TAG, "AI pack status unknown")
          break;
      }
    }
}

يمكنك بدلاً من ذلك استخدام طريقة getPackStates() للحصول على حالة عمليات التنزيل الحالية. يحتوي AiPackStates على مستوى تقدُّم عملية التنزيل وحالة التنزيل وأي رموز خطأ في حال تعذُّر التنزيل.

الوصول إلى حزم الذكاء الاصطناعي

يمكنك الوصول إلى حزمة الذكاء الاصطناعي باستخدام طلبات نظام الملفات بعد أن يصل طلب التنزيل إلى الحالة COMPLETED. استخدِم طريقة getPackLocation() للحصول على المجلد الجذر لحزمة الذكاء الاصطناعي.

يتم تخزين حِزم الذكاء الاصطناعي في دليل assets ضمن الدليل الجذري لحِزم الذكاء الاصطناعي. يمكنك الحصول على المسار إلى دليل assets باستخدام الطريقة المريحة assetsPath(). استخدِم الطريقة التالية للحصول على مسار مادة عرض معيّنة:

private String getAbsoluteAiAssetPath(String aiPack, String relativeAiAssetPath) {
    AiPackLocation aiPackPath = aiPackManager.getPackLocation(aiPack);

    if (aiPackPath == null) {
        // AI pack is not ready
        return null;
    }

    String aiAssetsFolderPath = aiPackPath.assetsPath();
    // equivalent to: FilenameUtils.concat(aiPackPath.path(), "assets");
    String aiAssetPath = FilenameUtils.concat(aiAssetsFolderPath, relativeAiAssetPath);
    return aiAssetPath;
}

ضبط استهداف الأجهزة

يمكنك اتّباع تعليمات استهداف الأجهزة لتحديد الأجهزة أو مجموعات الأجهزة التي يجب أن تتلقّى حِزم الذكاء الاصطناعي.

طرق أخرى في Play AI Delivery API

في ما يلي بعض الطرق الإضافية لواجهة برمجة التطبيقات التي قد تحتاج إلى استخدامها في تطبيقك.

إلغاء الطلب

استخدِم cancel() لإلغاء طلب حزمة AI نشط. يُرجى العِلم أنّ هذا الطلب هو عملية تُبذل فيها أقصى الجهود.

إزالة حزمة الذكاء الاصطناعي

استخدِم removePack() لتحديد موعد إزالة حزمة الذكاء الاصطناعي.

الحصول على مواقع جغرافية لحزم ذكاء اصطناعي متعددة

استخدِم getPackLocations() للاستعلام عن حالة حِزم الذكاء الاصطناعي المتعددة بشكل مجمّع، ما يؤدي إلى عرض خريطة لحِزم الذكاء الاصطناعي ومواقعها الجغرافية. تحتوي الخريطة التي تعرضها دالة getPackLocations() على إدخال لكل حزمة تم تنزيلها حاليًا ومحدَّثة.

استهداف الأجهزة

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

يمكنك استهداف خصائص الأجهزة، مثل:

  • مكونات النظام مثبَّتة على شريحة
  • طراز الجهاز
  • ذاكرة الوصول العشوائي للجهاز
  • ميزات النظام

نظرة عامة على الخطوات المطلوبة

يجب اتّباع الخطوات التالية لتفعيل استهداف الأجهزة:

  1. حدِّد مجموعات الأجهزة في ملف XML.
  2. حدِّد أجزاء الحزمة التي يجب إرسالها إلى مجموعات أجهزة معيّنة.
  3. [اختياري] اختبِر الإعدادات محليًا.
  4. حمِّل الحزمة (التي تحتوي على ملف XML) إلى Google Play.

التحقّق من إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android

لاستخدام ميزة "استهداف الأجهزة"، تأكَّد من أنّ إصدار "المكوّن الإضافي لنظام Gradle المتوافق مع Android" (AGP) هو 8.10.0 على الأقل. ويتم تجميعها مع استوديو Android (الإصدار Meerkat 2 والإصدارات الأحدث). نزِّل أحدث إصدار ثابت من "استوديو Android".

تفعيل هذه الميزة في المكوّن الإضافي لنظام Gradle المتوافق مع Android

يجب تفعيل استهداف الأجهزة صراحةً في ملف gradle.properties:

android.experimental.enableDeviceTargetingConfigApi=true

إنشاء ملف XML لإعدادات استهداف الأجهزة

ملف إعدادات استهداف الأجهزة هو ملف XML تحدّد فيه مجموعات الأجهزة المخصّصة. على سبيل المثال، يمكنك تحديد مجموعة أجهزة باسم qti_v79 تحتوي على جميع الأجهزة التي تتضمّن منظومة Qualcomm SM8750 على رقاقة:

<config:device-targeting-config
    xmlns:config="http://schemas.android.com/apk/config">

    <config:device-group name="qti_v79">
        <config:device-selector>
            <config:system-on-chip manufacturer="QTI" model="SM8750"/>
        </config:device-selector>
    </config:device-group>

</config:device-targeting-config>

تتألف مجموعة الأجهزة من 5 محدّدات أجهزة كحدّ أقصى. ويتم تضمين الجهاز في مجموعة أجهزة إذا كان يستوفي أيًا من أدوات اختيار الأجهزة الخاصة بها.

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

إذا كان الجهاز يتطابق مع مجموعات متعددة، سيتم عرض المحتوى الخاص بالمجموعة التي تم تحديدها أولاً في ملف XML. الترتيب الذي تحدّده للمجموعات في ملف XML هو ترتيب الأولوية.

إذا لم يتطابق جهاز مع أي مجموعات، سيتلقّى المجموعة التلقائية "أخرى". يتم إنشاء هذه المجموعة تلقائيًا ولا يجب تحديدها بشكل صريح.

خصائص الجهاز المتاحة

  • ‫device_ram: متطلبات ذاكرة الوصول العشوائي (RAM) للجهاز
    • ‫min_bytes (شامل): الحدّ الأدنى المطلوب لذاكرة الوصول العشوائي (بالبايت)
    • ‫max_bytes (exclusive): الحد الأقصى لذاكرة الوصول العشوائي المطلوبة (بالبايت)
  • ‫included_device_ids: طُرز الأجهزة التي سيتم تضمينها في هذا المحدِّد (الحد الأقصى هو 10,000 رقم تعريف جهاز لكل مجموعة) يتم استيفاء هذه السمة إذا كان الجهاز يتطابق مع أي device_id في القائمة.
    • ‫build_brand: الشركة المصنّعة للجهاز
    • ‫build_device: رمز طراز الجهاز
  • ‫excluded_device_ids: طُرز الأجهزة التي سيتم استبعادها في هذا المحدِّد (الحد الأقصى هو 10,000 رقم تعريف جهاز لكل مجموعة) يتم استيفاء هذه السمة إذا لم يتطابق الجهاز مع أي device_id في القائمة.
    • ‫build_brand: الشركة المصنّعة للجهاز
    • ‫build_device: رمز طراز الجهاز
  • ‫required_system_features: الميزات التي يجب أن تتوفّر في الجهاز ليتم تضمينه في هذا المحدِّد (بحدّ أقصى 100 ميزة لكل مجموعة). يجب أن يتضمّن الجهاز جميع ميزات النظام الواردة في هذه القائمة لاستيفاء هذه السمة.

    مرجع ميزات النظام

    • name: ميزة في النظام
  • ‫forbidden_system_features: الميزات التي يجب ألا تتوفّر في الجهاز ليتم تضمينه في هذا المحدِّد (بحد أقصى 100 ميزة لكل مجموعة). إذا كان الجهاز يحتوي على أي من ميزات النظام في هذه القائمة، فإنه لا يفي بهذه الخاصية.

    مرجع ميزات النظام

    • name: ميزة في النظام
  • ‫system-on-chip: المنظومات على الرقاقة التي سيتم تضمينها في هذا المحدِّد. يجب أن يحتوي الجهاز على أي شريحة في هذه القائمة لاستيفاء هذه السمة.

دمج سمات أداة الاختيار مع AND وOR

على سبيل المثال، ينشئ المحدِّد التالي الشرط لجميع الأجهزة التي تحتوي على ذاكرة وصول عشوائي (RAM) تزيد عن 7 غيغابايت والتي تكون من طراز Pixel 4:

<config:device-selector ram-min-bytes="7000000000">
    <config:included-device-id brand="google" device="flame"/>
</config:device-selector>

يُكتب هذا الشرط أيضًا على النحو التالي:

ضبط تقاطع الأجهزة التي تحتوي على ذاكرة وصول عشوائي (RAM) بسعة 7 غيغابايت على الأقل وPixel 4
الشكل 1. شرط AND منطقي باستخدام تقاطع المجموعات

إذا أردت استخدام شرط "أو"، أنشِئ أدوات اختيار منفصلة في مجموعة أجهزة واحدة. على سبيل المثال، تنشئ أدوات الاختيار التالية الشرط لجميع الأجهزة التي تزيد سعة ذاكرة الوصول العشوائي (RAM) فيها عن 7 غيغابايت أو التي تكون من طراز Pixel 4:

<config:device-selector ram-min-bytes="7000000000"/>
<config:device-selector>
    <config:included-device-id brand="google" device="flame"/>
</config:device-selector>

يُكتب هذا الشرط أيضًا على النحو التالي:

مجموعة اتحاد الأجهزة التي تحتوي على ذاكرة وصول عشوائي (RAM) بسعة 7 غيغابايت على الأقل وPixel 4
الشكل 2. شرط "أو" منطقي باستخدام اتحاد المجموعات

في ما يلي مثال يعرض جميع سمات الجهاز الممكنة:

<config:device-targeting-config
    xmlns:config="http://schemas.android.com/apk/config">

    <config:device-group name="myCustomGroup1">
      <config:device-selector ram-min-bytes="8000000000">
        <config:included-device-id brand="google" device="redfin"/>
        <config:included-device-id brand="google" device="sailfish"/>
        <config:included-device-id brand="good-brand"/>
        <config:excluded-device-id brand="google" device="caiman"/>
        <config:system-on-chip manufacturer="Sinclair" model="ZX80"/>
        <config:system-on-chip manufacturer="Commodore" model="C64"/>
      </config:device-selector>
      <config:device-selector ram-min-bytes="16000000000"/>
    </config:device-group>

    <config:device-group name="myCustomGroup2">
      <config:device-selector ram-min-bytes="4000000000" ram-max-bytes="8000000000">
        <config:required-system-feature name="android.hardware.bluetooth"/>
        <config:required-system-feature name="android.hardware.location"/>
        <config:forbidden-system-feature name="android.hardware.camera"/>
        <config:forbidden-system-feature name="mindcontrol.laser"/>
      </config:device-selector>
    </config:device-group>

</config:device-targeting-config>

رموز الشركة المصنّعة للجهاز وطرازه الرسمية

يمكنك العثور على التنسيق الصحيح للشركة المصنّعة للجهاز ورمز الطراز باستخدام "قائمة الأجهزة" في Google Play Console، من خلال:

  • فحص الأجهزة الفردية باستخدام "قائمة الأجهزة" والعثور على الشركة المصنّعة ورمز الطراز في المواقع الجغرافية كما هو موضّح في المثال أدناه (بالنسبة إلى هاتف Google Pixel 4a، الشركة المصنّعة هي "Google" ورمز الطراز هو "sunfish")

    صفحة Pixel 4a في قائمة الأجهزة

    صفحة Pixel 4a في قائمة الأجهزة

  • تنزيل ملف CSV للأجهزة المتوافقة، واستخدام الشركة المصنّعة ورمز الطراز للحقلَين build_brand وbuild_device على التوالي

تضمين ملف إعدادات استهداف الأجهزة في حزمة تطبيقك

أضِف ما يلي إلى ملف build.gradle في الوحدة الرئيسية:

android {
  ...
  bundle {
    deviceTargetingConfig = file('device_targeting_config.xml')
    deviceGroup {
      enableSplit = true   // split bundle by #group
      defaultGroup = "other"  // group used for standalone APKs
    }
  }
  ...
}

‫device_targeting_config.xml هو مسار ملف الإعداد بالنسبة إلى الوحدة الرئيسية. يضمن ذلك تجميع ملف الإعداد مع حزمة تطبيقك.

يضمن بند deviceGroup تقسيم حِزم APK التي تم إنشاؤها من حِزمة تطبيقك حسب مجموعات الأجهزة.

استخدام ميزة استهداف الأجهزة لحزم الذكاء الاصطناعي

يمكنك الحفاظ على حجم التطبيق المحسّن على الأجهزة من خلال تقديم النماذج الكبيرة فقط إلى الأجهزة التي يمكنها تشغيلها.

يمكنك تقسيم حِزم AI حسب مجموعات الأجهزة من خلال استخدام أدلة حِزم AI الحالية التي تم إنشاؤها في الخطوة الأخيرة، وإضافة لاحقة إلى المجلدات المناسبة (كما هو موضّح أدناه) باستخدام ‎#group_myCustomGroup1 و‎#group_myCustomGroup2 وما إلى ذلك. وعند استخدام حِزم AI في تطبيقك، لن تحتاج إلى إضافة لاحقة إلى المجلدات (بمعنى آخر، تتم إزالة اللاحقة تلقائيًا أثناء عملية الإنشاء).

بعد الخطوة السابقة، قد يبدو هذا مثل:

...
.../ai-pack-name/src/main/assets/image-classifier#group_myCustomGroup1/
.../ai-pack-name/src/main/assets/image-classifier#group_myCustomGroup2/
...

في هذا المثال، يمكنك الإشارة إلى ai-pack-name/assets/image-classifier/ بدون أي لاحقات.

ستتلقّى الأجهزة في myCustomGroup1 جميع مواد العرض ضمن image-classifier#group_myCustomGroup1/، بينما ستتلقّى الأجهزة في myCustomGroup2 جميع مواد العرض ضمن image-classifier#group_myCustomGroup2/.

ستتلقّى الأجهزة التي لا تنتمي إلى myCustomGroup1 أو myCustomGroup2 حزمة ai-pack-name فارغة.

ويعود السبب في ذلك إلى أنّ الأجهزة التي لا تتطابق مع أي مجموعة أجهزة ستتلقّى الإصدار التلقائي من حزمة الذكاء الاصطناعي. ويشمل ذلك أي شيء غير موجود داخل دليل يحتوي على #group_suffix.

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

استخدام ميزة "استهداف الأجهزة" لوحدات الميزات

يمكنك أيضًا استخدام ميزة "استهداف الأجهزة" لوحدات الميزات. بدلاً من تقسيم وحدات الميزات حسب مجموعة الأجهزة، يمكنك تحديد ما إذا كان يجب تسليم الوحدة بأكملها استنادًا إلى عضوية مجموعة الأجهزة.

لعرض وحدة ميزات على الأجهزة التي تنتمي إلى myCustomGroup1 أو myCustomGroup2، عليك تعديل AndroidManifest.xml:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="myCustomGroup1"/>
            <dist:device-group dist:name="myCustomGroup2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

الاختبار محليًا

قبل إنشاء إصدار لحزمتك الجديدة، يمكنك إجراء اختبار على جهازك باستخدام ميزة "مشاركة التطبيقات مع الفريق الداخلي" أو أداة Bundletool.

مشاركة التطبيقات الداخلية

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

اطّلِع على تعليمات مشاركة التطبيقات مع الفريق الداخلي.

Bundletool

بدلاً من ذلك، يمكنك إنشاء حِزم APK باستخدام bundletool (الإصدار 1.18.0 أو إصدار أحدث) وتثبيتها على جهازك من مصدر خارجي. اتّبِع الخطوات التالية لاختبار تطبيقك محليًا باستخدام أداة bundletool:

  1. أنشئ حزمة تطبيقك باستخدام "استوديو Android" أو أداة bundletool.

  2. أنشِئ حزم APK باستخدام علامة --local-testing:

    java -jar bundletool-all.jar build-apks --bundle=path/to/your/bundle.aab \
      --output=output.apks --local-testing
    
  3. وصِّل جهازًا وشغِّل bundletool لتثبيت حِزم APK من مصدر غير معروف:

    # Example without Device Targeting Configuration
    java -jar bundletool.jar install-apks --apks=output.apks
    
    # Example with Device Targeting Configuration (you must specify which groups the connected device belongs to)
    java -jar bundletool.jar install-apks --apks=output.apks --device-groups=myCustomGroup1,myCustomGroup2
    

القيود المفروضة على الاختبار المحلي باستخدام أداة bundletool

في ما يلي القيود المفروضة على الاختبار المحلي باستخدام أداة bundletool:

  • تعمل حِزم "fast-follow" كحِزم "on-demand". وهذا يعني أنّه لن يتم جلبها تلقائيًا عند تثبيت التطبيق من مصدر غير معروف. وعلى المطوّرين طلبها يدويًا عند بدء تشغيل التطبيق، ولا يتطلّب ذلك إجراء أي تغييرات على الرموز البرمجية في تطبيقك.
  • يتم جلب الحزم من وحدة تخزين خارجية بدلاً من Play، لذا لا يمكنك اختبار سلوك الرمز في حال حدوث أخطاء في الشبكة.
  • لا يغطي الاختبار المحلي سيناريو "الانتظار حتى الاتصال بشبكة Wi-Fi".
  • لا يمكن إجراء تعديلات. قبل تثبيت إصدار جديد من إصدارك، قم بإلغاء تثبيت الإصدار السابق يدويًا.

التحقّق من تثبيت حِزم APK الصحيحة

استخدِم الطريقة التالية لضمان تثبيت حِزم APK الصحيحة فقط على الجهاز

adb shell pm path {packageName}

من المفترَض أن يظهر لك محتوى مثل:

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_ai-pack-name.apk
package:{...}/split_main_ai-pack-name.config.group_myCustomGroup1.apk

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

اختبار التطبيقات وإصدارها على Google Play

ننصحك باختبار تطبيقك بالكامل على Google Play باستخدام مسار اختبار داخلي.

بعد إجراء ذلك، يمكنك إصدار تحديث تطبيقك تدريجيًا إلى قناة الإصدار العلني من خلال طرح الإصدار المؤقت.

نموذج تطبيق يستخدم Play for On-device AI

نزِّل نموذج التطبيق.

ويوضّح كيفية استخدام كل وضع من أوضاع العرض، بالإضافة إلى إعدادات استهداف الأجهزة. يمكنك الاطّلاع على قسم الاختبار المحلي للبدء.

يمكنك الاطّلاع على مزيد من المعلومات حول مجموعة حزمات تطبيق Android وقراءة المراجع الخاصة بحزمة تطوير البرامج (SDK) لعرض نماذج الذكاء الاصطناعي.