این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

بازی برای هوش مصنوعی روی دستگاه (بتا)

مقدمه

Play for On-Device AI مزایای Android App Bundles و تحویل Google Play را به توزیع سفارشی مدل ML می‌آورد تا بتوانید عملکرد مدل را با پیچیدگی کمتر اکوسیستم دستگاه بدون هزینه اضافی بهبود بخشید. این به شما امکان می‌دهد یک مصنوع واحد را در Play منتشر کنید که حاوی کد، دارایی‌ها، و مدل‌های ML شماست و از بین تعدادی حالت تحویل و گزینه‌های هدف انتخاب کنید.

مزایا

یک مصنوع انتشارات را در Google Play آپلود کنید و میزبانی، تحویل، به‌روزرسانی‌ها و هدف‌یابی را بدون هزینه اضافی به Play واگذار کنید.
مدل های ML خود را در زمان نصب، دنبال کردن سریع یا بر اساس تقاضا تحویل دهید.
- تحویل در زمان نصب می تواند تضمین کند که یک مدل بسیار بزرگ هنگام باز شدن برنامه شما وجود دارد. مدل شما به صورت APK نصب خواهد شد.
- پس از نصب برنامه، تحویل سریع به‌طور خودکار در پس‌زمینه انجام می‌شود. کاربران ممکن است برنامه شما را قبل از دانلود کامل مدل شما باز کنند. مدل شما در فضای ذخیره سازی داخلی برنامه شما دانلود می شود.
- تحویل برحسب تقاضا به شما امکان می‌دهد مدل را در زمان اجرا درخواست کنید، که اگر مدل فقط برای جریان‌های کاربر خاصی مورد نیاز باشد، مفید است. مدل شما در فضای ذخیره سازی داخلی برنامه شما دانلود می شود.
انواع مدل‌های ML خود را ارائه دهید که بر اساس مدل دستگاه، ویژگی‌های سیستم یا RAM برای دستگاه‌های خاصی هدف قرار می‌گیرند.
به‌روزرسانی‌های برنامه را با وصله خودکار Play کوچک و بهینه نگه دارید، به این معنی که فقط تفاوت‌های موجود در فایل‌ها باید دانلود شوند.

ملاحظات

با استفاده از Play for On-Device AI، با شرایط مندرج در توافقنامه توزیع برنامه‌نویس Google Play و شرایط خدمات کیت توسعه نرم‌افزار Play Core موافقت می‌کنید.
مدل‌های دانلود شده توسط Play for On-Device AI فقط باید توسط برنامه‌های شما استفاده شود. مدل‌ها نباید به برنامه‌های دیگر ارائه شوند.
بسته‌های هوش مصنوعی می‌توانند تا 1.5 گیگابایت بر اساس اندازه‌های دانلود فشرده‌شان باشند. حداکثر اندازه تجمعی برنامه هر نسخه از برنامه شما که از بسته برنامه شما تولید شده است 4 گیگابایت است.
برنامه‌های بیش از ۱ گیگابایت باید حداقل سطح SDK را روی ۲۱ یا بالاتر تنظیم کنند.

نحوه استفاده از Play for On-Device AI

Play for On-Device AI از بسته های هوش مصنوعی استفاده می کند. شما مدل‌های سفارشی را که برای توزیع در بسته‌های هوش مصنوعی آماده هستند در بسته برنامه خود بسته‌بندی می‌کنید. شما می‌توانید انتخاب کنید که بسته هوش مصنوعی در زمان نصب، دنبال کردن سریع یا بر اساس تقاضا تحویل داده شود.

با بسته‌بندی بسته‌های هوش مصنوعی با بسته برنامه خود، می‌توانید از همه ابزارهای آزمایشی و انتشار موجود Play، مانند آهنگ‌های آزمایشی و عرضه‌های مرحله‌ای برای مدیریت توزیع برنامه‌تان با مدل‌های سفارشی‌تان استفاده کنید.

بسته های هوش مصنوعی همراه با باینری برنامه به روز می شوند. اگر نسخه جدید برنامه شما تغییراتی در بسته هوش مصنوعی ایجاد نمی کند، فرآیند وصله خودکار Play باعث می شود کاربر مجبور به دانلود مجدد آن نباشد. وقتی برنامه را به‌روزرسانی می‌کند، Play فقط آنچه را که تغییر کرده است دانلود می‌کند.

بسته های هوش مصنوعی فقط شامل مدل هستند. جاوا/کاتلین و کتابخانه های بومی مجاز نیستند. اگر برای اجرای مدل ML خود نیاز به ارسال کتابخانه ها یا کد دارید، آن را به ماژول پایه یا یک ماژول ویژگی منتقل کنید. می توانید ماژول ویژگی خود را به گونه ای پیکربندی کنید که تنظیمات دانلود و هدف گذاری مشابه بسته هوش مصنوعی داشته باشد.

از LiteRT و MediaPipe با بسته های هوش مصنوعی استفاده کنید

می توانید از LiteRT و MediaPipe با بسته های هوش مصنوعی استفاده کنید. مدل خود را در یک بسته هوش مصنوعی بسته بندی کنید و سپس با استفاده از دستورالعمل های بسته های زمان نصب یا بسته های سریع و درخواستی به آن دسترسی پیدا کنید.

مطالعه بیشتر:

