Mulai 27 Maret 2025, sebaiknya gunakan android-latest-release, bukan aosp-main, untuk mem-build dan berkontribusi pada AOSP. Untuk mengetahui informasi selengkapnya, lihat Perubahan pada AOSP.

Halaman ini diterjemahkan oleh Cloud Translation API.

Kualitas layanan

Mulai dari Android 11, NNAPI menawarkan kualitas layanan (QoS) yang lebih baik dengan memungkinkan aplikasi menunjukkan prioritas relatif modelnya, jumlah waktu maksimum yang diperkirakan untuk menyiapkan model tertentu, dan jumlah waktu maksimum yang diperkirakan untuk menyelesaikan eksekusi tertentu. Selain itu, Android 11 memperkenalkan nilai error NNAPI tambahan yang memungkinkan layanan menunjukkan dengan lebih akurat apa yang salah saat terjadi kegagalan sehingga aplikasi klien dapat bereaksi dan memulihkan diri dengan lebih baik.

Prioritas

Untuk Android 11 atau yang lebih tinggi, model disiapkan dengan prioritas di NN HAL 1.3. Prioritas ini relatif terhadap model siap pakai lainnya yang dimiliki oleh aplikasi yang sama. Eksekusi dengan prioritas lebih tinggi dapat menggunakan lebih banyak resource komputasi daripada eksekusi dengan prioritas lebih rendah, dan dapat mendahului atau menghentikan eksekusi dengan prioritas lebih rendah.

Panggilan NN HAL 1.3 yang menyertakan Priority sebagai argumen eksplisit adalah IDevice::prepareModel_1_3. Perhatikan bahwa IDevice::prepareModelFromCache_1_3 secara implisit menyertakan Priority dalam argumen cache.

Ada banyak kemungkinan strategi untuk mendukung prioritas, bergantung pada kemampuan driver dan akselerator. Berikut beberapa strateginya:

Untuk driver yang memiliki dukungan prioritas bawaan, teruskan kolom Priority secara langsung ke akselerator.
Gunakan antrean prioritas per aplikasi untuk mendukung berbagai prioritas bahkan sebelum eksekusi mencapai akselerator.
Menjeda atau membatalkan model berprioritas rendah yang sedang dieksekusi untuk mengosongkan akselerator agar dapat mengeksekusi model berprioritas tinggi. Lakukan hal ini dengan menyisipkan titik pemeriksaan dalam model berprioritas rendah yang, saat tercapai, akan membuat kueri flag untuk menentukan apakah eksekusi saat ini harus dihentikan sebelum waktunya atau dengan mempartisi model menjadi submodel dan membuat kueri flag di antara eksekusi submodel. Perhatikan bahwa penggunaan titik pemeriksaan atau submodel dalam model yang disiapkan dengan prioritas dapat menimbulkan overhead tambahan yang tidak ada untuk model tanpa prioritas dalam versi yang lebih rendah dari NN HAL 1.3.
- Untuk mendukung pendahuluan, pertahankan konteks eksekusi termasuk operasi atau sub-model berikutnya yang akan dieksekusi dan data operand perantara yang relevan. Gunakan konteks eksekusi ini untuk melanjutkan eksekusi di lain waktu.
- Dukungan pendahuluan penuh tidak diperlukan, sehingga konteks eksekusi tidak perlu dipertahankan. Karena eksekusi model NNAPI bersifat deterministik, eksekusi dapat dimulai ulang dari awal di lain waktu.

Android memungkinkan layanan membedakan berbagai aplikasi yang memanggil melalui penggunaan AID (UID Android). HIDL memiliki mekanisme bawaan untuk mengambil UID aplikasi yang memanggil melalui metode ::android::hardware::IPCThreadState::getCallingUid. Daftar AID dapat ditemukan di libcutils/include/cutils/android_filesystem_config.h.

Batas waktu

Mulai dari Android 11, penyiapan dan eksekusi model dapat diluncurkan dengan argumen batas waktu OptionalTimePoint. Untuk pengemudi yang dapat memperkirakan durasi penyelesaian tugas, batas waktu ini memungkinkan pengemudi membatalkan tugas sebelum dimulai jika pengemudi memperkirakan bahwa tugas tidak dapat diselesaikan sebelum batas waktu. Demikian pula, batas waktu memungkinkan pengemudi membatalkan tugas yang sedang berlangsung yang diperkirakan tidak akan selesai sebelum batas waktu. Argumen batas waktu tidak memaksa driver untuk membatalkan tugas jika tugas belum selesai sebelum batas waktu atau jika batas waktu telah berlalu. Argumen batas waktu dapat digunakan untuk membebaskan resource komputasi dalam driver dan mengembalikan kontrol ke aplikasi lebih cepat daripada yang mungkin dilakukan tanpa batas waktu.

Panggilan NN HAL 1.3 yang menyertakan batas waktu OptionalTimePoint sebagai argumen adalah:

IDevice::prepareModel_1_3
IDevice::prepareModelFromCache_1_3
IPreparedModel::execute_1_3
IPreparedModel::executeSynchronously_1_3
IPreparedModel::executeFenced

Untuk melihat implementasi referensi fitur batas waktu untuk setiap metode di atas, lihat driver contoh NNAPI di frameworks/ml/nn/driver/sample/SampleDriver.cpp.

Kode error

Android 11 menyertakan empat nilai kode error di NN HAL 1.3 untuk meningkatkan pelaporan error, sehingga memungkinkan driver mengomunikasikan statusnya dengan lebih baik dan aplikasi pulih dengan lebih lancar. Berikut adalah nilai kode error di ErrorStatus.

MISSED_DEADLINE_TRANSIENT
MISSED_DEADLINE_PERSISTENT
RESOURCE_EXHAUSTED_TRANSIENT
RESOURCE_EXHAUSTED_PERSISTENT

Di Android 10 atau yang lebih rendah, driver hanya dapat menunjukkan kegagalan melalui kode error GENERAL_FAILURE. Mulai Android 11, dua kode error MISSED_DEADLINE dapat digunakan untuk menunjukkan bahwa workload dibatalkan karena batas waktu tercapai atau karena driver memprediksi bahwa workload tidak akan selesai sebelum batas waktu. Dua kode error RESOURCE_EXHAUSTED dapat digunakan untuk menunjukkan bahwa tugas gagal karena batasan resource dalam driver, seperti driver tidak memiliki memori yang cukup untuk panggilan.

Versi TRANSIENT dari kedua error menunjukkan bahwa masalah bersifat sementara, dan panggilan mendatang ke tugas yang sama mungkin berhasil setelah penundaan singkat. Misalnya, kode error ini harus ditampilkan saat driver sedang sibuk dengan pekerjaan sebelumnya yang berjalan lama atau menggunakan banyak resource, tetapi tugas baru akan berhasil diselesaikan jika driver tidak sedang sibuk dengan pekerjaan sebelumnya. Versi PERSISTENT dari kedua error menunjukkan bahwa panggilan selanjutnya ke tugas yang sama akan selalu gagal. Misalnya, kode error ini harus ditampilkan saat pengemudi memperkirakan tugas tidak akan selesai sebelum batas waktu meskipun dalam kondisi sempurna, atau model pada dasarnya terlalu besar dan melampaui resource pengemudi.

Validasi

Fungsi kualitas layanan diuji dalam pengujian VTS NNAPI (VtsHalNeuralnetworksV1_3Target). Hal ini mencakup serangkaian pengujian untuk validasi (TestGenerated/ValidationTest#Test/) guna memastikan bahwa driver menolak prioritas yang tidak valid dan serangkaian pengujian yang disebut DeadlineTest (TestGenerated/DeadlineTest#Test/) untuk memastikan bahwa driver menangani batas waktu dengan benar.