Environment:Alibaba MNN HuggingFace Ecosystem Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Model_Acquisition |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
External tool environment for downloading and preparing HuggingFace models for MNN conversion. Requires git-lfs, HuggingFace CLI, and sufficient disk storage.
Description
This environment defines the external tooling and system prerequisites needed to acquire pre-trained models from HuggingFace Hub before they are converted to MNN format. The primary workflow involves cloning model repositories using git with Large File Storage (LFS) enabled, as model weight files (*.bin, *.safetensors) are stored as LFS objects. Without git-lfs installed and initialized, git clone will download only LFS pointer files instead of the actual weight data, resulting in unusable model files. For gated models (e.g., Llama, Mistral), a HuggingFace access token is required. The huggingface-cli tool provides a convenient interface for authentication and model downloading, but direct git clone with LFS is also supported.
Usage
Use this environment as a prerequisite step before any model export or conversion workflow. Models must be fully downloaded (including all LFS-tracked weight files) before they can be passed to the MNN export scripts (llmexport.py, ONNX export, or diffusion export pipelines).
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Network | Internet access | Required for downloading models from HuggingFace Hub |
| Disk | 10-100GB | Depends on model size; large LLMs (7B+) require 15-30GB per model |
| Git | git with LFS support | git-lfs must be installed and initialized (git lfs install) |
| OS | Linux, macOS, Windows | Any OS with git-lfs support |
Dependencies
System Packages
- git (required; version control for cloning model repositories)
- git-lfs (required; Large File Storage extension for downloading model weight files)
Python Packages
- huggingface-cli (optional; HuggingFace Hub command-line tool for authentication and model downloading)
- transformers (optional; provides AutoModel.from_pretrained() as an alternative download method)
Credentials
WARNING: Never store actual secret values in wiki pages. Only document variable names and their purpose.
- HF_TOKEN: HuggingFace API token (optional). Required for downloading gated models (e.g., Llama, Mistral, Gemma). Obtain from https://huggingface.co/settings/tokens.
- huggingface-cli login: Alternative authentication method that stores the token in ~/.cache/huggingface/token.
Quick Install
# Install git-lfs
apt-get install git-lfs # Debian/Ubuntu
# or
brew install git-lfs # macOS
# Initialize git-lfs
git lfs install
# Download a public model
git clone https://huggingface.co/Qwen/Qwen2-1.5B /path/to/models/Qwen2-1.5B
# Download a gated model (requires HF_TOKEN)
export HF_TOKEN="hf_your_token_here"
git clone https://$HF_TOKEN@huggingface.co/meta-llama/Llama-2-7b-hf /path/to/models/Llama-2-7b-hf
# Alternative: use huggingface-cli
pip install huggingface_hub
huggingface-cli login
huggingface-cli download Qwen/Qwen2-1.5B --local-dir /path/to/models/Qwen2-1.5B
Code Evidence
MNN LLM documentation references git-lfs requirement for model download from docs/transformers/llm.md:
# Download the model using git-lfs
git lfs install
git clone https://huggingface.co/<model_org>/<model_name>
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| Model files incomplete (pointer files instead of weights) | git-lfs not installed or not initialized before cloning | Install git-lfs, run git lfs install, then re-clone the repository or run git lfs pull in the existing clone |
| 403 Forbidden or Access denied on gated model | Missing or invalid HuggingFace token for a gated model | Set HF_TOKEN environment variable with a valid token that has accepted the model license agreement |
| Disk space exhausted during download | Insufficient storage for large model weights | Free up disk space or use an external drive; large models (7B+) require 15-30GB |
| git lfs: command not found | git-lfs package not installed on the system | Install git-lfs via package manager: apt-get install git-lfs or brew install git-lfs |
| Slow or interrupted download | Network instability or HuggingFace rate limiting | Retry the download; use huggingface-cli download with --resume-download for resumable transfers |
Compatibility Notes
- git-lfs: Must be installed and initialized (git lfs install) before cloning any model repository. Cloning without git-lfs produces unusable pointer files.
- Gated models: Require accepting the model license on the HuggingFace website and providing a valid HF_TOKEN during download.
- huggingface-cli: Provides resumable downloads and better progress tracking compared to raw git clone. Recommended for large models.
- Disk usage: Models are stored twice during conversion (original HuggingFace format + exported MNN format). Plan for 2x the model size in available disk space.
- Offline usage: Once models are downloaded, no internet access is needed for the subsequent MNN export and conversion steps.