Справочник платформы по руководству Rockchip RKNN2 SDK V2.5.0. Рассматриваются только перечисленные в исходном документе SoC, Linux/Android Runtime и Toolkit. Возможности действуют при указанных в каждом разделе условиях для чипа, SDK, драйвера и ядра и не означают поддержку всех плат ArmSoM. Перед развёртыванием проверьте BSP, драйвер NPU, Runtime и версию модели конкретной платы. Проверка на оборудовании ArmSoM не проводилась; журналы, показатели и примеры взяты из оригинала.
Источники и вычитка: китайская версия следует китайскому V2.5.0 (182 страницы), английская, русская и немецкая — английскому V2.5.0 (208 страниц). Различия оригиналов сохранены; сведения старой версии не выдаются за новые. Китайские рисунки взяты из китайского PDF, остальные — из английского, включая отдельно извлечённые векторные схемы. Номера разделов и формул сохранены. Некоторые ссылки используют старую нумерацию; примеры динамической формы содержат «1224+140=264», утверждения о TP_NORM противоречат друг другу, а init()/rknn.val_perf() отличаются от последующих описаний API. Эти сомнения сохранены: перед выполнением проверьте реальные заголовки и справочник V2.5.0. Код и параметры сохранены, разрывы PDF и продолжения таблиц восстановлены.
RKNN2 SDK V2.5.0 · 19/22
1. Программный стек и основные понятия
2. Среда разработки, версии и подключение платы
3. Процесс разработки и выбор интерфейса
4. Преобразование моделей и редактирование ONNX
5. Квантование, гибридное квантование и QAT
6. Инференс, оценка точности, производительности и памяти
7. Жизненный цикл Runtime, размещение данных и память
8. Нулевое копирование и ограничения входов/выходов
9. Развёртывание через C API и генерация кода
10. Развёртывание Python через Toolkit Lite2
11. Matmul API и размещение матриц
12. Многоядерная настройка NPU и производительность
13. Модели с динамической формой и развёртывание
16. Согласованность кэша и разреженный инференс
17. Пользовательские операторы: Python и C API
18. Развёртывание зашифрованных моделей
Диагностика точности
20. Анализ производительности и оптимизация сети
21. Анализ, совместное использование и повторное использование памяти
22. Вопросы, обработка ошибок и справочные ресурсы
5. Устранение неполадок и оптимизация
5.1 Диагностика точности
Проблемы точности модели обычно исследуют с двух сторон: точность симулятора и точность Runtime на плате. Правильные результаты симулятора — необходимое условие правильного вывода Runtime на плате. Поэтому сначала следует убедиться в правильности симуляции, а затем искать проблемы Runtime. Общий порядок: «точность FP16 симулятора → точность квантования симулятора → точность при подключении платы → точность Runtime». Корректность каждого предыдущего этапа необходима для проверки следующего.
В этой главе приведены рекомендации и решения для проверки точности симулятора и Runtime. Конкретные шаги показаны на следующем рисунке:
Рисунок 5-1. Этапы анализа точности
Проверка точности симулятора состоит из двух этапов: проверка FP16 и проверка квантования (тёмные блоки на рисунке выше).
Проверка точности Runtime состоит из проверки с подключённой платой и проверки Runtime (светлые блоки на рисунке выше).
Косинусное расстояние можно использовать как основной критерий точности, однако окончательное влияние квантования необходимо проверять на наборе данных.
5.1.1 Проверка точности симулятора
Правильный инференс симулятора — условие правильной работы на плате; поэтому в первую очередь нужно проверить симулятор.
В RKNN-Toolkit2 симулятор выполняет FP16-вывод или квантованный вывод в зависимости от квантования модели. Правильные результаты FP16 необходимы для правильного квантованного вывода. Поэтому при проблемах квантованной модели сначала проверьте FP16, а затем исследуйте квантование.
5.1.1.1 Точность FP16 в симуляторе
RKNPU сейчас не поддерживает вычисления FP32, поэтому без квантования симулятор использует FP16. Чтобы преобразовать исходную модель в FP16 RKNN, вызовите rknn.build() с do_quantization = False. Затем выполните rknn.init_runtime(target=None) и rknn.inference() для симуляции FP16 и получения результатов.
При неверной выходной информации FP16 выполните следующие проверки:
Ошибка конфигурации
Основные настройки модели сосредоточены в rknn.config(), но на точность FP16 могут влиять и отдельные параметры других API. Главные параметры:
mean_values / std_values: параметры нормализации. В исходной модели нормализация обычно выполняется при предварительной обработке входа. В RKNN она может входить в сам инференс; при квантовании калибровочный набор сначала нормализуется. Если исходная модель использует нормализацию, эти параметры должны совпадать с её параметрами.
input_size_list: неверные формы входных узлов в rknn.load_tensorflow(), rknn.load_pytorch() или rknn.load_onnx() приводят к неверному инференсу.
inputs / outputs: неверные имена входных или выходных узлов в rknn.load_tensorflow() и rknn.load_onnx() приводят к неверному инференсу.
Параметры inference: основные входные параметры rknn.inference() — inputs и data_format.
В Python изображения обычно читают через cv2.imread(), который возвращает BGR. Если вход исходной модели — BGR (как у большинства моделей caffe), перестановка RGB не нужна. Если вход — RGB, выполните cv2.cvtColor(img, cv2.COLOR_BGR2RGB). Изображение cv2.imread() 3-мерное, а большинство моделей ожидают 4 измерения, поэтому перед rknn.inference() добавьте измерение через np.expand_dims(img, 0). Раскладка cv2.imread() — NHWC, и data_format по умолчанию также NHWC, поэтому задавать data_format не требуется.
Если данные прочитаны не через cv2.imread(), определите их раскладку и правильно задайте data_format. Форма данных должна соответствовать исходной модели. Для изображений также должен совпадать порядок RGB.
Проверка параметров крайне важна: неверная конфигурация — частая причина неправильных результатов FP16. Порядок проверки:
a. Выполните вывод исходной модели в исходном фреймворке и сохраните результаты.
b. Преобразуйте исходную модель и выполните вывод через RKNN-Toolkit2. Используйте те же входные данные и режим FP16: do_quantization=False в rknn.build(). Установите target=None в rknn.init_runtime(), чтобы использовать симулятор RKNN-Toolkit2, и сохраните результаты.
c. Сравните результаты двух запусков. Если они достаточно близки (согласованность можно оценить косинусным расстоянием), указанные настройки корректны.
d. Если результаты расходятся, проверьте правильность перечисленных параметров.
Если настройки верны, но результаты различаются, тензоры модели могут выходить за диапазон FP16.
Выход за диапазон FP16
При переходе с FP32 на FP16 промежуточные тензоры могут переполняться. Обычно модель использует FP32; значения вне диапазона FP16 (-65504～65504) вызывают переполнение и аномальные результаты.
Для проверки переполнения используйте rknn.accuracy_analysis(…, target=None), см. анализ точности модели. Аномальные значения, например ‘inf’, в колонках entire или single группы simulator_error могут означать переполнение FP16. Попробуйте изменить структуру, например добавить BN-слои, чтобы все тензоры укладывались в FP16.
Если настройки верны, переполнения FP16 нет, но результаты различаются, возможна ошибка реализации симулятора. Передайте воспроизводимый пример модели команде Rockchip NPU для анализа и исправления.
5.1.1.2 Точность квантования в симуляторе
Исключив проблемы FP16, квантируйте модель: do_quantization=True в rknn.build(). Затем вызовите rknn.accuracy_analysis(…, target=None) для анализа точности квантования в симуляторе; см. «Анализ точности модели».
Если в результатах точность столбца entire группы simulator_error заметно снизилась, но в столбце single этой группы нет слоя с особенно большим падением, проверьте следующие аспекты:
Ошибки конфигурации
Как и при FP16, неправильная конфигурация может нарушать точность квантованного вывода. После проверки FP16 дополнительно проверьте следующие параметры квантования.
quant_img_RGB2BGR: определяет преобразование RGB2BGR при загрузке изображений калибровки; обычно используется для caffe. Подробнее см. описание quant_img_RGB2BGR. Параметр должен соответствовать порядку каналов обучающих изображений; ошибка может существенно снизить точность.
optimization_level: выбор уровня оптимизации. По умолчанию 3 — приоритет скорости; включаются правила, улучшающие производительность с небольшим влиянием на точность. Уменьшение значения, например до 0, отключает эти правила.
dataset: набор калибровочных данных rknn.build(), используемый для вычисления scale / zero_point каждого тензора при квантовании. Значительное отличие набора от реального сценария применения может снизить точность. Слишком много или слишком мало изображений также влияет на результат; обычно выбирают 20~200.
Для проверки параметров квантования обычно выполняют следующие шаги:
a. Выполните квантованный вывод и сравните его результаты с выводом исходной модели в исходном фреймворке. Если различия невелики, quant_img_RGB2BGR и dataset можно считать в основном корректными.
b. Если различия всё ещё заметны:
Если исходная модель принимает BGR (часто у caffe), установите quant_img_RGB2BGR=True. Порядок RGB входа можно определить по коду обработки входных данных, использованному при предыдущей проверке FP16.
Сначала квантируйте по одному изображению, оставив одну строку в dataset.txt, и используйте это же изображение для вывода. Если точность заметно улучшится, прежний калибровочный набор был выбран неудачно: подберите изображения, лучше соответствующие применению. Если улучшения нет, причина может быть не в наборе.
Если первоначально использовалось одно изображение, то есть одна строка dataset.txt, увеличьте количество калибровочных изображений примерно до 20~200.
После этих проверок квантованные результаты не должны быть полностью неверными. Если это всё же происходит, перепроверьте конфигурацию. Если настройки верны, но точности недостаточно, попробуйте изменить метод и алгоритм квантования.
Методы и алгоритмы квантования
Некоторые модели плохо подходят для квантования. Попробуйте другие методы и алгоритмы. Основные методы: layer, channel и group; group действует только для линейных слоёв, см. 2.2.1.3 «Гранулярность квантования». Метод задаётся quantized_method в rknn.config(), по умолчанию channel. Основные алгоритмы: normal, kl_divergence, mmse и gdq, см. 2.2.3.2 «Внутренние алгоритмы квантования». Алгоритм задаётся quantized_algorithm в rknn.config(), по умолчанию normal. Порядок действий:
a. Если использовался layer, переключитесь на channel. Обычно точность channel значительно выше, чем layer.
b. Если уже выбран channel, но точности недостаточно, замените normal на kl_divergence или mmse. Квантование займёт значительно больше времени, но точность будет выше, а производительность Runtime не изменится.
Свойства алгоритмов и рекомендуемый объём калибровочных данных приведены ниже:
| Алгоритм квантования | Свойства | Рекомендуемый объём калибровочных данных |
|---|---|---|
| normal (по умолчанию) | Обычная быстрая калибровка | 20~100 изображений |
| kl_divergence | Хороший эффект при неравномерном распределении признаков; немного медленнее normal | 20~100 изображений |
| mmse | Итеративно ищет диапазон квантования; обычно точнее, но существенно увеличивает время и память | 20~50 изображений |
| gdq | Действует только для w4a16 и w8a16; эффективно повышает точность квантования весов | Более 200 изображений |
Рекомендуется начинать с normal; при недостаточной точности пробовать kl_divergence, mmse или gdq. Алгоритм влияет только на преобразование модели, а не на скорость её выполнения на плате.
Если после этих мер точность entire в simulator_error всё ещё низкая, а некоторые слои в single показывают значительное падение, возможна неудачная структура распределения весов этих слоёв. Например, при сильно неравномерных весах Conv попробуйте гибридное квантование. Шаги:
a. Проанализируйте точность, найдите слои с большим падением и запишите имена их выходных тензоров. Ошибки накапливаются от слоя к слою; чем раньше слой, тем сильнее его влияние на итог. Учитывайте не только потерю в single группы simulator_error, но и положение слоя в модели.
b. Внесите найденные имена тензоров в конфигурационный файл гибридного квантования; см. «Гибридное квантование».
c. Завершите гибридное квантование и проверьте точность. Для наблюдения изменений можно продолжать использовать интерфейс анализа точности.
Обычно гибридное квантование повышает точность. Если улучшения недостаточно, примените его к большему числу слоёв, учитывая снижение скорости вывода: нужен компромисс между точностью и скоростью. Если проблемный Op находится в последнем слое, его выполнение можно перенести в постобработку, что также позволяет избежать потери точности этого слоя.
QAT (обучение с учётом квантования):
Если после гибридного квантования точности недостаточно или она достаточна, но скорость не удовлетворяет требованиям, попробуйте переобучить модель с учётом квантования и экспортировать её с параметрами квантования, например в onnx/pt/pb/tflite. Подробнее см. «Обучение с учётом квантования (QAT)».
5.1.2 Проверка точности среды выполнения
Даже при корректном симуляторе развёртывание C API на плате может давать неверные результаты. Обычно причин три: ошибка runtime платы, неправильное использование RKNPU2 C API или неверная пред-/постобработка модели.
Сначала используйте режим с подключённой платой, чтобы быстро проверить возможную ошибку runtime. Если он работает правильно, проверяйте развёртывание C API.
5.1.2.1 Точность при подключённой плате
1 Настройте среду отладки с платой, как описано в настройке среды NPU, подключите плату к ПК через USB и выполните инференс RKNN-Toolkit2 с target в rknn.init_runtime(), например target=’rk3566’. Проверьте примерную корректность результата: симулятор не полностью воспроизводит NPU, поэтому абсолютного совпадения может не быть.
2 Значительное отличие от симулятора предварительно указывает на ошибку runtime платы. Выполните анализ точности с подключённой платой: rknn.accuracy_analysis() с target, например target=’rk3566’; см. анализ точности модели. После завершения будут выведены результаты каждого слоя.
- Проверьте столбец single_sim группы runtime_error. Если cos мало или euc велико (жёлтый либо красный цвет) и это приводит к увеличению различия между entire в runtime_error и entire в simulator_error, возможно, Runtime теряет точность или некорректно реализует этот слой. Передайте результаты анализа и воспроизводящую модель команде Rockchip NPU для исправления.
5.1.2.2 Точность runtime
Если точность с подключённой платой верна, но приложение всё ещё даёт неверные результаты, причина может быть в пользовательском C/C++-коде вызовов RKNN C API. Проверьте настройки интерфейса, предобработку и постобработку: они должны полностью совпадать с симулятором. Выполните следующие шаги:
1 Проверить настройки и данные входа
Проверьте вход C API. Если при преобразовании модели RKNN-Toolkit2 уже настроены среднее и дисперсия, нормализация в C/C++ не нужна. Для трёхканального входа порядок каналов должен совпадать с обучением; для 4D задайте fmt=NHWC, для остальных размерностей fmt=UNDEFINED. В обычном API размер буфера равен числу элементов входного тензора * числу байтов элемента. Для zero-copy размер памяти и формат данных rknn_create_mem описаны в 3.1.6 «Интерфейс zero-copy RKNN Runtime».
После проверки настроек проверьте данные входного слоя. Установите RKNN_LOG_LEVEL=5 перед запуском приложения. Послойные результаты вывода сохранятся в numpy-файлы в /data/dumps для Android или /userdata/dumps для Linux. Найдите файл с InputOperator и проверьте данные. В обычном API это результат нормализации входа, в zero-copy — данные до нормализации.
2 Проверить настройки и данные выхода
Проверив вход, проверьте настройки выхода. В обычном API want_float=1 выдаёт float32; want_float=0 выдаёт квантованный тип или float16 для неквантованных данных. Для zero-copy размер памяти и формат данных rknn_create_mem() описаны в 3.1.6 «Интерфейс zero-copy RKNN Runtime».
Для проверки выхода откройте сгенерированный numpy-файл с OutputOperator. Если вход точно верен, а выход неверен, Runtime может неправильно обрабатывать определённые типы ввода/вывода. Передайте анализ и воспроизводящую модель команде Rockchip NPU.