דף זה תורגם על ידי Cloud Translation API.

הפעלה של תוכנית הגישה המוקדמת של AI במכשיר (EAP)
קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

Play for On-device AI משלבת את היתרונות של Android App Bundles וההפצה של Google Play עם הפצת מודלים מותאמים אישית של למידת מכונה, כדי שתוכלו לשפר את ביצועי המודל עם סביבה עסקית פחות מורכבת, ללא עלות נוספת. בעזרת ה-Artifact אפשר לפרסם ב-Play פריט אחד שמכיל את הקוד, הנכסים ומודלי ה-ML, ולבחור מתוך מספר שיטות העברה ואפשרויות טירגוט.

יתרונות

אתם יכולים להעלות לאפליקציית Google Play פריט פרסום אחד ולהעביר אליה את האירוח, ההעברה, העדכונים והטירגוט ללא עלות נוספת.
אפשר להעביר את המודלים של למידת המכונה בזמן ההתקנה, במסגרת תהליך 'מהיר אחרי' או על פי דרישה.
- העברה בזמן ההתקנה יכולה להבטיח שמודל גדול מאוד יהיה נוכח כשהאפליקציה תיפתח. המודל יותקן כ-APK.
- ההעברה ב-Fast Follow מתבצעת באופן אוטומטי ברקע אחרי התקנת האפליקציה. המשתמשים יכולים לפתוח את האפליקציה לפני שההורדה של המודל הושלמה. המודל יורד למרחב האחסון הפנימי של האפליקציה.
- העברה על פי דרישה מאפשרת לבקש את המודל בזמן הריצה, וזו אפשרות שימושית אם המודל נדרש רק לתהליכי שימוש מסוימים. המודל יורד למרחב האחסון הפנימי של האפליקציה.
להציג גרסאות של מודלים של למידת מכונה שמטורגטות למכשירים ספציפיים על סמך דגם המכשיר, מאפייני המערכת או זיכרון ה-RAM.
תיקונים אוטומטיים ב-Play מאפשרים לכם לשמור על גודל קטן של עדכוני האפליקציות ועל אופטימיזציה שלהם, כך שצריך להוריד רק את ההבדלים בין הקבצים.

שיקולים

השימוש ב-Play for On-device AI מבטא את הסכמתכם לתנאים המפורטים בהסכם ההפצה למפתחים של Google Play ובתנאים ולהגבלות של Play Core Software Development Kit.
המפתחים שמשתתפים בתוכנית הגישה המוקדמת צפויים להעריך את Play for On-device AI ולספק משוב ל-Google Play.
רק האפליקציה שהורידה את המודל יכולה להשתמש במודלים שהורדתם באמצעות Play for On-device AI. אסור להציע מודלים לאפליקציות אחרות, למשל דרך חיבור לשירות.
חבילות AI בודדות יכולות להכיל עד 1.5GB, בהתאם לגודל ההורדה שלהן בפורמט דחוס. הגודל המצטבר המקסימלי של כל גרסה של האפליקציה שנוצרה מ-App Bundle הוא 4GB.
באפליקציות שגודלן מעל 1GB, רמת ה-SDK המינימלית צריכה להיות 21 ואילך.
במהלך תוכנית הגישה המוקדמת, Play לטכנולוגיית AI מובנית במכשיר עשוי להשתנות.

איך משתמשים ב-Play לטכנולוגיית AI מובנית במכשיר

ב-Play לטכנולוגיית AI מובנית במכשיר נעשה שימוש בחבילות AI. אתם יכולים לארוז מודלים מותאמים אישית שזמינים להפצה בחבילות AI בחבילת האפליקציות. אתם יכולים לבחור אם חבילת ה-AI תועבר בזמן ההתקנה, מיד אחרי ההתקנה או על פי דרישה.

כשאתם אורזים חבילות AI ב-App Bundle, אתם יכולים להשתמש בכל הכלים הקיימים של Play לבדיקה ולהשקה, כמו מסלולי בדיקה והשקות מדורגות, כדי לנהל את הפצת האפליקציה עם המודלים המותאמים אישית.

