تصنيف الصور باستخدام نموذج تم تدريبه على AutoML على Android

بعد تدريب النموذج الخاص بك باستخدام AutoML Vision Edge، يمكنك استخدامه في تطبيقك لتصنيف الصور.

هناك طريقتان لدمج النماذج المدرَّبة من AutoML Vision Edge: يمكنك تجميع النموذج من خلال وضعه داخل مجلد مواد العرض في تطبيقك، أو يمكنك تنزيله ديناميكيًا من Firebase.

خيارات تجميع النماذج
مضمّنة في تطبيقك
  • الطراز جزء من حزمة APK لتطبيقك
  • يتوفّر النموذج على الفور، حتى عندما يكون جهاز Android غير متصل بالإنترنت
  • لا حاجة إلى مشروع على Firebase
مستضافة باستخدام Firebase
  • استضافة النموذج من خلال تحميله إلى Firebase Machine Learning
  • تقليل حجم حزمة APK
  • يتم تنزيل النموذج عند الطلب
  • إرسال تحديثات النموذج بدون إعادة نشر تطبيقك
  • إجراء اختبارات A/B بسهولة باستخدام الإعداد عن بُعد في Firebase
  • يتطلّب مشروعًا على Firebase

قبل البدء

  1. أضِف التبعيات الخاصة بمكتبات ML Kit لنظام التشغيل Android إلى ملف Gradle على مستوى التطبيق في الوحدة، والذي يكون عادةً app/build.gradle:

    لتضمين نموذج مع تطبيقك، اتّبِع الخطوات التالية:

    dependencies {
  // ...
  // Image labeling feature with bundled automl model
  implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
}

    لتنزيل نموذج بشكل ديناميكي من Firebase، أضِف linkFirebaseالتبعية التالية:

    dependencies {
  // ...
  // Image labeling feature with automl model downloaded
  // from firebase
  implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
  implementation 'com.google.mlkit:linkfirebase:16.1.0'
}

  2. إذا كنت تريد تنزيل نموذج، تأكَّد من إضافة Firebase إلى مشروع Android، إذا لم يسبق لك إجراء ذلك. لا يكون ذلك مطلوبًا عند تجميع النموذج.

1. تحميل النموذج

ضبط مصدر نموذج محلي

لتضمين النموذج في تطبيقك، اتّبِع الخطوات التالية:

  1. استخرِج النموذج وبياناته الوصفية من ملف ZIP الذي نزّلته من وحدة تحكّم Firebase. ننصحك باستخدام الملفات كما نزّلتها بدون تعديل (بما في ذلك أسماء الملفات).

  2. أدرِج النموذج وملفات البيانات الوصفية الخاصة به في حزمة تطبيقك:

    1. إذا لم يكن لديك مجلد أصول في مشروعك، أنشئ مجلدًا من خلال النقر بزر الماوس الأيمن على المجلد app/، ثم النقر على جديد > مجلد > مجلد الأصول.
    2. أنشئ مجلدًا فرعيًا ضمن مجلد مواد العرض ليحتوي على ملفات التصميم.
    3. انسخ الملفات model.tflite وdict.txt وmanifest.json إلى المجلد الفرعي (يجب أن تكون الملفات الثلاثة في المجلد نفسه).

  3. أضِف ما يلي إلى ملف build.gradle في تطبيقك للتأكّد من أنّ Gradle لا يضغط ملف النموذج عند إنشاء التطبيق:

    android {
    // ...
    aaptOptions {
        noCompress "tflite"
    }
}

    سيتم تضمين ملف النموذج في حزمة التطبيق وسيكون متاحًا لخدمة ML Kit كمادة عرض أولية.

  4. أنشئ كائن LocalModel، مع تحديد مسار ملف بيان النموذج:

    Java

    AutoMLImageLabelerLocalModel localModel =
    new AutoMLImageLabelerLocalModel.Builder()
        .setAssetFilePath("manifest.json")
        // or .setAbsoluteFilePath(absolute file path to manifest file)
        .build();

    Kotlin

    val localModel = LocalModel.Builder()
    .setAssetManifestFilePath("manifest.json")
    // or .setAbsoluteManifestFilePath(absolute file path to manifest file)
    .build()

إعداد مصدر نموذج مستضاف على Firebase

