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:
  repositories:
    reflectorch:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "b_mc_point_xray_conv_standard_L2_InputQ"
          config: "configs/b_mc_point_xray_conv_standard_L2_InputQ.yaml"
          weights: "saved_models/model_b_mc_point_xray_conv_standard_L2_InputQ.safetensors"
        - name: "model_b_mc_point_neutron_conv_standard_L1_InputQDq"
          config: "configs/b_mc_point_neutron_conv_standard_L1_InputQDq.yaml"
          weights: "saved_models/model_b_mc_point_neutron_conv_standard_L1_InputQDq.safetensors"
        - name: "e_mc_point_neutron_conv_standard_L1_InputQDq_n256_size1024"
          config: "configs/e_mc_point_neutron_conv_standard_L1_InputQDq_n256_size1024.yaml"
          weights: "saved_models/model_e_mc_point_neutron_conv_standard_L1_InputQDq_n256_size1024.safetensors"
        - name: "b_mc_point_neutron_conv_standard_L2_InputQDq"
          config: "configs/b_mc_point_neutron_conv_standard_L2_InputQDq.yaml"
          weights: "saved_models/model_b_mc_point_neutron_conv_standard_L2_InputQDq.safetensors"
        - name: "g_mc_point_xray_intconv_standard_L2_InputQ_size1024"
          config: "configs/g_mc_point_xray_intconv_standard_L2_InputQ_size1024.yaml"
          weights: "saved_models/model_g_mc_point_xray_intconv_standard_L2_InputQ_size1024.safetensors"

    panpe:
      repo_id: "HW-SC/panpe-xrr-reflectometry"
      models:
        - name: "panpe-2layers-xrr"
          config: "configs/panpe-2layers-xrr.yaml"
          weights: "saved_models/model_panpe-2layers-xrr.pt"

Configuration Fields¶

Field	Type	Description
`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 variable mechanisms control where models are stored:

HF_HOME - General HuggingFace cache directory (if unset, plugin uses a temporary directory):

export HF_HOME=${PWD}/storage/huggingface_cache

root_dir_env_var - Environment variable that defines the persistent local model root for a configured repository.

In the current VIPR configuration, both reflectometry repositories use the shared reflectometry root:

reflectorch -> REFLECTOMETRY_ROOT_DIR
panpe -> REFLECTOMETRY_ROOT_DIR

Example:

export REFLECTOMETRY_ROOT_DIR=${PWD}/storage/reflectometry

Directory Structure¶

With REFLECTOMETRY_ROOT_DIR set, reflectometry models are organized as:

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

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:
  repositories:
    reflectorch:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "b_mc_point_xray_conv_standard_L2_InputQ"
          config: "configs/b_mc_point_xray_conv_standard_L2_InputQ.yaml"
          weights: "saved_models/model_b_mc_point_xray_conv_standard_L2_InputQ.safetensors"
        - name: "b_mc_point_neutron_conv_standard_L2_InputQDq"
          config: "configs/b_mc_point_neutron_conv_standard_L2_InputQDq.yaml"
          weights: "saved_models/model_b_mc_point_neutron_conv_standard_L2_InputQDq.safetensors"

    panpe:
      repo_id: "HW-SC/panpe-xrr-reflectometry"
      models:
        - name: "panpe-2layers-xrr"
          config: "configs/panpe-2layers-xrr.yaml"
          weights: "saved_models/model_panpe-2layers-xrr.pt"

Download Behavior¶

vipr --config huggingface.yaml huggingface download always attempts to download all configured models.
Existing files are skipped automatically (unless forced in code).
In API startup, downloads are triggered in vipr_api.main.lifespan() via runner.run_controller("huggingface", "download", ...).
This startup download can be disabled via:

export VIPR_NO_MODEL_DOWNLOAD=true