شروع با LiteRT
- برنامه نمونه نشان می دهد که چگونه می توانید یک مدل LiteRT را در یک بسته هوش مصنوعی بسته بندی کنید و آن را در زمان اجرا بارگذاری کنید.
- بسیاری از مدل های LiteRT از قبل آموزش دیده وجود دارد که می توانید در بسته های هوش مصنوعی برای شروع استفاده کنید.
شروع کار با MediaPipe
- برای بسته‌های سریع دنبال و درخواستی، می‌توانید از AssetCache.java برای بارگیری دارایی‌های خود (مانند فایل‌های .binarypb ) از طریق مسیرهای فایل‌شان استفاده کنید.
- برای بسته‌های زمان نصب، می‌توانید از AndroidAssetUtil.java استفاده کنید.

با بسته های هوش مصنوعی شروع کنید

در سطح بالا، در اینجا نحوه شروع استفاده از Play for On-Device AI آورده شده است:

مدل‌های خود را در بسته‌های هوش مصنوعی در Android App Bundle خود بسته‌بندی کنید و نحوه تحویل بسته‌های هوش مصنوعی را مشخص کنید.
[اختیاری] اگر می‌خواهید مدل‌های مختلف را به دستگاه‌های مختلف تحویل دهید، می‌توانید هدف‌گیری دستگاه را برای بسته‌های هوش مصنوعی خود پیکربندی کنید . برای مثال، می‌توانید بسته هوش مصنوعی A را به یک مدل دستگاه خاص، بسته هوش مصنوعی B را به دستگاه‌هایی با حداقل 6 گیگابایت رم تحویل دهید، و همه دستگاه‌های دیگر نمی‌توانند هیچ مدلی دریافت کنند.
[اختیاری] اگر از تحویل درخواستی یا پیگیری سریع استفاده می‌کنید، کتابخانه Play AI Delivery را در برنامه خود ادغام کنید تا بسته‌های هوش مصنوعی خود را در صورت نیاز دانلود کنید.
بسته نرم افزاری خود را آزمایش کرده و در Google Play منتشر کنید.

نسخه پلاگین Android Gradle را بررسی کنید

برای استفاده از بسته های هوش مصنوعی، مطمئن شوید که نسخه پلاگین Android Gradle (AGP) شما حداقل 8.8 باشد. این نسخه با اندروید استودیو لیدی باگ 2 بسته بندی شده است.

مدل خود را در یک بسته هوش مصنوعی استخراج کنید

Android Studio برای مراحل زیر مورد نیاز نیست.

در دایرکتوری سطح بالای پروژه خود، یک دایرکتوری برای بسته هوش مصنوعی ایجاد کنید. این نام دایرکتوری به عنوان نام بسته هوش مصنوعی استفاده می شود. نام بسته های هوش مصنوعی باید با یک حرف شروع شود و فقط شامل حروف، اعداد و زیرخط باشد.

در پوشه AI pack یک فایل 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 ]"
    }
}

در فایل برنامه build.gradle پروژه، نام هر بسته هوش مصنوعی را در پروژه خود مانند تصویر زیر اضافه کنید:
```
// In the app build.gradle file:
android {
    ...
    assetPacks = [":ai-pack-name", ":ai-pack2-name"]
}
```
در فایل settings.gradle پروژه، تمام بسته‌های هوش مصنوعی را مانند شکل زیر در پروژه خود قرار دهید:
```
// In the settings.gradle file:
include ':app'
include ':ai-pack-name'
include ':ai-pack2-name'
```
در بسته هوش مصنوعی خود، یک دایرکتوری src/main/assets/ ایجاد کنید.
مدل های خود را در دایرکتوری src/main/assets قرار دهید. در اینجا نیز می توانید زیر شاخه ها را ایجاد کنید. ساختار دایرکتوری برنامه شما اکنون باید به شکل زیر باشد:
- build.gradle
- settings.gradle
- app/
- ai-pack-name/build.gradle
- ai-pack-name/src/main/assets/your-model-directories
برای بارگذاری و اجرای مدل های خود کد اضافه کنید. نحوه انجام این کار به حالت تحویل بسته های هوش مصنوعی شما بستگی دارد. دستورالعمل‌های مربوط به زمان نصب و دنبال کردن سریع/طبق تقاضا را در زیر ببینید.
[اختیاری] هدف گذاری دستگاه را برای ارائه مدل های مختلف به دستگاه های مختلف پیکربندی کنید .
بسته نرم افزاری اندروید را با Gradle بسازید . در بسته نرم افزاری تولید شده، دایرکتوری سطح ریشه اکنون شامل موارد زیر است:
- ai-pack-name/manifest/AndroidManifest.xml : شناسه بسته هوش مصنوعی و حالت تحویل را پیکربندی می کند
- ai-pack-name/assets/your-model-directories : دایرکتوری حاوی تمام دارایی های ارائه شده به عنوان بخشی از بسته هوش مصنوعی است.
Gradle مانیفست را برای هر بسته هوش مصنوعی تولید می کند و فهرست assets/ فهرست را برای شما خروجی می دهد.

پیکربندی تحویل زمان نصب

بسته‌های هوش مصنوعی که به‌عنوان زمان نصب پیکربندی شده‌اند، بلافاصله با راه‌اندازی برنامه در دسترس هستند. از Java AssetManager API برای دسترسی به بسته های هوش مصنوعی در این حالت استفاده کنید:

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

تحویل سریع و درخواستی را پیکربندی کنید

برای دانلود بسته های هوش مصنوعی با تحویل سریع یا درخواستی، از کتابخانه تحویل هوش مصنوعی Play استفاده کنید.

وابستگی خود را به کتابخانه تحویل هوش مصنوعی Play اعلام کنید

در فایل build.gradle برنامه خود، یک وابستگی به کتابخانه تحویل هوش مصنوعی Play اعلام کنید:

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 حاوی لیستی از بسته ها و حالت ها و اندازه های دانلود اولیه آنها را برمی گرداند. اگر بسته AI درخواست شده از طریق fetch() در حال بارگیری باشد، وضعیت دانلود برگردانده می شود و دانلود اضافی شروع نمی شود.

وضعیت های دانلود را مانیتور کنید

برای ردیابی پیشرفت نصب بسته های هوش مصنوعی باید یک AiPackStateUpdateListener پیاده سازی کنید. به‌روزرسانی‌های وضعیت در هر بسته برای پشتیبانی از ردیابی وضعیت بسته‌های هوش مصنوعی جداگانه تجزیه می‌شوند. می‌توانید قبل از تکمیل همه دانلودهای دیگر برای درخواستتان، استفاده از بسته‌های هوش مصنوعی موجود را شروع کنید.

void registerListener(AiPackStateUpdateListener listener)
void unregisterListener(AiPackStateUpdateListener listener)

دانلودهای بزرگ

اگر دانلود بزرگتر از 200 مگابایت باشد و کاربر از Wi-Fi استفاده نکند، دانلود شروع نمی شود تا زمانی که کاربر صریحاً رضایت خود را برای ادامه دانلود با استفاده از اتصال داده تلفن همراه اعلام کند. به همین ترتیب، اگر بارگیری زیاد باشد و کاربر Wi-Fi را از دست بدهد، دانلود متوقف می‌شود و برای ادامه با استفاده از اتصال داده تلفن همراه، رضایت صریح لازم است. یک بسته متوقف شده دارای وضعیت WAITING_FOR_WIFI است. برای راه اندازی جریان UI برای درخواست رضایت از کاربر، از متد 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 در دایرکتوری ریشه بسته هوش مصنوعی ذخیره می شوند. با استفاده از روش راحتی assetsPath() می توانید مسیر دایرکتوری assets را دریافت کنید. برای رسیدن به یک دارایی خاص از روش زیر استفاده کنید:

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

در زیر چند روش API اضافی وجود دارد که ممکن است بخواهید در برنامه خود استفاده کنید.

لغو درخواست

cancel() برای لغو درخواست بسته AI فعال استفاده کنید. توجه داشته باشید که این درخواست بهترین عملیات است.

بسته هوش مصنوعی را بردارید

از removePack() برای برنامه ریزی حذف بسته هوش مصنوعی استفاده کنید.

مکان های بسته های هوش مصنوعی متعدد را دریافت کنید

از getPackLocations() برای پرس و جو کردن وضعیت چندین بسته هوش مصنوعی به صورت انبوه استفاده کنید که نقشه بسته های هوش مصنوعی و مکان آنها را برمی گرداند. نقشه برگردانده شده توسط getPackLocations() حاوی یک ورودی برای هر بسته است که در حال حاضر دانلود شده و به روز شده است.

هدف گذاری دستگاه

هدف‌گیری دستگاه به شما کنترل دقیق‌تری بر روی بخش‌هایی از بسته برنامه شما به دستگاه‌های خاص تحویل می‌دهد. برای مثال، می‌توانید اطمینان حاصل کنید که یک مدل بزرگ فقط به دستگاه‌هایی با RAM بالا تحویل داده می‌شود یا می‌توانید نسخه‌های مختلف یک مدل را به دستگاه‌های مختلف تحویل دهید.

شما می توانید ویژگی های دستگاه مانند:

سیستم روی تراشه
مدل دستگاه
رم دستگاه
ویژگی های سیستم

مروری بر مراحل مورد نیاز

مراحل زیر برای فعال کردن هدف گذاری دستگاه مورد نیاز است:

گروه های دستگاه خود را در یک فایل XML تعریف کنید.
مشخص کنید کدام بخش از بسته شما باید به کدام گروه دستگاه برود.
[اختیاری] پیکربندی خود را به صورت محلی آزمایش کنید.
بسته نرم افزاری خود (حاوی فایل XML) را در Google Play آپلود کنید.

نسخه پلاگین Android Gradle را بررسی کنید

برای استفاده از هدف گذاری دستگاه، مطمئن شوید که نسخه پلاگین Android Gradle (AGP) شما حداقل 8.10.0 باشد. این با Android Studio (Meerkat 2 و جدیدتر) بسته بندی شده است. آخرین نسخه پایدار اندروید استودیو را دانلود کنید.

این قابلیت را در افزونه Gradle اندروید فعال کنید

