Memperkenalkan Google AI Edge Portal: Lakukan benchmark Edge AI dalam skala besar. Daftar untuk meminta akses selama pratinjau pribadi.

Halaman ini diterjemahkan oleh Cloud Translation API.

LiteRT CompiledModel C++ API

API LiteRT CompiledModel tersedia di C++, sehingga developer dapat mengontrol alokasi memori dan pengembangan tingkat rendah secara terperinci. Sebagai contoh, lihat Aplikasi C++ Segmentasi gambar.

Panduan berikut menunjukkan inferensi CPU dasar CompiledModel Kotlin API. Lihat panduan tentang akselerasi GPU dan akselerasi NPU untuk fitur akselerasi lanjutan.

Menambahkan dependensi build

Pilih jalur yang sesuai dengan project Anda:

Menggunakan library bawaan (Android): Gunakan library bawaan dari paket Maven LiteRT untuk penyiapan instan. Lihat cara menggunakan library C++ bawaan dari LiteRT Maven.
Build dari sumber (lintas platform): Build dari sumber untuk kontrol penuh dan dukungan multiplatform (Android, iOS, macOS, Linux, Windows). Lihat petunjuk berikut.

Membangun dari sumber dengan Bazel

Mem-build aplikasi C++ dengan LiteRT untuk akselerasi GPU, NPU, dan CPU menggunakan Bazel melibatkan penentuan aturan cc_binary untuk memastikan semua komponen yang diperlukan dikompilasi, ditautkan, dan dipaketkan. Penyiapan contoh berikut memungkinkan aplikasi Anda memilih atau menggunakan akselerator GPU, NPU, dan CPU secara dinamis.

Berikut adalah komponen utama dalam konfigurasi build Bazel Anda:

