Hugging Face's logo

Spaces:
Peppinob
/
attribution-graph-probing
Running

App Files Community
attribution-graph-probing / eda /README.md
peppinob-ol
Initial deployment: Attribution Graph Probing app
cb8a7e5
preview code
|
raw
history blame contribute delete
17.1 kB

Attribution Graph Probing - Applicazione Streamlit

Versione: 2.0.0-clean | Pipeline v2
Data: Ottobre 2025

Panoramica

Applicazione Streamlit interattiva per l'analisi di attribution graphs e probe prompting su modelli linguistici con Sparse Autoencoders (SAE).

Funzionalita Principali

  1. Graph Generation - Genera attribution graphs su Neuronpedia
  2. Probe Prompts - Analizza attivazioni su concepts specifici
  3. Node Grouping - Classifica e nomina supernodi per interpretazione

Avvio Rapido

Prerequisiti 

pip install streamlit plotly pandas seaborn matplotlib numpy requests openai python-dotenv

Oppure:

pip install -r requirements.txt

Configurazione API Keys

Crea un file .env nella root del progetto:

NEURONPEDIA_API_KEY='your-neuronpedia-key-here'
OPENAI_API_KEY='your-openai-key-here'

Avvio Applicazione

Dalla root del progetto:

streamlit run eda/app.py

L'app si aprira automaticamente su http://localhost:8501

Pagine dell'Applicazione

Pagina Principale

Dashboard con:

  • Link rapidi alle pagine
  • Info sulla struttura output folder
  • Statistiche file disponibili (grafi, JSON, CSV)

00 - Graph Generation

Genera attribution graphs su Neuronpedia

Funzionalita

  • Generazione Graph: Crea nuovi attribution graphs tramite API Neuronpedia
  • Estrazione Metriche: Genera CSV con node_influence, cumulative_influence, frac_external_raw
  • Visualizzazione Interattiva: Scatter plot Layer vs Context Position con filtri
  • Export Features: Seleziona e scarica features per analisi successive
  • Grafici Riassuntivi: Coverage e Strength analysis

Parametri Configurabili

Model & Source Set:

  • Model ID (gemma-2-2b, gpt2-small, gemma-2-9b)
  • Source Set Name (gemmascope-transcoder-16k, etc.)
  • Max Feature Nodes (100-10000)

Thresholds:

  • Node Threshold (0.0-1.0, default 0.8)
  • Edge Threshold (0.0-1.0, default 0.85)
  • Max N Logits (1-50, default 10)
  • Desired Logit Probability (0.5-0.99, default 0.95)

Output

  • Graph JSON salvato in output/graph_data/
  • CSV metriche statiche in output/graph_feature_static_metrics.csv
  • Features selezionate JSON per Node Grouping

Workflow

  1. Configura parametri (model, thresholds)
  2. Inserisci prompt da analizzare
  3. Genera graph (salvato automaticamente)
  4. Genera CSV metriche statiche
  5. Visualizza scatter plot e filtra features per cumulative influence
  6. Esporta features selezionate (formato completo: features + node_ids)
  7. Scarica JSON/CSV per step successivi

01 - Probe Prompts

Analizza attivazioni su concepts specifici tramite API

Funzionalita

  • Caricamento Graph: Da file locale o API Neuronpedia
  • Feature Subset: Carica un subset di features o usa tutte
  • Generazione Concepts: Automatica via OpenAI o inserimento manuale
  • Analisi Attivazioni: Via API Neuronpedia o caricamento JSON pre-calcolato
  • Checkpoint & Recovery: Salvataggio automatico progressi, ripresa da interruzioni
  • Visualizzazioni: Main chart (Importance vs Activation), grafici colorati per peak token
  • Coverage Analysis: Percentuale features attive e coverage dell'importanza causale

Parametri Configurabili

API Keys:

  • Neuronpedia API Key (richiesta)
  • OpenAI API Key (per generazione concepts)
  • Model OpenAI (gpt-4o-mini, gpt-4o, gpt-3.5-turbo)

Analisi:

  • Activation Threshold Quantile (0.5-0.99, default 0.9)
  • Use Baseline (calcola metriche vs prompt originale)
  • Checkpoint Every N Features (5-100, default 10)

Output

  • CSV con attivazioni: output/acts_compared.csv
  • Checkpoint JSON (salvati automaticamente in output/checkpoints/)
  • Grafici interattivi con filtri

Workflow

  1. Carica Graph JSON (file o API)
  2. Carica feature subset (o usa tutte le features del grafo)
  3. Genera/carica concepts (OpenAI, manuale o da file)
  4. Modifica concepts nella tabella editabile
  5. Salva concepts come prompts JSON
  6. Analisi via API:
    • Configura parametri (threshold, baseline, checkpoint)
    • Esegui analisi (con progress tracking)
    • Visualizza risultati (tabella + grafici)
    • Scarica CSV filtrati
  7. Analisi da JSON (alternativa):
    • Carica JSON pre-calcolato da Colab
    • Visualizza Main Chart (Importance vs Activation)
    • Analizza grafico colorato per peak token
    • Scarica tabella di verifica dati

Main Chart: Importance vs Activation

Grafico a barre stacked che mostra:

  • X-axis: Features ordinate per node_influence (decrescente)
  • Y-axis (left): Activation (max_value, escludendo BOS)
  • Y-axis (right): node_influence (linea rossa)
  • Barre colorate: Per prompt o per peak token

Filtri:

  • Top N features (10-100)
  • Escludi features con peak su BOS

Tabella di Verifica: Dati grezzi usati per il grafico con metriche dettagliate:

  • activation_max: Picco massimo di attivazione (esclude BOS)
  • activation_sum: Somma totale attivazioni (esclude BOS)
  • activation_mean: Media attivazioni normalizzata
  • sparsity_ratio: Concentrazione attivazione (0=uniforme, 1=molto sparsa)
  • peak_token_idx: Posizione del picco (>=1, esclude BOS)
  • node_influence: Valore massimo dal CSV
  • csv_ctx_idx: Contesto token dove node_influence e massima

Coverage Analysis:

  • Features Coverage: % features (nel JSON) che si attivano (>0) su almeno un probe prompt
  • Importance Coverage: % importanza causale coperta dalle features attive

02 - Node Grouping

Classifica e nomina supernodi per interpretazione del grafo

Funzionalita

  • Step 1 - Preparazione: Classifica token (functional vs semantic), trova target tokens
  • Step 2 - Classificazione: Assegna classi ai nodi (Semantic, Say X, Relationship)
  • Step 3 - Naming: Genera nomi descrittivi per ogni supernodo
  • Parametri Configurabili: Modifica soglie in tempo reale
  • Gestione Soglie: Salva/carica preset di soglie
  • Spiegazione Classificazione: Tool interattivo per capire perche una feature e stata classificata
  • Upload Neuronpedia: Carica subgraph con supernodes per visualizzazione interattiva

Input Richiesti

Obbligatori:

  • CSV Export da Probe Prompts (es. *_export_ENRICHED.csv)

Opzionali:

  • JSON Attivazioni (migliora naming per Relationship)
  • Graph JSON (per csv_ctx_idx fallback in Semantic naming)
  • Selected Nodes JSON (per upload subgraph accurato)

Parametri Configurabili

Pipeline:

  • Finestra ricerca target (3-15, default 7)

Dictionary Semantic:

  • Peak Consistency min (0.5-1.0, default 0.8)
  • N Distinct Peaks max (1-5, default 1)

Say X:

  • Func vs Sem % min (0-100%, default 50%)
  • Confidence F min (0.5-1.0, default 0.9)
  • Layer min (0-30, default 7)

Relationship:

  • Sparsity max (0.0-1.0, default 0.45)

Semantic (Concept):

  • Layer max (0-10, default 3)
  • Confidence S min (0.0-1.0, default 0.5)
  • Func vs Sem % max (0-100%, default 50%)

Output

  • CSV completo con classificazione e naming
  • Summary JSON con statistiche e parametri usati
  • Upload su Neuronpedia (opzionale)

Workflow

Step 1: Preparazione

  1. Carica CSV Export (automatico o upload)
  2. (Opzionale) Carica JSON Attivazioni
  3. Esegui Step 1
  4. Verifica statistiche (token funzionali vs semantici)
  5. Esamina campione risultati

Step 2: Classificazione

  1. (Opzionale) Modifica soglie nella sidebar
  2. Esegui Step 2
  3. Verifica distribuzione classi
  4. Filtra per classe e esamina risultati
  5. Usa "Spiega Classificazione Feature" per capire le decisioni
  6. (Opzionale) Itera modificando soglie

Step 3: Naming

  1. Esegui Step 3
  2. Verifica esempi naming per classe
  3. Analizza raggruppamento per supernode_name
  4. Download CSV completo e Summary JSON

Upload Neuronpedia:

  1. Inserisci API Key
  2. Configura Display Name
  3. (Opzionale) Overwrite ID per aggiornare subgraph esistente
  4. Upload e visualizza su Neuronpedia

Classi di Supernodi

Semantic (Dictionary):

  • Si attiva sempre sullo stesso token specifico
  • Metriche: peak_consistency alta (>=0.8), n_distinct_peaks = 1
  • Naming: Nome del token (es. "Texas")

Semantic (Concept):

  • Si attiva su token semanticamente simili
  • Metriche: conf_S alta (>=0.5), layer medio-basso
  • Naming: Token con max activation (es. "city")

Say "X":

  • Si attiva su token funzionali per predire il prossimo token
  • Metriche: func_vs_sem alta (>=50%), conf_F alta (>=0.9), layer alto (>=7)
  • Naming: "Say (X)" dove X e il target_token (es. "Say (Austin)")

Relationship:

  • Collega concetti semantici multipli con attivazione diffusa
  • Metriche: sparsity bassa (<0.45), K_sem_distinct alto
  • Naming: "(X) related" dove X e il primo token semantico con max attivazione

Metriche Chiave

  • peak_consistency_main: Quanto spesso il token principale e peak quando appare
  • n_distinct_peaks: Numero di token distinti come peak
  • func_vs_sem_pct: Differenza % tra max activation su functional vs semantic
  • conf_F / conf_S: Frazione di peak su token funzionali/semantici
  • sparsity_median: Mediana sparsity (0=diffusa, 1=concentrata)
  • K_sem_distinct: Numero di token semantici distinti

Struttura Dati

File Input

Graph JSON (da Graph Generation):

{
  "metadata": {
    "scan": "gemma-2-2b",
    "prompt": "The capital of state containing Dallas is",
    "prompt_tokens": [...]
  },
  "nodes": [
    {
      "node_id": "24_79427_7",
      "feature_type": "cross layer transcoder",
      "layer": 24,
      "activation": 0.123,
      "influence": 0.0042,
      "ctx_idx": 7
    }
  ],
  "links": [...]
}

CSV Export ENRICHED (da Probe Prompts):

feature_key,layer,prompt,peak_token,peak_token_idx,activation_max,sparsity_ratio,node_influence,...
24_79427,24,"entity: The capital city of Texas is Austin",Austin,7,12.34,0.85,0.0042,...

JSON Attivazioni (da batch_get_activations.py):

{
  "model": "gemma-2-2b",
  "source_set": "clt-hp",
  "results": [
    {
      "probe_id": "p1",
      "prompt": "...",
      "tokens": ["<BOS>", "The", "capital", ...],
      "activations": [
        {
          "source": "24-clt-hp",
          "index": 79427,
          "values": [0.0, 0.5, 12.34, ...],
          "max_value": 12.34,
          "max_value_index": 7
        }
      ]
    }
  ]
}

