تبدیل محافظ های محافظ صورت بغل کردن به MediaPipe Task

این راهنما دستورالعمل هایی را برای تبدیل مدل های Gemma در قالب Hugging Face Safetensors ( .safetensors ) به فرمت فایل MediaPipe Task ( .task ) ارائه می دهد. این تبدیل برای استقرار مدل های Gemma از پیش آموزش دیده یا تنظیم شده برای استنتاج روی دستگاه در Android و iOS با استفاده از MediaPipe LLM Inference API و زمان اجرا LiteRT ضروری است.

برای ایجاد Task Bundle مورد نیاز ( .task )، از AI Edge Torch استفاده خواهید کرد. این ابزار مدل‌های PyTorch را به مدل‌های LiteRT چند امضایی ( .tflite ) صادر می‌کند، که با MediaPipe LLM Inference API سازگار هستند و برای اجرا در پشتیبان‌های CPU در برنامه‌های تلفن همراه مناسب هستند.

فایل .task نهایی یک بسته مستقل مورد نیاز MediaPipe است که شامل مدل LiteRT، مدل توکنایزر و ابرداده ضروری است. این بسته نرم افزاری ضروری است زیرا توکنایزر (که اعلان های متنی را به جاسازی توکن برای مدل تبدیل می کند) باید با مدل LiteRT بسته بندی شود تا استنتاج انتها به انتها را فعال کند.

در اینجا یک تفکیک گام به گام از این فرآیند است:

1. مدل Gemma خود را دریافت کنید

شما دو گزینه برای شروع دارید.

گزینه A. از یک مدل دقیق تنظیم شده موجود استفاده کنید

اگر یک مدل جما تنظیم شده را آماده کرده اید، فقط به مرحله بعدی بروید.

گزینه B. مدل رسمی تنظیم شده توسط دستورالعمل را دانلود کنید

اگر به یک مدل نیاز دارید، می توانید یک 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 تبدیل و کمی کنید

یک محیط مجازی پایتون راه اندازی کنید و آخرین نسخه پایدار بسته 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,
)

توجه داشته باشید که این فرآیند زمان بر است و به سرعت پردازش کامپیوتر شما بستگی دارد. برای مرجع، در یک CPU 8 هسته ای 2025، یک مدل 270M بیش از 5-10 دقیقه طول می کشد، در حالی که یک مدل 1B می تواند تقریباً 10-30 دقیقه طول بکشد.

خروجی نهایی، یک مدل LiteRT، در OUTPUT_DIR_PATH مشخص شده شما ذخیره خواهد شد.

مقادیر زیر را بر اساس محدودیت های حافظه و عملکرد دستگاه مورد نظر خود تنظیم کنید.

• kv_cache_max_len : کل اندازه تخصیص داده شده حافظه کاری مدل (حافظه پنهان KV) را تعریف می کند. این ظرفیت یک محدودیت سخت است و باید برای ذخیره مجموع ترکیبی از نشانه های درخواست (پیش پر کردن) و همه نشانه های تولید شده بعدی (رمزگشایی) کافی باشد.
• prefill_seq_len : تعداد توکن اعلان ورودی را برای تکه تکه شدن از قبل پر می کند. هنگام پردازش اعلان ورودی با استفاده از پر کردن تکه تکه کردن، کل دنباله (مثلاً 50000 توکن) یکباره محاسبه نمی شود. در عوض، به بخش‌های قابل مدیریت تقسیم می‌شود (به عنوان مثال، تکه‌هایی از 2048 توکن) که به‌طور متوالی در حافظه پنهان بارگذاری می‌شوند تا از خطای خارج از حافظه جلوگیری کنند.
• quantize : رشته ای برای طرح های کمی سازی انتخاب شده. در زیر لیستی از دستور العمل های کمی سازی موجود برای Gemma 3 آمده است.
  • none : بدون کوانتیزاسیون
  • fp16 : وزن FP16، فعال سازی FP32 و محاسبه ممیز شناور برای همه عملیات ها
  • dynamic_int8 : فعال سازی FP32، وزن INT8 و محاسبه عدد صحیح
  • weight_only_int8 : فعال سازی FP32، وزن INT8 و محاسبه ممیز شناور

3. یک Task Bundle از LiteRT و tokenizer ایجاد کنید

یک محیط مجازی پایتون راه اندازی کنید و بسته پایتون 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 در اندروید

کار را با گزینه های پیکربندی اولیه راه اندازی کنید:

// 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() برای ایجاد پاسخ متنی استفاده کنید.

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

برای استریم پاسخ، از متد generateResponseAsync() استفاده کنید.

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

برای اطلاعات بیشتر به راهنمای LLM Inference برای اندروید مراجعه کنید.

مراحل بعدی

با مدل های Gemma بیشتر بسازید و کاوش کنید:

• استقرار Gemma در دستگاه های تلفن همراه
• Gemma را برای کارهای متنی با استفاده از Transformers Hugging Face تنظیم کنید
• Gemma را برای کارهای بینایی با استفاده از Transformers Hugging Face تنظیم کنید
• تنظیم دقیق مدل کامل با استفاده از ترانسفورماتور Hugging Face