02 - Embeddings: Teoria e Pratica

# L'embedding della frase "Il gatto dorme sul divano"
# generato con text-embedding-3-small di OpenAI (1536 dimensioni)
embedding = [
    0.0231, -0.0456, 0.0891, -0.0123, 0.0567, -0.0234,
    0.0789, -0.0345, 0.0123, -0.0678, 0.0456, -0.0891,
    # ... altri 1524 valori ...
]
print(f"Tipo: {type(embedding)}")       # <class 'list'>
print(f"Dimensioni: {len(embedding)}")  # 1536
    

# Vocabolario: ["gatto", "cane", "pesce", "auto", "moto"]
# Dimensione vettore = dimensione vocabolario = 5

gatto = [1, 0, 0, 0, 0]
cane  = [0, 1, 0, 0, 0]
pesce = [0, 0, 1, 0, 0]
auto  = [0, 0, 0, 1, 0]
moto  = [0, 0, 0, 0, 1]

# Problema 1: la distanza tra "gatto" e "cane" e uguale
# alla distanza tra "gatto" e "auto"
import numpy as np
dist_gatto_cane = np.linalg.norm(
    np.array(gatto) - np.array(cane)
)  # sqrt(2) = 1.414
dist_gatto_auto = np.linalg.norm(
    np.array(gatto) - np.array(auto)
)  # sqrt(2) = 1.414 -- identica!

# Problema 2: con un vocabolario di 100.000 parole,
# ogni vettore ha 100.000 dimensioni (sparso, inefficiente)
    

from sklearn.feature_extraction.text import TfidfVectorizer

documenti = [
    "il gatto dorme sul divano",
    "il cane gioca nel giardino",
    "l'automobile corre sulla strada",
    "il felino riposa sulla poltrona",
]

vectorizer = TfidfVectorizer()
tfidf_matrix = vectorizer.fit_transform(documenti)

# Risultato: matrice sparsa (4 documenti x N termini)
print(f"Shape: {tfidf_matrix.shape}")  # (4, 14)
print(f"Termini: {vectorizer.get_feature_names_out()}")

# Problema: "gatto dorme" e "felino riposa" sono lontani
# perchè usano parole diverse, anche se il significato e simile
from sklearn.metrics.pairwise import cosine_similarity
sim = cosine_similarity(tfidf_matrix[0:1], tfidf_matrix[3:4])
print(f"Similarità gatto-felino: {sim[0][0]:.3f}")  # ~0.07 (bassa!)
    

from gensim.models import Word2Vec

# Corpus di esempio (in produzione: milioni di frasi)
frasi = [
    ["il", "gatto", "dorme", "sul", "divano"],
    ["il", "cane", "gioca", "nel", "giardino"],
    ["il", "felino", "riposa", "sulla", "poltrona"],
    ["il", "cane", "corre", "nel", "parco"],
]

# Addestramento Word2Vec (Skip-gram)
model = Word2Vec(
    sentences=frasi,
    vector_size=100,    # dimensionalità embedding
    window=5,           # contesto: 5 parole prima e dopo
    min_count=1,        # includi parole con almeno 1 occorrenza
    sg=1,               # 1 = Skip-gram, 0 = CBOW
    epochs=100
)

# Ora "gatto" e "felino" sono vicini!
print(model.wv.most_similar("gatto", topn=3))
# [('felino', 0.92), ('cane', 0.85), ('dorme', 0.71)]

# Accesso al vettore
vettore_gatto = model.wv["gatto"]
print(f"Dimensioni: {vettore_gatto.shape}")  # (100,)
print(f"Primi 5: {vettore_gatto[:5]}")
    

import gensim.downloader as api

# Carica embeddings GloVe pre-addestrati
model = api.load("glove-wiki-gigaword-100")

# king - man + woman = ?
result = model.most_similar(
    positive=["king", "woman"],
    negative=["man"],
    topn=3
)
print(result)
# [('queen', 0.7698), ('princess', 0.6450), ('monarch', 0.6345)]

# Altre analogie che funzionano:
# Parigi - Francia + Italia = Roma
result2 = model.most_similar(
    positive=["paris", "italy"],
    negative=["france"],
    topn=1
)
print(result2)  # [('rome', 0.8722)]

# buono - cattivo + triste = ?
result3 = model.most_similar(
    positive=["good", "sad"],
    negative=["bad"],
    topn=1
)
print(result3)  # [('happy', 0.6891)]
    

import numpy as np
from scipy.spatial.distance import cosine, euclidean, cityblock

