Запустите LiteRT Next на Android с помощью C++

API LiteRT Next доступны на языке C++ и могут предложить разработчикам Android больший контроль над распределением памяти и низкоуровневой разработкой, чем API Kotlin.

Пример приложения LiteRT Next на C++ см. в демонстрации Асинхронная сегментация с использованием C++ .

Начать

Чтобы добавить LiteRT Next в ваше приложение Android, выполните следующие действия.

Обновите конфигурацию сборки

Создание приложения C++ с LiteRT для ускорения GPU, NPU и CPU с использованием Bazel включает определение правила cc_binary , чтобы гарантировать, что все необходимые компоненты скомпилированы, связаны и упакованы. Следующий пример настройки позволяет вашему приложению динамически выбирать или использовать ускорители GPU, NPU и CPU.

Вот ключевые компоненты конфигурации сборки Bazel:

• Правило cc_binary : Это фундаментальное правило Базеля, используемое для определения целевого исполняемого файла C++ (например, name = "your_application_name" ).
• Атрибут srcs : выводит список исходных файлов C++ вашего приложения (например, main.cc и другие файлы .cc или .h ).
• Атрибут data (зависимости времени выполнения): это имеет решающее значение для упаковки общих библиотек и ресурсов, которые ваше приложение загружает во время выполнения.
  • LiteRT Core Runtime: основная общая библиотека LiteRT C API (например, //litert/c:litert_runtime_c_api_shared_lib ).
  • Библиотеки Dispatch: общие библиотеки, специфичные для поставщика, которые LiteRT использует для взаимодействия с драйверами оборудования (например, //litert/vendors/qualcomm/dispatch:dispatch_api_so ).
  • Библиотеки бэкэнда GPU: общие библиотеки для ускорения GPU (например, "@litert_gpu//:jni/arm64-v8a/libLiteRtGpuAccelerator.so ).
  • Библиотеки бэкэнда NPU: специальные общие библиотеки для ускорения NPU, такие как библиотеки QNN HTP компании Qualcomm (например, @qairt//:lib/aarch64-android/libQnnHtp.so , @qairt//:lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so ).
  • Файлы и ресурсы модели: файлы обученной модели, тестовые изображения, шейдеры или любые другие данные, необходимые во время выполнения (например, :model_files , :shader_files ).
• Атрибут deps (зависимости времени компиляции): здесь перечислены библиотеки, с которыми необходимо скомпилировать ваш код.
  • API и утилиты LiteRT: заголовочные файлы и статические библиотеки для компонентов LiteRT, таких как тензорные буферы (например, //litert/cc:litert_tensor_buffer ).
  • Графические библиотеки (для GPU): зависимости, связанные с графическими API, если ускоритель GPU их использует (например, gles_deps() ).
• Атрибут linkopts : указывает параметры, передаваемые компоновщику, которые могут включать связывание с системными библиотеками (например, -landroid для сборок Android или библиотеки GLES с gles_linkopts() ).

Ниже приведен пример правила cc_binary :

cc_binary(
    name = "your_application",
    srcs = [
        "main.cc",
    ],
    data = [
        ...
        # litert c api shared library
        "//litert/c:litert_runtime_c_api_shared_lib",
        # GPU accelerator shared library
        "@litert_gpu//:jni/arm64-v8a/libLiteRtGpuAccelerator.so",
        # NPU accelerator shared library
        "//litert/vendors/qualcomm/dispatch:dispatch_api_so",
    ],
    linkopts = select({
        "@org_tensorflow//tensorflow:android": ["-landroid"],
        "//conditions:default": [],
    }) + gles_linkopts(), # gles link options
    deps = [
        ...
        "//litert/cc:litert_tensor_buffer", # litert cc library
        ...
    ] + gles_deps(), # gles dependencies
)

Загрузить модель

После получения модели LiteRT или преобразования модели в формат .tflite загрузите модель, создав объект Model .

LITERT_ASSIGN_OR_RETURN(auto model, Model::CreateFromFile("mymodel.tflite"));

Создайте среду

Объект Environment предоставляет среду выполнения, которая включает такие компоненты, как путь к плагину компилятора и контексты GPU. Environment требуется при создании CompiledModel и TensorBuffer . Следующий код создает Environment для выполнения CPU и GPU без каких-либо параметров:

LITERT_ASSIGN_OR_RETURN(auto env, Environment::Create({}));

Создать скомпилированную модель

Используя API CompiledModel , инициализируйте среду выполнения с помощью недавно созданного объекта Model . На этом этапе вы можете указать аппаратное ускорение ( kLiteRtHwAcceleratorCpu или kLiteRtHwAcceleratorGpu ):

LITERT_ASSIGN_OR_RETURN(auto compiled_model,
  CompiledModel::Create(env, model, kLiteRtHwAcceleratorCpu));

Создание входных и выходных буферов

Создайте необходимые структуры данных (буферы) для хранения входных данных, которые вы будете передавать в модель для вывода, и выходных данных, которые модель выдает после выполнения вывода.

LITERT_ASSIGN_OR_RETURN(auto input_buffers, compiled_model.CreateInputBuffers());
LITERT_ASSIGN_OR_RETURN(auto output_buffers, compiled_model.CreateOutputBuffers());

Если вы используете память ЦП, заполните входы, записав данные непосредственно в первый входной буфер.

input_buffers[0].Write<float>(absl::MakeConstSpan(input_data, input_size));

Вызов модели

Предоставив входные и выходные буферы, запустите скомпилированную модель с моделью и аппаратным ускорением, указанными на предыдущих шагах.

compiled_model.Run(input_buffers, output_buffers);

Получить выходы

Извлекайте выходные данные, напрямую считывая выходные данные модели из памяти.

std::vector<float> data(output_data_size);
output_buffers[0].Read<float>(absl::MakeSpan(data));
// ... process output data

Ключевые концепции и компоненты

Информацию о ключевых концепциях и компонентах API LiteRT Next можно найти в следующих разделах.

Обработка ошибок

LiteRT использует litert::Expected для возврата значений или распространения ошибок аналогично absl::StatusOr или std::expected . Вы можете вручную проверить наличие ошибки самостоятельно.

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

• LITERT_ASSIGN_OR_RETURN(lhs, expr) присваивает результат expr lhs если это не приводит к ошибке, в противном случае возвращает ошибку.

  Он расширится до примерно следующего фрагмента.

  auto maybe_model = Model::CreateFromFile("mymodel.tflite");
  if (!maybe_model) {
    return maybe_model.Error();
  }
  auto model = std::move(maybe_model.Value());
  

• LITERT_ASSIGN_OR_ABORT(lhs, expr) делает то же самое, что и LITERT_ASSIGN_OR_RETURN , но прерывает программу в случае ошибки.

• LITERT_RETURN_IF_ERROR(expr) возвращает expr если его оценка приводит к ошибке.

• LITERT_ABORT_IF_ERROR(expr) делает то же самое, что и LITERT_RETURN_IF_ERROR , но прерывает программу в случае ошибки.

Дополнительную информацию о макросах LiteRT см. в файле litert_macros.h .

Скомпилированная модель (CompiledModel)

API скомпилированной модели ( CompiledModel ) отвечает за загрузку модели, применение аппаратного ускорения, создание среды выполнения, создание входных и выходных буферов и выполнение вывода.

Следующий упрощенный фрагмент кода демонстрирует, как API скомпилированной модели берет модель LiteRT ( .tflite ) и целевой аппаратный ускоритель (GPU) и создает скомпилированную модель, готовую к запуску вывода.

// Load model and initialize runtime
LITERT_ASSIGN_OR_RETURN(auto model, Model::CreateFromFile("mymodel.tflite"));
LITERT_ASSIGN_OR_RETURN(auto env, Environment::Create({}));
LITERT_ASSIGN_OR_RETURN(auto compiled_model,
  CompiledModel::Create(env, model, kLiteRtHwAcceleratorCpu));

Следующий упрощенный фрагмент кода демонстрирует, как API скомпилированной модели принимает входной и выходной буферы и выполняет выводы с использованием скомпилированной модели.

// Preallocate input/output buffers
LITERT_ASSIGN_OR_RETURN(auto input_buffers, compiled_model.CreateInputBuffers());
LITERT_ASSIGN_OR_RETURN(auto output_buffers, compiled_model.CreateOutputBuffers());

// Fill the first input
float input_values[] = { /* your data */ };
LITERT_RETURN_IF_ERROR(
  input_buffers[0].Write<float>(absl::MakeConstSpan(input_values, /*size*/)));

// Invoke
LITERT_RETURN_IF_ERROR(compiled_model.Run(input_buffers, output_buffers));

// Read the output
std::vector<float> data(output_data_size);
LITERT_RETURN_IF_ERROR(
  output_buffers[0].Read<float>(absl::MakeSpan(data)));

Для более полного представления о том, как реализован API CompiledModel , см. исходный код litert_compiled_model.h .

Тензорный буфер (TensorBuffer)

LiteRT Next обеспечивает встроенную поддержку взаимодействия буферов ввода-вывода, используя Tensor Buffer API ( TensorBuffer ) для обработки потока данных в скомпилированную модель и из нее. Tensor Buffer API обеспечивает возможность записи ( Write<T>() ) и чтения ( Read<T>() ), а также блокировки памяти ЦП.

Более полное представление о реализации API TensorBuffer см. в исходном коде litert_tensor_buffer.h .

Требования к вводу/выводу модели запроса

Требования к выделению буфера Tensor ( TensorBuffer ) обычно задаются аппаратным ускорителем. Буферы для входов и выходов могут иметь требования относительно выравнивания, буферных шагов и типа памяти. Вы можете использовать вспомогательные функции, такие как CreateInputBuffers для автоматической обработки этих требований.

Следующий упрощенный фрагмент кода демонстрирует, как можно получить требования к буферу для входных данных:

LITERT_ASSIGN_OR_RETURN(auto reqs, compiled_model.GetInputBufferRequirements(signature_index, input_index));

Более полное представление о реализации API TensorBufferRequirements см. в исходном коде litert_tensor_buffer_requirements.h .

Создание управляемых тензорных буферов (TensorBuffers)

Следующий упрощенный фрагмент кода демонстрирует, как создавать управляемые тензорные буферы, где API TensorBuffer выделяет соответствующие буферы:

LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_cpu,
TensorBuffer::CreateManaged(env, /*buffer_type=*/kLiteRtTensorBufferTypeHostMemory,
  ranked_tensor_type, buffer_size));

LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_gl, TensorBuffer::CreateManaged(env,
  /*buffer_type=*/kLiteRtTensorBufferTypeGlBuffer, ranked_tensor_type, buffer_size));

LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_ahwb, TensorBuffer::CreateManaged(env,
  /*buffer_type=*/kLiteRtTensorBufferTypeAhwb, ranked_tensor_type, buffer_size));

Создание тензорных буферов с нулевым копированием

Чтобы обернуть существующий буфер как тензорный буфер (нулевая копия), используйте следующий фрагмент кода:

// Create a TensorBuffer from host memory
LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_from_host,
  TensorBuffer::CreateFromHostMemory(env, ranked_tensor_type,
  ptr_to_host_memory, buffer_size));

// Create a TensorBuffer from GlBuffer
LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_from_gl,
  TensorBuffer::CreateFromGlBuffer(env, ranked_tensor_type, gl_target, gl_id,
  size_bytes, offset));

