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

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 (lintas platform): Gunakan library bawaan LiteRT untuk penyiapan instan. Lihat cara menggunakan library C++ bawaan dari paket Maven LiteRT di Android, atau download/integrasikan biner C++ bawaan di Android, iOS, macOS, Linux, dan Windows.
Build dari sumber (lintas platform): Build dari sumber dengan CMake untuk kontrol penuh dan dukungan multiplatform (Android, iOS, macOS, Linux, Windows). Lihat detailnya dalam panduan ini.

Inferensi dasar

Bagian ini menunjukkan cara inferensi dasar dilakukan.

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`

Setelah mendapatkan model LiteRT, atau mengonversi model ke format .tflite, lakukan inisialisasi runtime dengan file model menggunakan CompiledModel API. 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 = CompiledModel::Create(env, "mymodel.tflite", HwAccelerators::kCpu);
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 env, Environment::Create({}));
LITERT_ASSIGN_OR_RETURN(auto compiled_model, CompiledModel::Create(env, "mymodel.tflite",
  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 zero-copy 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 compiled_model1, CompiledModel::Create(env, "model1.tflite", 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 compiled_model2, CompiledModel::Create(env, "model2.tflite", 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);