circuit-tracerオープンソースツールの使い方
Anthropicが公開した解釈可能性ツールcircuit-tracerで、モデル内部の思考の痕跡(attribution graph)を自分の手で生成する手順。
circuit-tracerとは何か
circuit-tracerは、言語モデルが1つの出力を選ぶまでに内部でたどった計算の経路を可視化するオープンソースライブラリです。Anthropicが2025年5月29日に公開しました。モデルの重みに直接手を入れず、入力トークンから出力ロジットまでの因果関係を「attribution graph(帰属グラフ)」として描き出します。
このツールは2025年3月にAnthropicが発表した手法をベースにしています。当時の論文は大規模言語モデルの思考をトレースする新手法を示しましたが、追試や応用は社内にとどまっていました。circuit-tracerの公開によって、誰でも同じ手法を自分の環境で再現できるようになりました。開発を主導したのはAnthropic Fellowsプログラムの参加者2名(Michael Hanna、Mateusz Piotrowski)で、Decode Researchとの協業でNeuronpediaへの統合が実装されています。
circuit-tracerでできることは3つです。事前学習済みトランスコーダーを持つモデルに対してattribution graphを計算すること、そのグラフをインタラクティブに可視化・注釈すること、そしてグラフから得た知見をもとにモデルの特徴量の値を操作し、出力の変化を観察することです。
始める前に確認すること
最初に確認すべき最重要点は、circuit-tracerがClaudeを直接トレースできない点です。Claudeのモデル重みは公開されていないため、対応しているのはGemma-2(2B)、Llama-3.2(1B)、Qwen-3系列(0.6B〜14B)、GPT-OSS(20B)、Llama 3.1(8B)Instructといったオープンウェイトモデルに限られます。Claudeの内部動作そのものを調べるツールではなく、Anthropicが自社モデルの解釈可能性研究で培った手法を、公開されているモデルで追体験するためのツールだと理解しておく必要があります。
利用形態は3通りあり、必要な準備が異なります。
| 利用形態 | 必要な準備 | GPU | 向く人 |
|---|---|---|---|
| Neuronpedia(ブラウザ) | 必要な準備ブラウザのみ | GPU不要 | 向く人まず試したい人 |
| ノートブック(Python) | 必要な準備Python環境またはColab | GPUColabの無料枠(15GB)で可 | 向く人自分のプロンプトで分析したい人 |
| CLI(コマンドライン) | 必要な準備自前のGPU環境 | GPU必須(自己保有) | 向く人独自モデル・大規模分析をしたい人 |
Gemma-2(2B)であればColabの無料GPU(15GBメモリー)でも動きます。GPUメモリーが多いほどオフロードを減らせ、バッチサイズも大きくできます。
ステップ1: Neuronpediaでブラウザから試す
インストールなしで試せる方法です。Neuronpediaのグラフ画面を開き、「+ New Graph」から新しいプロンプトを入力するか、ドロップダウンから既存のグラフを選びます。生成されたグラフ上でノードをクリックすると詳細が表示され、Ctrl(またはCommand)+クリックでサブグラフ枠にピン留めできます。
ノードを選択した状態で右側の「Edit」ボタンを押すと、そのノードに注釈を付けられます。Gキーを押しながら複数ノードをクリックすると1つのスーパーノードにグループ化でき、ラベル部分をクリックすれば注釈を編集できます。Gemma-2(2B)に限り、ノードを1つ以上ピン留めしたうえでサブグラフ内の「Steer」を押すと、Neuronpedia上でそのままインターベンション(特徴量操作)も試せます。
ステップ2: ノートブックで自分のプロンプトを分析する
もう少し踏み込んで自分のプロンプトを分析したいなら、チュートリアルノートブック(circuit_tracing_tutorial.ipynb)から始めます。Colabバッジをクリックすれば、無料のGPUリソースでそのまま実行できます。このノートブックは2025年の論文で示された知見のうち2つをGemma-2(2B)で再現する内容です。
より基礎的な使い方を学ぶには、attribute_demo.ipynb(グラフの検出と可視化)とintervention_demo.ipynb(モデルへの介入)が役立ちます。特定のロジットだけを対象に帰属を計算したい場合はattribution_targets_demo.ipynbを参照します。すでに計算済みで注釈も付いたグラフを掘り下げたいなら、gemma_demo.ipynb・gemma_it_demo.ipynb(指示チューニング版)・llama_demo.ipynb(Colab非対応)が用意されています。
ステップ3: コマンドラインで独自の環境を構築する
自前のGPU環境がある場合は、CLIで一連の処理を自動化できます。まずリポジトリをクローンし、ディレクトリ内でpip install .を実行してライブラリを導入します。
git clone https://github.com/decoderesearch/circuit-tracer.git
cd circuit-tracer
pip install .CLIは「帰属計算」「グラフファイルの生成」「ローカルサーバーの起動」という3段階の処理を1コマンドでつなぎます。
circuit-tracer attribute \
--prompt "The capital of France is" \
--transcoder_set gemma \
--slug capital-demo \
--graph_file_dir ./graph_files \
--server--transcoder_setにはHuggingFaceのリポジトリ名のほか、gemma(GemmaScopeトランスコーダー)やllama(ReLUトランスコーダー)といった簡易指定も使えます。--slugと--graph_file_dir(もしくは生グラフを保存する--graph_output_path)のどちらかは必ず指定しないと、CLIは何も出力しません。実行するとローカルサーバーのポート番号(既定8041)が表示されるので、リモートマシンで実行する場合はポートフォワーディングを忘れずに設定します。
グラフの枝刈りには--node_threshold(既定0.8、累積寄与度がこの値に達するまでノードを残す)と--edge_threshold(既定0.98、同様にエッジを残す)の2つのパラメーターが効きます。値を下げるほどグラフは簡素になり、上げるほど詳細な経路まで表示されます。
トランスコーダーの選び方とバックエンドの違い
対応モデルごとにHuggingFace上でトランスコーダー(モデル内部の特徴量を復元する小型ネットワーク)が公開されています。Gemma-2(2B)はPLTs(GemmaScope由来)と2種類のCLTs(426K・2.5M特徴量)、Llama-3.2(1B)はPLTsとCLTs、Qwen-3は0.6B〜14Bの各サイズごとにPLTsが用意されています。GPT-OSS(20B)はCLT、Llama 3.1(8B)InstructはTopK PLTsに対応します。ローカルに保存したトランスコーダーを使う場合は、ReplacementModel.from_pretrainedにフルパスを渡し、可視化サーバー起動時のfeatures_dir引数にも同じディレクトリを指定します。
バックエンドは既定でTransformerLensのHookedTransformerを継承しますが、TransformerLensが対応していないHuggingFaceモデルを扱うときはbackend='nnsight'を指定します。ただしnnsightバックエンドはまだ実験的な位置付けで、動作は遅くメモリー効率も劣り、TransformerLens版の全機能をカバーしているわけではありません。
よくあるつまずき
- Claudeを分析対象にしようとして止まる: circuit-tracerが対応するのは公開ウェイトモデルのみ。Claudeの重みは非公開なので、そのままでは分析対象にできません
--slugと--graph_file_dirのどちらも指定せずに実行して出力が出ない: 可視化用のグラフファイルを残すにはこの2つ、生グラフだけでよいなら--graph_output_pathが必須です- ローカルの大容量トランスコーダーで特徴量が表示されない:
features_dirをトランスコーダーの保存先と一致させていないと、可視化サーバーが特徴量データを読み込めません - リモートサーバーでの実行時にブラウザが繋がらない:
--serverはローカルにサーバーを立てるだけなので、リモートマシンで動かす場合はポートフォワーディングの設定が別途必要です
Anthropicがこのツールを公開した理由
Anthropicは2025年、ダリオ・アモデイが「AIの能力向上のペースに対して、内部動作の理解が大きく遅れている」と解釈可能性研究の緊急性を訴える文章を公開しています。circuit-tracerの公開はその主張を実装に落とした動きです。attribution graphが依拠する枠組みは、ニューロンを特徴量に分解するMonosemanticity論文やTransformer Circuitsの数学的フレームワークといった一連の解釈可能性研究の延長線上にあります。社内でしか使えなかった手法を外部に開放することで、コミュニティ側からの応用や改良を呼び込む狙いがあります。
実際、公開時点でAnthropicはこのツールを使ってGemma-2(2B)とLlama-3.2(1B)の多段階推論・多言語表現の分析を進めており、デモノートブックでその一部を確認できます。さらに未分析のattribution graphもデモノートブックとNeuronpedia上で公開しており、コミュニティが独自に興味深い回路を見つけることを想定しています。
Claude自身を直接調べられない制約はあるものの、Anthropicが自社モデルの解釈可能性でどのような手法を積み重ねてきたかを、手を動かして追体験できる点に価値があります。研究目的だけでなく、AIの内部動作を検証可能な形で理解したいエンジニアにとっても、無料のGPUだけで始められる実践的な入り口です。
まとめ
circuit-tracerは、Anthropicの解釈可能性研究の手法をオープンウェイトモデルで再現できるライブラリです。ブラウザ完結のNeuronpedia、Colabで動くノートブック、自前GPUで動かすCLIの3通りの入り口があり、いずれも同じ3段階(帰属計算・グラフ生成・可視化)の処理を踏みます。対応モデルはGemma-2・Llama・Qwen-3・GPT-OSSなどの公開ウェイトモデルに限られ、Claude自体はトレースできない点だけは押さえたうえで、GitHubのIssueで質問やフィードバックを送ることもできます。