Mengonversi Safetensors Hugging Face menjadi Tugas MediaPipe

Panduan ini memberikan petunjuk untuk mengonversi model Gemma dalam format Safetensors Hugging Face (.safetensors) ke dalam format file Task MediaPipe (.task). Konversi ini penting untuk men-deploy model Gemma yang telah dilatih sebelumnya atau di-fine-tune untuk inferensi di perangkat di Android dan iOS menggunakan MediaPipe LLM Inference API dan runtime LiteRT.

Diagram alur untuk mengemas model Hugging Face ke dalam file MediaPipe Task

Untuk membuat Paket Tugas (.task) yang diperlukan, Anda akan menggunakan AI Edge Torch. Alat ini mengekspor model PyTorch ke dalam model LiteRT (.tflite) multi-signature, yang kompatibel dengan MediaPipe LLM Inference API dan cocok untuk dijalankan di backend CPU dalam aplikasi seluler.

File .task akhir adalah paket mandiri yang diperlukan oleh MediaPipe, yang menggabungkan model LiteRT, model tokenizer, dan metadata penting. Paket ini diperlukan karena tokenizer (yang mengonversi perintah teks menjadi embedding token untuk model) harus dipaketkan dengan model LiteRT untuk mengaktifkan inferensi end-to-end.

Berikut perincian proses langkah demi langkah:

Perincian proses langkah demi langkah

1. Mendapatkan model Gemma Anda

Anda memiliki dua opsi untuk memulai.

Opsi A. Menggunakan Model yang Sudah di-Fine-Tune

Jika Anda telah menyiapkan model Gemma yang dioptimalkan, lanjutkan ke langkah berikutnya.

Opsi B. Mendownload Model resmi yang dioptimalkan untuk mengikuti perintah

Jika Anda memerlukan model, Anda dapat mendownload Gemma yang disesuaikan dengan instruksi dari Hugging Face Hub.

Siapkan alat yang diperlukan:

python -m venv hf
source hf/bin/activate
pip install huggingface_hub[cli]

Download model:

Model di Hugging Face Hub diidentifikasi berdasarkan ID model, biasanya dalam format <organization_or_username>/<model_name>. Misalnya, untuk mendownload model resmi Gemma 3 270M yang disesuaikan dengan instruksi Google, gunakan:

hf download google/gemma-3-270m-it --local-dir "PATH_TO_HF_MODEL"
#"google/gemma-3-1b-it", etc

2. Mengonversi dan menguantisasi model ke LiteRT

Siapkan lingkungan virtual Python dan instal rilis stabil terbaru paket AI Edge Torch:

python -m venv ai-edge-torch
source ai-edge-torch/bin/activate
pip install "ai-edge-torch>=0.6.0"

Gunakan skrip berikut untuk mengonversi Safetensor menjadi model LiteRT.

from ai_edge_torch.generative.examples.gemma3 import gemma3
from ai_edge_torch.generative.utilities import converter
from ai_edge_torch.generative.utilities.export_config import ExportConfig
from ai_edge_torch.generative.layers import kv_cache

pytorch_model = gemma3.build_model_270m("PATH_TO_HF_MODEL")

# If you are using Gemma 3 1B
#pytorch_model = gemma3.build_model_1b("PATH_TO_HF_MODEL")

export_config = ExportConfig()
export_config.kvcache_layout = kv_cache.KV_LAYOUT_TRANSPOSED
export_config.mask_as_input = True

converter.convert_to_tflite(
    pytorch_model,
    output_path="OUTPUT_DIR_PATH",
    output_name_prefix="my-gemma3",
    prefill_seq_len=2048,
    kv_cache_max_len=4096,
    quantize="dynamic_int8",
    export_config=export_config,
)

Perlu diketahui bahwa proses ini memakan waktu dan bergantung pada kecepatan pemrosesan komputer Anda. Sebagai referensi, pada CPU 8-core 2025, model 270M memerlukan waktu lebih dari 5-10 menit, sedangkan model 1B dapat memerlukan waktu sekitar 10-30 menit.

Output akhir, yaitu model LiteRT, akan disimpan ke OUTPUT_DIR_PATH yang Anda tentukan.

