HuggingFace Plugin¶

Automatic model management and download from HuggingFace repositories.

Overview¶

Enabled by Default: Manages HuggingFace model downloads with automatic caching. Supports multiple repositories and models with configurable paths for weights and config files.

Configuration¶

Configure models in huggingface.yaml:

plugin.huggingface:
  enabled: true

huggingface:
  auto_download: true  # Automatically download models on startup
  repositories:
    reflectorch:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "model_name"
          config: "configs/model_config.yaml"
          weights: "saved_models/model_weights.safetensors"
    
    my_custom_repo:
      repo_id: "organization/repository-name"
      models:
        - name: "my_model"
          config: "path/to/config.yaml"
          weights: "path/to/weights.pt"

Configuration Fields¶

Field	Type	Description
`auto_download`	`bool`	Enable automatic model download on startup
`repositories`	`dict`	Collection of HuggingFace repositories
`repo_id`	`str`	HuggingFace repository identifier (org/repo)
`models`	`list`	List of models to download from repository
`name`	`str`	Model identifier for your application
`config`	`str`	Path to config file in repository
`weights`	`str`	Path to model weights in repository

Model Storage¶

Environment Variables¶

Two environment variables control where models are stored:

HF_HOME - General HuggingFace cache directory (default: ~/.cache/huggingface):

export HF_HOME=${PWD}/storage/huggingface_cache

REFLECTORCH_ROOT_DIR - Reflectorch-specific storage directory (required for reflectorch models):

export REFLECTORCH_ROOT_DIR=${PWD}/storage/reflectorch

Directory Structure¶

With REFLECTORCH_ROOT_DIR set, reflectorch models are organized as:

storage/reflectorch/
├── saved_models/     # Model weights (.safetensors, .pt)
└── configs/          # Model configuration files (.yaml)

Other models use the standard HuggingFace cache structure in HF_HOME.

CLI Commands¶

Download Models¶

Manually trigger model downloads:

vipr --config huggingface.yaml huggingface download

This downloads all configured models from HuggingFace repositories to the local cache.

Use Cases:

Pre-deployment: Download models before production
Offline scenarios: Cache models for air-gapped environments
CI/CD: Prepare models during build process

Adding Custom Models¶

Step 1: Identify Repository¶

Find your model on HuggingFace: https://huggingface.co/organization/repository-name

Step 2: Add to Configuration¶

huggingface:
  repositories:
    my_project:  # Unique identifier for your use
      repo_id: "organization/repository-name"  # HuggingFace repo
      models:
        - name: "my_model_identifier"  # Name used in your code
          config: "path/in/repo/config.yaml"
          weights: "path/in/repo/model.safetensors"

Step 3: Download¶

vipr --config huggingface.yaml huggingface download

Supported Weight Formats¶

.safetensors - Recommended format (faster, safer, no pickle)
.pt - Standard PyTorch format
.bin - Older PyTorch format (pickle-based)

Example: Multiple Models¶

huggingface:
  auto_download: true
  repositories:
    xray_models:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "xray_standard"
          config: "configs/xray_config.yaml"
          weights: "saved_models/xray_model.safetensors"
        - name: "xray_advanced"
          config: "configs/xray_advanced_config.yaml"
          weights: "saved_models/xray_advanced_model.safetensors"
    
    neutron_models:
      repo_id: "organization/neutron-analysis"
      models:
        - name: "neutron_standard"
          config: "configs/neutron.yaml"
          weights: "models/neutron.pt"

Disabling Auto-Download¶

For manual control over downloads:

huggingface:
  auto_download: false  # Disable automatic downloads

Then manually download when needed:

vipr --config huggingface.yaml huggingface download