// Create a TensorBuffer from AHardware Buffer
LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_from_ahwb,
  TensorBuffer::CreateFromAhwb(env, ranked_tensor_type, ahardware_buffer, offset));

Чтение и запись из тензорного буфера

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

// Example of reading to input buffer:
std::vector<float> input_tensor_data = {1,2};
LITERT_ASSIGN_OR_RETURN(auto write_success,
  input_tensor_buffer.Write<float>(absl::MakeConstSpan(input_tensor_data)));
if(write_success){
  /* Continue after successful write... */
}

// Example of writing to output buffer:
std::vector<float> data(total_elements);
LITERT_ASSIGN_OR_RETURN(auto read_success,
  output_tensor_buffer.Read<float>(absl::MakeSpan(data)));
if(read_success){
  /* Continue after successful read */
}

Расширенные возможности: взаимодействие буферов с нулевым копированием для специализированных типов аппаратных буферов

Некоторые типы буферов, такие как AHardwareBuffer , допускают взаимодействие с другими типами буферов. Например, буфер OpenGL может быть создан из AHardwareBuffer с нулевым копированием. Следующий фрагмент кода показывает пример:

LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_ahwb,
  TensorBuffer::CreateManaged(env, kLiteRtTensorBufferTypeAhwb,
  ranked_tensor_type, buffer_size));