# Due vettori di esempio (normalizzati)
a = np.array([0.5, 0.3, 0.8, 0.1, 0.6])
b = np.array([0.4, 0.35, 0.75, 0.15, 0.55])

# Normalizzazione L2
a_norm = a / np.linalg.norm(a)
b_norm = b / np.linalg.norm(b)

# 1. Cosine Similarity (1 - cosine distance)
cos_sim = 1 - cosine(a_norm, b_norm)
print(f"Cosine similarity:   {cos_sim:.6f}")   # ~0.999

# 2. Distanza Euclidea (L2)
l2_dist = euclidean(a_norm, b_norm)
print(f"Distanza L2:         {l2_dist:.6f}")   # ~0.042

# 3. Dot Product (per vettori normalizzati = cosine similarity)
dot = np.dot(a_norm, b_norm)
print(f"Dot product:         {dot:.6f}")       # ~0.999

# 4. Distanza Manhattan (L1)
l1_dist = cityblock(a_norm, b_norm)
print(f"Distanza L1:         {l1_dist:.6f}")   # ~0.072

# Relazione L2-Cosine per vettori normalizzati:
# d_L2^2 = 2 * (1 - cos_sim)
print(f"\nVerifica: L2^2 = {l2_dist**2:.6f}")
print(f"2*(1-cos) = {2*(1-cos_sim):.6f}")     # uguale!
    

# pip install sentence-transformers

from sentence_transformers import SentenceTransformer
import numpy as np

# Carica il modello (scaricato automaticamente al primo uso)
model = SentenceTransformer("all-MiniLM-L6-v2")

# Embedding di una singola frase
frase = "PostgreSQL e un database relazionale open-source"
embedding = model.encode(frase)
print(f"Tipo: {type(embedding)}")           # numpy.ndarray
print(f"Dimensioni: {embedding.shape}")      # (384,)

# Embedding di più frasi (batch - molto più efficiente)
frasi = [
    "PostgreSQL e un database relazionale open-source",
    "pgvector aggiunge il supporto per vettori a PostgreSQL",
    "Il machine learning richiede grandi quantità di dati",
    "La pizza margherita e un piatto tipico napoletano",
]

embeddings = model.encode(
    frasi,
    batch_size=32,          # processa 32 frasi alla volta
    show_progress_bar=True, # mostra progresso per batch grandi
    normalize_embeddings=True  # normalizza a norma L2 = 1
)
print(f"Shape: {embeddings.shape}")  # (4, 384)

# Calcola similarità tra tutte le coppie
from sentence_transformers.util import cos_sim
similarities = cos_sim(embeddings, embeddings)
print(f"\nMatrice di similarità:\n{similarities}")
# Le prime 2 frasi (su PostgreSQL) avranno alta similarità
# La frase sulla pizza sarà distante dalle altre
    

# pip install openai

from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def get_embeddings(
    texts: list[str],
    model: str = "text-embedding-3-small"
) -> list[list[float]]:
    """Genera embeddings per una lista di testi."""
    response = client.embeddings.create(
        input=texts,
        model=model,
    )
    return [item.embedding for item in response.data]

# Singolo embedding
testo = "PostgreSQL come vector database per AI"
embedding = get_embeddings([testo])[0]
print(f"Dimensioni: {len(embedding)}")  # 1536

# Batch di embeddings (fino a 2048 testi per chiamata)
testi = [
    "Come installare pgvector su Docker",
    "Tutorial per similarity search in PostgreSQL",
    "Guida alla cottura della pasta al forno",
]
embeddings = get_embeddings(testi)
print(f"Embeddings generati: {len(embeddings)}")  # 3

# Dimensione ridotta con text-embedding-3-small
# Puoi specificare dimensioni inferiori per risparmiare spazio
response = client.embeddings.create(
    input=["Testo di esempio"],
    model="text-embedding-3-small",
    dimensions=512  # ridotto da 1536 a 512
)
emb_ridotto = response.data[0].embedding
print(f"Dimensioni ridotte: {len(emb_ridotto)}")  # 512
    

# pip install huggingface_hub

from huggingface_hub import InferenceClient
import os

client = InferenceClient(
    token=os.getenv("HF_TOKEN")
)

def get_hf_embeddings(
    texts: list[str],
    model: str = "BAAI/bge-large-en-v1.5"
) -> list[list[float]]:
    """Genera embeddings usando HuggingFace Inference API."""
    result = client.feature_extraction(
        text=texts,
        model=model,
    )
    return result

# Genera embeddings
testi = [
    "Vector search con PostgreSQL e pgvector",
    "Come creare indici HNSW per ricerca veloce",
]
embeddings = get_hf_embeddings(testi)
print(f"Embeddings: {len(embeddings)}")        # 2
print(f"Dimensioni: {len(embeddings[0])}")     # 1024 (bge-large)
    

import time
from typing import Generator
from sentence_transformers import SentenceTransformer
import numpy as np

def chunk_list(
    lst: list, chunk_size: int
) -> Generator[list, None, None]:
    """Divide una lista in chunk di dimensione fissa."""
    for i in range(0, len(lst), chunk_size):
        yield lst[i:i + chunk_size]

def generate_embeddings_batch(
    texts: list[str],
    model_name: str = "all-MiniLM-L6-v2",
    batch_size: int = 256,
    device: str = "cpu"  # "cuda" per GPU
) -> np.ndarray:
    """Genera embeddings in batch con progress tracking."""
    model = SentenceTransformer(model_name, device=device)

    all_embeddings = []
    total_batches = (len(texts) + batch_size - 1) // batch_size
    start = time.time()

    for i, batch in enumerate(chunk_list(texts, batch_size)):
        batch_emb = model.encode(
            batch,
            batch_size=batch_size,
            normalize_embeddings=True,
            show_progress_bar=False
        )
        all_embeddings.append(batch_emb)

        elapsed = time.time() - start
        rate = (i + 1) * batch_size / elapsed
        print(
            f"Batch {i+1}/{total_batches} - "
            f"{rate:.0f} testi/sec"
        )

    return np.vstack(all_embeddings)

# Utilizzo
texts = [f"Documento numero {i}" for i in range(10_000)]
embeddings = generate_embeddings_batch(
    texts,
    batch_size=256,
    device="cuda"  # usa GPU se disponibile
)
print(f"Shape finale: {embeddings.shape}")  # (10000, 384)
    

-- Abilita pgvector
CREATE EXTENSION IF NOT EXISTS vector;

-- Tabella documenti con embedding
CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    title VARCHAR(500) NOT NULL,
    content TEXT NOT NULL,
    source VARCHAR(255),
    category VARCHAR(100),
    embedding vector(384),  -- dimensione del modello scelto
    created_at TIMESTAMPTZ DEFAULT NOW(),
    metadata JSONB DEFAULT '{}'::jsonb
);

-- Indice HNSW per ricerca veloce (cosine distance)
CREATE INDEX idx_documents_embedding
    ON documents
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 200);

-- Indice su categoria per filtri combinati
CREATE INDEX idx_documents_category
    ON documents (category);
    

import psycopg2
from psycopg2.extras import execute_values
from sentence_transformers import SentenceTransformer
import numpy as np

# Configurazione
DB_CONFIG = {
    "host": "localhost",
    "port": 5432,
    "dbname": "vectordb",
    "user": "admin",
    "password": "secret_password",
}

# 1. Genera embeddings
model = SentenceTransformer("all-MiniLM-L6-v2")

documenti = [
    {
        "title": "Introduzione a pgvector",
        "content": "pgvector e un'estensione PostgreSQL per vettori...",
        "source": "blog",
        "category": "database"
    },
    {
        "title": "RAG con LangChain",
        "content": "Retrieval Augmented Generation combina retrieval...",
        "source": "tutorial",
        "category": "ai"
    },
    {
        "title": "Python per Data Science",
        "content": "Python e il linguaggio più usato per data science...",
        "source": "guide",
        "category": "programming"
    },
]

# Genera embeddings per i contenuti
testi = [d["content"] for d in documenti]
embeddings = model.encode(testi, normalize_embeddings=True)

# 2. Salva in PostgreSQL
conn = psycopg2.connect(**DB_CONFIG)
cur = conn.cursor()

# Prepara i dati per batch insert
values = []
for doc, emb in zip(documenti, embeddings):
    values.append((
        doc["title"],
        doc["content"],
        doc["source"],
        doc["category"],
        emb.tolist()  # converti numpy array in lista Python
    ))

# Inserimento batch efficiente
execute_values(
    cur,
    """INSERT INTO documents
       (title, content, source, category, embedding)
       VALUES %s""",
    values,
    template="(%s, %s, %s, %s, %s::vector)"
)

conn.commit()
print(f"Inseriti {len(values)} documenti con embeddings")

cur.close()
conn.close()
    

def similarity_search(
    query: str,
    top_k: int = 5,
    category: str = None,
    threshold: float = 0.3
) -> list[dict]:
    """Cerca documenti simili alla query."""
    # Genera embedding della query
    query_embedding = model.encode(
        query, normalize_embeddings=True
    ).tolist()

    conn = psycopg2.connect(**DB_CONFIG)
    cur = conn.cursor()

    # Query con filtro opzionale
    if category:
        cur.execute("""
            SELECT id, title, content, category,
                   1 - (embedding <=> %s::vector) AS similarity
            FROM documents
            WHERE category = %s
              AND 1 - (embedding <=> %s::vector) > %s
            ORDER BY embedding <=> %s::vector
            LIMIT %s
        """, (
            query_embedding, category,
            query_embedding, threshold,
            query_embedding, top_k
        ))
    else:
        cur.execute("""
            SELECT id, title, content, category,
                   1 - (embedding <=> %s::vector) AS similarity
            FROM documents
            WHERE 1 - (embedding <=> %s::vector) > %s
            ORDER BY embedding <=> %s::vector
            LIMIT %s
        """, (
            query_embedding,
            query_embedding, threshold,
            query_embedding, top_k
        ))

    results = []
    for row in cur.fetchall():
        results.append({
            "id": row[0],
            "title": row[1],
            "content": row[2][:200],  # troncato
            "category": row[3],
            "similarity": round(row[4], 4),
        })

    cur.close()
    conn.close()
    return results

# Esempio d'uso
risultati = similarity_search(
    "come usare i vettori in un database",
    top_k=3,
    category="database"
)
for r in risultati:
    print(f"[{r['similarity']}] {r['title']}")
    

-- HNSW (raccomandato per produzione)
-- m: connessioni per nodo (16-64, default 16)
-- ef_construction: qualità costruzione (64-512, default 64)
CREATE INDEX idx_hnsw_cosine
    ON documents
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 200);

-- Per L2 distance
CREATE INDEX idx_hnsw_l2
    ON documents
    USING hnsw (embedding vector_l2_ops)
    WITH (m = 16, ef_construction = 200);

-- IVFFlat (più veloce da costruire)
-- lists: numero di cluster (sqrt(N) come regola base)
CREATE INDEX idx_ivfflat_cosine
    ON documents
    USING ivfflat (embedding vector_cosine_ops)
    WITH (lists = 100);  -- per ~10K documenti

-- Parametri di query per controllare recall vs velocità
SET hnsw.ef_search = 100;       -- default 40, alza per più recall
SET ivfflat.probes = 10;        -- default 1, alza per più recall
    

# pip install transformers pillow

from transformers import CLIPProcessor, CLIPModel
from PIL import Image
import torch
import numpy as np

# Carica CLIP
model = CLIPModel.from_pretrained("openai/clip-vit-base-patch32")
processor = CLIPProcessor.from_pretrained("openai/clip-vit-base-patch32")

# Embedding di un'immagine
image = Image.open("foto_gatto.jpg")
inputs = processor(images=image, return_tensors="pt")
with torch.no_grad():
    image_embedding = model.get_image_features(**inputs)
image_emb = image_embedding[0].numpy()
print(f"Image embedding: {image_emb.shape}")  # (512,)

# Embedding di testo (nello STESSO spazio!)
text_inputs = processor(
    text=["un gatto che dorme", "un cane che gioca"],
    return_tensors="pt",
    padding=True
)
with torch.no_grad():
    text_embeddings = model.get_text_features(**text_inputs)
text_embs = text_embeddings.numpy()

# Calcola similarità cross-modale
from numpy.linalg import norm
for i, text in enumerate(["un gatto che dorme", "un cane che gioca"]):
    sim = np.dot(image_emb, text_embs[i]) / (
        norm(image_emb) * norm(text_embs[i])
    )
    print(f"Similarità '{text}': {sim:.4f}")
# "un gatto che dorme" avra similarità più alta con foto_gatto.jpg
    

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import (
    InformationRetrievalEvaluator
)

# Prepara dataset di valutazione
queries = {
    "q1": "come installare pgvector",
    "q2": "cos'è la similarity search",
    "q3": "embedding di immagini con CLIP",
}

corpus = {
    "d1": "Guida installazione pgvector su Ubuntu",
    "d2": "pgvector per PostgreSQL: setup Docker",
    "d3": "Ricerca per similarità vettoriale",
    "d4": "CLIP: modello multimodale per immagini e testo",
    "d5": "Ricetta pasta alla carbonara",
}

# Mappatura query -> documenti rilevanti
relevant = {
    "q1": {"d1": 1, "d2": 1},  # d1 e d2 rilevanti per q1
    "q2": {"d3": 1},
    "q3": {"d4": 1},
}

