Conformità e Traccia di Audit
In questa pagina
Conformità e Traccia di Audit
Per le applicazioni AI in produzione, la tracciabilità è essenziale. Una traccia di audit completa ti protegge durante un’ispezione, una controversia o un incidente. Questa lezione ti mostra come implementare un sistema di audit robusto, chiudendo il corso riunendo tutto ciò che hai costruito finora—logging, moderazione e protezione dei dati—in un unico framework difendibile.
Perché una Traccia di Audit?
Quattro esigenze distinte convergono sulla stessa infrastruttura. Primo, la conformità normativa: il GDPR, l’European AI Act e gli standard di settore richiedono tutti di dimostrare cosa fa il tuo sistema, e una dimostrazione senza log non vale nulla. Secondo, la tracciabilità in senso stretto: sapere chi ha fatto cosa, quando, con quale risultato, anche sei mesi dopo. Il debug ne beneficia quotidianamente, poiché comprendere il comportamento inaspettato del modello richiede di recuperare le condizioni esatte della chiamata. Infine, la responsabilità: documentare le decisioni prese dall’AI è ciò che ti permetterà, al momento opportuno, di dimostrare che una raccomandazione contestata si basava su un processo controllato.
Struttura di un Record di Audit
La dataclass qui sotto è tanto un contratto quanto una struttura dati. Raggruppa identificatori, contesto dell’applicazione, la richiesta, la risposta, il verdetto di moderazione e i metadati tecnici. Due scelte meritano la tua attenzione. L’identificativo utente appare solo in forma hashata, mai in chiaro. E il prompt non viene memorizzato: ne vengono salvati solo l’hash e la lunghezza. Questo preserva la tua capacità di provare che due chiamate riguardavano lo stesso contenuto senza creare mai un archivio di ciò che i tuoi utenti hanno scritto.
from dataclasses import dataclass, field, asdict
from datetime import datetime
from typing import Optional
import json
import uuid
import hashlib
@dataclass
class AuditRecord:
"""Audit record for an API call."""
# Identifiers
audit_id: str = field(default_factory=lambda: str(uuid.uuid4()))
timestamp: str = field(
default_factory=lambda: datetime.now().isoformat()
)
# Context
user_id_hash: str = "" # Never the plain ID
session_id: str = ""
application: str = ""
# Request (no sensitive data)
model: str = ""
prompt_hash: str = "" # Hash of the prompt, not the prompt itself
prompt_length: int = 0
# Response
response_id: str = ""
output_length: int = 0
input_tokens: int = 0
output_tokens: int = 0
# Moderation
input_flagged: bool = False
output_flagged: bool = False
# Metadata
duration_ms: int = 0
status: str = "success"
error: Optional[str] = None
def to_json(self) -> str:
return json.dumps(asdict(self), ensure_ascii=False)
Sistema di Audit Completo
Il client che sfrutta questa struttura concatena la moderazione in input, la chiamata API, la moderazione in output e scrive in ogni caso. La parola importante è append-only: il file JSONL viene aperto in modalità aggiunta, mai riscritto, condizione necessaria affinché un log abbia valore probatorio. Nota il percorso di una voce segnalata: il record viene salvato prima che l’eccezione venga sollevata, con lo stato blocked_input. Un blocco lascia quindi una traccia proprio come un successo, e il blocco except finale garantisce che nessun errore, qualunque sia la sua origine, sfugga al radar.
import time
from openai import OpenAI
class AuditedClient:
"""OpenAI client with integrated audit trail."""
def __init__(self, application: str, audit_store: str = "audit.jsonl"):
self.client = OpenAI()
self.application = application
self.audit_store = audit_store
def _hash(self, text: str) -> str:
"""Truncated SHA-256 hash for auditing."""
return hashlib.sha256(text.encode()).hexdigest()[:16]
def _save_audit(self, record: AuditRecord):
"""Saves an audit record (append-only)."""
with open(self.audit_store, "a", encoding="utf-8") as f:
f.write(record.to_json() + "\n")
def create(self, user_id: str, session_id: str,
model: str, input: str, **kwargs) -> object:
"""API call with automatic auditing."""
record = AuditRecord(
user_id_hash=self._hash(user_id),
session_id=session_id,
application=self.application,
model=model,
prompt_hash=self._hash(input),
prompt_length=len(input),
)
start = time.monotonic()
try:
# Input moderation
mod = self.client.moderations.create(
model="omni-moderation-latest",
input=input
)
record.input_flagged = mod.results[0].flagged
if record.input_flagged:
record.status = "blocked_input"
self._save_audit(record)
raise ValueError("Inappropriate input content")
# API call
response = self.client.responses.create(
model=model,
input=input,
**kwargs
)
# Output moderation
mod_out = self.client.moderations.create(
model="omni-moderation-latest",
input=response.output_text
)
record.output_flagged = mod_out.results[0].flagged
# Fill metrics
record.response_id = response.id
record.output_length = len(response.output_text)
record.input_tokens = response.usage.input_tokens
record.output_tokens = response.usage.output_tokens
record.duration_ms = round((time.monotonic() - start) * 1000)
record.status = "success"
self._save_audit(record)
return response
except Exception as e:
record.duration_ms = round((time.monotonic() - start) * 1000)
record.status = "error"
record.error = type(e).__name__
self._save_audit(record)
raise
# Usage
audited = AuditedClient(application="support-chatbot")
response = audited.create(
user_id="[email protected]",
session_id="sess-abc123",
model="gpt-5.6-terra",
input="How do I return a product?"
)
print(response.output_text)
In questo esempio, l’indirizzo email passato come user_id non raggiunge mai il file: viene hashato non appena il record viene costruito. Un file JSONL va bene per iniziare e per una singola istanza; non appena più processi scrivono in parallelo, indirizza questo flusso verso un database o un collettore di log.
Query di Audit
Un log che non puoi interrogare serve solo a occupare spazio su disco. La lettura riga per riga del formato JSONL rende lo sfruttamento banale e il rapporto qui sotto riassume il periodo coperto, la distribuzione tra successi, errori e blocchi, il consumo di token e la latenza media. Il conteggio degli utenti unici si basa sugli hash, il che prova incidentalmente che un log pseudonimizzato rimane perfettamente analizzabile.
import json
def read_audit(file: str = "audit.jsonl") -> list[dict]:
"""Reads all audit records."""
records = []
try:
with open(file, "r", encoding="utf-8") as f:
for line in f:
if line.strip():
records.append(json.loads(line))
except FileNotFoundError:
pass
return records
def audit_report(file: str = "audit.jsonl") -> dict:
"""Generates an audit report."""
records = read_audit(file)
if not records:
return {"message": "No records"}
total = len(records)
errors = sum(1 for r in records if r["status"] == "error")
blocked = sum(1 for r in records if r["status"] == "blocked_input")
tokens_total = sum(
r.get("input_tokens", 0) + r.get("output_tokens", 0)
for r in records
)
durations = [r["duration_ms"] for r in records if r["duration_ms"] > 0]
return {
"period": {
"start": records[0]["timestamp"],
"end": records[-1]["timestamp"],
},
"total_calls": total,
"successes": total - errors - blocked,
"errors": errors,
"moderation_blocks": blocked,
"tokens_consumed": tokens_total,
"avg_latency_ms": round(sum(durations) / max(len(durations), 1)),
"unique_users": len(set(r["user_id_hash"] for r in records)),
}
print(json.dumps(audit_report(), indent=2, ensure_ascii=False))
Conservazione e Archiviazione
Mantenere i dati a tempo indeterminato contraddice il principio di limitazione della conservazione; cancellare troppo presto ti priva della prova di cui potresti aver bisogno. La rotazione risolve questo dilemma: oltre una durata che imposti—novanta giorni qui—i record lasciano il file attivo per un archivio datato, mentre il log corrente viene riscritto con solo quelli recenti. Programma questa funzione come attività periodica e allinea retention_days alla politica convalidata dal tuo consulente legale, non a un valore scelto a caso.
from datetime import datetime, timedelta
import shutil
import os
def archive_audit(file: str = "audit.jsonl",
retention_days: int = 90):
"""Archives and purges old records."""
records = read_audit(file)
limit = datetime.now() - timedelta(days=retention_days)
recent = []
archives = []
for record in records:
date_record = datetime.fromisoformat(record["timestamp"])
if date_record > limit:
recent.append(record)
else:
archives.append(record)
if archives:
# Archive old ones
archive_name = f"audit_archive_{datetime.now().strftime('%Y%m%d')}.jsonl"
with open(archive_name, "w", encoding="utf-8") as f:
for record in archives:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
# Rewrite main file with recent ones
with open(file, "w", encoding="utf-8") as f:
for record in recent:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print(f"Archived {len(archives)} records to {archive_name}")
print(f"Kept {len(recent)} recent records")
European AI Act: Cosa Cambia
L’European AI Act (AI Act) impone obblighi basati sul livello di rischio della tua applicazione. La logica è graduata: più il tuo sistema pesa sulla vita delle persone, più severi sono i requisiti. Un chatbot FAQ, un riassunto o una traduzione rientrano nel rischio minimo e richiedono solo una trasparenza di base. Non appena c’è conversazione o analisi del sentiment, passi al rischio limitato, con l’obbligo di informare l’utente che sta interagendo con un’AI. Il salto è brusco per l’alto rischio—scoring del credito, reclutamento, diagnosi medica—dove si aggiungono valutazione di conformità, gestione del rischio, documentazione dei dati di addestramento, tracciabilità completa, supervisione umana e dimostrazione dell’accuratezza. Alcuni usi, come lo scoring sociale o la manipolazione subliminale, sono puramente vietati.
# Assess the risk level of your application
RISK_LEVELS = {
"minimal": {
"examples": ["FAQ chatbot", "text summary", "translation"],
"obligations": ["Basic transparency"]
},
"limited": {
"examples": ["customer service chatbot", "sentiment analysis"],
"obligations": ["Inform the user they are interacting with an AI"]
},
"high": {
"examples": ["credit scoring", "recruitment", "medical diagnosis"],
"obligations": [
"Conformity assessment",
"Risk management system",
"Documented training data",
"Logging and complete traceability",
"Mandatory human supervision",
"Demonstrated accuracy and robustness"
]
},
"unacceptable": {
"examples": ["social scoring", "subliminal manipulation"],
"obligations": ["PROHIBITED"]
}
}
Colloca onestamente il tuo progetto in questa griglia prima di scrivere la prima riga di codice: un’applicazione classificata come ad alto rischio impone vincoli architetturali—logging esaustivo, punto di controllo umano—che non possono essere innestati dopo il fatto su un sistema progettato senza di essi.
Checklist di Conformità
- Traccia di audit append-only con timestamp
- Hash dei dati personali nei log (mai in chiaro)
- Moderazione sistematica di input e output
- Registro delle attività di trattamento GDPR aggiornato
- Politica di conservazione e archiviazione definita
- Valutazione del livello di rischio AI Act eseguita
- Informare gli utenti che stanno interagendo con un’AI
- Supervisione umana per le decisioni impattanti
Punti chiave
- Una traccia di audit è obbligatoria per la conformità normativa
- Logga in modalità append-only: non modificare mai i record esistenti
- Hasha tutti i dati personali nei log di audit
- L’European AI Act classifica le applicazioni per livello di rischio
- Implementa la moderazione automatica E la supervisione umana
- Definisci una politica di conservazione e archivia regolarmente
Metti alla Prova le Tue Conoscenze
Ventidue lezioni sulle API: valida i meccanismi che tengono insieme la produzione.
1. Perché migrare alle Responses API invece di rimanere su Chat Completions?
Risposta: È l’API moderna di OpenAI: gestione integrata dello stato della conversazione, strumenti nativi ed evoluzione focalizzata su di essa—Chat Completions rimane supportata ma legacy.
2. Come scegli tra Sol, Terra e Luna dal lato API?
Risposta: gpt-5.6-sol per compiti impegnativi, terra per l’equilibrio costo/qualità, luna per volumi economici—e il livello di ragionamento (none→max) viene quindi aggiustato per richiesta.
3. Cosa garantisce l'Output Strutturato?
Risposta: Un output conforme allo schema JSON fornito—campi, tipi, struttura—sfruttabile da un programma senza parsing difensivo o riparazione.
4. Cosa fai di fronte a un errore 429?
Risposta: Rispetta i limiti di frequenza: riprova con backoff esponenziale (e jitter), limita i tentativi e pianifica un circuit breaker—mai un ciclo di retry immediato.
5. Cita due protezioni indispensabili sul lato della sicurezza dell'applicazione.
Risposta: Moderazione dei contenuti in entrata/uscita tramite l’API dedicata e difesa contro il prompt injection: isola le istruzioni dai dati, valida gli output, limita le capacità esposte.
Produzione, sicurezza, conformità: gli ultimi tre blocchi del corso fanno la differenza tra un prototipo e un servizio—tienili come checklist.