0
# Model Management
1

2
Comprehensive utilities for downloading, storing, and managing pre-trained models and model packs. Handles automatic downloads, local caching, and model availability checks for seamless model deployment.
3

4
## Capabilities
5

6
### Download and Storage Functions
7

8
Core functions for model download and local storage management.
9

10
```python { .api }
11
def download(sub_dir, name, force=False, root='~/.insightface') -> str:
12
    """
13
    Download model or model pack to local storage.
14
    
15
    Parameters:
16
    - sub_dir: str, subdirectory within root ('models', 'objects', etc.)
17
    - name: str, model pack or file name to download
18
    - force: bool, force re-download even if already exists
19
    - root: str, root directory for insightface storage
20
    
21
    Returns:
22
    str: path to downloaded content
23
    """
24

25
def ensure_available(sub_dir, name, root='~/.insightface') -> str:
26
    """
27
    Ensure model is available locally, download if necessary.
28
    
29
    Parameters:
30
    - sub_dir: str, subdirectory for model storage
31
    - name: str, model name to ensure availability
32
    - root: str, root storage directory
33
    
34
    Returns:
35
    str: path to model directory or file
36
    """
37

38
def download_onnx(sub_dir, model_file, force=False, root='~/.insightface', download_zip=False) -> str:
39
    """
40
    Download specific ONNX model file.
41
    
42
    Parameters:
43
    - sub_dir: str, storage subdirectory
44
    - model_file: str, ONNX model filename
45
    - force: bool, force re-download
46
    - root: str, root storage directory
47
    - download_zip: bool, download as zip archive
48
    
49
    Returns:
50
    str: path to downloaded ONNX file
51
    """
52

53
def get_model_file(name, root='~/.insightface/models') -> str:
54
    """
55
    Get location for pretrained model on local file system.
56
    
57
    Downloads from online model zoo if model cannot be found or has hash mismatch.
58
    The root directory will be created if it doesn't exist.
59
    
60
    Parameters:
61
    - name: str, name of the model
62
    - root: str, location for keeping model parameters
63
    
64
    Returns:
65
    str: path to the requested pretrained model file
66
    """
67
```
68

69
### Filesystem Utilities
70

71
Functions for managing local model storage and directory operations.
72

73
```python { .api }
74
def get_model_dir(name, root='~/.insightface') -> str:
75
    """
76
    Get model directory path for given model pack.
77
    
78
    Parameters:
79
    - name: str, model pack name
80
    - root: str, root storage directory
81
    
82
    Returns:
83
    str: full path to model directory
84
    """
85

86
def makedirs(path) -> None:
87
    """
88
    Create directory structure recursively.
89
    
90
    Parameters:
91
    - path: str, directory path to create
92
    """
93
```
94

95
### Package Import Utilities
96

97
Helper functions for managing optional dependencies and package imports.
98

99
```python { .api }
100
def try_import(package, message=None) -> module:
101
    """
102
    Attempt to import package with graceful failure.
103
    
104
    Parameters:
105
    - package: str, package name to import
106
    - message: str, custom error message if import fails
107
    
108
    Returns:
109
    module: imported module or None if failed
110
    """
111

112
def try_import_cv2() -> module:
113
    """Try to import OpenCV (cv2) with helpful error message."""
114

115
def try_import_mmcv() -> module:  
116
    """Try to import MMCV library."""
117

118
def try_import_rarfile() -> module:
119
    """Try to import rarfile for RAR archive support."""
120

121
def import_try_install(package, extern_url=None) -> module:
122
    """
123
    Import package and attempt installation if not found.
124
    
125
    Parameters:
126
    - package: str, package name
127
    - extern_url: str, external installation URL if pip fails
128
    
129
    Returns:
130
    module: imported module
131
    """
132

133
def try_import_dali() -> module:
134
    """Try to import NVIDIA DALI for accelerated data loading."""
135
```
136

137
### File Download Utilities
138

139
Low-level utilities for downloading files from URLs with integrity checking.
140