هدف گذاری دستگاه باید به صراحت در فایل 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 : مورد نیاز رم دستگاه
- min_bytes ( شامل) : حداقل RAM مورد نیاز (بر حسب بایت)
- max_bytes ( انحصاری) : حداکثر RAM مورد نیاز (بر حسب بایت)
include_device_ids : مدل‌های دستگاهی که باید در این انتخابگر گنجانده شوند (حداکثر 10000 دستگاه_ids در هر گروه) . اگر دستگاه با هر ID_ID موجود در لیست مطابقت داشته باشد، این ویژگی برآورده می شود.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
excluded_device_ids : مدل‌های دستگاهی که در این انتخابگر حذف می‌شوند (حداکثر 10000 دستگاه_ids در هر گروه) . اگر دستگاه با هیچ device_id در لیست مطابقت نداشته باشد، این ویژگی برآورده می شود.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
require_system_features : ویژگی هایی که یک دستگاه باید توسط این انتخابگر گنجانده شود (حداکثر 100 ویژگی در هر گروه) . یک دستگاه باید تمام ویژگی های سیستم را در این لیست داشته باشد تا این ویژگی را برآورده کند.
مرجع ویژگی های سیستم
- نام : یک ویژگی سیستم
forbidden_system_features : ویژگی هایی که یک دستگاه نباید توسط این انتخابگر گنجانده شود (حداکثر 100 ویژگی در هر گروه) . اگر دستگاهی دارای یکی از ویژگی های سیستم در این لیست باشد، این ویژگی را برآورده نمی کند.
مرجع ویژگی های سیستم
- نام : یک ویژگی سیستم
system-on-chip : سیستم روی تراشه‌هایی که باید در این انتخابگر گنجانده شود. یک دستگاه باید هر چیپ را در این لیست داشته باشد تا این ویژگی را برآورده کند.
- سازنده : سیستم روی تراشه سازنده
- مدل : مدل سیستم روی تراشه

نکته: گنجاندن چندین ویژگی در یک انتخابگر، یک AND منطقی ایجاد می کند، به عنوان مثال:

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

این شرایط را برای همه دستگاه‌های دارای رم > 7 گیگابایت ایجاد می‌کند و پیکسل 4 است - همچنین به صورت زیر نوشته شده است:

اگر یک شرط OR می خواهید، انتخابگرهای جداگانه در یک گروه دستگاه ایجاد کنید، به عنوان مثال:

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

این شرایط را برای همه دستگاه‌های دارای رم > 7 گیگابایت یا پیکسل 4 ایجاد می‌کند - همچنین به صورت زیر نوشته می‌شود:

در اینجا یک مثال نشان می دهد که تمام ویژگی های ممکن دستگاه را نشان می دهد:

<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، با یکی از موارد زیر پیدا کنید:

بازرسی دستگاه‌های جداگانه با استفاده از کاتالوگ دستگاه، و یافتن کد سازنده و مدل در مکان‌هایی که در مثال زیر نشان داده شده است (برای Google Pixel 4a، سازنده «Google» و کد مدل «sunfish» است)».
دانلود 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 موجود که در مرحله آخر ایجاد شده‌اند، بر اساس گروه‌های دستگاه تقسیم کنید، و پوشه‌های مناسب (همانطور که در زیر توضیح داده شده است) را با استفاده از #group_myCustomGroup1، #group_myCustomGroup2، و غیره پس از رفع مشکل، پس از تعمیر قرار دهید. هنگام استفاده از بسته‌های AI در برنامه خود، نیازی به آدرس‌دهی پوشه‌ها با کلمات دیگر با postfix نیست.

بعد از مرحله قبل، ممکن است به صورت زیر باشد:

...
.../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 دنبال کنید:

بسته نرم افزاری خود را با Android Studio یا bundletool بسازید.

APK با پرچم --local-testing ایجاد کنید:

java -jar bundletool-all.jar build-apks --bundle=path/to/your/bundle.aab \
  --output=output.apks --local-testing

یک دستگاه را وصل کنید و 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 با یک مسیر آزمایشی داخلی آزمایش کنید.

هنگامی که این کار را انجام دادید، می‌توانید به‌روزرسانی برنامه‌تان را به‌صورت تدریجی برای تولید با عرضه‌های مرحله‌ای منتشر کنید.

نمونه برنامه با استفاده از Play for On-Device AI

نمونه برنامه را دانلود کنید.

نحوه استفاده از هر یک از حالت های تحویل و همچنین پیکربندی هدف گیری دستگاه را نشان می دهد. برای شروع به بخش تست محلی مراجعه کنید.

مطالب مرتبط

درباره Android App Bundles بیشتر بیاموزید و مراجع AI Delivery SDK را بخوانید.

مقدمه

مزایا

یک مصنوع انتشارات را در Google Play آپلود کنید و میزبانی، تحویل، به‌روزرسانی‌ها و هدف‌یابی را بدون هزینه اضافی به Play واگذار کنید.
مدل های ML خود را در زمان نصب، دنبال کردن سریع یا بر اساس تقاضا تحویل دهید.
- تحویل در زمان نصب می تواند تضمین کند که یک مدل بسیار بزرگ هنگام باز شدن برنامه شما وجود دارد. مدل شما به صورت APK نصب خواهد شد.
- پس از نصب برنامه، تحویل سریع به‌طور خودکار در پس‌زمینه انجام می‌شود. کاربران ممکن است برنامه شما را قبل از دانلود کامل مدل شما باز کنند. مدل شما در فضای ذخیره سازی داخلی برنامه شما دانلود می شود.
- تحویل برحسب تقاضا به شما امکان می‌دهد مدل را در زمان اجرا درخواست کنید، که اگر مدل فقط برای جریان‌های کاربر خاصی مورد نیاز باشد، مفید است. مدل شما در فضای ذخیره سازی داخلی برنامه شما دانلود می شود.
انواع مدل‌های ML خود را ارائه دهید که بر اساس مدل دستگاه، ویژگی‌های سیستم یا RAM برای دستگاه‌های خاصی هدف قرار می‌گیرند.
به‌روزرسانی‌های برنامه را با وصله خودکار Play کوچک و بهینه نگه دارید، به این معنی که فقط تفاوت‌های موجود در فایل‌ها باید دانلود شوند.