لاستخدام النموذج المستضاف عن بُعد، أنشئ عنصر CustomRemoteModel، مع تحديد الاسم الذي خصّصته للنموذج عند نشره:

Java

// Specify the name you assigned in the Firebase console.
FirebaseModelSource firebaseModelSource =
    new FirebaseModelSource.Builder("your_model_name").build();
CustomRemoteModel remoteModel =
    new CustomRemoteModel.Builder(firebaseModelSource).build();

Kotlin

// Specify the name you assigned in the Firebase console.
val firebaseModelSource = FirebaseModelSource.Builder("your_model_name")
    .build()
val remoteModel = CustomRemoteModel.Builder(firebaseModelSource).build()

بعد ذلك، ابدأ مهمة تنزيل النموذج، مع تحديد الشروط التي تريد السماح بالتنزيل بموجبها. إذا لم يكن النموذج متوفّرًا على الجهاز، أو إذا كان يتوفّر إصدار أحدث منه، ستنزّل المهمة النموذج بشكل غير متزامن من Firebase:

Java

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(@NonNull Task<Void> task) {
                // Success.
            }
        });

Kotlin

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

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

إنشاء أداة تصنيف صور من نموذجك

بعد ضبط مصادر النموذج، أنشئ عنصر ImageLabeler من أحدها.

إذا كان لديك نموذج مجمّع محليًا فقط، ما عليك سوى إنشاء أداة تصنيف من عنصر CustomImageLabelerOptions وضبط الحد الأدنى المطلوب لنتيجة الثقة (راجِع تقييم النموذج):

Java

CustomImageLabelerOptions customImageLabelerOptions = new CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

Kotlin

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

إذا كان لديك نموذج مستضاف عن بُعد، عليك التأكّد من تنزيله قبل تشغيله. يمكنك التحقّق من حالة تنزيل النموذج باستخدام الطريقة isModelDownloaded() في &quot;أداة إدارة النماذج&quot;.

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

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener<Boolean>() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                        .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                                       // to determine an appropriate threshold.
                        .build();

                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
        val optionsBuilder =
            if (isDownloaded) {
                CustomImageLabelerOptions.Builder(remoteModel)
            } else {
                CustomImageLabelerOptions.Builder(localModel)
            }
        // Evaluate your model in the Cloud console to determine an appropriate threshold.
        val options = optionsBuilder.setConfidenceThreshold(0.0f).build()
        val labeler = ImageLabeling.getClient(options)
}

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

Java

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

Kotlin

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

2- إعداد الصورة المدخَلة

بعد ذلك، أنشئ InputImage عنصرًا من صورتك لكل صورة تريد تصنيفها. يعمل مصنّف الصور بأسرع ما يمكن عند استخدام Bitmap أو YUV_420_888 media.Image إذا كنت تستخدم Camera2 API، وهما الخياران اللذان يُنصح بهما عند الإمكان.

يمكنك إنشاء InputImage من مصادر مختلفة، ويتم توضيح كل مصدر أدناه.

استخدام media.Image

لإنشاء عنصر InputImage من عنصر media.Image، مثلاً عند التقاط صورة من كاميرا جهاز، مرِّر عنصر media.Image ودوران الصورة إلى InputImage.fromMediaImage().

إذا كنت تستخدم مكتبة CameraX، سيحسب لك الفئتان OnImageCapturedListener وImageAnalysis.Analyzer قيمة الدوران.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {
    override fun analyze(imageProxy: ImageProxy?) {
        val mediaImage = imageProxy?.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        if (imageProxy == null || imageProxy.getImage() == null) {
            return;
        }
        Image mediaImage = imageProxy.getImage();
        InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees);
        // Pass image to an ML Kit Vision API
        // ...
    }
}

