Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Conformità e Traccia di Audit

Lezione 22 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Conformità e Traccia di Audit
  2. Perché una Traccia di Audit?
  3. Struttura di un Record di Audit
  4. Sistema di Audit Completo
  5. Query di Audit
  6. Conservazione e Archiviazione
  7. European AI Act: Cosa Cambia
  8. Checklist di Conformità
  9. Punti chiave
  10. Metti alla Prova le Tue Conoscenze

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.