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

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

مقدمه

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

مزایا

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

ملاحظات

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

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

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

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

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

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

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

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

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

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

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

در سطح بالا، در اینجا نحوه شروع استفاده از Play برای هوش مصنوعی روی دستگاه آورده شده است:

مدل‌های خود را در بسته‌های هوش مصنوعی در بسته نرم‌افزاری اندروید خود قرار دهید و نحوه ارائه بسته‌های هوش مصنوعی را مشخص کنید.
[اختیاری] اگر می‌خواهید مدل‌های مختلف را به دستگاه‌های مختلف ارائه دهید، می‌توانید هدف‌گیری دستگاه را برای بسته‌های هوش مصنوعی خود پیکربندی کنید . به عنوان مثال، می‌توانید بسته هوش مصنوعی A را به یک مدل دستگاه خاص، بسته هوش مصنوعی B را به دستگاه‌هایی با حداقل ۶ گیگابایت رم ارائه دهید و سایر دستگاه‌ها می‌توانند هیچ مدلی را دریافت نکنند.
[اختیاری] اگر از تحویل بر اساس تقاضا یا تحویل سریع استفاده می‌کنید، کتابخانه تحویل هوش مصنوعی Play را در برنامه خود ادغام کنید تا بسته‌های هوش مصنوعی خود را در صورت نیاز دانلود کنید.
بسته برنامه خود را در گوگل پلی آزمایش و منتشر کنید.

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

برای استفاده از بسته‌های هوش مصنوعی، مطمئن شوید که نسخه افزونه اندروید گریدل (AGP) شما حداقل ۸.۸ باشد. این نسخه با اندروید استودیو لیدی‌باگ ۲ بسته‌بندی شده است.

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

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

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

در پوشه‌ی بسته‌ی هوش مصنوعی، یک فایل 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 برای هر بسته هوش مصنوعی، فایل manifest را تولید می‌کند و دایرکتوری assets/ را برای شما خروجی می‌دهد.

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

بسته‌های هوش مصنوعی پیکربندی‌شده به صورت زمان نصب، بلافاصله در هنگام اجرای برنامه در دسترس هستند. برای دسترسی به بسته‌های هوش مصنوعی ارائه شده در این حالت، از API 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 استفاده کنید.

وابستگی به کتابخانه Play AI Delivery را اعلام کنید

در فایل 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 شامل وضعیت هر بسته هوش مصنوعی درخواستی است که با نام آن کلیدگذاری شده است:

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)

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

اگر حجم دانلود بیش از ۲۰۰ مگابایت باشد و کاربر به وای‌فای متصل نباشد، دانلود تا زمانی که کاربر صراحتاً رضایت خود را برای ادامه دانلود با استفاده از اتصال داده تلفن همراه اعلام نکند، شروع نمی‌شود. به طور مشابه، اگر حجم دانلود زیاد باشد و کاربر وای‌فای خود را از دست بدهد، دانلود متوقف می‌شود و برای ادامه دانلود با استفاده از اتصال داده تلفن همراه، رضایت صریح لازم است. یک بسته متوقف شده دارای وضعیت WAITING_FOR_WIFI است. برای فعال کردن جریان رابط کاربری و درخواست رضایت از کاربر، از متد showConfirmationDialog() استفاده کنید.

توجه داشته باشید که اگر برنامه این متد را فراخوانی نکند، دانلود متوقف می‌شود و تنها زمانی که کاربر دوباره به اتصال Wi-Fi متصل شود، به طور خودکار از سر گرفته می‌شود.

تایید کاربر الزامی

اگر یک بسته وضعیت REQUIRES_USER_CONFIRMATION داشته باشد، دانلود ادامه پیدا نمی‌کند تا زمانی که کاربر کادر محاوره‌ای نمایش داده شده با showConfirmationDialog() را بپذیرد. این وضعیت می‌تواند زمانی رخ دهد که برنامه توسط Play شناسایی نشده باشد - برای مثال، اگر برنامه از طریق sideload دانلود شده باشد. توجه داشته باشید که فراخوانی showConfirmationDialog() در این حالت باعث به‌روزرسانی برنامه می‌شود. پس از به‌روزرسانی، باید دوباره بسته‌های هوش مصنوعی را درخواست کنید.

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

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

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

