Returns a new llm handle that adds coef * direction to the residual
stream at layer during every subsequent forward pass (llm_generate(),
llm_logits()). The original handle is untouched: to remove the steering, use
the original object (reversibility is exact, D-003). Interventions compose –
see Details.
Arguments
- m
An
llmhandle fromllm().- layer
Single 1-based transformer block to steer, in
2:m$layers(layer 1 is not steerable – see Details).- direction
Numeric vector of length
m$hidden_size: the steering direction in residual space (finite, noNA).- coef
Single finite number scaling
direction(default1). Negative values steer the opposite way.- positions
Which token positions to steer. Only
"all"(the default) is supported in this release.
Value
A new llm handle with the steering added to its accumulated
interventions; the source handle is returned unchanged. print() shows the
active intervention count and summary() lists them.
Details
Steering is llama.cpp's native control-vector mechanism: a per-layer,
hidden_size-wide vector added to the residual at layer's output, for all
token positions (hence positions = "all" is the only supported value in this
release; a position subset raises relm_error_intervention).
Composition. Deriving from an already-steered or ablated handle carries its
full spec forward and adds the new one, then builds a single fresh context from
the original weights (contexts are never chained). Steering stacks by
summation – two steers on the same layer add – and the semantics are
derivation-order-independent: m |> llm_steer(...) |> llm_ablate(...)
produces the same forward pass as m |> llm_ablate(...) |> llm_steer(...). A
steer never moves an ablated neuron: at the graph the ablation runs after the
steer ((x + steer) * mask + add), so a jointly steered-and-ablated neuron is
forced to the ablation value (D-016).
Layer 1 is not steerable. The native control vector reserves engine index 0
and has no slot for the first transformer block, so layer = 1 raises
relm_error_intervention. Steer a later layer (2:m$layers), or ablate
layer 1 with llm_ablate() (ablation covers every layer).
Not free. Each llm_steer()/llm_ablate() call allocates a fresh context
on the shared weights – a sub-second pause and real memory (its own KV cache,
~hundreds of MB on the demo models), not a cheap copy. Hold a handful of
intervened handles, not hundreds.
Generation/logits only (for now). Interventions apply to llm_generate()
and llm_logits(). llm_embed() and llm_trace() build their own fresh
contexts that do not inherit the adapters, so calling them on an intervened
handle raises relm_error_embed / relm_error_trace rather than silently
returning base (un-intervened) vectors mislabeled as steered.
Model support. Interventions work on any standard-residual decoder. Before
the handle is returned, a runtime probe verifies on this model that steering
actually shifts the residual at each requested layer; if it would silently do
nothing (an architecture that does not route its residual through the choke point
the mechanism hooks), relm_error_intervention is raised instead of a no-op
handle. The llama and qwen2 architectures are additionally behaviorally
validated – they pass the valence-steering and KL-ablation acceptance fixtures;
any other architecture is enabled the moment it passes the probe.
Examples
if (FALSE) { # nzchar(Sys.getenv("RELM_TEST_MODEL_QWEN"))
m <- llm(Sys.getenv("RELM_TEST_MODEL_QWEN"))
# A steering direction is any hidden_size-wide vector (here a placeholder).
dir <- rep(0.05, m$hidden_size)
steered <- llm_steer(m, layer = 8, direction = dir, coef = 2)
summary(steered) # lists the active intervention
# The original handle is untouched -- generation reproduces the base output.
identical(
llm_generate(m, "Tell me about the sea.", max_tokens = 20, seed = 1),
llm_generate(m, "Tell me about the sea.", max_tokens = 20, seed = 1)
)
close(steered)
close(m)
}