File Output

CSV Metriche Statiche (Graph Generation):

layer,id,ctx_idx,activation,node_influence,cumulative_influence,frac_external_raw
24,79427,7,12.34,0.0042,0.0056,0.23

Selected Features JSON (Graph Generation, formato completo):

{
  "features": [
    {"layer": 24, "index": 79427},
    {"layer": 12, "index": 5432}
  ],
  "node_ids": [
    "24_79427_7",
    "12_5432_3"
  ],
  "metadata": {
    "n_features": 2,
    "n_nodes": 2,
    "cumulative_threshold": 0.95,
    "exported_at": "2025-10-25T12:00:00"
  }
}

Acts Compared CSV (Probe Prompts):

feature_key,label,category,layer,activation_max,z_score,picco_su_label,cosine_similarity,...
24_79427,Austin,entity,24,12.34,2.5,True,0.85,...

Node Grouping CSV (Node Grouping):

feature_key,layer,prompt,pred_label,subtype,supernode_name,peak_token,activation_max,...
24_79427,24,"...",Semantic,Dictionary,Austin,Austin,12.34,...

Node Grouping Summary JSON:

{
  "timestamp": "2025-10-25T12:00:00",
  "n_features": 150,
  "n_unique_names": 45,
  "class_distribution": {
    "Semantic": 120,
    "Relationship": 20,
    "Say \"X\"": 10
  },
  "thresholds_used": {...},
  "top_supernodes": [...]
}

Workflow Completo

Pipeline Standard 

1. Graph Generation
   ↓
   - Graph JSON
   - CSV metriche statiche
   - Selected Features JSON
   ↓
2. Probe Prompts
   ↓
   - Genera/carica concepts
   - Analizza attivazioni (API o JSON)
   - Acts Compared CSV
   ↓
3. Node Grouping
   ↓
   - Classifica nodi
   - Nomina supernodi
   - Upload su Neuronpedia (opzionale)

Esempio Pratico

Obiettivo: Analizzare come il modello predice "Austin" nel prompt "The capital of state containing Dallas is"

  1. Graph Generation:

    • Prompt: "The capital of state containing Dallas is"
    • Genera graph su Neuronpedia
    • Estrai CSV metriche con node_influence
    • Filtra features per cumulative_influence <= 0.95
    • Esporta Selected Features JSON (50 features)

  2. Probe Prompts:

    • Carica Graph JSON + Selected Features JSON
    • Genera concepts con OpenAI (Dallas, Austin, Texas, capital, state)
    • Esegui analisi API (checkpoint ogni 10 features)
    • Visualizza Main Chart: feature ordinate per node_influence
    • Scarica Acts Compared CSV

  3. Node Grouping:

    • Carica Acts Compared CSV + JSON Attivazioni
    • Step 1: Classifica token (functional: "is", "the" / semantic: "Dallas", "Austin")
    • Step 2: Classifica features (90% Semantic, 10% Relationship)
    • Step 3: Nomina supernodi ("Austin", "Dallas", "Texas", "(state) related", etc.)
    • Upload su Neuronpedia per visualizzazione

Troubleshooting

Problemi Comuni

"API Key non trovata"

  • Soluzione: Crea file .env con le chiavi API

"Dati essenziali mancanti"

  • Soluzione: Esegui la pipeline completa in ordine (Graph Generation → Probe Prompts → Node Grouping)

"Grafo causale non disponibile"

  • Soluzione: Genera Graph JSON in Step 00, poi genera CSV metriche statiche

"ModuleNotFoundError: eda"

  • Soluzione: Avvia da root del progetto: streamlit run eda/app.py

"Checkpoint corrotto"

  • Soluzione: Elimina checkpoint in output/checkpoints/ e riavvia analisi