חבילות ה-AI מתעדכנות יחד עם קובץ הבינארי של האפליקציה. אם במהדורת האפליקציה החדשה לא בוצעו שינויים בחבילת ה-AI, תהליך התיקון האוטומטי של Play יבטיח שהמשתמש לא יצטרך להוריד אותה מחדש. כשהאפליקציה תתעדכן, Play יוריד רק את הנתונים שהשתנו.

חבילות AI מכילות רק מודלים. אסור להשתמש בספריות Java/Kotlin ובספריות מקומיות. אם אתם צריכים לשלוח ספריות או קוד כדי להריץ את מודל ה-ML, צריך להעביר אותם למודול הבסיס או למודול התכונה. אפשר להגדיר את מודול התכונות כך שיהיה לו אותו הגדרות הורדה וטירגוט כמו של חבילת ה-AI.

שימוש ב-LiteRT וב-MediaPipe עם חבילות AI

אפשר להשתמש ב-LiteRT וב-MediaPipe עם חבילות AI. אורזים את המודל בחבילת AI, ואז ניגשים אליו לפי ההוראות לחבילות לזמן ההתקנה או לחבילות מסוג fast-follow וחבילות על פי דרישה.

מקורות מידע נוספים:

תחילת העבודה עם LiteRT
- באפליקציית הדוגמה מוסבר איך לארוז מודל LiteRT בחבילת AI ולטעון אותו בסביבת זמן הריצה.
- יש הרבה מודלים של LiteRT שהותאמו מראש שאפשר להשתמש בהם בחבילות ה-AI כדי להתחיל.
תחילת העבודה עם MediaPipe
- בחבילות של מעקב מהיר וחבילות על פי דרישה, אפשר להשתמש ב-AssetCache.java כדי לטעון את הנכסים (למשל: .binarypb) לפי נתיבי הקבצים שלהם.
- לחבילות לזמן ההתקנה, אפשר להשתמש ב-AndroidAssetUtil.java.

תחילת העבודה עם חבילות AI

באופן כללי, כך מתחילים להשתמש ב-Play לטכנולוגיית AI מובנית במכשיר:

כדי להצטרף ל-EAP, צריך לספק ל-Google Play את מזהה חשבון הפיתוח שלכם ב-Play.
אריזת המודלים בחבילות AI ב-Android App Bundle וציון האופן שבו צריך לשלוח את חבילות ה-AI.
[אופציונלי] אם רוצים להציג מודלים שונים במכשירים שונים, אפשר להגדיר טירגוט לפי מכשיר לחבילות ה-AI. לדוגמה, אפשר לשלוח את חבילת ה-AI A לדגם מכשיר ספציפי, את חבילת ה-AI B למכשירים עם זיכרון RAM בנפח של 6GB לפחות, ואת כל שאר המכשירים לא לשלוח להם אף מודל.
[אופציונלי] אם אתם משתמשים בהעברה על פי דרישה או בהעברה מהירה, תוכלו לשלב את Play AI Delivery Library באפליקציה כדי להוריד את חבילות ה-AI לפי הצורך.
בודקים את חבילת האפליקציות ומפרסמים אותה ב-Google Play.

יש לציין את מזהה חשבון הפיתוח ב-Play

מכיוון שהתכונה הזו נמצאת עדיין בגישה מוקדמת, חשבון המפתחים שלכם צריך להופיע ברשימת ההיתרים כדי שתהיה לכם גישה ל-Play for On-device AI. מוודאים שהמזהי החשבון של מפתחי Play ושמות החבילות של האפליקציות נכונים, ומעבירים אותם למנהל השותפים של Google Play או למשתתף בצוות Play for On-device AI. מציינים אם רוצים לטרגט את המודלים למכשירים ספציפיים (זהו שלב 3 מהקטע הקודם). בשלב הזה אנחנו מזמינים שותפי Play נבחרים לבדוק את התכונה הזו.

