circuit-tracer и Neuronpedia: путеводитель по графам атрибуции на открытых моделях

Методы из статей Circuit Tracing и On the Biology of a Large Language Model Anthropic применяла к закрытой модели Claude 3.5 Haiku. Чтобы их мог повторить любой, есть два открытых инструмента:

• circuit-tracer — библиотека Python, которая строит графы атрибуции на открытых моделях с готовыми транскодерами, рисует их в том же интерфейсе, что в статьях, и позволяет делать вмешательства (менять признаки и смотреть на ответ). Лицензия MIT.
• Neuronpedia — открытая веб-платформа интерпретируемости: браузер признаков SAE и транскодеров, steering, поиск, автоинтерпретация и графы атрибуции в браузере (их бэкенд построен на circuit-tracer). Код — Apache-2.0, сайт — neuronpedia.org.

На чём основана страница

Путеводитель составлен по README и демо-ноутбукам репозитория safety-research/circuit-tracer (состояние на 11.09.2026; в описании цитирования указан и адрес decoderesearch/circuit-tracer) и README репозитория hijohnnylin/neuronpedia. Команды взяты из README; оценки времени и памяти на вашей машине помечены как оценки — мы их не замеряли.

Для кого и как связано с курсом

• Урок 9.3.2 «Суперпозиция и разреженные автоэнкодеры» уже содержит короткую практику с circuit-tracer (граф для «Даллас → Остин» на Gemma-2-2B). Эта страница — подробная карта: что ещё умеет библиотека, какие модели поддерживаются, как вмешиваться в признаки, что даёт Neuronpedia.
• Выпускной проект (10.1.1): «разобрать схему одного поведения открытой модели» — хорошая тема проекта, и circuit-tracer — основной инструмент для неё.
• Что нужно знать: что такое транскодер, граф атрибуции, супер-узел и вмешательство — по конспекту Circuit Tracing.

Карта ресурсов

Ресурс	Что это	Когда использовать	Важность
Neuronpedia: графы	готовые и свои графы атрибуции для Gemma-2-2B в браузере, кнопка + New Graph, steering из подграфа	первое знакомство, без установки	★★★
demos/circuit_tracing_tutorial.ipynb	главный учебник: повторяет два результата из Biology (двухшаговое рассуждение и многоязычные схемы) на Gemma-2-2B, работает в бесплатном Colab	после браузера — разобраться с API	★★★
demos/attribute_demo.ipynb	как построить граф, сохранить, проредить и открыть в локальном интерфейсе	свои промпты	★★★
demos/intervention_demo.ipynb	как выключать и включать признаки и генерировать с вмешательством	проверка гипотез	★★★
demos/attribution_targets_demo.ipynb	атрибуция от выбранных целей: конкретных логитов, разности логитов и т. п.	«почему Austin, а не Dallas?»	★★
demos/gemma_demo.ipynb, gemma_it_demo.ipynb	разобранные и подписанные графы Gemma-2-2B (базовой и instruction-tuned) с проверочными вмешательствами	образцы анализа	★★
demos/llama_demo.ipynb	то же для Llama-3.2-1B (не в Colab)	на своей машине	★
Командная строка circuit-tracer attribute	полный цикл «граф → файлы → локальный сервер» одной командой	быстрые эксперименты	★★
Интерфейс графов (Anthropic, MIT)	тот самый фронтенд из статей	встроен в circuit-tracer	—
Neuronpedia: код	исходники платформы: веб-приложение, сервер инференса, сервер графов, автоинтерпретация	развернуть у себя	★

Neuronpedia в браузере: первые шаги

1. Откройте neuronpedia.org/gemma-2-2b/graph и в выпадающем списке выберите готовый граф — например, gemma-fact-dallas-austin («Fact: the capital of the state containing Dallas is»). README circuit-tracer даёт прямую ссылку на этот граф с уже собранными супер-узлами «Texas», «capital», «state».
2. Найдите в графе путь «Dallas → Texas → say Austin» и «capital → say a capital». Кликните на узел — справа появятся примеры текстов, где признак активен, и токены, которые он продвигает.
3. Закрепите узлы в подграфе (Ctrl/Cmd + клик) и объедините похожие в супер-узел (удерживая G, кликайте по узлам).
4. Проверьте гипотезу: в подграфе нажмите Steer (нужен хотя бы один закреплённый узел) и выключите супер-узел «Texas». Изменился ли ответ?
5. Постройте свой граф кнопкой + New Graph: например, «The opposite of “small” is ”» и его французскую версию.

Кроме графов, на Neuronpedia есть (по списку в README): API, steering, просмотр активаций, автоинтерпретация и её оценка, поиск признаков по тексту и по объяснениям, дашборды признаков, косинусная близость и UMAP, пробы, списки, экспорт и загрузка своих SAE. Признаки многих открытых словарей (например, Gemma Scope) уже загружены — это лучший способ «пощупать» признаки, о которых рассказывают Monosemanticity и урок 9.3.2.