"Naming Relationship non accurato"

  • Soluzione: Fornisci JSON attivazioni completo in Node Grouping

"Classificazione non soddisfacente"

  • Soluzione: Modifica soglie in Node Grouping sidebar e riesegui Step 2

Cache Streamlit

Se i dati sembrano obsoleti:

  • Menu hamburger (top-right) > Clear cache
  • Oppure Settings > Clear cache
  • Riavvia l'app

Best Practices

Graph Generation

  1. Inizia con thresholds di default, poi affina
  2. Usa filtro cumulative_influence per selezionare features rilevanti
  3. Esporta sempre Selected Features JSON (formato completo con node_ids) per Node Grouping

Probe Prompts

  1. Usa checkpoint per analisi lunghe (>100 features)
  2. Abilita baseline per confronti robusti
  3. Carica JSON pre-calcolato da Colab per analisi veloci
  4. Filtra features con peak su BOS per grafici piu puliti
  5. Usa tabella di verifica per debug e quality check

Node Grouping

  1. Fornisci sempre JSON attivazioni per naming Relationship accurato
  2. Inizia con soglie di default, poi itera su Step 2-3
  3. Usa "Spiega Classificazione Feature" per capire decisioni
  4. Scarica Summary JSON per documentare parametri usati
  5. Carica Selected Nodes JSON per upload Neuronpedia accurato

Performance

Caricamento:

  • Prima apertura app: < 10 secondi
  • Cambio pagina: < 2 secondi

Cache:

  • Dati caricati con @st.cache_data
  • Grafici renderizzati on-demand

Limiti:

  • Graph Generation: max 10000 feature nodes
  • Probe Prompts: rate limit API 5 req/sec
  • Node Grouping: gestisce dataset fino a 1000 features

Dipendenze

Core:

  • streamlit >= 1.28
  • plotly >= 5.18
  • pandas >= 2.0
  • numpy >= 1.24

API:

  • requests >= 2.31
  • openai >= 1.0
  • python-dotenv >= 1.0

Visualization:

  • seaborn >= 0.12
  • matplotlib >= 3.7

Optional:

  • scipy (per test statistici in Causal Validation)
  • scikit-learn (per ROC curves)

Riferimenti

Documentazione Tecnica

  • Graph Generation: scripts/00_neuronpedia_graph_generation.py
  • Probe Prompts: scripts/01_probe_prompts.py
  • Node Grouping: scripts/02_node_grouping.py
  • Causal Utils: scripts/causal_utils.py

Guide

  • Quick Start: QUICK_START_STREAMLIT.md
  • Neuronpedia Export: docs/NEURONPEDIA_EXPORT_GUIDE.md
  • Probe Prompts: docs/PROBE_PROMPTS_QUICKSTART.md
  • Node Grouping: eda/pages/README_NODE_GROUPING.md

Utilities

  • Graph Visualization: eda/utils/graph_visualization.py
  • Data Loader: eda/utils/data_loader.py
  • Plots: eda/utils/plots.py

Sviluppo

Struttura Codice 

eda/
├── app.py                          # Entry point
├── pages/                          # Pagine Streamlit
│   ├── 00_Graph_Generation.py
│   ├── 01_Probe_Prompts.py
│   ├── 02_Node_Grouping.py
│   └── README_NODE_GROUPING.md
├── utils/                          # Utilities
│   └── graph_visualization.py
└── README.md                       # Questa guida

Modifiche

Per modificare l'app:

  1. Modifica file in eda/
  2. Streamlit rileva automaticamente cambiamenti
  3. Testa con dati reali da output/

Supporto

Per domande o problemi:

  1. Consulta questa guida
  2. Leggi la documentazione tecnica in docs/
  3. Esamina gli script di backend in scripts/
  4. Controlla i test in tests/

Autore: Sistema automatizzato
Licenza: Vedi LICENSE
Repository: attribution-graph-probing

Buon lavoro con Attribution Graph Probing! 🔬🌐🔍