Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
orchestra-research avatar

Sparse Autoencoder Training

  • 400 installs
  • 11.2k repo stars
  • Updated June 16, 2026
  • orchestra-research/ai-research-skills

sparse-autoencoder-training is a Claude Code skill that loads, trains, and inspects sparse autoencoders with SAELens so developers who analyze language-model activations can run interpretability and feature-analysis work

About

sparse-autoencoder-training is an Orchestra Research skill for SAELens sparse autoencoder workflows on transformer activations. The skill documents SAE.from_pretrained loading from official releases such as gpt2-small-res-jb, HuggingFace repos, or local disk paths, plus core attributes including W_enc and W_dec weight matrices with documented shapes. Developers reach for sparse-autoencoder-training when they need feature dictionaries, sparsity metrics, and activation decomposition for mechanistic interpretability on hooks like blocks.8.hook_resid_pre. The guide covers pretrained SAE retrieval, CUDA device placement, and inspection patterns for encoder-decoder weights and sparsity statistics.

  • SAE.from_pretrained for official releases, HuggingFace repos, and local disk
  • Core encode, decode, and forward paths with documented tensor shapes
  • SAEConfig parameters for architecture and training context
  • save_model and load_from_disk for reproducible artifact handoff
  • CUDA-oriented loading patterns in reference snippets

Sparse Autoencoder Training by the numbers

  • 400 all-time installs (skills.sh)
  • +35 installs in the week ending Jul 18, 2026 (Skillselion tracking)
  • Ranked #492 of 2,066 Data Science & ML skills by installs in the Skillselion catalog
  • Security screen: MEDIUM risk (skills.sh audit)
  • Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/orchestra-research/ai-research-skills --skill sparse-autoencoder-training

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs400
repo stars11.2k
Security audit2 / 3 scanners passed
Last updatedJune 16, 2026
Repositoryorchestra-research/ai-research-skills

How do you train sparse autoencoders on LM activations?

Load, train, and inspect sparse autoencoders with SAELens for interpretability and feature analysis on language-model activations.

Who is it for?

Interpretability researchers working with SAELens on GPT-style or Hugging Face language-model activation hooks.

Skip if: Application developers shipping standard RAG or chat features with no activation-level feature analysis requirements.

When should I use this skill?

A developer asks to load a pretrained SAE, train sparse autoencoders with SAELens, or inspect W_enc and W_dec features on LM activations.

What you get

Loaded SAE weights (W_enc, W_dec), sparsity metrics, cfg_dict, and feature-analysis scripts for transformer hooks.

  • Loaded SAE checkpoint
  • sparsity report
  • feature weight inspection notebook or script

Files

SKILL.mdMarkdownGitHub ↗

SAELens: Sparse Autoencoders for Mechanistic Interpretability

SAELens is the primary library for training and analyzing Sparse Autoencoders (SAEs) - a technique for decomposing polysemantic neural network activations into sparse, interpretable features. Based on Anthropic's groundbreaking research on monosemanticity.

GitHub: jbloomAus/SAELens (1,100+ stars)

The Problem: Polysemanticity & Superposition

Individual neurons in neural networks are polysemantic - they activate in multiple, semantically distinct contexts. This happens because models use superposition to represent more features than they have neurons, making interpretability difficult.

SAEs solve this by decomposing dense activations into sparse, monosemantic features - typically only a small number of features activate for any given input, and each feature corresponds to an interpretable concept.

When to Use SAELens

Use SAELens when you need to:

  • Discover interpretable features in model activations
  • Understand what concepts a model has learned
  • Study superposition and feature geometry
  • Perform feature-based steering or ablation
  • Analyze safety-relevant features (deception, bias, harmful content)

Consider alternatives when:

  • You need basic activation analysis → Use TransformerLens directly
  • You want causal intervention experiments → Use pyvene or TransformerLens
  • You need production steering → Consider direct activation engineering

Installation

pip install sae-lens

Requirements: Python 3.10+, transformer-lens>=2.0.0

Core Concepts

What SAEs Learn

SAEs are trained to reconstruct model activations through a sparse bottleneck:

Input Activation → Encoder → Sparse Features → Decoder → Reconstructed Activation
    (d_model)       ↓        (d_sae >> d_model)    ↓         (d_model)
                 sparsity                      reconstruction
                 penalty                          loss

Loss Function: MSE(original, reconstructed) + L1_coefficient × L1(features)

Key Validation (Anthropic Research)

In "Towards Monosemanticity", human evaluators found 70% of SAE features genuinely interpretable. Features discovered include:

  • DNA sequences, legal language, HTTP requests
  • Hebrew text, nutrition statements, code syntax
  • Sentiment, named entities, grammatical structures

Workflow 1: Loading and Analyzing Pre-trained SAEs

Step-by-Step

from transformer_lens import HookedTransformer
from sae_lens import SAE

# 1. Load model and pre-trained SAE
model = HookedTransformer.from_pretrained("gpt2-small", device="cuda")
sae, cfg_dict, sparsity = SAE.from_pretrained(
    release="gpt2-small-res-jb",
    sae_id="blocks.8.hook_resid_pre",
    device="cuda"
)

# 2. Get model activations
tokens = model.to_tokens("The capital of France is Paris")
_, cache = model.run_with_cache(tokens)
activations = cache["resid_pre", 8]  # [batch, pos, d_model]

# 3. Encode to SAE features
sae_features = sae.encode(activations)  # [batch, pos, d_sae]
print(f"Active features: {(sae_features > 0).sum()}")

# 4. Find top features for each position
for pos in range(tokens.shape[1]):
    top_features = sae_features[0, pos].topk(5)
    token = model.to_str_tokens(tokens[0, pos:pos+1])[0]
    print(f"Token '{token}': features {top_features.indices.tolist()}")

# 5. Reconstruct activations
reconstructed = sae.decode(sae_features)
reconstruction_error = (activations - reconstructed).norm()

Available Pre-trained SAEs

ReleaseModelLayers
gpt2-small-res-jbGPT-2 SmallMultiple residual streams
gemma-2b-resGemma 2BResidual streams
Various on HuggingFaceSearch tag saelensVarious

Checklist

  • [ ] Load model with TransformerLens
  • [ ] Load matching SAE for target layer
  • [ ] Encode activations to sparse features
  • [ ] Identify top-activating features per token
  • [ ] Validate reconstruction quality

Workflow 2: Training a Custom SAE

Step-by-Step

from sae_lens import SAE, LanguageModelSAERunnerConfig, SAETrainingRunner

# 1. Configure training
cfg = LanguageModelSAERunnerConfig(
    # Model
    model_name="gpt2-small",
    hook_name="blocks.8.hook_resid_pre",
    hook_layer=8,
    d_in=768,  # Model dimension

    # SAE architecture
    architecture="standard",  # or "gated", "topk"
    d_sae=768 * 8,  # Expansion factor of 8
    activation_fn="relu",

    # Training
    lr=4e-4,
    l1_coefficient=8e-5,  # Sparsity penalty
    l1_warm_up_steps=1000,
    train_batch_size_tokens=4096,
    training_tokens=100_000_000,

    # Data
    dataset_path="monology/pile-uncopyrighted",
    context_size=128,

    # Logging
    log_to_wandb=True,
    wandb_project="sae-training",

    # Checkpointing
    checkpoint_path="checkpoints",
    n_checkpoints=5,
)

# 2. Train
trainer = SAETrainingRunner(cfg)
sae = trainer.run()

# 3. Evaluate
print(f"L0 (avg active features): {trainer.metrics['l0']}")
print(f"CE Loss Recovered: {trainer.metrics['ce_loss_score']}")

Key Hyperparameters

ParameterTypical ValueEffect
d_sae4-16× d_modelMore features, higher capacity
l1_coefficient5e-5 to 1e-4Higher = sparser, less accurate
lr1e-4 to 1e-3Standard optimizer LR
l1_warm_up_steps500-2000Prevents early feature death

Evaluation Metrics

MetricTargetMeaning
L050-200Average active features per token
CE Loss Score80-95%Cross-entropy recovered vs original
Dead Features<5%Features that never activate
Explained Variance>90%Reconstruction quality

Checklist

  • [ ] Choose target layer and hook point
  • [ ] Set expansion factor (d_sae = 4-16× d_model)
  • [ ] Tune L1 coefficient for desired sparsity
  • [ ] Enable L1 warm-up to prevent dead features
  • [ ] Monitor metrics during training (W&B)
  • [ ] Validate L0 and CE loss recovery
  • [ ] Check dead feature ratio

Workflow 3: Feature Analysis and Steering

Analyzing Individual Features

from transformer_lens import HookedTransformer
from sae_lens import SAE
import torch

model = HookedTransformer.from_pretrained("gpt2-small", device="cuda")
sae, _, _ = SAE.from_pretrained(
    release="gpt2-small-res-jb",
    sae_id="blocks.8.hook_resid_pre",
    device="cuda"
)

# Find what activates a specific feature
feature_idx = 1234
test_texts = [
    "The scientist conducted an experiment",
    "I love chocolate cake",
    "The code compiles successfully",
    "Paris is beautiful in spring",
]

for text in test_texts:
    tokens = model.to_tokens(text)
    _, cache = model.run_with_cache(tokens)
    features = sae.encode(cache["resid_pre", 8])
    activation = features[0, :, feature_idx].max().item()
    print(f"{activation:.3f}: {text}")

Feature Steering