circuit-tracer на своей машине

Что делает библиотека

Три задачи (по README):

1. По модели с предобученными транскодерами строит граф атрибуции — прямые эффекты каждого ненулевого признака, узла ошибки и входного токена на другие признаки и выходные логиты.
2. Визуализирует граф и позволяет подписывать признаки.
3. Делает вмешательства: выставляет признакам любые значения и показывает, как меняется выход.

flowchart LR
P["Промпт"] --> A["attribute(): граф атрибуции (.pt)"]
A --> G["create_graph_files(): прореживание, JSON"]
G --> S["serve(): локальный интерфейс графа"]
S --> H["Гипотеза: супер-узлы"]
H --> I["feature_intervention(): проверка на модели"]

Рабочий цикл с circuit-tracer

Установка

git clone https://github.com/safety-research/circuit-tracer
cd circuit-tracer
python -m venv .venv && source .venv/bin/activate   # отдельное окружение: библиотека тянет свою версию TransformerLens
pip install .
export HF_TOKEN=hf_...   # Gemma на Hugging Face выдают после принятия лицензии

Командная строка

Одна команда делает три шага: атрибуцию, создание файлов графа (с прореживанием) и запуск локального сервера:

circuit-tracer attribute \
  --prompt "The International Advanced Security Group (IAS" \
  --transcoder_set gemma \
  --slug gemma-demo \
  --graph_file_dir ./graph_files \
  --server

Команда напишет адрес сервера (порт по умолчанию — 8041). Если считаете на удалённой машине, пробросьте порт. Полезные параметры (значения по умолчанию — из README):

Параметр	По умолчанию	Смысл
--transcoder_set, -t	—	набор транскодеров: gemma, llama, репозиторий Hugging Face или локальный путь
--max_n_logits	10	от скольких логитов (максимум) строить граф
--desired_logit_prob	0,95	брать столько верхних логитов, чтобы набрать эту вероятность
--max_feature_nodes	7500	ограничение числа узлов-признаков (меньше — быстрее, но граф беднее)
--batch_size	256	размер батча обратных проходов
--dtype	—	fp32, fp16, bf16
--offload	—	выгрузка частей в cpu или disk для экономии видеопамяти
--node_threshold	0,8	оставить минимум узлов с суммарным влиянием не меньше порога
--edge_threshold	0,98	то же для рёбер
--graph_output_path, -o	—	сохранить «сырой» граф в .pt для работы из Python

Нужно задать --slug и --graph_file_dir (для интерфейса), или --graph_output_path, или всё вместе — иначе команда ничего не сохранит.

Управление в интерфейсе: клик — выбрать узел; Ctrl/Cmd + клик — закрепить в подграфе; кнопка Edit — подписать узел; удерживая G, кликать по узлам — объединить в супер-узел; клик по подписи супер-узла — переименовать.

Python API (по демо-ноутбукам)

from pathlib import Path
import torch
from circuit_tracer import ReplacementModel, attribute
from circuit_tracer.utils import create_graph_files
from circuit_tracer.frontend.local_server import serve

# Модель + транскодеры. "gemma" — сокращение для транскодеров Gemma Scope
model = ReplacementModel.from_pretrained(
    "google/gemma-2-2b", "gemma", dtype=torch.bfloat16, backend="transformerlens"
)

# 1. Граф атрибуции
graph = attribute(
    prompt="The capital of state containing Dallas is",
    model=model,
    max_n_logits=10,          # максимум логитов-целей
    desired_logit_prob=0.95,  # набрать 95 % вероятности
    batch_size=256,
    max_feature_nodes=8192,   # меньше — быстрее, но граф беднее
    offload="cpu",            # в Colab в демо используют "disk"
)
Path("graphs").mkdir(exist_ok=True)
graph.to_pt("graphs/dallas.pt")   # файл большой: в демо — около 167 МБ

# 2. Файлы для интерфейса (с прореживанием)
create_graph_files(
    graph_or_path="graphs/dallas.pt", slug="dallas-austin", output_path="./graph_files",
    node_threshold=0.8, edge_threshold=0.98,
)

# 3. Локальный интерфейс
server = serve(data_dir="./graph_files/", port=8046)   # откройте http://localhost:8046/index.html
# server.stop()

Вмешательства. Признак задаётся тройкой (слой, позиция, номер признака); вмешательство — четвёркой (слой, позиция, признак, новое значение):

# Пример из intervention_demo: выключаем «испанский» признак на последней позиции
intervention_tuples = [(20, -1, 341, 0.0)]          # (layer, pos, feature_idx, new_value)
s = "Hecho: Michael Jordan juega al"
with torch.inference_mode():
    original_logits, _ = model.feature_intervention(s, [])
    new_logits, _ = model.feature_intervention(s, intervention_tuples)
