Craicek's Activation Steering per Local LLMs

Implementazione completa di Activation Steering per modelli linguistici locali (Gemma, Llama, Mistral, etc.) con supporto per:

• ✅ Basic Activation Steering - Estrazione e applicazione di vettori di steering
• ✅ Dynamic Activation Steering - Steering adattivo che si aggiorna durante la generazione
• ✅ Power Sampling - Tecnica di sampling avanzata per controllo preciso dell'influenza
• ✅ Multi-modello - Supporta Gemma, Gemma2, Gemma3, Llama, Mistral, Phi-2, Qwen2, e altri

🚀 Installazione

pip install -r requirements.txt

📚 Concetti Base

Activation Steering

L'Activation Steering modifica il comportamento di un LLM intervenendo direttamente sulle attivazioni interne dei layer del modello, senza dover fare fine-tuning.

Vantaggi:

• Nessun training richiesto
• Controllo granulare del comportamento
• Reversibile e aggiustabile in tempo reale
• Funziona su modelli locali

Power Sampling

Tecnica di sampling che eleva le probabilità a una potenza prima di campionare:

• alpha = 1.0: Sampling standard
• alpha > 1.0: Amplifica differenze, output più "audace"
• alpha < 1.0: Output più uniforme

Dynamic Activation Steering

Il sistema adatta i vettori di steering durante la generazione in base alle attivazioni correnti, permettendo un controllo più fine.

🎯 Utilizzo Rapido

Esempio 1: Basic Steering

from transformers import AutoTokenizer, AutoModelForCausalLM
from activation_steering import ActivationSteering

# Carica modello
model_name = "google/gemma-2-2b-it"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto"
)

# Inizializza steering
steering = ActivationSteering(
    model=model,
    tokenizer=tokenizer,
    layers=[10, 15, 20],
    coefficient=1.5
)

# Estrarre attivazioni da esempi positivi e negativi
positive_examples = [
    "I'm always helpful and provide accurate information.",
    "I strive to give thorough and useful answers."
]

negative_examples = [
    "I don't know and I don't care to help.",
    "That's not something I want to answer."
]

steering.extract_activations(positive_examples, "positive")
steering.extract_activations(negative_examples, "negative")
steering.compute_steering_vectors()

# Generare con steering
output = steering.generate_with_steering(
    "How can you help me?",
    max_length=100,
    temperature=0.7
)
print(output)

Esempio 2: Power Sampling

output = steering.generate_with_steering(
    "Tell me about space exploration",
    max_length=100,
    temperature=0.8,
    power_sampling=True,
    power_alpha=2.0  # Higher = more "bold" steering
)

Esempio 3: Dynamic Steering

from dynamic_steering import DynamicActivationSteering

dynamic_steering = DynamicActivationSteering(
    model=model,
    tokenizer=tokenizer,
    layers=[8, 12, 16, 20],
    coefficient=1.0,
    adaptation_rate=0.15,
    update_frequency=3
)

# Configura
dynamic_steering.extract_activations(positive_examples, "positive")
dynamic_steering.compute_steering_vectors(method="mean_pos")

# Imposta target
layer = list(dynamic_steering.positive_activations.keys())[0]
target = torch.stack(
    dynamic_steering.positive_activations[layer]
).mean(dim=0)
dynamic_steering.set_target_direction({layer: target})

# Genera con steering dinamico
output, metadata = dynamic_steering.generate_with_dynamic_steering(
    prompt,
    max_length=100,
    layer_schedule="gradient",  # "constant", "early", "late", "gradient"
    coefficient_schedule="adaptive",  # "constant", "decay", "adaptive"
    power_sampling=True,
    power_alpha=2.0
)

📖 Esempi Pratici

Eseguire gli esempi

# Esempi base
python example_usage.py

# Esempio pratico - migliorare helpfulness
python practical_example.py

Caso d'uso: Ridurre Refusals

from practical_example import HelpfulnessSteering

# Inizializza
steerer = HelpfulnessSteering(model_name="google/gemma-2-2b-it")
steerer.configure()

# Confronta
result = steerer.compare(
    "Can you explain how neural networks learn?",
    max_tokens=150
)

🔧 Parametri Chiave

Basic Steering

Parametro	Default	Descrizione
layers	[10, 15, 20]	Layer da modificare
coefficient	1.0	Forza dello steering
steering_type	"linear"	Tipo: "linear", "normalized", "directional"

Dynamic Steering

