circuit-tracerオープンソースツールの使い方

circuit-tracerとは何か

circuit-tracerは、言語モデルが1つの出力を選ぶまでに内部でたどった計算の経路を可視化するオープンソースライブラリです。Anthropicが2025年5月29日に公開しました。モデルの重みに直接手を入れず、入力トークンから出力ロジットまでの因果関係を「attribution graph(帰属グラフ)」として描き出します。

土台は、2025年にAnthropicが発表した2本の論文(手法編と、モデルの振る舞いを調べた生物学編)です。circuit-tracerの公開で、同じ手法を自分の環境で再現できるようになりました。開発を主導したのはAnthropic Fellowsプログラムの参加者2名(Michael Hanna、Mateusz Piotrowski)で、Decode Researchとの協業でNeuronpediaへの統合が実装されています。

circuit-tracerでできることは3つです。事前学習済みトランスコーダーを持つモデルに対してattribution graphを計算すること、そのグラフをインタラクティブに可視化・注釈すること、そしてグラフから得た知見をもとにモデルの特徴量の値を操作し、出力の変化を観察することです。

Claudeは分析できない:対象になるモデル

最初に押さえたいのは、circuit-tracerがClaudeを直接トレースできない点です。Claudeのモデル重みは公開されていないため、対応しているのはオープンウェイトモデルに限られます。Claudeの内部動作そのものを調べるツールではなく、Anthropicが培った手法を公開モデルで追体験するためのツールです。

対応するトランスコーダーは、モデルごとにHuggingFace上で公開されています。トランスコーダーとは、モデル内部の特徴量を復元する小型ネットワークです。

PLTsはレイヤーごとのトランスコーダー、CLTsはレイヤーをまたぐトランスコーダーです。Gemma-3の対応サイズは270M・1B・4B・12B・27Bで、nnsightバックエンドの扱いは後の節で触れます。

どの入口から始めるか

入口は3つあり、必要な準備が違います。自分のプロンプトで分析したいのか、まず雰囲気をつかみたいのかで選びます。

Gemma-2(2B)であれば、無料のColab GPUでも動きます。GPUメモリーが多いほどオフロードを減らせ、バッチサイズも大きくできます。

ブラウザ(Neuronpedia)でグラフを見る

インストールなしで試せる方法です。Neuronpediaのグラフ画面を開き、「+ New Graph」から新しいプロンプトを入力するか、ドロップダウンから既存のグラフを選びます。生成されたグラフ上でノードをクリックすると詳細が表示され、Ctrl(またはCommand)+クリックでサブグラフ枠にピン留めできます。

ノードを選択した状態で右側の「Edit」ボタンを押すと、そのノードに注釈を付けられます。Gキーを押しながら複数ノードをクリックすると1つのスーパーノードにグループ化できます。ラベル部分をクリックすれば、スーパーノードの注釈も編集できます。

特徴量の操作(インターベンション)は、Gemma-2(2B)に限ってNeuronpedia上でできます。ノードを1つ以上ピン留めしたうえで、サブグラフ内の「Steer」を押します。

ノートブックで自分のプロンプトを分析する

自分のプロンプトを分析したいなら、チュートリアルノートブック(circuit_tracing_tutorial.ipynb)から始めます。Colabバッジをクリックすれば、無料のGPUリソースでそのまま実行できます。このノートブックは、2025年の論文で示された知見のうち2つをGemma-2(2B)で再現する内容です。

リポジトリのdemosフォルダには、目的別のノートブックが並んでいます。

llama_demo.ipynbだけはColab非対応で、ほかは無料のColabで動きます。注釈つきのグラフは、GemmaとLlamaそれぞれのデモの冒頭にまとまっています。

CLIで1コマンドにまとめる

自前の計算環境があるなら、CLIで帰属計算から可視化までを自動化できます。導入はリポジトリのクローンとpip install .です。Pythonは3.10以上が前提です。

git clone https://github.com/decoderesearch/circuit-tracer.git
cd circuit-tracer
pip install .

CLIは、次の3段階をcircuit-tracer attributeの1コマンドでつなぎます。

実行例は次のとおりです。gemmaはGemmaScopeトランスコーダーの簡易指定で、モデル名は自動で推定されます。

circuit-tracer attribute \
  --prompt "The capital of France is" \
  --transcoder_set gemma \
  --slug capital-demo \
  --graph_file_dir ./graph_files \
  --server

--transcoder_setには、HuggingFaceのリポジトリ名(username/repo-name@revisionの形でリビジョン指定も可)、gemma・llamaの簡易指定、ローカルに保存したトランスコーダーのパスを渡せます。llamaはReLUトランスコーダーを指します。

実行するとローカルサーバーのアドレスが表示されます。リモートマシンで走らせるなら、ポートフォワーディングを設定しないと手元のブラウザからは見られません。

出力を何に残すかで引数が変わる

保存先の指定は、--slugと--graph_file_dirの組か、--graph_output_path(-o)のどちらかが必須です。両方を指定してもかまいませんが、どれも付けないとCLIは何も出力しません。

可視化せずに生のグラフだけ残したいときは、.ptファイルに保存します。後からPythonで読み込んで使えます。

circuit-tracer attribute \
  --prompt "The capital of France is" \
  --transcoder_set llama \
  --graph_output_path france_capital.pt

枝刈りと計算量のつまみ

グラフの見た目と実行時間は、次のオプションで調整します。

