В настоящем руководстве пользователя могут быть приведены названия и программные продукты, которые содержат в себе зарегистрированные товарные знаки своих владельцев.

Руководство пользователя содержит полную и исчерпывающую информацию для корректной работы с программным обеспечением AMLT (далее по тексту – ПО) производства компании АО «Софит».
Программное обеспечение AMLT предназначено для обеспечения работы ускорителя нейронных сетей разработанного компанией АО «Софит».
Перед началом работы с программным обеспечением AMLT рекомендуется ознакомится с руководством пользователя.
При возникновении вопросов или неисправностей, убедитесь в отсутствии описания вопроса в руководстве, если пользовательская документация не помогла в решении проблемы, то обратитесь за помощью в «Центр поддержки пользователей» компании АО «Софит».

1  Общие сведения
Программное обеспечение AMLT предназначено для работы с ускорителями I100CPP и I105CPP, а также центральными процессорами с архитектурой x86 и ARM. Одна из ключевых задач, возникающая при внедрении искусственного интеллекта, является вывод (inference) нейросети, которая состоит в том, чтобы для входных данных пользователя в нейросеть получить результирующую выборку (ответ). Далее уже результаты вывода могут быть использованы в конечном пользовательском сценарии. Для решения задачи вывода нейросети нами предлагается специализированный аппаратный ускоритель и программное обеспечение AMLT, обеспечивающие высокую производительность и минимальные временные затраты на уровне современных иностранных решений.

1.1 Основные компоненты
Основные архитектурные компоненты программного обеспечения выделяются в следующие группы:

OpenVino™ Runtime – набор библиотек, предоставляющие интерфейсы для вывода (Inference) нейросетей на различных вычислительных устройствах. Средствами реализованных плагинов, включается в состав программного обеспечения AMLT. OpenVINO™ предоставляет нативную поддержку широкого спектра модельных фреймворков и форматов моделей (PyTorch, TensorFlow, ONNXи тд.)
IASIC Plug-in – представляет собой расширение функциональности OpenVINO™ для поддержки вывода данных (Inference) на устройстве. Компонент содержит в себе узкоспециализированные оптимизации (тензорный компилятор), позволяющие добиться максимальнойпроизводительности вывода нейросетей на ускорителях  I100CPP и I105CPP, а также на центральны процессорах с архитектурой x86 и ARM.
IASIC driver – компонент отвечает за выполнение вывода данных (Inference) в соответствии с настройками переданными из IASIC Plug-in, и обеспечивает многопользовательский режим работы, а также управляет устройством.
IASIC profiler – компонент, представляет собой инструмент командной строки для сбора и анализа производительности и профилировочных данных с ускорителя и хост-системы, на которую установлено устройство. Основной фокус на утилизацию устройства и производительность (GFLOP/s).


1.2 Принцип работы программного обеспечения
Программное обеспечение AMLT – набор компонентов, которые обеспечивают работу ускорителей и помогают им выполнять работу алгоритмов нейронных сетей на них.
Благодаря архитектурным и программным решениям AMLT помогает ускорить работу серверных систем, выполняя сложные математические вычисления.
Принцип работы программного обеспечения состоит из нескольких этапов:
1.  Конвертация модели в поддерживаемый формат;
2.  Подготовка программы для исполнения на карте расширения;
3.  Запуск процедуры исполнения.
Состояние программного обеспечения и ускорителя можно запросить через терминал. После того как ускоритель (количество зависит от задач пользователя) установлен на сервер, а программное обеспечение установлено на стороне хоста и его работоспособность проверена, пользователь может начинать работу через доступные интерфейсы интеграции с PyTorch или библиотеками OpenVINO™.
Для написания собственных программ по работе с библиотеками OpenVINO™ пользователь может использовать любой удобный ему текстовый редактор.

1.3 Основные функции ПО
Программное обеспечение AMLT поддерживает следующие функциональные характеристики:

·      Подготовка входных данных, включая конвертацию всех необходимых форматов;
·      снятия метрик работы ускорителя, таких как температура, загруженность основных вычислительных блоков и доступный объём оперативной памяти;
·      поддержка форматов моделей ONNX;
·      исполнение программы на устройстве и контроль результатов;
·      поддержка программной платформы PyTorch;


1.4 Уровень подготовки пользователей
До работы с программным обеспечение AMLT допускаются специалисты в области инженерии, системные администраторы и IT-специалисты, имеющие опыт работы с картами расширения, микросхемами и их программным обеспечением.
Специалисты, которые будут непосредственно допущены к эксплуатации программного обеспечения AMLT должны быть ознакомлены с пользовательской документацией на программное обеспечение и с эксплуатационной документацией на изделие, где оно применяется.

Примечание – пользователями данного программного обеспечения являются специалисты Data Science и системные администраторы.

2    Системные требования
2.1 Рекомендуемая конфигурация хоста

 
2.2 Программные требования

Операционная система:
AstraLinux версии 1.7.7 или выше.
Platform V SberLinux OS Server версии 9.6.2 и выше.

Ядро Linux:
версия 5.15 и выше.

Для корректной работы необходимо установить Python версии 3.8 или выше.

3    Установка программного обеспечения
3.1 Общие рекомендации BIOS/UEFI
Корректная работа ускорителя и программного обеспечения AMLT напрямую зависит от правильной конфигурации PCIe в BIOS/UEFI. Ниже приведены рекомендуемые параметры и пояснения.

BIOS/UEFI Обновление:
Используйте последнюю стабильную версию BIOS/UEFI, совместимую с вашей материнской платой или серверной платформой.

Сохранение Настроек:
После внесения изменений обязательно сохраните настройки (F10 → Save & Exit) и перезагрузите систему.

Названия Опций:
Названия опций могут отличаться в зависимости от производителя (Dell, ASUS, Supermicro и т.д.) и UEFI-стека (AMI, Insyde). См. документацию к платформе для точной информации.

Названия Опций:
Названия опций могут отличаться в зависимости от производителя (Dell, ASUS, Supermicro и т.д.) и UEFI-стека (AMI, Insyde). См. документацию к платформе для точной информации.

Таблица 1 – Настройка основных параметров

3.2 Установка основных компонентов
3.2.1 Настройка параметров ядра
Для корректной работы программного обеспечения AMLT и ускорителя необходимо добавить обязательные параметры загрузки, изменив файл /etc/default/grub или выполнив команды представленные ниже.

SberLinux/Astra Linux:

Перезагрузите систему после выполнения этих шагов.

Примечание - Команда изменяет названия сетевых интерфейсов, что может привести к недоступности сервера по сети.

3.2.2 Установка пакетов
Убедитесь, что пакеты находятся в директории /home/testuser/asic_install.
Все последующие действия выполняются внутри этой директории.

SberLinux/Astra Linux:

Перезагрузите систему после выполнения этих шагов.

Примечание - Команда изменяет названия сетевых интерфейсов, что может привести к недоступности сервера по сети.

3.2.2 Установка пакетов
Убедитесь, что пакеты находятся в директории /home/testuser/asic_install.
Все последующие действия выполняются внутри этой директории.

SberLinux/Astra Linux:

3.2.3 Настройка группы video
Настройка группы video предназначена для оптимизации работы ускорителя для обработки видео. Эта группа позволяет настраивать различные параметры, связанные с производительностью, ресурсами и функциональностью видео.

Для настройки необходимо сделать следующее:

После этого выполните команду newgrp video или войдите в систему заново.

3.2.4 Загрузка драйверов
Установка драйверов для ускорителя необходима для обеспечения правильной работы и взаимодействия между программным обеспечением и аппаратным ускорителем.
Для установки драйверов программного обеспечения AMLT воспользуйтесь следующими командами:

3.2.5 Настройка udev и запуск сервиса minervad

Настройка udev позволяет автоматически конфигурировать ускорители при их подключении к системе. Сервис minervad используется для управления и мониторинга ускорителей или процессов, запущенных на них.
Ниже описаны шаги по настройке udev и запуску сервиса minervad.

