Skip to contents

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.

Usage

llm_steer(m, layer, direction, coef = 1, positions = "all")

Arguments

m

An llm handle from llm().

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, no NA).

coef

Single finite number scaling direction (default 1). 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)
}