cc_binary Aturan: Ini adalah aturan Bazel mendasar yang digunakan untuk menentukan target yang dapat dieksekusi C++ Anda (misalnya, name = "your_application_name").
Atribut srcs: Mencantumkan file sumber C++ aplikasi Anda (misalnya, main.cc, dan file .cc atau .h lainnya).
Atribut data (Dependensi Runtime): Atribut ini sangat penting untuk memaketkan library bersama dan aset yang dimuat aplikasi Anda saat runtime.
- LiteRT Core Runtime: Library bersama C API LiteRT utama (misalnya, //litert/c:litert_runtime_c_api_shared_lib).
- Library Dispatch: Library bersama khusus vendor yang digunakan LiteRT untuk berkomunikasi dengan driver hardware (misalnya, //litert/vendors/qualcomm/dispatch:dispatch_api_so).
- Library Backend GPU: Library bersama untuk akselerasi GPU (misalnya, "@litert_gpu//:jni/arm64-v8a/libLiteRtGpuAccelerator.so).
- Library Backend NPU: Library bersama khusus untuk akselerasi NPU, seperti library HTP QNN Qualcomm (misalnya, @qairt//:lib/aarch64-android/libQnnHtp.so, @qairt//:lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so).
- File & Aset Model: File model terlatih, gambar pengujian, shader, atau data lain yang diperlukan saat runtime (misalnya, :model_files, :shader_files).
Atribut deps (Dependensi Waktu Kompilasi): Mencantumkan library yang dibutuhkan kode Anda untuk dikompilasi.
- LiteRT & Utilitas: Header dan library statis untuk komponen LiteRT seperti buffer tensor (misalnya, //litert/cc:litert_tensor_buffer).
- Library Grafis (untuk GPU): Dependensi terkait API grafis jika akselerator GPU menggunakannya (misalnya, gles_deps()).
Atribut linkopts: Menentukan opsi yang diteruskan ke linker, yang dapat mencakup penautan ke library sistem (misalnya, -landroid untuk build Android, atau library GLES dengan gles_linkopts()).

Berikut adalah contoh aturan 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
)

Inferensi dasar

Memuat Model

Setelah mendapatkan model LiteRT, atau mengonversi model ke format .tflite, muat model dengan membuat objek Model.

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

Buat lingkungan

Objek Environment menyediakan lingkungan runtime yang mencakup komponen seperti jalur plugin compiler dan konteks GPU. Environment diperlukan saat membuat CompiledModel dan TensorBuffer. Kode berikut membuat Environment untuk eksekusi CPU dan GPU tanpa opsi apa pun:

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

Membuat `CompiledModel`

Dengan menggunakan CompiledModel API, inisialisasi runtime dengan objek Model yang baru dibuat. Anda dapat menentukan akselerasi hardware pada tahap ini (kLiteRtHwAcceleratorCpu atau kLiteRtHwAcceleratorGpu):

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

Membuat Buffer Input dan Output

Buat struktur data (buffer) yang diperlukan untuk menyimpan data input yang akan dimasukkan ke dalam model untuk inferensi, dan data output yang dihasilkan model setelah menjalankan inferensi.

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

Jika Anda menggunakan memori CPU, isi input dengan menulis data langsung ke buffer input pertama.

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

Memanggil model

Dengan menyediakan buffer input dan output, jalankan Model yang Dikompilasi dengan model dan akselerasi hardware yang ditentukan pada langkah-langkah sebelumnya.

compiled_model.Run(input_buffers, output_buffers);

Mengambil Output

Mengambil output dengan membaca output model langsung dari memori.

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

Konsep dan komponen utama

Lihat bagian berikut untuk mengetahui informasi tentang konsep dan komponen utama API LiteRT CompiledModel.

Penanganan Error

LiteRT menggunakan litert::Expected untuk menampilkan nilai atau menyebarkan error dengan cara yang serupa dengan absl::StatusOr atau std::expected. Anda dapat memeriksa error secara manual.

Untuk memudahkan, LiteRT menyediakan makro berikut:

LITERT_ASSIGN_OR_RETURN(lhs, expr) menetapkan hasil expr ke lhs jika tidak menghasilkan error dan menampilkan error jika tidak.

Ini akan diperluas menjadi seperti cuplikan berikut.
```
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) melakukan hal yang sama seperti LITERT_ASSIGN_OR_RETURN tetapi membatalkan program jika terjadi error.
LITERT_RETURN_IF_ERROR(expr) menampilkan expr jika evaluasinya menghasilkan error.
LITERT_ABORT_IF_ERROR(expr) melakukan hal yang sama seperti LITERT_RETURN_IF_ERROR, tetapi membatalkan program jika terjadi error.

Untuk mengetahui informasi selengkapnya tentang makro LiteRT, lihat litert_macros.h.

Buffer Tensor (TensorBuffer)

LiteRT menyediakan dukungan bawaan untuk interoperabilitas buffer I/O, menggunakan Tensor Buffer API (TensorBuffer) untuk menangani aliran data ke dalam dan ke luar model yang dikompilasi. Tensor Buffer API memberikan kemampuan untuk menulis (Write<T>()) dan membaca (Read<T>()), serta mengunci memori CPU.

Untuk melihat gambaran yang lebih lengkap tentang cara penerapan API TensorBuffer, lihat kode sumber untuk litert_tensor_buffer.h.

Persyaratan input/output model kueri

Persyaratan untuk mengalokasikan Buffer Tensor (TensorBuffer) biasanya ditentukan oleh akselerator hardware. Buffer untuk input dan output dapat memiliki persyaratan terkait perataan, langkah buffer, dan jenis memori. Anda dapat menggunakan fungsi helper seperti CreateInputBuffers untuk menangani persyaratan ini secara otomatis.

Cuplikan kode yang disederhanakan berikut menunjukkan cara Anda dapat mengambil persyaratan buffer untuk data input:

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

Untuk melihat gambaran yang lebih lengkap tentang cara penerapan API TensorBufferRequirements, lihat kode sumber untuk litert_tensor_buffer_requirements.h.

Membuat Managed Tensor Buffers (TensorBuffers)

Cuplikan kode yang disederhanakan berikut menunjukkan cara membuat Managed Tensor Buffers, tempat API TensorBuffer mengalokasikan buffer masing-masing:

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));

Membuat Buffer Tensor dengan zero-copy

Untuk membungkus buffer yang ada sebagai Tensor Buffer (tanpa penyalinan), gunakan cuplikan kode berikut:

// 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));

Membaca dan menulis dari Tensor Buffer

Cuplikan berikut menunjukkan cara membaca dari buffer input dan menulis ke buffer output:

// 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 */
}

Lanjutan: Interop buffer tanpa salinan untuk jenis buffer hardware khusus

Jenis buffer tertentu, seperti AHardwareBuffer, memungkinkan interoperabilitas dengan jenis buffer lainnya. Misalnya, buffer OpenGL dapat dibuat dari AHardwareBuffer dengan salinan nol. Cuplikan kode berikut menunjukkan contoh:

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());

Buffer OpenCL juga dapat dibuat dari AHardwareBuffer:

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

Pada perangkat seluler yang mendukung interoperabilitas antara OpenCL dan OpenGL, buffer CL dapat dibuat dari buffer 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());

Contoh penerapan

Lihat penerapan LiteRT berikut di C++.

Inferensi Dasar (CPU)

Berikut adalah versi ringkas dari cuplikan kode dari bagian Mulai. Ini adalah penerapan inferensi paling sederhana dengan LiteRT.

// 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));

Zero-Copy dengan Memori Host

API LiteRT CompiledModel mengurangi gesekan pipeline inferensi, terutama saat menangani beberapa backend hardware dan alur tanpa salinan. Cuplikan kode berikut menggunakan metode CreateFromHostMemory saat membuat buffer input, yang menggunakan salinan nol dengan memori host.

// 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);