def steer_with_feature(model, sae, prompt, feature_idx, strength=5.0):
    """Add SAE feature direction to residual stream."""
    tokens = model.to_tokens(prompt)

    # Get feature direction from decoder
    feature_direction = sae.W_dec[feature_idx]  # [d_model]

    def steering_hook(activation, hook):
        # Add scaled feature direction at all positions
        activation += strength * feature_direction
        return activation

    # Generate with steering
    output = model.generate(
        tokens,
        max_new_tokens=50,
        fwd_hooks=[("blocks.8.hook_resid_pre", steering_hook)]
    )
    return model.to_string(output[0])

Feature Attribution

# Which features most affect a specific output?
tokens = model.to_tokens("The capital of France is")
_, cache = model.run_with_cache(tokens)

# Get features at final position
features = sae.encode(cache["resid_pre", 8])[0, -1]  # [d_sae]

# Get logit attribution per feature
# Feature contribution = feature_activation × decoder_weight × unembedding
W_dec = sae.W_dec  # [d_sae, d_model]
W_U = model.W_U    # [d_model, vocab]

# Contribution to "Paris" logit
paris_token = model.to_single_token(" Paris")
feature_contributions = features * (W_dec @ W_U[:, paris_token])

top_features = feature_contributions.topk(10)
print("Top features for 'Paris' prediction:")
for idx, val in zip(top_features.indices, top_features.values):
    print(f"  Feature {idx.item()}: {val.item():.3f}")

Common Issues & Solutions

Issue: High dead feature ratio

# WRONG: No warm-up, features die early
cfg = LanguageModelSAERunnerConfig(
    l1_coefficient=1e-4,
    l1_warm_up_steps=0,  # Bad!
)

# RIGHT: Warm-up L1 penalty
cfg = LanguageModelSAERunnerConfig(
    l1_coefficient=8e-5,
    l1_warm_up_steps=1000,  # Gradually increase
    use_ghost_grads=True,   # Revive dead features
)

Issue: Poor reconstruction (low CE recovery)

# Reduce sparsity penalty
cfg = LanguageModelSAERunnerConfig(
    l1_coefficient=5e-5,  # Lower = better reconstruction
    d_sae=768 * 16,       # More capacity
)

Issue: Features not interpretable

# Increase sparsity (higher L1)
cfg = LanguageModelSAERunnerConfig(
    l1_coefficient=1e-4,  # Higher = sparser, more interpretable
)
# Or use TopK architecture
cfg = LanguageModelSAERunnerConfig(
    architecture="topk",
    activation_fn_kwargs={"k": 50},  # Exactly 50 active features
)

Issue: Memory errors during training

cfg = LanguageModelSAERunnerConfig(
    train_batch_size_tokens=2048,  # Reduce batch size
    store_batch_size_prompts=4,    # Fewer prompts in buffer
    n_batches_in_buffer=8,         # Smaller activation buffer
)

Integration with Neuronpedia

Browse pre-trained SAE features at neuronpedia.org:

# Features are indexed by SAE ID
# Example: gpt2-small layer 8 feature 1234
# → neuronpedia.org/gpt2-small/8-res-jb/1234

Key Classes Reference

ClassPurpose
SAESparse Autoencoder model
LanguageModelSAERunnerConfigTraining configuration
SAETrainingRunnerTraining loop manager
ActivationsStoreActivation collection and batching
HookedSAETransformerTransformerLens + SAE integration

Reference Documentation

For detailed API documentation, tutorials, and advanced usage, see the references/ folder:

FileContents
references/README.mdOverview and quick start guide
references/api.mdComplete API reference for SAE, TrainingSAE, configurations
references/tutorials.mdStep-by-step tutorials for training, analysis, steering

External Resources

Tutorials

Papers

Official Documentation

SAE Architectures

ArchitectureDescriptionUse Case
StandardReLU + L1 penaltyGeneral purpose
GatedLearned gating mechanismBetter sparsity control
TopKExactly K active featuresConsistent sparsity
# TopK SAE (exactly 50 features active)
cfg = LanguageModelSAERunnerConfig(
    architecture="topk",
    activation_fn="topk",
    activation_fn_kwargs={"k": 50},
)

Related skills

How it compares

Use sparse-autoencoder-training when you need SAELens-specific load, train, and inspect flows rather than generic autoencoder PyTorch tutorials.

FAQ

How does sparse-autoencoder-training load pretrained SAEs?

sparse-autoencoder-training uses SAELens SAE.from_pretrained with a release name such as gpt2-small-res-jb and an sae_id hook path, or loads from HuggingFace repos and local disk via SAE.load_from_disk on CUDA.

Which SAE weight matrices does the skill document?

sparse-autoencoder-training covers SAE attributes W_enc with shape [d_in, d_sae] and W_dec decoder weights, plus sparsity metrics returned alongside cfg_dict from from_pretrained calls.

Is Sparse Autoencoder Training safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Data Science & MLllmresearchautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.