English | 日本語

gguf-neuron-explorer (gne)

Find, rank and steer individual MLP neurons of GGUF models on llama.cpp, then ship what you find as a control vector that stock llama-cli / llama-server can load.

gne pushes a neuron's output direction (a column of W_down) into the residual stream, generates text, and measures what changed against random-direction controls. It runs on llama.cpp through llama-cpp-python, so it works with the quantized GGUF files you already have.

• Sweep and rank. Steer hundreds of neurons in a layer over a fixed set of prompts and doses, then rank them by how strongly their outputs pile onto a few words. Every score is compared with random directions pushed the same way.
• Cheap first passes.
  • Logit lens: weights only, on the CPU.
  • Steer lens: the next-token change when a neuron is pushed ± a dose.
  • Reverse lookup: contrast two personas, then rank every neuron in every layer by cosine to the difference.
• Dossier per neuron. Sweep rank, top words per prompt, rollouts, lens results and up/downstream connections, all in one view.
• Recipes. Combine units such as 14:8949:+1.0 and 13:7956:-1.0, compare them in a 3-column chat (−, no steering, +), and export them:
  • as a control vector (.cvec.gguf), checked against llama-completion --control-vector;
  • as npz, json or safetensors;
  • baked into a GGUF as FFN down biases, for architectures whose llama.cpp graph reads that bias (llama, granite, mistral3, nemotron, gpt2 and others; not Qwen or Gemma — see configs/arch/bias_support.yaml).
• Steer only where it matters (when). Push only the generated tokens (gen), only the assistant's turns, everything but earlier replies (skip-replies), only after a given text appears in the output, or ramp the dose down. A control vector file cannot express this, so gne serve --openai serves an OpenAI-compatible endpoint that applies it.
• Audio input. For models that can hear (LFM3-Omni), gne steer --audio speech.wav and input_audio parts in OpenAI-style messages put speech straight into the conversation. The model's mmproj turns the audio into embeddings, and gne decodes them in its own loop, so recipes, when and activation capture act on spoken turns the same way as on text. Replies are text; use any TTS to speak them.
• Gain steering. 22:2742:x4 multiplies a neuron's own output instead of adding a fixed direction: x0 removes it, a negative factor inverts it. It acts only where the neuron already fires. It exports as a LoRA adapter GGUF for llama.cpp's --lora (works on Qwen too) or as a rewritten GGUF; by default the rewrite is a scale patch (only the scales of the quantization blocks are rewritten), which keeps the original quantization and scales the rows exactly.
• Directions (gne direction). When a persona or behaviour is spread over many neurons, work with a direction instead. A direction comes from a contrast set, which reads questions under two conditions (for example side A with a system prompt that asks for the persona and side B without it). The direction is the difference between the two sides' mean residuals at the token just before the reply begins, per layer. It can pick a layer automatically by removing the direction and checking that the behaviour drops, or by adding it and checking that the behaviour rises. Add a direction like a neuron with 30:dir:yandere:+0.3; it exports as a control vector. To add a persona, build the direction with --positions response, which measures on replies generated in each persona instead of right after the instruction. Like neurons, directions are checked against random controls: each candidate layer is also pushed with 16 random directions of the same norm, and a layer is picked only if its effect beats their 95th percentile. gne steer --contrast does the same for a whole recipe and reports null_pct.
• Directional ablation (gne ablate). Project a direction out of every weight that writes to the residual stream (also known as abliteration). It exports as a LoRA adapter or as a rewritten GGUF, either Q8_0/F16 or requantized back to the original types with llama-quantize. Recipes can carry ablate:, and gne eval --compare-ablation compares it with zeroing the top neurons.
• Side-effect check (gne eval). Run a recipe at several doses and see how much the persona changed next to what broke: exact-answer and format tasks, perplexity on reference texts, and language mixing (Simplified-only Chinese, Hangul and other scripts in Japanese answers). An optional second GGUF can rate the persona 1–5. Doses that stay within the thresholds are marked as shippable. --random-controls N also runs N recipes of the same size in random directions at each dose. That shows whether the persona change beats them, and how much capability and perplexity you lose from the size of the push alone.
• Who writes a state (gne writers). Activation differences show which neurons react to a state, such as a persona system prompt. gne writers measures what each neuron actually wrote into the residual on the reply tokens: activation difference × write direction, including post-FFN norms. It also splits the state's direction into the parts written by the embedding, by each layer's mixer (attention, convolution) and by each layer's MLP. The UI has a writers view and a map overlay for it.
• Attention heads (gne heads). Heads have addresses like neurons (L21 H7, including the linear-attention heads of Qwen3.5). gne heads contrast runs the same conversations with and without a persona and ranks heads by:
  • how much more they look at trigger words (for example other people's names);
  • how much their attention pattern and output change;
  • how well their output writes the persona direction.

This is the beginning of the README. Read the rest at the original. Read the full README ↗