Konvertoni mbrojtëset e fytyrës përqafuese në MediaPipe Task

Ky udhëzues ofron udhëzime për konvertimin e modeleve Gemma në formatin Hugging Face Safetensors ( .safetensors ) në formatin e skedarit MediaPipe Task ( .task ). Ky konvertim është thelbësor për vendosjen e modeleve Gemma të trajnuar paraprakisht ose të rregulluar mirë për konkluzionet në pajisje në Android dhe iOS duke përdorur MediaPipe LLM Inference API dhe kohën e ekzekutimit LiteRT.

Grafiku i rrjedhës për paketimin e një modeli Hugging Face në një skedar MediaPipe Task

Për të krijuar grupin e nevojshëm të detyrave ( .task ), do të përdorni AI Edge Torch . Ky mjet eksporton modelet e PyTorch në modelet LiteRT ( .tflite ) me shumë nënshkrime, të cilat janë të pajtueshme me MediaPipe LLM Inference API dhe të përshtatshme për ekzekutim në backend të CPU-së në aplikacionet celulare.

Skedari përfundimtar .task është një paketë e pavarur e kërkuar nga MediaPipe, duke bashkuar modelin LiteRT, modelin e tokenizuesit dhe metadatat thelbësore. Kjo paketë është e nevojshme sepse tokenizuesi (i cili konverton kërkesat e tekstit në ngulitje token për modelin) duhet të paketohet me modelin LiteRT për të mundësuar konkluzionet nga fundi në fund.

Këtu është një përmbledhje hap pas hapi e procesit:

Zbërthimi hap pas hapi i procesit

1. Merrni modelin tuaj Gemma

Ju keni dy mundësi për të filluar.

Opsioni A. Përdorni një model ekzistues të rregulluar mirë

Nëse keni përgatitur një model Gemma të rregulluar mirë , thjesht vazhdoni në hapin tjetër.

Opsioni B. Shkarkoni modelin zyrtar të akorduar sipas udhëzimeve

Nëse keni nevojë për një model, mund të shkarkoni një Gemma të akorduar sipas udhëzimeve nga Hugging Face Hub.

Vendosni mjetet e nevojshme:

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

Shkarkoni modelin:

Modelet në Hub Hugging Face identifikohen nga një ID modeli, zakonisht në formatin <organization_or_username>/<model_name> . Për shembull, për të shkarkuar modelin zyrtar të Google Gemma 3 270M të akorduar me udhëzime, përdorni:

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

2. Konvertoni dhe kuantizoni modelin në LiteRT

Vendosni një mjedis virtual Python dhe instaloni versionin më të fundit të qëndrueshëm të paketës AI Edge Torch:

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

Përdorni skriptin e mëposhtëm për të kthyer Safetensor në modelin 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,
)

Kini parasysh se ky proces kërkon kohë dhe varet nga shpejtësia e përpunimit të kompjuterit tuaj. Për referencë, në një CPU me 8 bërthama të vitit 2025, një model 270M merr më shumë se 5-10 minuta, ndërsa një model 1B mund të marrë afërsisht 10-30 minuta.

Dalja përfundimtare, një model LiteRT, do të ruhet në OUTPUT_DIR_PATH të specifikuar.

Rregulloni vlerat e mëposhtme bazuar në kufizimet e kujtesës dhe performancës së pajisjes suaj të synuar.

  • kv_cache_max_len : Përcakton madhësinë totale të alokuar të memories së punës së modelit (cache KV). Ky kapacitet është një kufi i vështirë dhe duhet të jetë i mjaftueshëm për të ruajtur shumën e kombinuar të shenjave të promptit (parambushja) dhe të gjitha shenjat e krijuara më pas (dekodimi).
  • prefill_seq_len : Përcakton numrin e shenjave të kërkesës hyrëse për copëzimin e parambushjes. Kur përpunohet kërkesa e hyrjes duke përdorur copëzimin e parambushjes, e gjithë sekuenca (p.sh. 50,000 tokena) nuk llogaritet menjëherë; në vend të kësaj, ajo ndahet në segmente të menaxhueshme (p.sh., copa prej 2048 tokenësh) që ngarkohen në mënyrë sekuenciale në cache për të parandaluar një gabim jashtë memorie.
  • quantize : varg për skemat e përzgjedhura të kuantizimit. Më poshtë është lista e recetave të disponueshme të kuantizimit për Gemma 3.
    • none : Nuk ka kuantizim
    • fp16 : peshat FP16, aktivizimet e FP32 dhe llogaritja e pikës lundruese për të gjitha operacionet
    • dynamic_int8 : aktivizimet e FP32, peshat INT8 dhe llogaritja e numrave të plotë
    • weight_only_int8 : aktivizimet e FP32, peshat INT8 dhe llogaritja e pikës lundruese

3. Krijoni një grup detyrash nga LiteRT dhe tokenizuesi

Vendosni një mjedis virtual Python dhe instaloni paketën mediapipe Python:

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

Përdorni bibliotekën genai.bundler për të bashkuar modelin:

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)

Funksioni bundler.create_bundle krijon një skedar .task që përmban të gjithë informacionin e nevojshëm për të ekzekutuar modelin.

4. Konkluzioni me Mediapipe në Android

Inicializoni detyrën me opsionet bazë të konfigurimit:

// 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(),
    )

Përdorni generateResponse() për të gjeneruar një përgjigje tekstuale.

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

Për të transmetuar përgjigjen, përdorni generateResponseAsync() .

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

Shikoni udhëzuesin LLM Inference për Android për më shumë informacion.

Hapat e ardhshëm

Ndërtoni dhe eksploroni më shumë me modelet Gemma: