Skip to content

Model Management

OxideShield uses HuggingFace transformer models for security analysis. The models CLI command lets you pre-download, inspect, and verify these models.

License Required

The models command requires the pro feature flag.

Models Overview

Model Purpose
Embedding model Semantic similarity embeddings
Primary classifier Prompt injection classification
Compact classifier Adversarial prompt detection

Model IDs and download details are available via the CLI (oxideshield models status) or to licensed users.

Pre-downloading Models

Download all models to the local HuggingFace cache before deployment:

# Download all models
oxideshield models download

# Download a specific model
oxideshield models download --model "DeBERTa"
oxideshield models download --model "llama"
oxideshield models download --model "minilm"

Llama Guard Gated Access

Llama Prompt Guard 2 is a gated model. Before downloading:

  1. Create a HuggingFace account
  2. Visit the Llama Prompt Guard 2 model page on HuggingFace
  3. Accept the Llama Community License
  4. Generate an access token at Settings > Access Tokens
  5. Set the environment variable:
export HF_TOKEN=hf_your_token_here

Cache Location

Models are stored in the HuggingFace Hub cache:

# Show cache paths
oxideshield models path

Default locations:

Platform Default Path
Linux ~/.cache/huggingface/hub/
macOS ~/.cache/huggingface/hub/
Windows C:\Users\<user>\.cache\huggingface\hub\

Environment Variables

Variable Description
HF_HOME Override HuggingFace home directory
HF_TOKEN Authentication token (required for gated models)
XDG_CACHE_HOME Override XDG cache base (Linux)

Checking Status

View which models are cached:

oxideshield models status

Output shows a table with model name, size, and cache status (cached/not cached/access denied).

Integrity Verification

Verify that cached model files are not corrupt:

oxideshield models verify

This memory-maps each model.safetensors file and validates:

  • File is large enough to contain a valid header
  • Header size is consistent with file size
  • Header JSON parses correctly
  • At least one tensor is present

Air-Gapped Deployment

For environments without internet access:

1. Download on a connected machine

# Download all models
oxideshield models download

# Verify integrity
oxideshield models verify

# Show cache location
oxideshield models path

2. Copy the cache

# Find the cache directory
CACHE_DIR=$(oxideshield models path | grep "Hub models" | awk '{print $NF}')

# Archive the model directories
tar -czf oxideshield-models.tar.gz -C "$CACHE_DIR" .

3. Deploy to air-gapped system

# Extract to the same cache location
mkdir -p ~/.cache/huggingface/hub
tar -xzf oxideshield-models.tar.gz -C ~/.cache/huggingface/hub/

# Verify integrity
oxideshield models verify

4. Use local paths directly

For maximum control, use from_local_path() on the classifier types:

use oxide_embeddings::Classifier;

// Load classifiers from local paths (air-gapped deployment)
let primary = Classifier::from_local_path("/opt/models/primary-classifier").await?;
let secondary = Classifier::from_local_path("/opt/models/secondary-classifier").await?;

Troubleshooting

"Access denied" for Llama Guard

Ensure you have:

  1. Set HF_TOKEN environment variable
  2. Accepted the license at the model page
  3. Used a token with "Read" permission

Slow downloads

Models are downloaded from HuggingFace Hub CDN. For faster downloads:

  • Use a wired connection
  • Set HF_HUB_ENABLE_HF_TRANSFER=1 with pip install hf_transfer for faster transfers

Verification failures

If models verify reports corruption:

# Re-download the specific model
oxideshield models download --model "ModelName"

# Verify again
oxideshield models verify