2025년 3월 27일부터 AOSP를 빌드하고 기여하려면 aosp-main 대신 android-latest-release를 사용하는 것이 좋습니다. 자세한 내용은 AOSP 변경사항을 참고하세요.
서비스 품질
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Android 11부터 NNAPI는 앱이 모델의 상대적 우선순위, 지정된 모델 준비에 예상되는 최대 시간 및 지정된 실행 완료에 예상되는 최대 시간을 표시하도록 허용함으로써 향상된 서비스 품질(QoS)을 제공합니다. 또한 Android 11에는 추가 NNAPI 오류 값이 도입되었습니다. 이 오류 값을 사용하면 장애가 발생한 경우 서비스가 무엇이 잘못되었는지 좀 더 정확하게 표시할 수 있기 때문에 클라이언트 앱이 보다 정확하게 대응하고 복구할 수 있습니다.
우선순위
Android 11 이상의 경우 NN HAL 1.3에서는 모델이 우선순위가 지정된 상태로 준비됩니다. 이 우선순위는 동일한 앱이 소유한 다른 준비된 모델에 따라 다릅니다. 우선순위가 높은 실행은 우선순위가 낮은 실행보다 더 많은 컴퓨팅 리소스를 사용할 수 있으며, 우선순위가 낮은 실행을 선점하거나 우선순위가 낮은 실행에 아무런 리소스를 제공하지 않을 수 있습니다.
Priority를 명시적 인수로 포함하는 NN HAL 1.3 호출은 IDevice::prepareModel_1_3입니다.
IDevice::prepareModelFromCache_1_3은 캐시 인수에 Priority를 암시적으로 포함합니다.
드라이버와 액셀러레이터의 기능에 따라 우선순위를 지원하는 데는 여러 가지 전략이 가능합니다. 다음은 그중 몇 가지 전략입니다.
- 우선순위 지원이 내장된 드라이버의 경우
Priority 필드를 액셀러레이터에 직접 전파합니다.
- 실행이 액셀러레이터에 도달하기 전이더라도 서로 다른 우선순위를 지원하도록 앱별 우선순위 큐를 사용합니다.
실행 중인 우선순위가 낮은 모델을 일시중지 또는 취소하여 액셀러레이터가 우선순위가 높은 모델을 자유롭게 실행할 수 있도록 합니다. 이렇게 하는 방법은 우선순위가 낮은 모델에 체크포인트를 삽입하여 도달 시 그 모델이 플래그를 쿼리하여 현재 실행을 사전에 중지해야 하는지 결정하거나, 모델을 하위 모델로 나누고 하위 모델과 실행 간의 플래그를 쿼리함으로써 가능합니다. 참고로, 우선순위를 지정하여 준비된 모델에 체크포인트 또는 하위 모델을 사용하면 추가 오버헤드가 발생할 수 있습니다. 이러한 오버헤드는 우선순위가 없고 NN HAL 1.3보다 낮은 버전의 모델에서는 발생하지 않습니다.
- 선점을 지원하려면 실행할 다음 작업이나 하위 모델, 관련된 중간 피연산자 데이터 같은 실행 컨텍스트를 보존해야 합니다. 이 같은 실행 컨텍스트를 사용하여 나중에 실행을 다시 시작할 수 있습니다.
- 전체 선점 지원은 필요하지 않으므로 실행 컨텍스트를 보존할 필요는 없습니다. NNAPI 모델 실행은 확정적이므로 나중에 처음부터 실행을 다시 시작할 수 있습니다.
Android에서는 서비스가 AID(Android UID)를 사용하여 서로 다른 통화 앱을 구분할 수 있습니다. HIDL에는 메서드 ::android::hardware::IPCThreadState::getCallingUid를 통해 통화 앱의 UID를 가져올 수 있는 메커니즘이 내장되어 있습니다. AID 목록은 libcutils/include/cutils/android_filesystem_config.h에서 확인할 수 있습니다.
기한
Android 11부터 OptionalTimePoint 기한 인수로 모델 준비와 실행을 시작할 수 있습니다. 작업 소요 시간을 예측할 수 있는 드라이버는 이러한 기한을 통해 기한 전에 작업을 완료할 수 없다고 예상하면 작업 시작 전에 작업을 취소할 수 있습니다. 마찬가지로, 기한을 통해 드라이버는 진행 중인 작업 중에서 기한 전에 완료되지 않을 것으로 예상하는 작업을 취소할 수 있습니다.
기한 인수는 작업이 기한까지 완료되지 않거나 기한이 지나더라도 드라이버에 작업 취소를 강제하지 않습니다. 기한 인수를 사용하면 드라이버 내의 컴퓨팅 리소스를 확보할 수 있고 기한이 지정되지 않았을 때 가능한 속도보다 더 빨리 앱에 제어권을 반환할 수 있습니다.
OptionalTimePoint 기한을 인수로 포함하는 NN HAL 1.3 호출은 다음과 같습니다.
IDevice::prepareModel_1_3IDevice::prepareModelFromCache_1_3IPreparedModel::execute_1_3IPreparedModel::executeSynchronously_1_3IPreparedModel::executeFenced
위의 각 메서드에 관한 기한 기능 참조 구현은 frameworks/ml/nn/driver/sample/SampleDriver.cpp의 NNAPI 샘플 드라이버를 참고하세요.
오류 코드
Android 11에는 오류 보고 개선을 위해 NN HAL 1.3의 4가지 오류 코드 값이 포함되어 있습니다. 이러한 값을 통해 드라이버는 보다 정확하게 상태를 전달할 수 있고 앱은 더욱 안정적으로 복구될 수 있습니다. 다음은 ErrorStatus의 오류 코드 값입니다.
MISSED_DEADLINE_TRANSIENTMISSED_DEADLINE_PERSISTENTRESOURCE_EXHAUSTED_TRANSIENTRESOURCE_EXHAUSTED_PERSISTENT
Android 10 이하에서 드라이버는 GENERAL_FAILURE 오류 코드를 통해서만 오류를 나타낼 수 있었습니다. Android 11부터는 기한에 도달했거나 드라이버가 워크로드를 기한까지 완료하지 못한다고 예상했기 때문에 워크로드가 취소되었음을 나타내는 두 가지 MISSED_DEADLINE 오류 코드를 사용할 수 있습니다. 두 가지 RESOURCE_EXHAUSTED 오류 코드는 호출에 필요한 메모리가 드라이버에 부족한 경우 등 드라이버의 리소스 제한으로 인해 작업이 실패했음을 나타내는 데 사용할 수 있습니다.
두 오류의 TRANSIENT 버전은 문제가 일시적이며 잠시 지연이 있은 후 향후의 같은 작업 호출이 성공할 수 있음을 나타냅니다. 예를 들어 이 오류 코드는 드라이버가 오래 실행되거나 리소스 소모가 많은 이전 작업으로 바쁘기는 하지만 드라이버가 이전 작업으로 바쁘지 않으면 새 작업이 성공적으로 완료될 수 있는 경우에 반환됩니다. 두 오류의 PERSISTENT 버전은 향후의 동일한 작업 호출이 예외 없이 실패할 것으로 예상됨을 나타냅니다. 예를 들어 이 오류 코드는 완벽한 조건에서도 기한까지 작업이 완료되지 않을 것으로 드라이버가 예상하거나 본질적으로 모델이 너무 커서 드라이버 리소스를 초과하는 경우에 반환됩니다.
유효성 검사
서비스 품질 기능은 NNAPI VTS 테스트(VtsHalNeuralnetworksV1_3Target)에서 테스트됩니다. 이 기능에는 드라이버가 잘못된 우선순위를 거부하도록 하는 일련의 유효성 검사 테스트(TestGenerated/ValidationTest#Test/ )와 드라이버가 기한을 올바로 처리하도록 하는 DeadlineTest(TestGenerated/DeadlineTest#Test/)라는 일련의 테스트가 포함되어 있습니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-27(UTC)"],[],[],null,["# Quality of service\n\n| **Deprecated:** Starting in Android 15, the\n| [NNAPI (NDK API)](https://developer.android.com/ndk/guides/neuralnetworks) is deprecated. The Neural Networks HAL interface\n| continues to be supported.\n|\n| For more information, see the\n| [NNAPI Migration Guide](https://developer.android.com/ndk/guides/neuralnetworks/migration-guide).\n\nStarting from Android 11, the NNAPI offers better\nquality of service (QoS) by allowing an app to indicate the relative priorities\nof its models, the maximum amount of time expected for a given model to be\nprepared, and the maximum amount of time expected for a given execution to be\ncompleted. Further, Android 11 introduces\nadditional NNAPI error values enabling a service to more accurately indicate\nwhat went wrong when a failure occurs so that the client app can better react\nand recover.\n\nPriority\n--------\n\nFor Android 11 or higher, models are prepared with a\npriority in the NN HAL 1.3. This priority is relative to other prepared models\nowned by the same app. Higher-priority executions can use more compute resources\nthan lower-priority executions, and can preempt or starve lower-priority\nexecutions.\n\nThe NN HAL 1.3 call that includes `Priority` as an explicit argument is\n[`IDevice::prepareModel_1_3`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/neuralnetworks/1.3/IDevice.hal;l=199).\nNote that\n[`IDevice::prepareModelFromCache_1_3`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/neuralnetworks/1.3/IDevice.hal;l=294)\nimplicitly includes `Priority` in the cache arguments.\n\nThere are many possible strategies for supporting priorities depending on the\ncapabilities of the driver and accelerator. Here are several strategies:\n\n- For drivers that have built-in priority support, directly propagate the `Priority` field to the accelerator.\n- Use a per-app priority queue to support different priorities even before an execution reaches the accelerator.\n- Pause or cancel low-priority models that are being executed to\n free the accelerator to execute high-priority models. Do this by either\n inserting *checkpoints* in low-priority models that, when reached, query\n a flag to determine whether the current execution should be halted\n prematurely or by partitioning the model into *submodels* and querying the\n flag between submodel executions. Note that the use of checkpoints or\n submodels in models prepared with a priority can introduce additional\n overhead that isn't present for models without a priority in versions\n lower than NN HAL 1.3.\n\n - To support preemption, preserve the execution context including the next operation or sub-model to be executed and any relevant intermediate operand data. Use this execution context to resume the execution at a later time.\n - Full preemption support isn't necessary, so the execution context doesn't need to be preserved. Because NNAPI model executions are deterministic, executions can be restarted from scratch at a later time.\n\nAndroid enables services to differentiate between different calling apps through\nthe use of an AID (Android UID). HIDL has built-in mechanisms to retrieve the\ncalling app's UID through the method\n`::android::hardware::IPCThreadState::getCallingUid`. A list of AIDs can be\nfound in\n[`libcutils/include/cutils/android_filesystem_config.h`](https://android.googlesource.com/platform/system/core/+/android16-release/libcutils/include/cutils/android_filesystem_config.h).\n\nDeadlines\n---------\n\nStarting from Android 11, model preparation and\nexecutions can be launched with an `OptionalTimePoint` deadline argument. For\ndrivers that can estimate how long a task takes, this deadline allows the driver\nto abort the task before it starts if the driver estimates that the task can't\nbe completed before the deadline. Similarly, the deadline allows the driver to\nabort an ongoing task that it estimates won't be completed before the deadline.\nThe deadline argument doesn't force a driver to abort a task if the task isn't\ncomplete by the deadline or if the deadline has passed. The deadline argument\ncan be used to free up compute resources within the driver and return control\nto the app faster than is possible without the deadline.\n\nThe NN HAL 1.3 calls that include `OptionalTimePoint` deadlines as an argument\nare:\n\n- `IDevice::prepareModel_1_3`\n- `IDevice::prepareModelFromCache_1_3`\n- `IPreparedModel::execute_1_3`\n- `IPreparedModel::executeSynchronously_1_3`\n- `IPreparedModel::executeFenced`\n\nTo see a reference implementation of the deadline feature for each of the above\nmethods, see the NNAPI sample driver at\n[`frameworks/ml/nn/driver/sample/SampleDriver.cpp`](https://cs.android.com/android/platform/superproject/+/android-latest-release:packages/modules/NeuralNetworks/driver/sample_hidl/SampleDriver.cpp?q=SampleDriver.cpp).\n\nError codes\n-----------\n\nAndroid 11 includes four error code values in\nNN HAL 1.3 to improve error reporting, allowing drivers to better communicate\ntheir state and apps to recover more gracefully. These are the error code\nvalues in `ErrorStatus`.\n\n- `MISSED_DEADLINE_TRANSIENT`\n- `MISSED_DEADLINE_PERSISTENT`\n- `RESOURCE_EXHAUSTED_TRANSIENT`\n- `RESOURCE_EXHAUSTED_PERSISTENT`\n\nIn Android 10 or lower, a driver could only indicate a failure through the\n`GENERAL_FAILURE` error code. From Android 11, the\ntwo `MISSED_DEADLINE` error codes can be used to indicate that the workload was\naborted because the deadline was reached or because the driver predicted the\nworkload wouldn't complete by the deadline. The two `RESOURCE_EXHAUSTED` error\ncodes can be used to indicate that the task failed because of a resource\nlimitation within the driver, such as the driver not having enough memory for\nthe call.\n\nThe `TRANSIENT` version of both errors indicates that the problem is temporary,\nand that future calls to the same task might succeed after a short delay. For\nexample, this error code should be returned when the driver is busy with prior\nlong-running or resource-intensive work, but that the new task would complete\nsuccessfully if the driver wasn't busy with the prior work. The `PERSISTENT`\nversion of both errors indicates that future calls to the same task are always\nexpected to fail. For example, this error code should be returned when the\ndriver estimates the task wouldn't complete by the deadline even under perfect\nconditions, or that the model is inherently too large and exceeds the driver's\nresources.\n\nValidation\n----------\n\nThe quality of service functionality is tested in the NNAPI VTS tests\n(`VtsHalNeuralnetworksV1_3Target`). This includes a set of tests for validation\n(`TestGenerated/ValidationTest#Test/`) to ensure that the driver rejects invalid\npriorities and a set of tests called `DeadlineTest`\n(`TestGenerated/DeadlineTest#Test/`) to ensure that the driver handles deadlines\ncorrectly."]]