# Значения «из распределения» удобно брать из активаций на другом промпте:
_, activations = model.get_activations(s, sparse=True)
# Для генерации с действующим вмешательством — model.feature_intervention_generate(...),
# а позицию можно задать открытым срезом slice(pos, None, None)

В демо авторы честно показывают, что выключение одного признака языка почти не меняет ответ — признаков языка много; нужно вмешиваться в весь супер-узел. А в учебнике подмена «Texas» на «California» даёт «Sacramento», подмена на «Китай» (из промпта с Шанхаем) — «Beijing», но подмена на «Британскую Колумбию» срабатывает плохо: не всякая гипотеза подтверждается.

Какие модели и транскодеры доступны

По README (раздел Available Transcoders) с circuit-tracer работают:

Модель	Транскодеры
Gemma-2 2B	послойные (PLT, из Gemma Scope) и межслойные (CLT) на 426 тыс. и 2,5 млн признаков
Llama-3.2 1B	PLT и CLT (524 тыс. признаков)
Qwen3 0.6B, 1.7B, 4B, 8B, 14B	PLT
GPT-OSS 20B	CLT (131 тыс. признаков)
Gemma-3 270M, 1B, 4B, 12B, 27B (PT и IT)	PLT из Gemma Scope 2 — нужен бэкенд nnsight
Llama 3.1 8B Instruct	TopK PLT

Бэкенды: по умолчанию transformerlens (только модели, реализованные в TransformerLens); backend="nnsight" поддерживает большинство моделей Hugging Face, но экспериментальный — медленнее и прожорливее по памяти. Свои транскодеры можно загрузить по абсолютному пути (тогда для интерфейса нужен features_dir). Транскодеры большого размера можно кэшировать локально (save_transcoders_to_cache), чтобы пользоваться ленивой загрузкой кодировщика и декодера.

🖥 На вашей машине (4×RTX 4080 32 ГБ)

По README Gemma-2-2B работает и на GPU с 15 ГБ (Colab); с 32 ГБ меньше выгрузки в CPU и больше батч. Llama-3.2-1B и Qwen3 до 4B — тоже на одной карте. Для Qwen3-8B/14B и Gemma-3 12B/27B (бэкенд nnsight) рассчитывайте на выгрузку (--offload cpu) и меньший --max_feature_nodes — это наша оценка, не замер; библиотека считает граф на одной GPU. Граф для промпта из 10–20 токенов на Gemma-2-2B — порядка минут (оценка). Обучать свои CLT на этой машине дорого: по оценке из статьи Circuit Tracing, CLT на 2 млн признаков для Gemma 2 2B — около 210 часов H100.

Neuronpedia у себя (для продвинутых)

Neuronpedia — монорепозиторий из нескольких независимых сервисов (по README): веб-приложение (Next.js, порт 3000, плюс публичный API), база данных (Postgres 16+ с pgvector), сервер инференса (steering, проверка активаций, поиск; отдельный экземпляр на каждую модель), сервер автоинтерпретации (на основе Delphi от EleutherAI), сервер графов (на основе circuit-tracer или Language-Model-SAEs) и другие. Рекомендуется от 16 ГБ RAM; для инференса и графов нужен GPU с CUDA. Для сервера графов нужен HF_TOKEN с доступом к Gemma-2-2B. Разворачивать всё это ради учёбы не нужно — сайт бесплатен; но код полезно почитать, чтобы понять, как устроен публичный инструмент интерпретируемости.

Идеи для экспериментов и проекта

1. Повторить находки Biology на открытой модели: двухшаговое рассуждение (Даллас/Окленд/Шанхай), многоязычный антоним («small/petit» и тот же вопрос по-китайски), галлюцинация на выдуманном имени. Что повторяется, а что нет?
2. Сравнить модели: один и тот же промпт на Gemma-2-2B и Qwen3-4B. Похожи ли супер-узлы?
3. Атрибуция от разности логитов (attribution_targets_demo): «почему Austin, а не Dallas?» — граф часто становится чище.
4. Проект ступени 10: выбрать одно поведение (рифма, перевод, простая арифметика), построить и подписать граф, проверить 3–5 гипотез вмешательствами, честно записать, где метод не помог (узлы ошибки, внимание).

Что читать дальше

• Конспекты: Circuit Tracing (метод и ограничения) и Biology (что искать).
• Урок 9.3.1: активационный патчинг и индукционные головы — то, что граф атрибуции не показывает (внимание).
• Ноутбуки ARENA (глава 1) и TransformerLens — см. «Учимся у создателей».

Словарик

EN	RU
per-layer transcoder (PLT) / cross-layer transcoder (CLT)	послойный / межслойный транскодер
attribution target	цель атрибуции
node / edge threshold	порог узлов / рёбер (прореживание)
offload	выгрузка (в CPU или на диск)
pin a node, supernode	закрепить узел, супер-узел
steering	управление (через признаки)
autointerp	автоинтерпретация
backend	бэкенд (движок модели)