Parametro	Default	Descrizione
adaptation_rate	0.1	Velocità di adattamento (0-1)
momentum	0.9	Momentum per aggiornamenti
update_frequency	5	Aggiorna ogni N token
layer_schedule	"constant"	Schedule layer: "constant", "early", "late", "gradient"
coefficient_schedule	"constant"	Schedule coefficiente: "constant", "decay", "adaptive"

Power Sampling

Parametro	Default	Descrizione
power_alpha	2.0	Potenza per sampling (>1 = più "audace")

💡 Best Practices

1. Scelta dei Layer

• Layer iniziali (0-10): Influenzano stile e tono
• Layer medi (10-20): Buon equilibrio, spesso ottimali
• Layer finali (20+): Influenzano contenuto e decisioni finali

2. Coefficiente di Steering

• Inizia con 1.0-1.5
• Aumenta gradualmente se l'effetto è debole
• Troppo alto → comportamento estremo/ripetitivo

3. Power Alpha

• 1.5-2.0: Buon punto di partenza
• 2.5-3.0: Steering più forte
• 3.0+: Molto aggressivo,可能性退化

4. Esempi Positivi/Negativi

• Usa 5-10 esempi per categoria
• Esempi positivi: comportamento desiderato
• Esempi negativi: comportamento da evitare
• Sii specifico e chiaro

🎨 Casi d'Uso Avanzati

Steering per Creatività

positive_creative = [
    "Here's a highly creative and imaginative response.",
    "Let me provide an original and innovative perspective.",
]

negative_boring = [
    "Here's a standard, conventional answer.",
    "I'll give you the most basic response possible.",
]

steering.extract_activations(positive_creative, "positive")
steering.extract_activations(negative_boring, "negative")

Steering per Precisione

positive_precise = [
    "Based on the available data, the answer is approximately...",
    "Research indicates that this approach is most effective because...",
]

negative_vague = [
    "Maybe it's something like that, I'm not sure.",
    "It could be this or that or something else.",
]

Steering per Tonc Specifico

positive_formal = [
    "I would be delighted to assist you with this inquiry.",
    "Allow me to provide a comprehensive explanation.",
]

positive_casual = [
    "Sure, I can help with that! Here's the deal...",
    "No problem! Let me break this down for you.",
]

🔬 Architettura

activation_steering.py
├── ActivationSteering              # Classe base
│   ├── extract_activations()       # Estrae attivazioni
│   ├── compute_steering_vectors()  # Calcola vettori
│   ├── apply_steering()           # Applica steering
│   └── generate_with_steering()   # Genera con steering
│
dynamic_steering.py
├── DynamicActivationSteering       # Steering dinamico
│   ├── update_steering_vectors()  # Aggiorna vettori
│   └── generate_with_dynamic_steering()
│
└── AdaptiveActivationSteering      # Steering adattivo auto
    └── auto_tune_parameters()     # Ottimizzazione automatica

📊 Metodologie

Mean Difference

steering.compute_steering_vectors(method="mean_diff")

Calcola: vettore = media(positivi) - media(negativi)

Mean Positive

steering.compute_steering_vectors(method="mean_pos")

Calcola: vettore = media(positivi)

⚙️ Troubleshooting

Problema: Nessun effetto

• Aumenta coefficient
• Prova layer diversi
• Verifica che extract_activations abbia catturato dati

Problema: Comportamento ripetitivo

• Riduci coefficient
• Riduci power_alpha
• Aumenta temperature

Problema: Output degradato

• Riduci adaptation_rate in dynamic steering
• Meno frequenti aggiornamenti (update_frequency)
• Usa layer meno critici

📝 Note Tecniche

• Supporta modelli con architettura: Llama, Mistral, Gemma, Gemma2, Gemma3, GPT-2, GPT-NeoX, Qwen2
• Richiede torch>=2.0
• Raccomandato: GPU con 8GB+ VRAM per modelli 7B
• Per CPU: usa modelli più piccoli (1-3B parametri)

🤝 Contributi

Questo è un progetto dimostrativo/educativo. Sentiti libero di estendere e migliorare!

📄 Licenza

MIT License - Sentiti libero di usare questo codice per i tuoi progetti.

🙏 Riferimenti

Basato sulla ricerca su Activation Steering e representation engineering:

• Activation Steering
• Representation Engineering
• Refusal Direction

---

Creato per l'utilizzo con modelli locali - Privacy first, senza dipendenze esterne!