ملاحظات

با استفاده از Play for On-Device AI، با شرایط مندرج در توافقنامه توزیع برنامه‌نویس Google Play و شرایط خدمات کیت توسعه نرم‌افزار Play Core موافقت می‌کنید.
مدل‌های دانلود شده توسط Play for On-Device AI فقط باید توسط برنامه‌های شما استفاده شود. مدل‌ها نباید به برنامه‌های دیگر ارائه شوند.
بسته‌های هوش مصنوعی می‌توانند تا 1.5 گیگابایت بر اساس اندازه‌های دانلود فشرده‌شان باشند. حداکثر اندازه تجمعی برنامه هر نسخه از برنامه شما که از بسته برنامه شما تولید شده است 4 گیگابایت است.
برنامه‌های بیش از ۱ گیگابایت باید حداقل سطح SDK را روی ۲۱ یا بالاتر تنظیم کنند.

نحوه استفاده از Play for On-Device AI

از LiteRT و MediaPipe با بسته های هوش مصنوعی استفاده کنید

مطالعه بیشتر:

شروع با LiteRT
- برنامه نمونه نشان می دهد که چگونه می توانید یک مدل LiteRT را در یک بسته هوش مصنوعی بسته بندی کنید و آن را در زمان اجرا بارگذاری کنید.
- بسیاری از مدل های LiteRT از قبل آموزش دیده وجود دارد که می توانید در بسته های هوش مصنوعی برای شروع استفاده کنید.
شروع کار با MediaPipe
- برای بسته‌های سریع دنبال و درخواستی، می‌توانید از AssetCache.java برای بارگیری دارایی‌های خود (مانند فایل‌های .binarypb ) از طریق مسیرهای فایل‌شان استفاده کنید.
- برای بسته‌های زمان نصب، می‌توانید از AndroidAssetUtil.java استفاده کنید.

با بسته های هوش مصنوعی شروع کنید

در سطح بالا، در اینجا نحوه شروع استفاده از Play for On-Device AI آورده شده است:

مدل‌های خود را در بسته‌های هوش مصنوعی در Android App Bundle خود بسته‌بندی کنید و نحوه تحویل بسته‌های هوش مصنوعی را مشخص کنید.
[اختیاری] اگر می‌خواهید مدل‌های مختلف را به دستگاه‌های مختلف تحویل دهید، می‌توانید هدف‌گیری دستگاه را برای بسته‌های هوش مصنوعی خود پیکربندی کنید . برای مثال، می‌توانید بسته هوش مصنوعی A را به یک مدل دستگاه خاص، بسته هوش مصنوعی B را به دستگاه‌هایی با حداقل 6 گیگابایت رم تحویل دهید، و همه دستگاه‌های دیگر نمی‌توانند هیچ مدلی دریافت کنند.
[اختیاری] اگر از تحویل درخواستی یا پیگیری سریع استفاده می‌کنید، کتابخانه Play AI Delivery را در برنامه خود ادغام کنید تا بسته‌های هوش مصنوعی خود را در صورت نیاز دانلود کنید.
بسته نرم افزاری خود را آزمایش کرده و در Google Play منتشر کنید.

نسخه پلاگین Android Gradle را بررسی کنید

مدل خود را در یک بسته هوش مصنوعی استخراج کنید

Android Studio برای مراحل زیر مورد نیاز نیست.

در دایرکتوری سطح بالای پروژه خود، یک دایرکتوری برای بسته هوش مصنوعی ایجاد کنید. این نام دایرکتوری به عنوان نام بسته هوش مصنوعی استفاده می شود. نام بسته های هوش مصنوعی باید با یک حرف شروع شود و فقط شامل حروف، اعداد و زیرخط باشد.

// 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 ]"
    }
}

در فایل برنامه build.gradle پروژه، نام هر بسته هوش مصنوعی را در پروژه خود مانند تصویر زیر اضافه کنید:
```
// In the app build.gradle file:
android {
    ...
    assetPacks = [":ai-pack-name", ":ai-pack2-name"]
}
```
در فایل settings.gradle پروژه، تمام بسته‌های هوش مصنوعی را مانند شکل زیر در پروژه خود قرار دهید:
```
// In the settings.gradle file:
include ':app'
include ':ai-pack-name'
include ':ai-pack2-name'
```
در بسته هوش مصنوعی خود، یک دایرکتوری src/main/assets/ ایجاد کنید.
مدل های خود را در دایرکتوری src/main/assets قرار دهید. در اینجا نیز می توانید زیر شاخه ها را ایجاد کنید. ساختار دایرکتوری برنامه شما اکنون باید به شکل زیر باشد:
- build.gradle
- settings.gradle
- app/
- ai-pack-name/build.gradle
- ai-pack-name/src/main/assets/your-model-directories
برای بارگذاری و اجرای مدل های خود کد اضافه کنید. نحوه انجام این کار به حالت تحویل بسته های هوش مصنوعی شما بستگی دارد. دستورالعمل‌های مربوط به زمان نصب و دنبال کردن سریع/طبق تقاضا را در زیر ببینید.
[اختیاری] هدف گذاری دستگاه را برای ارائه مدل های مختلف به دستگاه های مختلف پیکربندی کنید .
بسته نرم افزاری اندروید را با Gradle بسازید . در بسته نرم افزاری تولید شده، دایرکتوری سطح ریشه اکنون شامل موارد زیر است:
- ai-pack-name/manifest/AndroidManifest.xml : شناسه بسته هوش مصنوعی و حالت تحویل را پیکربندی می کند
- ai-pack-name/assets/your-model-directories : دایرکتوری حاوی تمام دارایی های ارائه شده به عنوان بخشی از بسته هوش مصنوعی است.
Gradle مانیفست را برای هر بسته هوش مصنوعی تولید می کند و فهرست assets/ فهرست را برای شما خروجی می دهد.