בדיקת הגרסה של פלאגין Android Gradle

כדי להשתמש בחבילות AI, צריך לוודא שגרסת Android Gradle Plugin‏ (AGP) היא לפחות 8.8. הגרסה הזו נכללת בחבילה של Android Studio Ladybug 2.

חילוץ המודל לחבילת AI

אין צורך ב-Android Studio כדי לבצע את השלבים הבאים.

בספרייה ברמה העליונה של הפרויקט, יוצרים ספרייה לחבילת ה-AI. שם הספרייה הזה משמש כשם חבילת ה-AI. שמות של חבילות AI חייבים להתחיל באות, והם יכולים להכיל רק אותיות, מספרים וקווים תחתונים.

בתיקיית חבילת ה-AI, יוצרים קובץ build.gradle ומוסיפים את הקוד הבא. חשוב לציין את שם חבילת ה-AI ורק סוג העברה אחד:

// 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 של האפליקציה בפרויקט, מוסיפים את השם של כל חבילת AI בפרויקט, כפי שמתואר בהמשך:
```
// In the app build.gradle file:
android {
    ...
    assetPacks = [":ai-pack-name", ":ai-pack2-name"]
}
```
בקובץ settings.gradle של הפרויקט, כוללים את כל חבילות ה-AI בפרויקט, כפי שמתואר בהמשך:
```
// In the settings.gradle file:
include ':app'
include ':ai-pack-name'
include ':ai-pack2-name'
```
בתוך חבילת ה-AI, יוצרים ספרייה 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
מוסיפים קוד כדי לטעון ולהריץ את המודלים. הדרך לעשות זאת תלויה במצב המסירה של חבילות ה-AI. בהמשך מפורטות הוראות להתקנה ולמעקב מהיר/מעקב על פי דרישה.
[אופציונלי] מגדירים טירגוט לפי מכשיר כדי להציג מודלים שונים במכשירים שונים.
פיתוח קובץ Android App Bundle באמצעות Gradle. בחבילת האפליקציות שנוצרה, התיקייה ברמת השורש כוללת עכשיו את הפריטים הבאים:
- ai-pack-name/manifest/AndroidManifest.xml: הגדרת המזהה ומצב המסירה של חבילת ה-AI
- ai-pack-name/assets/your-model-directories: הספרייה שמכילה את כל הנכסים שסופקו כחלק מחבילת ה-AI
Gradle יוצר את המניפסט לכל חבילת AI ומפיק את הספרייה assets/ בשבילכם.

הגדרת העברה בזמן ההתקנה

חבילות AI שמוגדרות להתקנה בזמן ההתקנה זמינות באופן מיידי כשמפעילים את האפליקציה. משתמשים ב-Java AssetManager API כדי לגשת לחבילות AI שמוצגות במצב הזה:

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

הגדרת הפצה מסוג fast follow והפצה על פי דרישה

כדי להוריד חבילות AI עם העברה מהירה או על פי דרישה, משתמשים בספריית Play AI Delivery.

הצהרת תלות בספריית Play AI Delivery

בקובץ build.gradle של האפליקציה, מגדירים תלות בספריית Play AI Delivery:

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

בדיקת הסטטוס

כל חבילת AI מאוחסנת בתיקייה נפרדת באחסון הפנימי של האפליקציה. משתמשים ב-method‏ getPackLocation() כדי לקבוע את תיקיית השורש של חבילת AI. השיטה הזו מחזירה את הערכים הבאים:

הערך המוחזר	סטטוס
אובייקט `AiPackLocation` תקין	תיקיית הבסיס של חבילת ה-AI מוכנה לגישה מיידית בכתובת `assetsPath()`
`null`	חבילת AI לא ידועה או חבילות AI שאינן זמינות

קבלת מידע על הורדה של חבילות AI

משתמשים בשיטה
getPackStates() כדי לקבוע את גודל ההורדה ואם החבילה כבר מורדת.

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