بسته‌های هوش مصنوعی در دایرکتوری 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;
}

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

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

سایر روش‌های API تحویل Play AI

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

لغو درخواست

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

حذف یک بسته هوش مصنوعی

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

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

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

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

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

شما می‌توانید ویژگی‌های دستگاه مانند موارد زیر را هدف قرار دهید:

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

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

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

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

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

برای استفاده از هدف‌گیری دستگاه، مطمئن شوید که نسخه افزونه اندروید گریدل (AGP) شما حداقل ۸.۱۰.۰ باشد. این نسخه به همراه اندروید استودیو (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>

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

یک انتخابگر دستگاه می‌تواند یک یا چند ویژگی دستگاه داشته باشد. یک دستگاه در صورتی انتخاب شده است که با تمام ویژگی‌های دستگاه انتخابگر مطابقت داشته باشد.

اگر یک دستگاه با چندین گروه مطابقت داشته باشد، محتوای گروهی که ابتدا در فایل XML تعریف شده است، به آن نمایش داده می‌شود. ترتیبی که گروه‌ها را در فایل XML تعریف می‌کنید، اولویت شماست.

اگر دستگاهی با هیچ گروهی مطابقت نداشته باشد، گروه پیش‌فرض "سایر" را دریافت خواهد کرد. این گروه به طور خودکار ایجاد می‌شود و نباید صریحاً تعریف شود.

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

device_ram : رم مورد نیاز دستگاه
- min_bytes ( شامل) : حداقل رم مورد نیاز (به بایت)
- max_bytes ( اختصاصی) : حداکثر رم مورد نیاز (به بایت)
included_device_ids : مدل‌های دستگاهی که قرار است در این انتخابگر گنجانده شوند (حداکثر ۱۰۰۰۰ device_id در هر گروه) . این ویژگی در صورتی برقرار است که دستگاه با هر device_id در لیست مطابقت داشته باشد.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
exclude_device_ids : مدل‌های دستگاهی که باید در این انتخابگر حذف شوند (حداکثر ۱۰۰۰۰ device_id در هر گروه) . این ویژگی در صورتی برقرار است که دستگاه با هیچ device_id در لیست مطابقت نداشته باشد.
- build_brand : سازنده دستگاه
- build_device : کد مدل دستگاه
required_system_features : ویژگی‌هایی که یک دستگاه باید توسط این انتخابگر شامل شود (حداکثر ۱۰۰ ویژگی در هر گروه) . یک دستگاه برای برآورده کردن این ویژگی باید تمام ویژگی‌های سیستم را در این لیست داشته باشد.
مرجع ویژگی‌های سیستم
- نام : یک ویژگی سیستمی
prohibitive_system_features : ویژگی‌هایی که یک دستگاه نباید توسط این انتخابگر شامل شود (حداکثر ۱۰۰ ویژگی در هر گروه) . اگر دستگاهی هر یک از ویژگی‌های سیستم موجود در این لیست را داشته باشد، این ویژگی را برآورده نمی‌کند.
مرجع ویژگی‌های سیستم
- نام : یک ویژگی سیستمی
سیستم روی تراشه : سیستم روی تراشه‌هایی که باید در این انتخابگر گنجانده شوند. یک دستگاه برای برآورده کردن این ویژگی باید هر تراشه‌ای را در این لیست داشته باشد.
- سازنده : سازنده سیستم روی تراشه
- مدل : مدل سیستم روی تراشه

نکته: گنجاندن چندین ویژگی در یک انتخابگر واحد، یک 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>

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

شما می‌توانید قالب‌بندی صحیح سازنده دستگاه و کد مدل را با استفاده از کاتالوگ دستگاه در کنسول گوگل پلی یا به یکی از روش‌های زیر پیدا کنید:

بررسی تک تک دستگاه‌ها با استفاده از کاتالوگ دستگاه‌ها و یافتن سازنده و کد مدل در مکان‌هایی که در مثال زیر نشان داده شده است (برای گوگل پیکسل ۴a، سازنده «گوگل» و کد مدل «سان‌فیش» است)
دانلود فایل 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های تولید شده از بسته شما بر اساس گروه‌های دستگاه تقسیم‌بندی شوند.

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

شما می‌توانید با ارائه مدل‌های بزرگ خود فقط به دستگاه‌هایی که می‌توانند آنها را اجرا کنند، اندازه را در دستگاه‌ها بهینه نگه دارید.

بسته‌های هوش مصنوعی خود را بر اساس گروه‌های دستگاه تقسیم کنید، برای این کار دایرکتوری‌های بسته هوش مصنوعی موجود که در مرحله قبل ایجاد شده‌اند را در نظر بگیرید و پوشه‌های مناسب (مطابق توضیحات زیر) را با #group_myCustomGroup1، #group_myCustomGroup2 و غیره اصلاح کنید. هنگام استفاده از بسته‌های هوش مصنوعی در برنامه خود، نیازی به آدرس‌دهی پوشه‌ها با پسوند نخواهید داشت (به عبارت دیگر، پسوند به طور خودکار در طول فرآیند ساخت حذف می‌شود).

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

...
.../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>

تست به صورت محلی

قبل از ایجاد نسخه‌ای برای بسته جدید خود، می‌توانید آن را به صورت محلی با استفاده از Internal App Sharing یا Bundletool آزمایش کنید.

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

اشتراک‌گذاری داخلی برنامه به شما امکان می‌دهد از یک بسته برنامه برای تولید سریع یک URL استفاده کنید که می‌توانید روی یک دستگاه محلی روی آن ضربه بزنید تا دقیقاً همان چیزی را که گوگل پلی برای آن دستگاه نصب می‌کند، نصب کنید، اگر آن نسخه از برنامه در یک مسیر آزمایشی یا تولید زنده باشد.

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

ابزار بسته

از طرف دیگر، می‌توانید با استفاده از bundletool (نسخه ۱.۱۸.۰ یا بالاتر) فایل‌های APK تولید کنید و آنها را روی دستگاه خود بارگذاری جانبی (sideload) کنید. برای آزمایش برنامه خود به صورت محلی با استفاده از bundletool، این مراحل را دنبال کنید:

بسته برنامه خود را با اندروید استودیو یا 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 از حافظه خارجی دریافت می‌شوند، بنابراین نمی‌توانید نحوه رفتار کد خود را در صورت بروز خطاهای شبکه آزمایش کنید.
آزمایش محلی سناریوی انتظار برای وای‌فای را پوشش نمی‌دهد.
به‌روزرسانی‌ها پشتیبانی نمی‌شوند. قبل از نصب نسخه جدید، نسخه قبلی را به صورت دستی حذف نصب کنید.

تأیید کنید که 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 نصب نمی‌شوند.

تست و انتشار در گوگل پلی

توصیه می‌کنیم برنامه خود را به صورت کامل در گوگل پلی و با یک مسیر تست داخلی آزمایش کنید.

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

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

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

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

مطالب مرتبط

درباره بسته‌های نرم‌افزاری اندروید بیشتر بدانید و منابع مربوط به کیت توسعه نرم‌افزار AI Delivery را مطالعه کنید.

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

مقدمه

مزایا

ملاحظات

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

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

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

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

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

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

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

وابستگی به کتابخانه Play AI Delivery را اعلام کنید

بررسی وضعیت

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

نصب

نظارت بر وضعیت دانلودها

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

تایید کاربر الزامی

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

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

سایر روش‌های API تحویل Play AI

لغو درخواست

حذف یک بسته هوش مصنوعی

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

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

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

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

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

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

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

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

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

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

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

تست به صورت محلی

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

ابزار بسته

محدودیت‌های تست محلی با bundletool

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

تست و انتشار در گوگل پلی

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

مطالب مرتبط

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