إذا لم تستخدم مكتبة كاميرا تمنحك درجة دوران الصورة، يمكنك احتسابها من درجة دوران الجهاز واتجاه مستشعر الكاميرا في الجهاز:

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 90)
    ORIENTATIONS.append(Surface.ROTATION_90, 0)
    ORIENTATIONS.append(Surface.ROTATION_180, 270)
    ORIENTATIONS.append(Surface.ROTATION_270, 180)
}
/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, context: Context): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
        .getCameraCharacteristics(cameraId)
        .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    val result: Int
    when (rotationCompensation) {
        0 -> result = FirebaseVisionImageMetadata.ROTATION_0
        90 -> result = FirebaseVisionImageMetadata.ROTATION_90
        180 -> result = FirebaseVisionImageMetadata.ROTATION_180
        270 -> result = FirebaseVisionImageMetadata.ROTATION_270
        else -> {
            result = FirebaseVisionImageMetadata.ROTATION_0
            Log.e(TAG, "Bad rotation value: $rotationCompensation")
        }
    }
    return result
}
VisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 90);
    ORIENTATIONS.append(Surface.ROTATION_90, 0);
    ORIENTATIONS.append(Surface.ROTATION_180, 270);
    ORIENTATIONS.append(Surface.ROTATION_270, 180);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, Context context)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    int result;
    switch (rotationCompensation) {
        case 0:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            break;
        case 90:
            result = FirebaseVisionImageMetadata.ROTATION_90;
            break;
        case 180:
            result = FirebaseVisionImageMetadata.ROTATION_180;
            break;
        case 270:
            result = FirebaseVisionImageMetadata.ROTATION_270;
            break;
        default:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            Log.e(TAG, "Bad rotation value: " + rotationCompensation);
    }
    return result;
}
VisionImage.java

بعد ذلك، مرِّر العنصر media.Image وقيمة درجة التدوير إلى InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

استخدام معرّف الموارد المنتظم (URI) للملف

لإنشاء عنصر InputImage من معرّف URI لملف، مرِّر سياق التطبيق ومعرّف URI للملف إلى InputImage.fromFilePath(). ويكون ذلك مفيدًا عند استخدام ACTION_GET_CONTENT intent لطلب أن يختار المستخدم صورة من تطبيق المعرض.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

استخدام ByteBuffer أو ByteArray

لإنشاء عنصر InputImage من ByteBuffer أو ByteArray، عليك أولاً حساب درجة دوران الصورة كما سبق وصفها لإدخال media.Image. بعد ذلك، أنشئ الكائن InputImage باستخدام المخزن المؤقت أو المصفوفة، بالإضافة إلى ارتفاع الصورة وعرضها وتنسيق ترميز الألوان ودرجة التدوير:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

استخدام Bitmap

لإنشاء كائن InputImage من كائن Bitmap، عليك إجراء التصريح التالي:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);

يتم تمثيل الصورة بكائن Bitmap مع درجات التدوير.

3- تشغيل أداة تصنيف الصور

لتصنيف العناصر في صورة، مرِّر العنصر image إلى طريقة ImageLabeler's process().

Java

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });

Kotlin

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }

4. الحصول على معلومات عن العناصر المصنَّفة

في حال نجاح عملية تصنيف الصور، يتم تمرير قائمة ImageLabel بالكائنات إلى أداة معالجة النجاح. يمثّل كل كائن ImageLabel شيئًا تم تصنيفه في الصورة. يمكنك الحصول على وصف نصي لكل تصنيف، ونتيجة الثقة في المطابقة، وفهرس المطابقة. على سبيل المثال:

Java

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}

Kotlin

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}

نصائح لتحسين الأداء في الوقت الفعلي

إذا كنت تريد تصنيف الصور في تطبيق يعمل في الوقت الفعلي، اتّبِع الإرشادات التالية للحصول على أفضل معدّلات عرض اللقطات في الثانية:

  • تقييد عدد الطلبات التي يتم إرسالها إلى أداة تصنيف الصور إذا أصبح إطار فيديو جديد متاحًا أثناء تشغيل أداة تصنيف الصور، يجب تجاهل الإطار. يمكنك الاطّلاع على فئة VisionProcessorBase في نموذج تطبيق البدء السريع للحصول على مثال.
  • إذا كنت تستخدم ناتج أداة تصنيف الصور لتراكب الرسومات على صورة الإدخال، عليك أولاً الحصول على النتيجة، ثم عرض الصورة وتراكبها في خطوة واحدة. وبذلك، يتم العرض على مساحة العرض مرة واحدة فقط لكل إطار إدخال. يمكنك الاطّلاع على الفئتين CameraSourcePreview و GraphicOverlay في تطبيق نموذج البدء السريع للحصول على مثال.

  • إذا كنت تستخدم Camera2 API، التقط الصور بتنسيق ImageFormat.YUV_420_888.

    إذا كنت تستخدم الإصدار القديم من Camera API، التقط الصور بتنسيق ImageFormat.NV21.