getPackStates() היא שיטה אסינכרונית שמחזירה Task<AiPackStates>. השיטה packStates() של אובייקט AiPackStates מחזירה Map<String, AiPackState>. המפה הזו מכילה את המצב של כל חבילת AI שהתבקשה, לפי השם שלה:

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 מספקות את גודל חבילת ה-AI, את הסכום שהורדתם עד כה (אם ביקשת זאת) ואת הסכום שכבר הועבר לאפליקציה:

כדי לקבל את הסטטוס של חבילת AI, משתמשים ב-method‏ status(), שמחזיר את הסטטוס כמספר שלם שתואם לשדה קבוע בכיתה AiPackStatus. חבילת AI שעדיין לא הותקנה תהיה בסטטוס AiPackStatus.NOT_INSTALLED.

אם בקשה נכשלת, משתמשים ב-method‏ errorCode(), וערך ההחזרה שלו תואם לשדה קבוע בכיתה AiPackErrorCode.

התקנה

משתמשים ב-method‏ fetch() כדי להוריד חבילת AI בפעם הראשונה או כדי להפעיל את העדכון של חבילת AI:

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

השיטה הזו מחזירה אובייקט AiPackStates שמכיל רשימה של חבילות, את הגדלים והסטטוסים הראשוניים של ההורדה שלהן. אם כבר מתבצעת הורדה של חבילת AI שהתבקשה באמצעות fetch(), סטטוס ההורדה מוחזר ולא מתחילה הורדה נוספת.

מעקב אחר מצבי ההורדה

מומלץ להטמיע AiPackStateUpdateListener כדי לעקוב אחרי התקדמות ההתקנה של חבילות ה-AI. עדכוני הסטטוס מפורטים לפי חבילה כדי לאפשר מעקב אחרי הסטטוס של חבילות AI ספציפיות. תוכלו להתחיל להשתמש בחבילות ה-AI הזמינות לפני שכל ההורדות האחרות של הבקשה יושלמו.

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

הורדות גדולות

אם ההורדה גדולה מ-200MB והמשתמש לא מחובר לרשת Wi-Fi, ההורדה לא תתחיל עד שהמשתמש ייתן הסכמה מפורשת להמשיך בהורדה באמצעות חיבור לנתונים ניידים. באופן דומה, אם ההורדה גדולה והמשתמש מאבד את החיבור ל-Wi-Fi, ההורדה מושהית ונדרשת הסכמה מפורשת כדי להמשיך אותה באמצעות חיבור לחבילת גלישה. לחבילה מושהית יש את המצב WAITING_FOR_WIFI. כדי להפעיל את תהליך ממשק המשתמש לבקשת הסכמה מהמשתמש, משתמשים ב-method‏ showConfirmationDialog().

חשוב לזכור שאם האפליקציה לא קוראת לשיטה הזו, ההורדה מושהית ותתחדש באופן אוטומטי רק כשהמשתמש יחזור להתחבר ל-Wi-Fi.

אישור נדרש מהמשתמש

אם לחבילה יש את הסטטוס REQUIRES_USER_CONFIRMATION, ההורדה לא תמשיך עד שהמשתמש יאשר את תיבת הדו-שיח שמוצגת עם showConfirmationDialog(). הסטטוס הזה יכול להופיע אם האפליקציה לא מזוהה על ידי Play – לדוגמה, אם האפליקציה הועברה להתקנה ידנית. לתשומת ליבכם: במקרה כזה, קריאה ל-showConfirmationDialog() תגרום לעדכון האפליקציה. אחרי העדכון, תצטרכו לבקש שוב את חבילות ה-AI.

דוגמה להטמעה של מאזין:

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

לחלופין, אפשר להשתמש ב-method‏ getPackStates() כדי לקבל את הסטטוס של ההורדות הנוכחיות. AiPackStates מכיל את התקדמות ההורדה, סטטוס ההורדה וקודי שגיאה של כשל.

גישה לחבילות AI