枝刈りの2つは、値を下げるほどグラフが簡素になり、上げるほど細かい経路まで残ります。メモリーが足りないときは、--offload(cpu・disk)で逃がし、--dtype(float32・float16・bfloat16)で精度を落とす手があります。--verboseを付けると進捗が詳しく出ます。ローカルのトランスコーダーを使うときは、特徴量ファイルのディレクトリを--features_dir(既定はなし)で渡します。--model(-m)は、gemmaやllamaの簡易指定なら自動で推定されます。

ローカルのトランスコーダーとキャッシュ

HuggingFace上のトランスコーダーはサイズが大きく、保存に容量を食います。lazy_decoder・lazy_encoderを使うには、トランスコーダーがcircuit-tracer互換の形式で保存されている必要があります。

互換形式のローカルキャッシュを作る関数が用意されています。

from circuit_tracer.utils.caching import save_transcoders_to_cache
 
hf_ref = "mwhanna/gemma-scope-2-27b-pt/transcoder_all/width_262k_l0_small"
save_transcoders_to_cache(hf_ref, cache_dir="~/.cache/")

キャッシュを空にするにはcircuit_tracer.utils.caching.empty_cacheを使います。

ローカルに保存したトランスコーダーを使う場合は、ReplacementModel.from_pretrainedにルートからのフルパスを渡します。相対パスは使えません。可視化サーバーを起動するserveには、同じディレクトリをfeatures_dirに指定します。指定がないと特徴量のデータを読めず、グラフ上の特徴量が表示されません。

serve(data_dir=graph_path, port=port, features_dir='/path/to/local_transcoders/')

バックエンドの違いと、インストールで詰まる点

内部のバックエンドは2種類あります。通常はTransformerLens、対応していないHuggingFaceモデルにはnnsightです。

Gemma-3のトランスコーダーはnnsightが必須なので、Gemma-3を試すなら上の制約を承知のうえで使うことになります。

TransformerLens 4.0の登場でimportが落ちる報告

GitHubのissue #115は、TransformerLens 4.0.0がPyPIに公開された2026年9月21日の翌日に報告されています。circuit-tracer側の依存はtransformer-lens>=2.16.0と上限なしだったため、新規にインストールすると4.0.0が入ります。するとHookedTransformerが見つからず、ImportErrorでモジュールを読み込めない、という内容です。

このissueによれば、nnsightバックエンドの側は影響を受けません。issueが提案する対処はtransformer-lens<4という上限の追加です。依存関係の解決で同じエラーに当たったら、このissueを起点に状況を追えます。

あわせて、transformersのバージョンにも上限(<=4.57.3)があり、nnsightは0.8.0rc1以上0.9未満というプレリリース版を指定しています。ほかのライブラリと同居させる環境では、仮想環境を分けておくほうが衝突を避けやすくなります。

プロンプトが長いとメモリーが先に尽きる

issue #92では、H100(80GB)でGemma-2(2B)を使い、約1,500トークンまでは動いたものの、約2,300トークンで枝刈りの並べ替え中にメモリー不足(OOM)になったと報告されています。報告者は5,000〜6,000トークンのプロンプトを通したかったため、長文対応の予定や回避策を尋ねています。

つまずきの症状から原因を探す

• Claudeを分析対象にしようとして止まる:対応するのは公開ウェイトのモデルだけです。Claudeの重みは非公開なので、そのままでは分析対象にできません
• 実行しても何も出力されない:--slugと--graph_file_dirの組、または--graph_output_pathのどれも指定していません
• ローカルのトランスコーダーで特徴量が表示されない:features_dirをトランスコーダーの保存先と同じにしてください
• リモートマシンでブラウザが繋がらない:--serverはそのマシン上にサーバーを立てるだけなので、ポート(既定8041)を転送します
• import circuit_tracerでImportErrorが出る:TransformerLensのバージョンが4.0以上になっていないか、上の節のissue #115を見てください
• 特徴量の操作ボタンがNeuronpediaにない:Neuronpedia上のSteerはGemma-2(2B)限定です。それ以外はスクリプトやノートブック(intervention_demo.ipynbなど)で行います

Anthropicがこのツールを公開した理由

Anthropicは2025年、ダリオ・アモデイが「AIの能力向上のペースに対して、内部動作の理解が大きく遅れている」と解釈可能性研究の緊急性を訴える文章を公開しています。circuit-tracerの公開は、その主張を実装に落とした動きです。attribution graphが依拠する枠組みは、ニューロンを特徴量に分解するMonosemanticity論文やTransformer Circuitsの数学的フレームワークといった一連の研究の延長線上にあります。

公開時点で、AnthropicはこのツールでGemma-2(2B)とLlama-3.2(1B)の多段階推論・多言語表現の分析を進めており、デモノートブックでその一部を見られます。まだ解析していないattribution graphもデモノートブックとNeuronpediaに置かれ、コミュニティが独自に興味深い回路を見つけることを想定しています。可視化画面のフロントエンドは、元の論文と同じものが別のリポジトリで公開されています。

質問や改善提案は、GitHubのissueで受け付けています。

まとめ

Claudeそのものは調べられないので、これは「Anthropicの解釈可能性の手法を公開モデルで手を動かして学ぶ」ための道具です。まずNeuronpediaでグラフの読み方に慣れ、自分のプロンプトで試すならColabのノートブック、実験を自動化するならCLIへ進む順が、無理が少ない進め方です。