141
```python { .api }
142
def check_sha1(filename, sha1_hash) -> bool:
143
    """
144
    Check SHA1 hash of downloaded file.
145
    
146
    Parameters:
147
    - filename: str, path to file to check
148
    - sha1_hash: str, expected SHA1 hash
149
    
150
    Returns:
151
    bool: True if hash matches, False otherwise
152
    """
153

154
def download_file(url, path=None, overwrite=False, sha1_hash=None) -> str:
155
    """
156
    Download file from URL with optional integrity checking.
157
    
158
    Parameters:
159
    - url: str, URL to download from
160
    - path: str, local path to save file (optional)
161
    - overwrite: bool, overwrite existing file
162
    - sha1_hash: str, expected SHA1 hash for verification
163
    
164
    Returns:
165
    str: path to downloaded file
166
    """
167
```
168

169
### Constants and Configuration
170

171
Default configuration values and model pack names.
172

173
```python { .api }
174
DEFAULT_MP_NAME = 'buffalo_l'  # Default model pack name
175
```
176

177
### Command Line Interface
178

179
CLI commands for model management operations.
180

181
```python { .api }
182
class ModelDownloadCommand:
183
    def __init__(self, model: str, root: str, force: bool):
184
        """
185
        Initialize model download command.
186
        
187
        Parameters:
188
        - model: str, model pack name to download
189
        - root: str, storage root directory
190
        - force: bool, force re-download
191
        """
192
    
193
    def run(self) -> None:
194
        """Execute model download."""
195

196
def main() -> None:
197
    """Main CLI entry point for insightface-cli command."""
198
```
199

200
## Usage Examples
201

202
### Basic Model Download
203

204
```python
205
from insightface.utils import download, ensure_available
206

207
# Download default model pack
208
model_path = download('models', 'buffalo_l')
209
print(f"Model downloaded to: {model_path}")
210

211
# Ensure model is available (download if needed)
212
model_dir = ensure_available('models', 'buffalo_s')
213
print(f"Model available at: {model_dir}")
214

215
# List files in model directory
216
import os
217
model_files = os.listdir(model_dir)
218
print(f"Model files: {model_files}")
219
```
220

221
### Custom Storage Location
222

223
```python
224
# Use custom storage directory
225
custom_root = './my_models'
226
model_path = download('models', 'buffalo_m', root=custom_root)
227

228
# Check model directory structure
229
from insightface.utils import get_model_dir
230
model_dir = get_model_dir('buffalo_m', root=custom_root)
231
print(f"Custom model directory: {model_dir}")
232
```
233

234
### Download Specific ONNX Models
235

236
```python
237
from insightface.utils import download_onnx
238

239
# Download specific ONNX model
240
onnx_path = download_onnx('models/buffalo_l', 'det_10g.onnx')
241
print(f"Downloaded ONNX model: {onnx_path}")
242

243
# Download as zip archive
244
zip_path = download_onnx('models', 'arcface_r100_v1.onnx', download_zip=True)
245
print(f"Downloaded zip archive: {zip_path}")
246
```
247

248
### Model Availability Check
249

250
```python
251
import os
252
from insightface.utils import get_model_dir
253

254
def check_model_availability(model_name, root='~/.insightface'):
255
    """Check if model pack is available locally."""
256
    model_dir = get_model_dir(model_name, root)
257
    
258
    if os.path.exists(model_dir):
259
        # List available ONNX files
260
        onnx_files = [f for f in os.listdir(model_dir) if f.endswith('.onnx')]
261
        print(f"Model '{model_name}' available with {len(onnx_files)} ONNX files:")
262
        for onnx_file in onnx_files:
263
            print(f"  - {onnx_file}")
264
        return True
265
    else:
266
        print(f"Model '{model_name}' not found locally")
267
        return False
268

269
# Check multiple models
270
models_to_check = ['buffalo_l', 'buffalo_m', 'buffalo_s', 'antelopev2']
271
for model in models_to_check:
272
    check_model_availability(model)
273
    print()
274
```
275

276
### Force Model Re-download
277

278
```python
279
# Force re-download of model pack (useful for updates)
280
fresh_model_path = download('models', 'buffalo_l', force=True)
281
print(f"Fresh model downloaded to: {fresh_model_path}")
282

283
# Force re-download specific ONNX file
284
fresh_onnx = download_onnx('models/buffalo_l', 'w600k_r50.onnx', force=True)
285
print(f"Fresh ONNX model: {fresh_onnx}")
286
```
287

