neuron-explorer README

README проекта с github.com/lyramakesmusic/neuron-explorer. Одним файлом markdown: README.md.

neuron explorer

Steering-first neuron explorer for Qwen3.5-4B. Every MLP neuron in a layer is pushed up and down on a few prompts, every rollout is kept, and the explorer lays the results out over a 3D view of the model.

neuron explorer

Explorer

uv sync
uv run python explorer/server.py        # http://localhost:8791

Reads sweep runs from runs/ and per-layer stats from stats/, both produced by the sweep below; the caches in explorer/cache/ ship with the repo. Loads Qwen3.5-4B locally (MPS, CUDA or CPU) for live steered chat, lens, connections and live inference over your own text.

The R and J++ lens rows read the maps of bubskee/qwen3.5-4b-r-jpp-lenses (Apache-2.0):

hf download bubskee/qwen3.5-4b-r-jpp-lenses --local-dir explorer/cache/rjpp

Sweep

Runs on a CUDA 13 GPU pod with the steering fork of vLLM (RhizoNymph/vllm).

bash sweep/setup_pod.sh                                   # fork, deps, model; writes /workspace/env.sh
python sweep/neuron_stats.py --layers 22 --tokens 2000000 --out stats/q35-4b
python sweep/steer_sweep.py --stats stats/q35-4b_L22.npz --design main_rel --dose-unit rel \
    --neurons all --random-controls 256 --run q35-4b-L22
sweep/run_depth.sh "4 9 13 17" 384 64                     # random-subset sweep across several layers

main_rel doses are fractions of the median residual norm leaving the layer: {who, snake, orange} × {−0.7, +0.5, +0.8} and {free} × {+3}, plus one unsteered baseline per prompt.

script output
sweep/neuron_stats.py per-neuron activation extremes by sign regime, down columns, residual norms
sweep/steer_sweep.py runs/<run>.jsonl: text, token ids, logprobs, top-k per step; optional activation captures
sweep/rank.py runs/<run>.units.jsonl: distinctive words, cluster mass, percentile against controls
sweep/steer_lens.py stats/steer_lens_L{l}.npz: next-token Δlogprob and KL for ±0.8 pushes on every neuron
sweep/depth_report.py runs/depth_report.json: per-layer share of neurons above controls, coherence, top units
sweep/shift.py word-shift score against controls, all words counted
sweep/merge_runs.py joins sharded runs of one layer
sweep/check_equivalence.py HF vs vLLM steering and capture agreement
sweep/bench.py, sweep/peek.py throughput conditions; terminal views of a run
explorer/build_embeddings.py runs/<run>.umap.json
explorer/build_layout.py explorer/cache/layout_writes.npz
explorer/build_connections.py explorer/cache/connections.npz: each neuron's 24 strongest direct-path links up and down
sweep/fit_input_lens.py S.pt: the fitted input map S_L (token embeddings to the residual each MLP reads, layers 0–31), RelP rules of safety-research/jpp_lens; shards over prompts, merged by num_prompts; copy to explorer/cache/slens/S.pt
explorer/build_s_index.py explorer/cache/s_index.npz: each neuron's top S-lens (read side) tokens, both poles
explorer/build_rjpp_index.py explorer/cache/r_index.npz, jpp_index.npz: each neuron's top R- and J++-lens tokens, both poles (needs the R/J++ release in explorer/cache/rjpp/)
sweep/finefineweb.py <out>/corpus.npz, urls.json, acts.npz: a domain-balanced FineFineWeb sample (about 20M tokens over 66 domains) and every neuron's top contexts per sign and per-domain activation statistics; copy the three files to explorer/cache/ffw/
sweep/capture_prefill.py captures/<run>.mlp_in.npy: MLP input at the last prompt token at the run's capture layers, steered

research_log.md holds the findings and reasoning; NOTES.md the source notes.

License

MIT, see LICENSE.

neuron-explorer (lyramakesmusic/neuron-explorer)

Ищем в базе…

Что это такое?Это обозреватель нейронов, в центре которого управление поведением модели. Он сдвигает каждый нейрон MLP вверх и вниз на нескольких промптах, сохраняет каждый прогон и раскладывает результаты на интерактивном трёхмерном виде модели Qwen3.5-4B.
Это исследовательский инструмент или готовое приложение?Это локальный исследовательский инструмент: Python-сервер (explorer/server.py) открывает в браузере интерактивный трёхмерный обозреватель. Он опирается на заранее вычисленные данные свипов и загружает модель Qwen3.5-4B.
Как запустить обозреватель?Выполните 'uv sync', затем 'uv run python explorer/server.py'. Сервер загрузит готовые кэши свипов, которые входят в репозиторий, так что можно сразу просматривать результаты без запуска собственного свипа.
Легко ли запустить собственный свип нейронов?Не особенно: нужна GPU-машина с CUDA 13 и собственный форк vLLM с поддержкой управления (RhizoNymph/vllm), который настраивается через sweep/setuppod.sh. Кроме того, перед тем как результаты попадут в обозреватель, нужно запустить несколько скриптов: neuronstats.py, steersweep.py, rank.py, steerlens.py и другие.
Что показывает каждая вкладка: карта, список, нейрон и эмбеддинги?Карта показывает слои модели в 3D, по одной точке на нейрон, окрашенные по сходству проекций. Список ранжирует нейроны по силе словесных кластеров и позволяет искать по линзам. Вкладка «нейрон» показывает управляемые прогоны по каждому промпту и дозе, а также трёхколоночный чат (−, 0, +) с управлением. Эмбеддинги показывают UMAP прогонов слоя, окрашенный по нейрону, промпту, дозе или типу.
Что на самом деле делает вкладка Claude?Она запускает Claude CLI как чат, связанный с обозревателем через MCP-сервер (agentmcp.py). Он может читать нейроны, конусы и линзы, выполнять живые запросы на управление, активации и абляцию, двигать карту и подсветку. Также у него есть инструменты для работы с файлами и командная оболочка в вашей домашней папке.
Что такое «доза» в свипах управления?Доза — это доля от медианной нормы остаточного потока на выходе из слоя. Например, стандартный план сдвигает промпты 'who', 'snake', 'orange' на ±0.7/+0.5/+0.8, а 'free' на +3, и добавляет по одному базовому прогону без управления на каждый промпт.
Можно ли прогнать через модель свой текст вместо готовых промптов?Да: инструмент 'fires' во вкладке списка прогоняет ваш текст через модель и фильтрует нейроны по активации. Агент Claude во вкладке Claude тоже может запускать живой инференс на любом тексте.
Какие есть похожие проекты?detectorscope, NeoHorse, MemT-1.0, unsloth, ZDTaichu5.0-9B, Agent-Reflex, DeepAnalyze, nesformer
Автор
lyramakesmusic
Размер
150.9 MB
Звёзды
2K
Обновлён
КоммитNov 01
Возраст
28 д
Коммиты · 90 дней