پیکربندی تحویل زمان نصب

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

تحویل سریع و درخواستی را پیکربندی کنید

برای دانلود بسته های هوش مصنوعی با تحویل سریع یا درخواستی، از کتابخانه تحویل هوش مصنوعی Play استفاده کنید.

وابستگی خود را به کتابخانه تحویل هوش مصنوعی Play اعلام کنید

در فایل build.gradle برنامه خود، یک وابستگی به کتابخانه تحویل هوش مصنوعی Play اعلام کنید:

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

وضعیت را بررسی کنید

ارزش برگشتی	وضعیت
یک شیء معتبر `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;
            });

نصب کنید

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

وضعیت های دانلود را مانیتور کنید

void registerListener(AiPackStateUpdateListener listener)
void unregisterListener(AiPackStateUpdateListener listener)

دانلودهای بزرگ

تایید کاربر مورد نیاز است

در زیر نمونه ای از اجرای شنونده است:

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 شامل پیشرفت بارگیری ، وضعیت بارگیری و هرگونه خطای خطای خرابی است.

به بسته های AI دسترسی پیدا کنید

پس از رسیدن درخواست بارگیری به حالت COMPLETED ، می توانید با استفاده از تماس های سیستم فایل به یک بسته AI دسترسی پیدا کنید. برای به دست آوردن پوشه ریشه بسته AI از روش getPackLocation() استفاده کنید.

بسته های AI در فهرست assets در فهرست AI Pack Root ذخیره می شوند. می توانید با استفاده از روش راحتی assetsPath() مسیر دایرکتوری assets را دریافت کنید. از روش زیر استفاده کنید تا مسیر یک دارایی خاص را بدست آورید:

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;
}

هدف قرار دادن دستگاه را پیکربندی کنید

برای مشخص کردن دستگاه ها یا گروه هایی از دستگاه هایی که باید بسته های هوش مصنوعی شما را دریافت کنند ، می توانید دستورالعمل های هدفمند دستگاه را دنبال کنید.

سایر روشهای API تحویل AI بازی

در زیر چند روش API اضافی وجود دارد که ممکن است بخواهید در برنامه خود استفاده کنید.

لغو درخواست

برای لغو درخواست فعال AI Pack cancel() استفاده کنید. توجه داشته باشید که این درخواست بهترین عملیات است.

یک بسته AI را بردارید

برای برنامه ریزی حذف یک بسته AI از removePack() استفاده کنید.

مکانهای مختلف بسته AI را دریافت کنید

برای پرس و جو از وضعیت چندین بسته هوش مصنوعی به صورت عمده ، از getPackLocations() استفاده کنید ، که نقشه بسته های AI و مکان های آنها را برمی گرداند. نقشه برگشتی توسط getPackLocations() حاوی ورودی برای هر بسته است که در حال حاضر بارگیری و به روز است.

هدف گذاری دستگاه

هدف قرار دادن دستگاه به شما کنترل دقیق تری می دهد که قسمت هایی از بسته نرم افزاری برنامه شما به دستگاه های خاص تحویل داده می شود. به عنوان مثال ، شما می توانید اطمینان حاصل کنید که یک مدل بزرگ فقط به دستگاه هایی با رم بالا تحویل داده می شود یا می توانید نسخه های مختلف یک مدل را به دستگاه های مختلف تحویل دهید.

شما می توانید خصوصیات دستگاه مانند:

سیستم روی چیپ
مدل دستگاه
قوچ
ویژگی های سیستم

نمای کلی از مراحل مورد نیاز

مراحل زیر برای فعال کردن هدف قرار دادن دستگاه مورد نیاز است:

گروه های دستگاه خود را در یک پرونده XML تعریف کنید.
مشخص کنید که کدام قسمت از بسته نرم افزاری شما باید به کدام گروه های دستگاه مراجعه کند.
[اختیاری] پیکربندی خود را به صورت محلی آزمایش کنید.
بسته نرم افزاری خود (حاوی پرونده XML) را در Google Play بارگذاری کنید.

نسخه افزونه Gradle Android را بررسی کنید

برای استفاده از هدف قرار دادن دستگاه ، اطمینان حاصل کنید که نسخه افزونه Android Gradle (AGP) حداقل 8.10.0 است. این بسته بندی شده با Android Studio (Meerkat 2 و بعد) است. آخرین نسخه پایدار Android Studio را بارگیری کنید.

این ویژگی را در افزونه Android Gradle فعال کنید

هدف قرار دادن دستگاه باید به صراحت در پرونده 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 : نیاز به قوچ دستگاه
- min_bytes ( فراگیر) : حداقل رم مورد نیاز (در بایت)
- max_bytes ( اختصاصی) : حداکثر رم مورد نیاز (در بایت)
شامل_ device_ids : مدل های دستگاهی که باید در این انتخاب کننده گنجانده شوند (حداکثر 10000 دستگاه_ید در هر گروه) . این ویژگی اگر دستگاه با هر دستگاهی در لیست مطابقت داشته باشد ، راضی است.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
EXCLUDED_DEVICE_IDS : مدل های دستگاهی که باید در این انتخاب کننده حذف شوند (حداکثر 10000 دستگاه_ید در هر گروه) . این ویژگی اگر دستگاه با دستگاهی_ید در لیست مطابقت نداشته باشد ، راضی است.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
مورد نیاز_ system_features : ویژگی هایی که یک دستگاه باید توسط این انتخاب کننده (حداکثر 100 ویژگی در هر گروه) گنجانده شود. یک دستگاه برای برآورده کردن این ویژگی باید تمام ویژگی های سیستم را در این لیست داشته باشد.
مرجع ویژگی سیستم
- نام : یک ویژگی سیستم
BidgeDen_System_Features : ویژگی هایی که دستگاه لازم نیست توسط این انتخاب کننده (حداکثر 100 ویژگی در هر گروه) درج شود. اگر یک دستگاه از ویژگی های سیستم در این لیست برخوردار باشد ، این ویژگی را برآورده نمی کند.
مرجع ویژگی سیستم
- نام : یک ویژگی سیستم
سیستم بر روی تراشه : سیستم روی تراشه ها که در این انتخاب کننده گنجانده می شوند. یک دستگاه برای برآورده کردن این ویژگی باید در این لیست دارای تراشه باشد.
- سازنده : سیستم در تولید کننده تراشه
- مدل : سیستم در مدل تراشه

نکته: شامل چندین ویژگی در یک انتخاب کننده واحد ، یک منطقی و به عنوان مثال:

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

شرط همه دستگاه ها را با> 7 گیگابایت رم ایجاد می کند و یک پیکسل 4 است - همچنین به شرح زیر نوشته شده است:

اگر می خواهید یک یا شرایط یا شرایط دیگری را در یک گروه دستگاه واحد ایجاد کنید ، به عنوان مثال:

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

این شرط را برای همه دستگاه ها با> 7 گیگابایت رم ایجاد می کند یا پیکسل 4 است - همچنین به شرح زیر نوشته شده است:

در اینجا مثالی آورده شده است که تمام خصوصیات دستگاه ممکن را نشان می دهد:

<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 ، توسط هر دو ، می توانید قالب بندی صحیح را برای سازنده دستگاه و کد مدل پیدا کنید:

بازرسی از دستگاه های جداگانه با استفاده از کاتالوگ دستگاه ، و پیدا کردن تولید کننده و کد مدل در مکانها همانطور که در مثال زیر نشان داده شده است (برای یک Google Pixel 4A ، سازنده "Google" است و کد مدل "Sunfish" است) ")
بارگیری 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 موجود در آخرین مرحله ، زیر مجموعه های AI خود را به صورت زیر تقسیم کنید و پس از تنظیم پوشه های مناسب (همانطور که در زیر شرح داده شده است) با #group_mycustomgroup1 ، #group_mycustomgroup2 و غیره. هنگام استفاده از بسته های AI در برنامه خود ، نیازی به ایجاد خطرات در طول ساخت و سازها با استفاده از Postfix نیست (به کلمات دیگر ، Postfix)

بعد از قدم قبلی ، این ممکن است به نظر برسد:

...
.../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/ بدون هیچ گونه postfixes را ارجاع دهید.

دستگاه های موجود در myCustomGroup1 تمام دارایی های زیر image-classifier#group_myCustomGroup1/ دریافت می کنند ، در حالی که دستگاه های myCustomGroup2 تمام دارایی ها را تحت image-classifier#group_myCustomGroup2/ دریافت می کنند.

دستگاه هایی که متعلق به myCustomGroup1 یا myCustomGroup2 نیستند ، یک بسته خالی ai-pack-name دریافت می کنند.

این امر به این دلیل است که دستگاه هایی که با هیچ گروه دستگاه مطابقت ندارند ، نوع پیش فرض بسته AI شما را دریافت می کنند. این شامل هر چیزی است که در داخل یک فهرست با #group_suffix نیست.

پس از بارگیری AI Pack ، می توانید بررسی کنید که آیا مدل شما با استفاده از 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 برای آن دستگاه نصب می کند ، نصب کنید اگر این نسخه از برنامه در یک تست یا آهنگ تولید شود.

به دستورالعمل های اشتراک برنامه داخلی نگاهی بیندازید.

دسته

از طرف دیگر ، می توانید APK ها را با استفاده از bundletool (1.18.0 یا بالاتر) تولید کنید و آنها را بر روی دستگاه خود بارگذاری کنید. این مراحل را دنبال کنید تا برنامه خود را به صورت محلی با استفاده از Bundletool آزمایش کنید:

بسته نرم افزاری برنامه خود را با Android Studio یا Bundletool بسازید.

تولید APK با پرچم --local-testing :

java -jar bundletool-all.jar build-apks --bundle=path/to/your/bundle.aab \
  --output=output.apks --local-testing

یک دستگاه را وصل کنید و 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 رفتار می کنند. یعنی وقتی برنامه در کنار هم قرار می گیرد ، آنها به طور خودکار از بین نمی روند. توسعه دهندگان باید هنگام شروع برنامه از آنها به صورت دستی درخواست کنند. این نیازی به تغییر کد در برنامه شما ندارد.
بسته ها به جای بازی از ذخیره خارجی خارج می شوند ، بنابراین نمی توانید آزمایش کنید که چگونه کد شما در مورد خطاهای شبکه رفتار می کند.
آزمایش محلی سناریوی انتظار برای 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 ها را مشاهده خواهید کرد ، که از ماژول های ویژگی و بسته های AI نصب شده ساخته شده است. بسته های AI در صورت تقاضا و سریع به عنوان APK نصب نمی شوند.

تست و انتشار در Google Play

توصیه می کنیم برنامه خود را به پایان برسانید تا در Google Play با یک آهنگ تست داخلی به پایان برسید.

پس از انجام این کار ، می توانید به طور تدریجی به روزرسانی برنامه خود را با تولید صحنه های مرحله ای به روز کنید.

برنامه نمونه با استفاده از Play برای AI در دستگاه AI

برنامه نمونه را بارگیری کنید.

این نحوه استفاده از هر یک از حالت های تحویل و همچنین پیکربندی دستگاه را نشان می دهد. برای شروع به بخش تست محلی مراجعه کنید.

مطالب مرتبط

در مورد بسته های برنامه Android بیشتر بدانید و منابع مربوط به SDK Delivery AI را بخوانید.

بازی برای هوش مصنوعی روی دستگاه (بتا) با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مقدمه

مزایا

ملاحظات

نحوه استفاده از Play for On-Device AI

از LiteRT و MediaPipe با بسته های هوش مصنوعی استفاده کنید

با بسته های هوش مصنوعی شروع کنید

نسخه پلاگین Android Gradle را بررسی کنید

مدل خود را در یک بسته هوش مصنوعی استخراج کنید

پیکربندی تحویل زمان نصب

تحویل سریع و درخواستی را پیکربندی کنید

وابستگی خود را به کتابخانه تحویل هوش مصنوعی Play اعلام کنید

وضعیت را بررسی کنید

دریافت اطلاعات دانلود در مورد بسته های هوش مصنوعی

نصب کنید

وضعیت های دانلود را مانیتور کنید

دانلودهای بزرگ

تایید کاربر مورد نیاز است

دسترسی به بسته های هوش مصنوعی

هدف گذاری دستگاه را پیکربندی کنید

سایر روش‌های Play AI Delivery API

لغو درخواست

بسته هوش مصنوعی را بردارید

مکان های بسته های هوش مصنوعی متعدد را دریافت کنید

هدف گذاری دستگاه

مروری بر مراحل مورد نیاز

نسخه پلاگین Android Gradle را بررسی کنید

این قابلیت را در افزونه Gradle اندروید فعال کنید

یک فایل XML پیکربندی هدفمند دستگاه ایجاد کنید

ویژگی های دستگاه موجود

کدهای رسمی سازنده دستگاه و مدل دستگاه

فایل پیکربندی هدفمندی دستگاه خود را در بسته برنامه خود قرار دهید

از هدف گیری دستگاه برای بسته های هوش مصنوعی خود استفاده کنید

از هدف گذاری دستگاه برای ماژول های ویژگی خود استفاده کنید

به صورت محلی تست کنید

اشتراک گذاری داخلی برنامه

Bundletool

محدودیت‌های آزمایش محلی با bundletool

بررسی کنید که APK های صحیح در حال نصب هستند

تست کنید و در گوگل پلی منتشر کنید

نمونه برنامه با استفاده از Play for On-Device AI

مطالب مرتبط

مقدمه

مزایا

ملاحظات

نحوه استفاده از Play for On-Device AI

از LiteRT و MediaPipe با بسته های هوش مصنوعی استفاده کنید

با بسته های هوش مصنوعی شروع کنید

نسخه پلاگین Android Gradle را بررسی کنید

مدل خود را در یک بسته هوش مصنوعی استخراج کنید

پیکربندی تحویل زمان نصب

تحویل سریع و درخواستی را پیکربندی کنید

وابستگی خود را به کتابخانه تحویل هوش مصنوعی Play اعلام کنید

وضعیت را بررسی کنید

دریافت اطلاعات دانلود در مورد بسته های هوش مصنوعی

نصب کنید

وضعیت های دانلود را مانیتور کنید

دانلودهای بزرگ

تایید کاربر مورد نیاز است

به بسته های AI دسترسی پیدا کنید

هدف قرار دادن دستگاه را پیکربندی کنید

سایر روشهای API تحویل AI بازی

لغو درخواست

یک بسته AI را بردارید

مکانهای مختلف بسته AI را دریافت کنید

هدف گذاری دستگاه

نمای کلی از مراحل مورد نیاز

نسخه افزونه Gradle Android را بررسی کنید

این ویژگی را در افزونه Android Gradle فعال کنید

یک دستگاه را با هدف تنظیم فایل XML ایجاد کنید

خصوصیات دستگاه موجود

کدهای رسمی تولید کننده دستگاه و دستگاه دستگاه

فایل پیکربندی هدفمند دستگاه خود را در بسته برنامه خود قرار دهید

برای بسته های AI خود از هدف قرار دادن دستگاه استفاده کنید

برای ماژول های ویژگی خود از هدف قرار دادن دستگاه استفاده کنید

به صورت محلی تست کنید

اشتراک برنامه داخلی

دسته

محدودیت های آزمایش محلی با Bundletool

تأیید کنید که APK های صحیح نصب شده اند

بازی برای هوش مصنوعی روی دستگاه (بتا)