אפשר לגשת לחבילת AI באמצעות קריאות למערכת הקבצים אחרי שסטטוס הבקשה להורדה מגיע ל-COMPLETED. משתמשים ב-method‏ getPackLocation() כדי לקבל את תיקיית השורש של חבילת ה-AI.

חבילות ה-AI מאוחסנות בתיקייה assets בספריית השורש של חבילת ה-AI. אפשר לקבל את הנתיב לספרייה assets באמצעות ה-method הנוחה 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;
}

הגדרת טירגוט לפי מכשיר

תוכלו לפעול לפי ההוראות לטירגוט לפי מכשיר כדי לציין את המכשירים או הקבוצות של המכשירים שצריכים לקבל את חבילות ה-AI.

שיטות אחרות של Play AI Delivery API

בהמשך מפורטות כמה שיטות API נוספות שאפשר להשתמש בהן באפליקציה.

ביטול הבקשה

אפשר להשתמש ב-cancel() כדי לבטל בקשה פעילה לחבילת AI. חשוב לזכור שהבקשה הזו היא פעולה לפי יכולת.

הסרה של חבילת AI

משתמשים ב-removePack() כדי לתזמן את ההסרה של חבילת AI.

אחזור המיקומים של כמה חבילות AI

אפשר להשתמש ב-getPackLocations() כדי לשלוח שאילתה לגבי הסטטוס של כמה חבילות AI בבת אחת, וכתוצאה מכך תקבלו מפה של חבילות ה-AI והמיקומים שלהן. המפה שמוחזרת על ידי getPackLocations() מכילה רשומה לכל חבילה שהורדתם כרגע והיא עדכנית.

מיקוד למכשירים

טירגוט לפי מכשיר מאפשר לכם לשלוט בצורה מדויקת יותר בחלקים של חבילת האפליקציות שיוצגו במכשירים ספציפיים. לדוגמה, אפשר להבטיח שמודל גדול יועבר רק למכשירים עם נפח RAM גדול, או לשלוח גרסאות שונות של מודל למכשירים שונים.

אפשר לטרגט מאפייני מכשירים כמו:

פרטי CPU ו-GPU ‏(System on Chip)
דגם המכשיר
זיכרון RAM של המכשיר
תכונות מערכת

סקירה כללית של השלבים הנדרשים

כדי להפעיל טירגוט לפי מכשיר, צריך לבצע את השלבים הבאים:

מגדירים את קבוצות המכשירים בקובץ XML.
מציינים אילו חלקים מהחבילה יישלחו לאילו קבוצות של מכשירים.
[אופציונלי] בודקים את ההגדרות באופן מקומי.
מעלים את החבילה (שמכילה את קובץ ה-XML) ל-Google Play.

בדיקת הגרסה של פלאגין Android Gradle

כדי להשתמש בטירגוט לפי מכשיר, צריך לוודא שגרסת Android Gradle Plugin‏ (AGP) היא לפחות 8.10.0-alpha01. התכונה הזו נכללת בחבילה של Android Studio Meerkat 2, שנמצאת בגרסת canary.

הפעלת התכונה הזו בפלאגין של 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: דרישות ה-RAM של המכשיר
- min_bytes (כולל): נפח ה-RAM המינימלי הנדרש (בייטים)
- max_bytes (בלעדי): נפח ה-RAM המרבי הנדרש (בבייטים)
included_device_ids: דגמי המכשירים שרוצים לכלול בבורר הזה (עד 10,000 מזהי device_id לכל קבוצה). הנכס הזה מתקיים אם המכשיר תואם לאחד מהמכשירים שמופיעים ברשימה.
- build_brand: יצרן המכשיר
- build_device: קוד דגם המכשיר
excluded_device_ids: דגמי המכשירים שצריך להחריג בבורר הזה (עד 10,000 מזהי device_id לכל קבוצה). הנכס הזה מתקיים אם המכשיר לא תואם לאף device_id ברשימה.
- build_brand: יצרן המכשיר
- build_device: קוד דגם המכשיר
required_system_features: התכונות שצריכות להיות במכשיר כדי שהוא ייכלל על ידי הבורר הזה (עד 100 תכונות לכל קבוצה). כדי לעמוד בדרישות של המאפיין הזה, המכשיר צריך לכלול את כל תכונות המערכת שמפורטות ברשימה הזו.