288
### Dependency Management
289

290
```python
291
from insightface.utils import try_import, import_try_install
292

293
# Try importing optional dependencies
294
cv2 = try_import('cv2', 'OpenCV is required for image processing')
295
if cv2:
296
    print("OpenCV available")
297

298
# Import with auto-install attempt
299
try:
300
    mmcv = import_try_install('mmcv')
301
    print("MMCV imported successfully")
302
except ImportError as e:
303
    print(f"Could not import MMCV: {e}")
304

305
# Check for GPU acceleration libraries
306
dali = try_import('nvidia.dali', 'DALI not available - using standard data loading')
307
if dali:
308
    print("NVIDIA DALI available for accelerated data loading")
309
```
310

311
### File Integrity Verification
312

313
```python
314
from insightface.utils import check_sha1, download_file
315

316
# Download file with integrity check
317
url = 'https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_l.zip'
318
expected_hash = 'a1b2c3d4e5f6...'  # Expected SHA1 hash
319

320
try:
321
    file_path = download_file(url, path='./buffalo_l.zip', sha1_hash=expected_hash)
322
    print(f"File downloaded and verified: {file_path}")
323
except Exception as e:
324
    print(f"Download or verification failed: {e}")
325

326
# Verify existing file
327
if check_sha1('./buffalo_l.zip', expected_hash):
328
    print("File integrity verified")
329
else:
330
    print("File integrity check failed")
331
```
332

333
### CLI Usage Examples
334

335
```bash
336
# Download model pack via CLI
337
insightface-cli model.download buffalo_l
338

339
# Download to custom directory
340
insightface-cli model.download buffalo_s --root ./my_models
341

342
# Force re-download
343
insightface-cli model.download buffalo_m --force
344

345
# Add mask parameters to recognition dataset
346
insightface-cli rec.add_mask_param --input dataset.rec --output masked_dataset.rec
347
```
348

349
### Model Management Utilities
350

351
```python
352
def list_available_models(root='~/.insightface'):
353
    """List all locally available model packs."""
354
    import os
355
    from insightface.utils import get_model_dir
356
    
357
    models_dir = os.path.expanduser(os.path.join(root, 'models'))
358
    if not os.path.exists(models_dir):
359
        print("No models directory found")
360
        return []
361
    
362
    available_models = []
363
    for item in os.listdir(models_dir):
364
        model_path = os.path.join(models_dir, item)
365
        if os.path.isdir(model_path):
366
            # Count ONNX files
367
            onnx_count = len([f for f in os.listdir(model_path) if f.endswith('.onnx')])
368
            available_models.append((item, onnx_count))
369
    
370
    return available_models
371

372
def cleanup_old_models(root='~/.insightface', keep_latest=2):
373
    """Clean up old model versions, keeping only the latest."""
374
    available = list_available_models(root)
375
    
376
    # Sort by modification time and keep latest
377
    # Implementation would depend on specific versioning scheme
378
    print(f"Found {len(available)} model packs")
379
    for model_name, onnx_count in available:
380
        print(f"  {model_name}: {onnx_count} ONNX files")
381

382
# List available models
383
models = list_available_models()
384
print("Available model packs:")
385
for name, count in models:
386
    print(f"  {name}: {count} models")
387
```
388

389
### Advanced Model Setup
390

391
```python
392
def setup_models_for_production(models_needed=['buffalo_l'], root='./production_models'):
393
    """Set up models for production deployment."""
394
    from insightface.utils import download, makedirs
395
    
396
    # Create production directory
397
    makedirs(root)
398
    
399
    downloaded_models = {}
400
    for model_name in models_needed:
401
        try:
402
            print(f"Setting up {model_name}...")
403
            model_path = download('models', model_name, root=root)
404
            downloaded_models[model_name] = model_path
405
            print(f"✓ {model_name} ready")
406
        except Exception as e:
407
            print(f"✗ Failed to setup {model_name}: {e}")
408
    
409
    return downloaded_models
410

411
# Setup for production
412
production_models = setup_models_for_production(['buffalo_l', 'buffalo_s'])
413
print(f"Production setup complete. Models: {list(production_models.keys())}")
414
```