3.2.6 Проверка установки
После установки программного обеспечения AMLT, проверьте правильность установки следующим способом:

Ожидаемый результат:
active
группа: video, права: crw-rw----
группа: video, права: rw-rw----
journalctl -u minerva.service -n 20 --no-pager

3.3 Удаление пакетов и очистка системы
Полное удаление драйверов AMLT и сопутствующих компонентов требует строгой последовательности действий, чтобы избежать следующих проблем:

• Остаточных файлов, мешающих новой установке. 
• «Зависших» модулей ядра. 
• Конфликтов с udev и systemd. 
• Утечек ресурсов безопасности (SELinux, AppArmor).

 
3.3.1 Предварительные условия
Перед удалением обязательно остановите и выключите сервис, выгрузите драйвера, отключите автозагрузку.
1.    Остановка и отключение сервиса.

2.    Выгрузка драйверов.

3.    Отключение автозагрузки
Для того, чтобы модули не загружались автоматически (через /etc/modules-load.d/ или DKMS), создайте файл блокировки:

blacklist — предотвращает загрузку по зависимостям.
install … /bin/true — гарантирует, что даже прямой вызов modprobe hdma ничего не сделает.

4    Работа с программным обеспечением
4.1 Запуск программного обеспечения
4.1.1 Основные этапы вывода нейросети.
При организации вывода нейросети можно выделить 2 этапа и 3 группы компонентов, которые можно разнести на разные вычислительные узлы.
Этап 1. Подготовки сети. 
Группа компонентов для компиляции: получение нейросети  в формате пользователя и компиляция ее в код для устройства и, опционально, дополнительные структуры для гетерогенного исполнения. Этот этап выполняется однократно для нейросети  и может быть выполнен заблаговременно. Результатом является последовательный набор инструкций (программа) для исполнения на ускорителе. Далее этот код может быть загружен на устройство.
Этап 2. Исполнения сети.
Группа компонентов фронтенд-рантайма: получение скомпилированной нейросети  (с весами) и данных, отправка для исполнения на устройстве через RPC на бэкенд-рантайм, и, опционально, на CPU для гетерогенного исполнения посредством OpenVINO™.
Группа компонентов Бэкенд-рантайма: получение данных в бэкенд-рантайме и исполнение на устройстве вывода нейросети.

4.1.2 Основные пользовательские пути 
Развернутый программный продукт в динамической инфраструктуре позволяет конечному пользователю выполнить вывод нейросети одним из ниже представленных способов.
Сценарий 1: использование через PyTorch. Программный продукт интегрируется с PyTorch. Пользователь работая с сетью в PyTorch при помощи интерфейсов OpenVINO™ вызывает вывод. 
Сценарий 2: прямое использование через OpenVINO™. Пользователь интегрирует OpenVINO™ в свой продукт и далее модель в формате ONNX/TF/paddle paddle - подается на вход OpenVINO™ API. Средствами API OpenVINO™ осуществляется вывод нейросети.
Поддерживается возможность сохранения результатов.
Сценарий 3: Раздельная компиляция и исполнение с использованием OpenVINO™

• Пользователь загружает модель через интерфейсы OpenVINO™, запускает процесс компиляции и далее средствами OpenVINO™ делает экспорт скомпилированной модели в файл на жесткий диск.
• Пользователь загружает ранее скомпилированный и экспортированный файл и после этого вызывает интерфейсы OpenVINO™ для выполнения вывода (Inference).
• Для полученного файла выполняется вывод без повторного вызова компилятора.

Примечание - номер версии может отличаться от представленного в настоящем руководстве. Номер версии в настоящем документе представлен для примера.
Номер версий у пользователя должен соответствовать последнему релизу.

4.2 Интеграция с приложением PyTorch
Программное обеспечение AMLT поддерживает PyTorch с помощью функциональности torch.compile.

4.2.1 Установка и проверка
Установите пакет, используя следующие команды:

Убедитесь, что связка PyTorch и OpenVINO™ корректно работает, выполнив следующие команды:

При исполнении в списке доступных серверных компонентов должен присутствовать OpenVINO™.

