המרת Hugging Face Safetensors למשימת MediaPipe

במדריך הזה מוסבר איך להמיר מודלים של Gemma בפורמט Hugging Face Safetensors ‏ (.safetensors) לפורמט קובץ המשימות של MediaPipe ‏(.task). ההמרה הזו חיונית לפריסת מודלים של Gemma שעברו אימון מראש או כוונון עדין להסקת מסקנות במכשיר ב-Android וב-iOS באמצעות MediaPipe LLM Inference API וזמן הריצה של LiteRT.

כדי ליצור את חבילת המשימות הנדרשת (.task), תשתמשו ב-AI Edge Torch. הכלי הזה מייצא מודלים של PyTorch למודלים של LiteRT (.tflite) עם חתימות מרובות, שתואמים לממשק ה-API של MediaPipe LLM Inference ומתאימים להרצה ב-backends של CPU באפליקציות לנייד.

קובץ ה-.task הסופי הוא חבילה עצמאית שנדרשת על ידי MediaPipe, שכוללת את מודל LiteRT, את מודל הטוקנייזר ומטא-נתונים חיוניים. החבילה הזו נדרשת כי צריך לארוז את ה-tokenizer (שממיר הנחיות טקסט להטבעות של טוקנים עבור המודל) עם מודל LiteRT כדי לאפשר הסקה מקצה לקצה.

פירוט שלבי התהליך:

1. קבלת מודל Gemma

יש שתי דרכים להתחיל.

אפשרות א'. שימוש במודל קיים שעבר התאמה אישית

אם יש לכם מודל Gemma שעבר כוונון עדין, אתם יכולים פשוט להמשיך לשלב הבא.

אפשרות ב'. הורדה של מודל רשמי שעבר כוונון לפי הוראות

אם אתם צריכים מודל, אתם יכולים להוריד Gemma שעבר כוונון לפי הוראות מ-Hugging Face Hub.

הגדרת הכלים הנדרשים:

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

הורדת המודל:

מודלים ב-Hugging Face Hub מזוהים באמצעות מזהה מודל, בדרך כלל בפורמט <organization_or_username>/<model_name>. לדוגמה, כדי להוריד את המודל הרשמי של Google Gemma 3 270M שעבר כוונון להוראות, משתמשים בפקודה הבאה:

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

2. המרת המודל וכימות שלו ל-LiteRT

מגדירים סביבה וירטואלית של Python ומתקינים את הגרסה היציבה העדכנית של חבילת AI Edge Torch:

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

משתמשים בסקריפט הבא כדי להמיר את Safetensor למודל 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,
)

חשוב לדעת שהתהליך הזה אורך זמן ותלוי במהירות העיבוד של המחשב. לשם השוואה, במעבד עם 8 ליבות משנת 2025, מודל של 270M לוקח יותר מ-5 עד 10 דקות, ומודל של 1B יכול לקחת בערך 10 עד 30 דקות.

הפלט הסופי, מודל LiteRT, יישמר ב-OUTPUT_DIR_PATH שציינתם.

כדאי לשנות את הערכים הבאים בהתאם למגבלות הזיכרון והביצועים של מכשיר היעד.

• ‫kv_cache_max_len: הגודל הכולל של זיכרון העבודה שהוקצה למודל (מטמון KV). הקיבולת הזו היא מגבלה קשיחה, והיא צריכה להיות מספיקה לאחסון הסכום המשולב של האסימונים של ההנחיה (המילוי המקדים) וכל האסימונים שנוצרו לאחר מכן (הפענוח).
• ‫prefill_seq_len: מציין את מספר האסימונים בהנחיה לקלט לצורך חלוקה לחלקים של מילוי מראש. כשמעבדים את הנחיית הקלט באמצעות חלוקה לחלקים של מילוי אוטומטי, הרצף כולו (למשל, ‫50,000 טוקנים) לא מחושב בבת אחת, אלא מחולק לפלחים קטנים (למשל, 2,048 טוקנים) שנטענים ברצף למטמון כדי למנוע שגיאה של חוסר זיכרון.
• ‫quantize: מחרוזת של סכימות הכימות שנבחרו. בהמשך מופיעה רשימה של מתכוני קוונטיזציה זמינים ל-Gemma 3.
  • ‫none : No quantization
  • ‫fp16 : משקלים מסוג FP16, הפעלות מסוג FP32 וחישוב נקודה צפה לכל הפעולות
  • ‫dynamic_int8 : הפעלות FP32, משקלים INT8 וחישוב מספרים שלמים
  • ‫weight_only_int8 : הפעלות FP32, משקלים INT8 וחישוב נקודה צפה

‫3. יצירת חבילת משימות מ-LiteRT ומטוקנייזר

מגדירים סביבה וירטואלית של Python ומתקינים את חבילת Python‏ mediapipe:

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

משתמשים בספרייה genai.bundler כדי לארוז את המודל:

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)

הפונקציה bundler.create_bundle יוצרת קובץ .task שמכיל את כל המידע שנדרש להפעלת המודל.

4. הסקת מסקנות באמצעות Mediapipe ב-Android

מאחלים את המשימה עם אפשרויות הגדרה בסיסיות:

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

משתמשים ב-generateResponse() method כדי ליצור תשובת טקסט.

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

כדי להזרים את התשובה, משתמשים בשיטה generateResponseAsync().

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

מידע נוסף זמין במדריך בנושא הסקת מסקנות של LLM ב-Android.

השלבים הבאים

אפשר ליצור ולחקור עוד באמצעות מודלים של Gemma:

• פריסת Gemma במכשירים ניידים
• שיפור של Gemma למשימות טקסט באמצעות Hugging Face Transformers
• שיפור של Gemma למשימות שקשורות לראייה באמצעות Hugging Face Transformers
• כוונון עדין של מודל מלא באמצעות Hugging Face Transformers