Implementation:Mlc ai Mlc llm Bundle weight

Knowledge Sources	MLC-LLM
Domains	Deep_Learning, Mobile_Deployment
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for deploying model artifacts (APK and bundled weights) to a physical Android device for on-device inference testing and validation provided by MLC-LLM.

Description

The bundle_weight.py script automates the Android on-device deployment workflow by performing three operations in sequence:

1. APK Installation: Installs the compiled MLCChat APK to a connected Android device using adb install.
2. Data Directory Creation: Creates the application's external files directory on the device at /storage/emulated/0/Android/data/ai.mlc.mlcchat/files/ using adb shell mkdir -p.
3. Weight Transfer: For each model weight directory found in the package output's bundle/ folder, the script pushes the weights to a temporary staging location (/data/local/tmp/<model_id>) via adb push, then moves them to the application's files directory via adb shell mv. This two-step approach is necessary because ADB cannot write directly to app-private storage on modern Android versions.

The script expects the output directory structure produced by the mlc_llm package command, where bundled model weights reside under <package_output_path>/bundle/<model_id>/.

Usage

Use this script when:

• Deploying a newly built MLCChat APK with pre-compiled model weights to a physical Android device
• Iterating on model compilation and testing on-device inference performance
• Setting up Android devices for demonstrations or benchmarking of on-device LLM inference
• Automating device deployment in a CI/CD pipeline for mobile LLM testing

Code Reference

Source Location

• Repository: MLC-LLM
• File: android/MLCChat/bundle_weight.py (Lines 12-36)

Signature

def main(apk_path: Path, package_output_path: Path):
    """Push weights to the android device with adb.

    Parameters
    ----------
    apk_path : Path
        Path to the compiled MLCChat APK file.
    package_output_path : Path
        Path to the output directory of "mlc_llm package",
        containing the bundle/ subdirectory with model weights.
    """

Command-line invocation:

python android/MLCChat/bundle_weight.py \
    --apk-path <path_to_apk> \
    --package-output-path <path_to_package_output>

I/O Contract

Inputs

Name	Type	Required	Description
apk_path / --apk-path	Path	No	Path to the MLCChat APK file to install (default: app/release/app-release.apk)
package_output_path / --package-output-path	Path	No	Path to the output directory of mlc_llm package (default: dist)

Prerequisites:

• A connected Android device with USB debugging enabled
• adb available on the system PATH
• The APK file must exist at the specified path
• The package_output_path/bundle/ directory must contain model weight subdirectories

Outputs

Name	Type	Description
Installed APK	Android application	The MLCChat application installed on the connected device
Device weight directory	Device filesystem	Model weights transferred to /storage/emulated/0/Android/data/ai.mlc.mlcchat/files/<model_id>/ on the device

Usage Examples

Basic Usage with Defaults

# From the android/MLCChat directory, after building the APK and running mlc_llm package
cd android/MLCChat
python bundle_weight.py

This uses the default paths:

• APK: app/release/app-release.apk
• Package output: dist

Custom Paths

python android/MLCChat/bundle_weight.py \
    --apk-path /path/to/app-release.apk \
    --package-output-path /path/to/dist

Full End-to-End Android Deployment Workflow

# Step 1: Package the models for Android
mlc_llm package \
    --package-config android/MLCChat/mlc-package-config.json \
    --mlc-llm-source-dir /path/to/mlc-llm \
    --output dist/

# Step 2: Build the Android APK in Android Studio or via Gradle
cd android/MLCChat
./gradlew assembleRelease

# Step 3: Deploy APK and weights to a connected device
python bundle_weight.py \
    --apk-path app/release/app-release.apk \
    --package-output-path dist/

Verify Deployment

# Check that weights were transferred successfully
adb shell ls /storage/emulated/0/Android/data/ai.mlc.mlcchat/files/

# Expected output: directories for each bundled model
# Llama-3.2-3B-Instruct-q4f16_1-MLC
# gemma-2-2b-it-q4f16_1-MLC
# ...

Related Pages

Implements Principle

• Principle:Mlc_ai_Mlc_llm_On_Device_Deployment

Environment Links

• Environment:Mlc_ai_Mlc_llm_OpenCL_Android_Environment