# Valuta il modello
model = SentenceTransformer("all-MiniLM-L6-v2")
evaluator = InformationRetrievalEvaluator(
    queries=queries,
    corpus=corpus,
    relevant_docs=relevant,
    name="custom-eval"
)
results = evaluator(model)
print(f"NDCG@10: {results['custom-eval_ndcg@10']:.4f}")
print(f"MAP@10:  {results['custom-eval_map@10']:.4f}")
    

# pip install umap-learn matplotlib

import umap
import matplotlib.pyplot as plt
import numpy as np
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")

# Testi con categorie diverse
testi = [
    # Database
    "PostgreSQL e un database relazionale",
    "MongoDB e un database NoSQL",
    "Redis e un database in-memory",
    # AI/ML
    "Il deep learning usa reti neurali profonde",
    "GPT e un modello di linguaggio",
    "La regressione lineare e un algoritmo semplice",
    # Cucina
    "La pizza si cuoce nel forno a legna",
    "Il tiramisu e un dolce italiano",
    "La pasta alla carbonara usa uova e guanciale",
]
categorie = ["DB"]*3 + ["AI"]*3 + ["Cucina"]*3
colori = ["blue"]*3 + ["red"]*3 + ["green"]*3

# Genera embeddings (384 dimensioni)
embeddings = model.encode(testi, normalize_embeddings=True)

# Riduci a 2D con UMAP
reducer = umap.UMAP(n_components=2, random_state=42)
emb_2d = reducer.fit_transform(embeddings)

# Visualizza
plt.figure(figsize=(10, 8))
for i, (x, y) in enumerate(emb_2d):
    plt.scatter(x, y, c=colori[i], s=100, zorder=5)
    plt.annotate(testi[i][:30], (x, y),
                 fontsize=8, ha='left')
plt.title("Embeddings in 2D (UMAP)")
plt.savefig("embeddings_umap.png", dpi=150)
plt.show()
    

from openai import OpenAI
import numpy as np
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

testo = "PostgreSQL come vector database per applicazioni AI"

# Genera lo stesso embedding a dimensioni diverse
for dim in [256, 512, 1024, 1536]:
    response = client.embeddings.create(
        input=[testo],
        model="text-embedding-3-small",
        dimensions=dim
    )
    emb = response.data[0].embedding
    print(f"Dimensioni: {dim}, norma: {np.linalg.norm(emb):.4f}")

# In PostgreSQL: usa colonne con dimensione appropriata
# CREATE TABLE docs_compact (
#     id BIGSERIAL PRIMARY KEY,
#     content TEXT,
#     embedding vector(256)  -- più compatto, 6x meno storage
# );
    

import hashlib
import json
import psycopg2
from typing import Optional
import numpy as np

class EmbeddingCache:
    """Cache embeddings in PostgreSQL per evitare ricalcoli."""

    def __init__(self, db_config: dict):
        self.db_config = db_config
        self._init_table()

    def _init_table(self):
        conn = psycopg2.connect(**self.db_config)
        cur = conn.cursor()
        cur.execute("""
            CREATE TABLE IF NOT EXISTS embedding_cache (
                content_hash VARCHAR(64) PRIMARY KEY,
                model_name VARCHAR(100) NOT NULL,
                embedding vector(1536),
                created_at TIMESTAMPTZ DEFAULT NOW()
            )
        """)
        conn.commit()
        cur.close()
        conn.close()

    def _hash(self, text: str, model: str) -> str:
        """Hash deterministico del contenuto + modello."""
        key = f"{model}::{text}"
        return hashlib.sha256(key.encode()).hexdigest()

    def get(
        self, text: str, model: str
    ) -> Optional[list[float]]:
        """Cerca embedding in cache."""
        h = self._hash(text, model)
        conn = psycopg2.connect(**self.db_config)
        cur = conn.cursor()
        cur.execute(
            "SELECT embedding FROM embedding_cache "
            "WHERE content_hash = %s",
            (h,)
        )
        row = cur.fetchone()
        cur.close()
        conn.close()
        return row[0] if row else None

    def put(
        self, text: str, model: str, embedding: list[float]
    ):
        """Salva embedding in cache."""
        h = self._hash(text, model)
        conn = psycopg2.connect(**self.db_config)
        cur = conn.cursor()
        cur.execute(
            "INSERT INTO embedding_cache "
            "(content_hash, model_name, embedding) "
            "VALUES (%s, %s, %s::vector) "
            "ON CONFLICT (content_hash) DO NOTHING",
            (h, model, embedding)
        )
        conn.commit()
        cur.close()
        conn.close()