vlmprobe GitHub PUBLIC

A TOOLKIT FOR MODEL INTERPRETABILITY

vlmprobe

Beyond the answer.
Inside the model.

Explore what vision-language models read, where they attend, and which computations change their answers.

Explore the experimentsTechnical report

Lens readouts · Attention explanations · Causal interventions

A LOOK INSIDEActual model measurements
GQA / 07302654

“Is the shirt black or yellow?”

Generated answerYellow
What happens when attention routes are blocked?
Archived attention knockout curves: probability of first answer token Y across layer windows1.00.50.001631
Image to questionImage to answerQuestion to answer
LLaVA-1.5-7BP(first token “Y”) · layer-window center

One model binding.
Three complementary views.

03method families
08VLM adapter families
09replayable notebooks
01 / OVERVIEWExploring model internals beyond the answer

An answer is only
the beginning.

vlmprobe connects observations and interventions through one interface bound to a model you already own.

Read vocabulary predictions from internal states. Compare attention patterns on the same input. Then intervene on activations or attention routes and measure what changes. Explicit adapters handle model-specific hook locations, visual-token coordinates, and readouts.

Each result keeps tensors and experiment metadata together, so the same computation can be inspected, visualized, saved, and replayed.

02 / THREE PERSPECTIVESObserve. Compare. Intervene.

Different questions.
One probing interface.

From internal predictions to controlled changes,
choose the view your research question needs.

01 READOUT

Lens

What is represented inside?

Decode residual states, attention-head outputs, and projected visual embeddings into vocabulary predictions.

Logit LensTuned LensAttention LensJacobian LensEmbedLensPatchscopes
Lens method guides
02 EXPLANATION

Attention

Where does the model look?

Compare attention flow and target-conditioned spatial attributions on the same image and question.

RolloutGrad-CAMATTATTRTAMBeyond IntuitionRelevance
Attention method guides
03 INTERVENTION

Causal

Which computations matter?

Patch activations, isolate paths, block attention routes, or steer residual states and measure the effect.

Activation patchingPath patchingAttention KnockoutEAP / EAP-IGSteering / VSV
Causal method guides

Method availability depends on the model adapter. Fitted lenses require compatible calibration artifacts.

03 / FRAMEWORKModel-bound by design

Bind once. Probe together.

A shared execution contract connects native inputs,
explicit adapters, and structured results.

vlmprobe architecture: model inputs and adapter configuration feed lens, attention, and causal tools, returning structured results and visualizations
Model-specific coordinates and capability checks keep observations and interventions grounded in the same computation. View full-size framework
01

Explicit adapters

Architecture-specific hooks and expanded visual-token coordinates.

02

Capability checks

Unsupported operations are distinguished from measured zero effects.

03

Structured results

Tensors, metadata, and shared visualizations travel together.

04 / EXPLORE AN EXPERIMENTArchived measurements · no model loading

Block a route.
Watch the answer change.

Replay a real Attention Knockout scan.
Different routes have different effects on the same input.

LLAVA-1.5-7B / GQA

“Is the shirt black
or yellow?”

Question 07302654 · 576 image tokens

Layer 0Layer 31

Blocked layers 8–16 · all attention heads

Baseline75.3%
After knockout11.9%
Probability of the first answer token “Y” (ID 612), not the full word “Yellow”.

Answer-token probability

MEASURED REPLAY
After route blockingUnmodified baseline
Loading the archived measurement…
Experimental settings & source

Joint windows of up to 9 consecutive layers, clipped at the boundaries; all heads are blocked at masked pre-softmax attention logits. Layer indices start at zero. LLaVA-1.5-7B uses bf16 model execution and float32 probability readout.

This browser replays stored numbers; it does not run a new intervention. A single GQA example does not establish dataset-level performance.

View original measurement

Nine notebooks. Three perspectives.

Browse all demonstrations
LENS

Text lens comparison

GPT-2 · shared IOI prompts

 LENS

VLM lens comparison

LLaVA · GQA shirt questions

 ATTENTION

ViT attention comparison

ViT-B/16 · maps & patch deletion

 ATTENTION

VLM attention comparison

LLaVA · fixed complete-answer score

 CAUSAL

Activation & attribution patching

SmolVLM / LLaVA · residual sensitivity

 CAUSAL

Attention Knockout

LLaVA · route & image-region scans

 CAUSAL

Path patching

Qwen2.5-VL · controlled receiver replay

 CAUSAL

Residual steering / VSV

LLaVA · captions & strength responses

 CAUSAL

EAP / EAP-IG

GPT-2 · edge scores & circuit recovery

Notebooks replay compact actual measurements by default. Rerunning models is optional and requires weights and compatible fitted artifacts where applicable.

05 / MODEL SUPPORTExplicit architecture contracts

Across vision and language.

Eight VLM families, with language and vision controls.
Check capabilities for your specific model and method.

Qwen3-VL2BQwen2.5-VL3BQwen2-VL2BQwen3.54B · hybridSmolVLM256M / 500MInternVL1BLLaVA7BPixtral12B
COMPLEMENTARY CONTROLSGPT-2LlamaViT-B/16
Support is method-specific.

Adapter support and pretrained validation are different scopes. Five pretrained VLMs were exercised in the technical report; some families have architecture-level validation. Qwen3.5 has restrictions across its hybrid attention stack. Fitted decoders are not supplied for every model.

Read the capability matrix
06 / GET STARTEDPython 3.10+ · PyTorch

Your model.
A clearer view.

Install from PyPI, bind a loaded model, and inspect the methods available to it.

Read the API guide

Model weights and complete datasets are downloaded separately.

INSTALL & PROBE
# Install from PyPI
python -m pip install "vlmprobe[transformers,visualization]"

# In Python, with your loaded model and native inputs
from vlmprobe import Prober

probe = Prober(model, processor)
print(probe.describe())

result = probe.lens.logit(
    layers=[0, 13, 27],
    tokens="last_prompt",
).run(inputs)

result.save("outputs/logit_lens")
Use layer indices valid for your model. Inputs come from its native processor. For development builds, see GitHub installation.
07 / RESOURCESContinue exploring
REPORT

Technical report

Shared-case comparisons across five pretrained VLMs, with language and vision controls.

DOCUMENTATION

Guides & API

Model loading, method definitions, calibration workflows, and visualization tools.

PROVENANCE

Papers & datasets

Original methods, author implementations, and sources used for the demonstrations.