// Buffer interop: Get OpenGL buffer from AHWB,
// internally creating an OpenGL buffer backed by AHWB memory.
LITERT_ASSIGN_OR_RETURN(auto gl_buffer, tensor_buffer_ahwb.GetGlBuffer());

Буферы OpenCL также можно создать из AHardwareBuffer :

LITERT_ASSIGN_OR_RETURN(auto cl_buffer, tensor_buffer_ahwb.GetOpenClMemory());

На мобильных устройствах, поддерживающих взаимодействие OpenCL и OpenGL, буферы CL можно создавать из буферов GL:

LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_from_gl,
  TensorBuffer::CreateFromGlBuffer(env, ranked_tensor_type, gl_target, gl_id,
  size_bytes, offset));

// Creates an OpenCL buffer from the OpenGL buffer, zero-copy.
LITERT_ASSIGN_OR_RETURN(auto cl_buffer, tensor_buffer_from_gl.GetOpenClMemory());

Примеры реализации

Ознакомьтесь со следующими реализациями LiteRT Next на языке C++.

Базовый вывод (ЦП)

Ниже приведена сжатая версия фрагментов кода из раздела «Начало работы» . Это простейшая реализация вывода с LiteRT Next.

// Load model and initialize runtime
LITERT_ASSIGN_OR_RETURN(auto model, Model::CreateFromFile("mymodel.tflite"));
LITERT_ASSIGN_OR_RETURN(auto env, Environment::Create({}));
LITERT_ASSIGN_OR_RETURN(auto compiled_model, CompiledModel::Create(env, model,
  kLiteRtHwAcceleratorCpu));