Sesuaikan nilai berikut berdasarkan batasan memori dan performa perangkat target Anda.

  • kv_cache_max_len: Menentukan ukuran total yang dialokasikan untuk memori kerja model (cache KV). Kapasitas ini adalah batas tetap dan harus cukup untuk menyimpan jumlah gabungan token perintah (pengisian awal) dan semua token yang dihasilkan berikutnya (dekode).
  • prefill_seq_len: Menentukan jumlah token perintah input untuk pembuatan potongan pengisian otomatis. Saat memproses perintah input menggunakan chunking pengisian otomatis, seluruh urutan (misalnya, 50.000 token) tidak dihitung sekaligus; melainkan dibagi menjadi segmen yang dapat dikelola (misalnya, potongan 2.048 token) yang dimuat secara berurutan ke dalam cache untuk mencegah error kehabisan memori.
  • quantize: string untuk skema kuantisasi yang dipilih. Berikut adalah daftar resep kuantisasi yang tersedia untuk Gemma 3.
    • none : Tidak ada kuantisasi
    • fp16 : Bobot FP16, aktivasi FP32, dan komputasi floating point untuk semua operasi
    • dynamic_int8 : Aktivasi FP32, bobot INT8, dan komputasi bilangan bulat
    • weight_only_int8 : Aktivasi FP32, bobot INT8, dan komputasi floating point

3. Membuat Task Bundle dari LiteRT dan tokenizer

Siapkan lingkungan virtual Python dan instal paket Python mediapipe:

python -m venv mediapipe
source mediapipe/bin/activate
pip install mediapipe

Gunakan library genai.bundler untuk memaketkan model:

from mediapipe.tasks.python.genai import bundler
config = bundler.BundleConfig(
    tflite_model="PATH_TO_LITERT_MODEL.tflite",
    tokenizer_model="PATH_TO_HF_MODEL/tokenizer.model",
    start_token="<bos>",
    stop_tokens=["<eos>", "<end_of_turn>"],
    output_filename="PATH_TO_TASK_BUNDLE.task",
    prompt_prefix="<start_of_turn>user\n",
    prompt_suffix="<end_of_turn>\n<start_of_turn>model\n",
)
bundler.create_bundle(config)

Fungsi bundler.create_bundle membuat file .task yang berisi semua informasi yang diperlukan untuk menjalankan model.

4. Inferensi dengan MediaPipe di Android

Lakukan inisialisasi tugas dengan opsi konfigurasi dasar:

// Default values for LLM models
private object LLMConstants {
    const val MODEL_PATH = "PATH_TO_TASK_BUNDLE_ON_YOUR_DEVICE.task"
    const val DEFAULT_MAX_TOKEN = 4096
    const val DEFAULT_TOPK = 64
    const val DEFAULT_TOPP = 0.95f
    const val DEFAULT_TEMPERATURE = 1.0f
}

// Set the configuration options for the LLM Inference task
val taskOptions = LlmInference.LlmInferenceOptions.builder()
    .setModelPath(LLMConstants.MODEL_PATH)
    .setMaxTokens(LLMConstants.DEFAULT_MAX_TOKEN)
    .build()

// Create an instance of the LLM Inference task
llmInference = LlmInference.createFromOptions(context, taskOptions)
llmInferenceSession =
    LlmInferenceSession.createFromOptions(
        llmInference,
        LlmInferenceSession.LlmInferenceSessionOptions.builder()
            .setTopK(LLMConstants.DEFAULT_TOPK)
            .setTopP(LLMConstants.DEFAULT_TOPP)
            .setTemperature(LLMConstants.DEFAULT_TEMPERATURE)
            .build(),
    )

Gunakan metode generateResponse() untuk menghasilkan respons teks.

val result = llmInferenceSession.generateResponse(inputPrompt)
logger.atInfo().log("result: $result")

Untuk melakukan streaming respons, gunakan metode generateResponseAsync().

llmInferenceSession.generateResponseAsync(inputPrompt) { partialResult, done ->
    logger.atInfo().log("partial result: $partialResult")
}

Lihat panduan Inferensi LLM untuk Android untuk mengetahui informasi selengkapnya.

Langkah berikutnya

Bangun dan jelajahi lebih banyak dengan model Gemma: