Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Rilevamento di anomalie e duplicati

Lezione 20 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Rilevamento delle anomalie
  3. Rilevamento semantico dei duplicati
  4. Pipeline di deduplicazione
  5. Punti chiave

Obiettivi

  • Rilevare testi anomali all’interno di un corpus
  • Identificare duplicati semantici
  • Costruire una pipeline di deduplicazione

Rilevamento delle anomalie

Le due applicazioni di questa lezione condividono la stessa intuizione, applicata agli estremi opposti della scala di similarità. Un testo è “anomalo” se è semanticamente distante da tutto il resto del corpus; un testo è un duplicato se è troppo vicino. Gli embedding ti permettono di misurare questa distanza in entrambi i casi. La maggior parte del lavoro consiste nel calibrare le soglie.

Il primo approccio costruisce il centroide del corpus—la media di tutti i vettori, che rappresenta “l’argomento usuale di questo corpus”—e poi misura quanto ogni testo si discosta da esso. La soglia non è intenzionalmente un valore assoluto ma un percentile: non puoi sapere in anticipo quanto sia distante un’anomalia, ma sai di voler esaminare il 5% più atipico.

from openai import OpenAI
import numpy as np

client = OpenAI()

def detect_anomalies(
    texts: list[str],
    percentile_threshold: float = 95,
    model: str = "text-embedding-3-large"
) -> list[dict]:
    """Detects abnormal texts by distance to the centroid."""
    response = client.embeddings.create(
        input=texts, model=model
    )
    embeddings = np.array(
        [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    )

    # Corpus centroid
    centroid = embeddings.mean(axis=0)
    centroid /= np.linalg.norm(centroid)

    # Distance of each text to the centroid
    similarities = embeddings @ centroid
    threshold = np.percentile(similarities, 100 - percentile_threshold)

    anomalies = []
    for i, sim in enumerate(similarities):
        if sim < threshold:
            anomalies.append({
                "index": i,
                "text": texts[i],
                "similarity": float(sim),
                "is_anomaly": True
            })

    return anomalies

# Example
corpus = [
    "Our leave policy provides 25 days per year",
    "Leave must be requested 2 weeks in advance",
    "Leave balances are visible on the HR portal",
    "Exceptional leave is granted with supporting documentation",
    "SELECT * FROM users WHERE admin=1; DROP TABLE users;--",  # Anomaly!
    "The remote work policy allows 3 days per week",
]

anomalies = detect_anomalies(corpus)
for a in anomalies:
    print(f"  ANOMALY [{a['similarity']:.3f}] : {a['text'][:60]}...")

L’esempio del corpus parla da solo: cinque frasi sulle policy HR e un tentativo di SQL injection. Nessun filtro per parole chiave avrebbe catturato l’iniezione senza una regola pre-scritta; la distanza dal centroide la segnala senza alcuna anticipazione preventiva. Questo è l’argomento principale per usare il metodo nel monitoraggio di un flusso di documenti in arrivo.

Il centroide ha però una debolezza: presuppone che il corpus ruoti attorno a un unico tema. Se i tuoi documenti coprono tre domini molto diversi, il punto medio cade in un vuoto semantico e tutti i testi appaiono ugualmente distanti. L’approccio k-nearest neighbors aggira il problema giudicando ogni testo in base al suo vicinato immediato piuttosto che all’intero insieme: un documento appartenente a un gruppo minoritario rimane normale finché ha dei vicini.

def detect_anomalies_knn(
    texts: list[str],
    k: int = 3,
    percentile_threshold: float = 90,
    model: str = "text-embedding-3-large"
) -> list[dict]:
    """Detects anomalies by distance to the k nearest neighbors."""
    response = client.embeddings.create(
        input=texts, model=model
    )
    embeddings = np.array(
        [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    )

    # Similarity matrix
    sim_matrix = embeddings @ embeddings.T

    # For each text, average of the k nearest neighbors
    isolation_scores = []
    for i in range(len(texts)):
        sims = sim_matrix[i].copy()
        sims[i] = -1  # Exclude self
        top_k_sims = np.sort(sims)[-k:]
        isolation_scores.append(top_k_sims.mean())

    threshold = np.percentile(isolation_scores, 100 - percentile_threshold)

    anomalies = []
    for i, score in enumerate(isolation_scores):
        if score < threshold:
            anomalies.append({
                "index": i,
                "text": texts[i],
                "isolation_score": float(score)
            })

    return anomalies

Rilevamento semantico dei duplicati

All’altro estremo della scala ci sono i testi troppo vicini. Due voci possono essere duplicati anche con parole diverse—«Come重置o la mia password?» e «Password dimenticata, cosa faccio?» condividono solo tre parole comuni—ed è esattamente ciò che l’hashing o il confronto di stringhe non cattureranno mai. Gli embedding li rilevano.

La funzione calcola l’intera matrice di similarità e restituisce tutte le coppie sopra la soglia. Fai attenzione al costo: questo confronto è quadratico, il che rimane istantaneo per alcune migliaia di testi ma diventa impraticabile per un milione—devi allora usare un indice approssimato come quelli trattati con i database vettoriali.

def find_duplicates(
    texts: list[str],
    threshold: float = 0.90,
    model: str = "text-embedding-3-large"
) -> list[dict]:
    """Finds pairs of semantically identical texts."""
    response = client.embeddings.create(
        input=texts, model=model
    )
    embeddings = np.array(
        [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    )

    # Similarity matrix
    sim_matrix = embeddings @ embeddings.T

    duplicates = []
    for i in range(len(texts)):
        for j in range(i + 1, len(texts)):
            if sim_matrix[i][j] >= threshold:
                duplicates.append({
                    "text_a": texts[i],
                    "text_b": texts[j],
                    "index_a": i,
                    "index_b": j,
                    "similarity": float(sim_matrix[i][j])
                })

    return sorted(duplicates, key=lambda x: x["similarity"], reverse=True)

# Example
texts = [
    "How do I reset my password?",
    "I cannot log in to my account",
    "Forgot password, what do I do?",           # Duplicate of [0]
    "What is the refund policy?",
    "Unable to access my personal space",       # Duplicate of [1]
    "How do I get a refund?",                   # Duplicate of [3]
]

dupes = find_duplicates(texts, threshold=0.85)
print(f"{len(dupes)} duplicate pairs found:")
for d in dupes:
    print(f"  [{d['similarity']:.3f}]")
    print(f"    A: {d['text_a']}")
    print(f"    B: {d['text_b']}")

La chiamata qui usa una soglia di 0,85 invece del default 0,90 perché le riformulazioni della stessa domanda di supporto spesso scendono ben sotto 0,90. Questa è l’impostazione su cui passerai più tempo a lavorare: se la imposti troppo alta, lasci passare i duplicati; se la imposti troppo bassa, unisci «come cambio la password» con «come cambio il mio indirizzo email», due domande distinte che sembrano molto simili.

Pipeline di deduplicazione

Rilevare le coppie non basta per pulire un corpus. Se A assomiglia a B e B assomiglia a C, tutti e tre appartengono allo stesso gruppo, anche se A e C non sono stati mai confrontati direttamente sopra la soglia. Il raggruppamento transitivo è il vero lavoro, e la struttura Union-Find lo gestisce in un’unica passata: ogni coppia rilevata unisce due insiemi, producendo alla fine gruppi di duplicati completamente formati.

Devi ancora scegliere quale membro sopravvive. La regola usata qui—il testo più breve—funziona bene per le domande di supporto, dove la formulazione più concisa è spesso la più canonica. Per un corpus di documenti, probabilmente vorrai l’opposto, o il più recente: questa è una decisione di business, non un dettaglio tecnico. Il dizionario restituito mantiene la lista dei testi eliminati così che un umano possa verificare i casi limite prima di approvare.

class Deduplicator:
    def __init__(self, threshold: float = 0.90):
        self.client = OpenAI()
        self.threshold = threshold

    def deduplicate(self, texts: list[str]) -> dict:
        """Removes semantic duplicates."""
        response = self.client.embeddings.create(
            input=texts, model="text-embedding-3-large"
        )
        embeddings = np.array(
            [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
        )

        # Union-Find to group duplicates
        parent = list(range(len(texts)))

        def find(x):
            while parent[x] != x:
                parent[x] = parent[parent[x]]
                x = parent[x]
            return x

        def union(a, b):
            pa, pb = find(a), find(b)
            if pa != pb:
                parent[pb] = pa

        # Find similar pairs
        sim_matrix = embeddings @ embeddings.T
        for i in range(len(texts)):
            for j in range(i + 1, len(texts)):
                if sim_matrix[i][j] >= self.threshold:
                    union(i, j)

        # Keep one representative per group
        groups = {}
        for i in range(len(texts)):
            root = find(i)
            if root not in groups:
                groups[root] = []
            groups[root].append(i)

        # Select unique texts (shortest in each group)
        uniques = []
        deleted = []
        for root, members in groups.items():
            representative = min(members, key=lambda i: len(texts[i]))
            uniques.append(texts[representative])
            for m in members:
                if m != representative:
                    deleted.append(texts[m])

        return {
            "uniques": uniques,
            "deleted": deleted,
            "n_original": len(texts),
            "n_deduplicated": len(uniques),
            "n_deleted": len(deleted)
        }

# Usage
dedup = Deduplicator(threshold=0.85)
result = dedup.deduplicate(texts)
print(f"Before: {result['n_original']} texts")
print(f"After: {result['n_deduplicated']} texts")
print(f"Deleted: {result['n_deleted']}")

Applicata a monte di un indice RAG, questa deduplicazione ha un effetto diretto sulla qualità: impedisce che i cinque risultati restituiti per una domanda siano cinque versioni dello stesso passaggio, il che priverebbe il generatore di qualsiasi informazione aggiuntiva.

Punti chiave

  • La distanza dal centroide o k-NN rileva i testi anomali
  • La similarità del coseno sopra una soglia identifica i duplicati
  • Union-Find raggruppa efficientemente i duplicati transitivi
  • Calibra le soglie sui tuoi dati (tipicamente 0,85–0,95 per i duplicati)