// Preallocate input/output buffers
LITERT_ASSIGN_OR_RETURN(auto input_buffers, compiled_model.CreateInputBuffers());
LITERT_ASSIGN_OR_RETURN(auto output_buffers, compiled_model.CreateOutputBuffers());

// Fill the first input
float input_values[] = { /* your data */ };
input_buffers[0].Write<float>(absl::MakeConstSpan(input_values, /*size*/));

// Invoke
compiled_model.Run(input_buffers, output_buffers);

// Read the output
std::vector<float> data(output_data_size);
output_buffers[0].Read<float>(absl::MakeSpan(data));

Нулевое копирование с памятью хоста

API LiteRT Next Compiled Model уменьшает трение конвейеров вывода, особенно при работе с несколькими аппаратными бэкэндами и потоками с нулевым копированием. Следующий фрагмент кода использует метод CreateFromHostMemory при создании входного буфера, который использует нулевое копирование с памятью хоста.

// Define an LiteRT environment to use existing EGL display and context.
const std::vector<Environment::Option> environment_options = {
   {OptionTag::EglDisplay, user_egl_display},
   {OptionTag::EglContext, user_egl_context}};
LITERT_ASSIGN_OR_RETURN(auto env,
   Environment::Create(absl::MakeConstSpan(environment_options)));

// Load model1 and initialize runtime.
LITERT_ASSIGN_OR_RETURN(auto model1, Model::CreateFromFile("model1.tflite"));
LITERT_ASSIGN_OR_RETURN(auto compiled_model1, CompiledModel::Create(env, model1, kLiteRtHwAcceleratorGpu));

// Prepare I/O buffers. opengl_buffer is given outside from the producer.
LITERT_ASSIGN_OR_RETURN(auto tensor_type, model.GetInputTensorType("input_name0"));
// Create an input TensorBuffer based on tensor_type that wraps the given OpenGL Buffer.
LITERT_ASSIGN_OR_RETURN(auto tensor_buffer_from_opengl,
    litert::TensorBuffer::CreateFromGlBuffer(env, tensor_type, opengl_buffer));

// Create an input event and attach it to the input buffer. Internally, it creates
// and inserts a fence sync object into the current EGL command queue.
LITERT_ASSIGN_OR_RETURN(auto input_event, Event::CreateManaged(env, LiteRtEventTypeEglSyncFence));
tensor_buffer_from_opengl.SetEvent(std::move(input_event));

std::vector<TensorBuffer> input_buffers;
input_buffers.push_back(std::move(tensor_buffer_from_opengl));

// Create an output TensorBuffer of the model1. It's also used as an input of the model2.
LITERT_ASSIGN_OR_RETURN(auto intermedidate_buffers,  compiled_model1.CreateOutputBuffers());

// Load model2 and initialize runtime.
LITERT_ASSIGN_OR_RETURN(auto model2, Model::CreateFromFile("model2.tflite"));
LITERT_ASSIGN_OR_RETURN(auto compiled_model2, CompiledModel::Create(env, model2, kLiteRtHwAcceleratorGpu));
LITERT_ASSIGN_OR_RETURN(auto output_buffers, compiled_model2.CreateOutputBuffers());

compiled_model1.RunAsync(input_buffers, intermedidate_buffers);
compiled_model2.RunAsync(intermedidate_buffers, output_buffers);