מידע על התכונות של המערכת
- name: תכונת מערכת
forbidden_system_features: תכונות שלא חייבות להיכלל במכשיר על ידי הבורר הזה (עד 100 תכונות לכל קבוצה). אם במכשיר יש אחת מתכונות המערכת שמפורטות ברשימה הזו, הוא לא עומד בדרישות של המאפיין הזה.

מידע על התכונות של המערכת
- name: תכונת מערכת
system-on-chip: מערכת על שבב (SoC) שרוצים לכלול בבורר הזה. כדי לעמוד בקריטריון הזה, המכשיר צריך לכלול צ'יפ כלשהו מהרשימה הזו.
- manufacturer: יצרן מערכת אחת (SoC)
- model: מודל של מערכת אחת על שבב (SoC)

טיפ: הוספה של כמה מאפיינים לבורר יחיד יוצרת לוגיקת AND, לדוגמה:

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

תיצור את התנאי לכל המכשירים עם זיכרון RAM בנפח של יותר מ-7GB וגם מכשיר Pixel 4. אפשר לכתוב את זה גם כך:

אם רוצים להשתמש בתנאי OR, צריך ליצור בוררים נפרדים בקבוצת מכשירים אחת, לדוגמה:

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

תיצור את התנאי לכל המכשירים עם זיכרון RAM בנפח של יותר מ-7GB או שהמכשיר הוא Pixel 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 Console באחת מהדרכים הבאות:

בודקים מכשירים ספציפיים באמצעות קטלוג המכשירים ומאתרים את היצרן ואת קוד הדגם במיקומים שמוצגים בדוגמה הבאה (במכשיר 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 שנוצרות מה-App Bundle יתחלקו לפי קבוצות מכשירים.

שימוש בטירגוט לפי מכשיר בחבילות ה-AI

כדי לשמור על אופטימיזציה של הגודל במכשירים, אפשר לשלוח את המודלים הגדולים רק למכשירים שיכולים להריץ אותם.

כדי לפצל את חבילות ה-AI לפי קבוצות של מכשירים, צריך לקחת את ספריות הקיימות של חבילות ה-AI שנוצרו בשלב האחרון, ולהוסיף למספרי הקבצים של התיקיות המתאימות את הסיומת #group_myCustomGroup1, ‏ #group_myCustomGroup2 וכו' (כפי שמתואר בהמשך). כשמשתמשים בחבילות ה-AI באפליקציה, לא צריך להתייחס לתיקיות לפי הסיומת (כלומר, הסיומת מוסרת באופן אוטומטי במהלך תהליך ה-build).

אחרי השלב הקודם, זה עשוי להיראות כך:

...
.../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 ריקה.

הסיבה לכך היא שמכשירים שלא תואמים לאף קבוצת מכשירים יקבלו את גרסת ברירת המחדל של חבילת ה-AI. הרשאות הקריאה והכתיבה יהיו זמינות לכל דבר שאינו נמצא בספרייה עם #group_suffix.

אחרי שתורידו את חבילת ה-AI, תוכלו לבדוק אם המודל נמצא בה באמצעות AssetManager לחבילות שהותקנו בזמן ההתקנה, או באמצעות AiPackManager לחבילות מסוג fast-follow ולחבילות על פי דרישה. דוגמאות לביצוע הפעולה הזו מוצגות לכל שיטות המסירה באפליקציה לדוגמה.

שימוש בטירגוט לפי מכשיר במודולים של הפיצ'רים

אפשר גם להשתמש בטירגוט לפי מכשיר במודולים של תכונות. במקום לפצל את מודולי התכונות לפי קבוצת מכשירים, אפשר לציין אם יש להעביר את המודול כולו על סמך החברות בקבוצת המכשירים.

כדי להעביר מודול תכונות למכשירים ששייכים ל-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:

יוצרים את קובץ ה-App Bundle באמצעות 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.
אין תמיכה בעדכונים. לפני התקנת גרסה חדשה של ה-build, צריך להסיר את הגרסה הקודמת באופן ידני.

מוודאים שה-APKs הנכונים מותקנים

כדי לוודא שרק קובצי ה-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 על פי דרישה וחבילות AI לעדכון מהיר לא מותקנות כ-APK.

בדיקה ופרסום ב-Google Play

מומלץ לבדוק את האפליקציה מקצה לקצה ב-Google Play באמצעות מסלול בדיקה פנימי.

לאחר מכן תוכלו להשיק את עדכון האפליקציה בהדרגה בסביבת הייצור באמצעות השקות מדורגות.

אפליקציה לדוגמה שמשתמשת ב-Play לטכנולוגיית AI מובנית במכשיר

כדי לקבל גישה לאפליקציית הדוגמה, פנו ל-Partner Manager שלכם ב-Google Play.

בקישור הזה מוסבר איך להשתמש בכל אחד משיטות ההצגה, וגם איך להגדיר טירגוט למכשירים. בקטע בדיקה מקומית מוסבר איך מתחילים.

שליחת משוב

המשתתפים בתוכנית הגישה המוקדמת צריכים לדווח על בעיות ולספק משוב. אתם יכולים לפנות למנהל השותפים שלכם ב-Google Play או לצוות Play for On-device AI.

תוכן קשור

מידע נוסף על חבילות אפליקציות ל-Android ומקורות מידע נוספים על AI Delivery SDK

הפעלה של תוכנית הגישה המוקדמת של AI במכשיר (EAP) קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

יתרונות

שיקולים

איך משתמשים ב-Play לטכנולוגיית AI מובנית במכשיר

שימוש ב-LiteRT וב-MediaPipe עם חבילות AI

תחילת העבודה עם חבילות AI

יש לציין את מזהה חשבון הפיתוח ב-Play

בדיקת הגרסה של פלאגין Android Gradle

חילוץ המודל לחבילת AI

הגדרת העברה בזמן ההתקנה

הגדרת הפצה מסוג fast follow והפצה על פי דרישה

הצהרת תלות בספריית Play AI Delivery

בדיקת הסטטוס

קבלת מידע על הורדה של חבילות AI

התקנה

מעקב אחר מצבי ההורדה

הורדות גדולות

אישור נדרש מהמשתמש

גישה לחבילות AI

הגדרת טירגוט לפי מכשיר

שיטות אחרות של Play AI Delivery API

ביטול הבקשה

הסרה של חבילת AI

אחזור המיקומים של כמה חבילות AI

מיקוד למכשירים

סקירה כללית של השלבים הנדרשים

בדיקת הגרסה של פלאגין Android Gradle

הפעלת התכונה הזו בפלאגין של Android Gradle

יצירת קובץ XML של הגדרות טירגוט לפי מכשיר

מאפייני המכשיר הזמינים

קודים רשמיים של יצרן המכשיר ודגם המכשיר

הכללת קובץ התצורה של הטירגוט למכשיר בחבילת האפליקציה

שימוש בטירגוט לפי מכשיר בחבילות ה-AI

שימוש בטירגוט לפי מכשיר במודולים של הפיצ'רים

בדיקה מקומית

שיתוף פנימי של אפליקציות

Bundletool

מגבלות של בדיקה מקומית באמצעות bundletool

מוודאים שה-APKs הנכונים מותקנים

בדיקה ופרסום ב-Google Play

אפליקציה לדוגמה שמשתמשת ב-Play לטכנולוגיית AI מובנית במכשיר

שליחת משוב

תוכן קשור

הפעלה של תוכנית הגישה המוקדמת של AI במכשיר (EAP)
קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.