Для компиляции нейронной сети с использованием функции torch.compile необходимо выполнить следующие шаги:

4.2.2 Запуск на устройстве
Для запуска нейронной сети на целевом устройстве с использованием сервисных компонентов OpenVINO™ через функцию torch.compile, необходимо указать соответствующее устройство в параметре-словаре options.

4.2.3 Применение пакета iasic_dynamo
Пакет iasic_dynamo предназначен для упрощенной интеграции нейронных сетей, разработанных с использованием PyTorch, с ИИ-ускорителем (IASIC). Он позволяет указывать ИИ-ускоритель (IASIC) в качестве имени torch.device и передавать параметры устройства непосредственно при вызове функции torch.compile.

Для проверки запустите следующие команды:

При исполнении в списке доступных серверных компонентов должно присутствовать IASIC.

Для запуска нейронной сети на устройстве с использованием сервисных компонентов ИИ-ускорителя необходимо указать его в качестве сервисного компонента и целевого устройства в параметре-словаре options при вызове функции torch.compile.

4.3 Рекомендации по использованию ПО
Программного обеспечение рекомендуется использовать предварительно ознакомившись с документацией, входящей в состав пакета ПО и согласно описанной в документации последовательности шагов для обеспечения корректной работы ИИ-ускорителя.
 
4.4 Пример обнаружения объектов
Данный пример демонстрирует использование моделей обнаружения объектов с встроенным non-maximum suppression (NMS) и показывает гетерогенное выполнение, при котором нейронная сеть работает на ускорителях, при помощи программного обеспечения AMLT.
При запуске приложение выполняет следующие действия:
1.    Считывает параметры командной строки.
2.    Подготавливает входные данные.
3.    Загружает указанную модель в плагин OpenVINO™ Runtime.
4.    Выполняет синхронный вывод.
5.    Обрабатывает выходные данные, регистрируя каждый шаг в стандартный поток вывода.
6.    Сохраняет изображение с результатами обнаружения в локальной папке.

4.4.1 Установка
Для успешной интеграции и использования модели с сервисным компонентом ИИ-ускоритель, необходимо выполнить следующие шаги установки и настройки окружения.
Шаг 1. Установка конкретной версии пакета OpenVINO™.
Установите конкретную версию пакета OpenVINO™, необходимую для работы с ускорителями:

Шаг 2. Установите AI ASIC plugin и убедитесь, что пакет OpenVINO™ находится в PYTHONPATH.

Ожидаемый результат:

Установите дополнительные зависимости с помощью следующей команды:

Шаг 3. Запуск обнаружения объектов.

Примечание – в зависимости от возможностей пользователя сеть и изображение могут различаться. Указанные ниже пути являются условными, а ожидаемый результат демонстрирует пример и является индивидуальным для каждой сети.

Введите следующую команду для обнаружения объектов на изображении:

Ожидаемый результат:

4.5 Пример классификации ImageNet
Данный пример демонстрирует несколько возможностей:
Преобразование модели PyTorch в формат ONNX.

• Запуск конвейера классификации изображений с использованием OpenVINO™.
• Описание порядка выполнения действий приложением.

При запуске приложение выполняет следующие действия:

Считывание параметров командной строки.
Приложение считывает параметры, переданные через командную строку, для настройки работы.

Подготовка входных данных.
Входные изображения подготавливаются для дальнейшей обработки моделью.

Загрузка модели и изображения в плагин OpenVINO™ Runtime.
Указанная модель в формате ONNX и изображение загружаются в плагин OpenVINO™ Runtime для выполнения вычислений на целевом устройстве.

Выполнение синхронного вывода.
Приложение выполняет синхронный вывод данных через загруженную модель.

Обработка выходных данных.
Выходные данные обрабатываются, и каждый шаг регистрируется в стандартный поток вывода.
Вы можете легко изменить код для работы с моделями классификации ImageNet:

• resnet50
• resnet152
• resnet34
• efficentNetb4
• swin-static и тд.

Шаг 1. Установка конкретной версии пакета OpenVINO™.
Установите конкретную версию пакета OpenVINO™, необходимую для работы с ускорителями:

Шаг 2. Установите AI ASIC plugin и убедитесь, что пакет OpenVINO™ находится в PYTHONPATH.

Ожидаемый результат:

Установите дополнительные зависимости с помощью следующей команды:

Шаг 3. Загрузка и преобразование моделей.

Введите следующую команду для загрузки и преобразования моделей:

Шаг 4. Запуск классификации.

Ожидаемый результат:

5    Обновление программного обеспечения

Для обновления программного продукта необходимо полностью удалить старую версию и установить новую.
Ознакомьтесь с инструкцией по удалению и установке ПО согласно п.3.3 и 3.2 настоящего документа.

6    Возможные неисправности в работе программного обеспечения
6.1 Устройство не определяется в lspci
- lspci -d 7752:0001 возвращает пустой результат. Устройство не отображается в BIOS/UEFI.

Возможные причины появления ошибки:

• Физическое отсутствие питания или плохой контакт в слоте.
• PCIe-слот отключён или работает в режиме x1/x4 вместо x16.
• Secure Boot блокирует инициализацию.
• BIOS не поддерживает Gen4 на данном слоте.

Диагностика:

Решение:
1.    Переподключить ускоритель.
2.    Проверьте BIOS:
- Убедитесь, что слот включён и работает в режиме x16 electrical.
- Отключите Secure Boot.
- Установите PCIe Link Speed = Gen4 или Auto.
3.    Проверьте блок питания — недостаток мощности может привести к отключению устройства.


6.2  «Operation not permitted» при загрузке модуля
modprobe: ERROR: could not insert 'minerva-iasic': Operation not permitted 
Возможные причины появления ошибки:

·    Secure Boot включён, а драйвер не подписан доверенным ключом.

Диагностика:

Решение:
Вариант 1 (рекомендуется): Отключите Secure Boot в BIOS.
Вариант 2: Подпишите модуль собственным ключом (MOK):

6.3 Сервис minervad.service не может открыть /dev/iasic и/или /run/minervad/socket.sock

·    В логах: Permission denied при открытии устройства.
·    ls -l /dev/iasic показывает: crw-rw—- 1 root root (группа не video).
 
Возможные причины появления ошибки:

·    udev- правило не применилось.
·    Пользователь/сервис не состоит в группе video.

Диагностика:

Решение:
1.    Убедитесь, что файл /etc/udev/rules.d/99-minerva.rules существует и содержит:
GROUP="video", MODE="0660"
2.    Перезагрузите правила:
sudo udevadm control --reload-rules && sudo udevadm trigger
3.     Добавьте пользователя сервиса в группу video.

6.4 Система «зависает» или перезагружается при загрузке драйвера
·    Kernel panic при выполнении modprobe hdma.
·    Система перезагружается без сообщений.

Возможные причины появления ошибки:
·    Несовместимость версии ядра и драйвера.
·    Конфликт с IOMMU.
·    Ошибки в DMA-буферах из-за недостатка памяти.

Диагностика:
·    Подключите serial-консоль или используйте IPMI/KVM.
·    Проверьте параметры ядра: убедитесь, что pci=realloc=off задан.

Решение:
1.    Загрузитесь с параметром ядра modprobe.blacklist=hdma,minerva-iasic.
2.    Убедитесь, что в GRUB есть:
net.ifnames=0 pci=realloc=off
3.    Отключите IOMMU (если не используется):
intel_iommu=off amd_iommu=off
4.    Установите точную версию драйвера, совместимую с ядром.

6.5 После обновления ядра драйвер перестал загружаться
·    modprobe: FATAL: Module minerva-iasic not found.
·    Файлы .ko отсутствуют в /lib/modules/$(uname -r)/{extra,modules}/.

Возможные причины появления ошибки:
Драйвер не был пересобран для нового ядра.

Решение:
·    Если используется DKMS:
sudo dkmsautoinstall -k $(uname-r)

·    Если пакет статический:
Переустановите пакет — он должен содержать модули для нескольких версий ядра или триггер для DKMS.