Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Produzione: Scalabilità e Caching

Lezione 22 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Sfide della Produzione
  3. Caching degli Embedding
  4. Gestione dei Limiti di Frequenza (Rate Limits)
  5. Elaborazione Asincrona
  6. Ottimizzazione dello Storage
  7. Architettura di Produzione
  8. Checklist di Produzione
  9. Punti chiave
  10. Metti alla prova le tue conoscenze

Obiettivi

  • Ottimizzare le prestazioni di un sistema di embedding in produzione
  • Implementare il caching per ridurre costi e latenza
  • Gestire la scalabilità e l’alta disponibilità

Sfide della Produzione

Durante lo sviluppo, chiamare le API di OpenAI per ogni richiesta non è un problema: potresti fare dieci chiamate al giorno. In produzione, quello stesso codice si scontra contemporaneamente con tre muri. Primo, il costo: ogni chiamata viene addebitata e una re-indicizzazione completa di un corpus viene pagata interamente ogni volta che viene eseguita. Secondo, la latenza: un round trip di rete da 100 a 300 ms per richiesta si somma al tempo di ricerca e di generazione, e l’utente percepisce la somma di tutti e tre. Infine, i limiti di frequenza (rate limits): OpenAI limita il numero di chiamate al minuto, un limite che non vedrai mai in sviluppo ma che colpirai il giorno del lancio.

Tutti e tre i problemi hanno sostanzialmente la stessa soluzione: non chiamare le API quando non è necessario.

Caching degli Embedding

Un embedding è deterministico: lo stesso testo con lo stesso modello restituisce sempre lo stesso vettore. Questo rende il caching estremamente efficace qui, molto più che per un LLM generativo. Per un’applicazione con traffico moderato, il decoratore lru_cache della libreria standard è sufficiente e richiede solo due righe. Il valore di ritorno viene convertito in una tupla perché lru_cache richiede valori hashable; questa è l’unica complicazione da conoscere.

from functools import lru_cache
from openai import OpenAI
import hashlib
import json

client = OpenAI()

@lru_cache(maxsize=10_000)
def embedding_cache(text: str, model: str = "text-embedding-3-large") -> tuple:
    """LRU cache for embeddings (tuple because it's hashable)."""
    response = client.embeddings.create(input=text, model=model)
    return tuple(response.data[0].embedding)

# Usage - the 2nd call is instant
emb1 = embedding_cache("Hello world")  # API call
emb2 = embedding_cache("Hello world")  # From cache

Questa cache scompare a qualsiasi riavvio e non è condivisa tra i processi: non appena esegui due istanze dietro un load balancer, ognuna ricostruisce la propria. Redis risolve entrambi i problemi. La chiave è un hash della coppia modello-testo, il che impedisce che un cambiamento del modello serva vecchi vettori, e un TTL di trenta giorni limita la crescita dello storage.

Il metodo get_embeddings_batch merita molta attenzione, poiché è ciò che fa la differenza durante l’ingestione. Non controlla semplicemente la cache testo per testo: separa i mancati riscontri (misses), li invia in un’unica chiamata API, quindi reinserisce ogni risultato nella sua posizione originale utilizzando indices_a_calculer. Su un batch di mille documenti dove novecento sono già noti, passi da una chiamata per documento a una singola chiamata per le rimanenti cento.

import redis
import numpy as np
import json

class EmbeddingCacheRedis:
    def __init__(self, redis_url: str = "redis://localhost:6379"):
        self.redis = redis.from_url(redis_url)
        self.client = OpenAI()
        self.ttl = 86400 * 30  # 30 days

    def _cache_key(self, text: str, model: str) -> str:
        h = hashlib.md5(f"{model}:{text}".encode()).hexdigest()
        return f"emb:{h}"

    def get_embedding(
        self, text: str, model: str = "text-embedding-3-large"
    ) -> list[float]:
        key = self._cache_key(text, model)

        # Check cache
        cached = self.redis.get(key)
        if cached:
            return json.loads(cached)

        # Generate and cache
        response = self.client.embeddings.create(
            input=text, model=model
        )
        embedding = response.data[0].embedding

        self.redis.setex(key, self.ttl, json.dumps(embedding))
        return embedding

    def get_embeddings_batch(
        self, texts: list[str], model: str = "text-embedding-3-large"
    ) -> list[list[float]]:
        """Batch with partial caching."""
        results = [None] * len(texts)
        to_calculate = []
        indices_to_calculate = []

        # Check cache for each text
        for i, text in enumerate(texts):
            key = self._cache_key(text, model)
            cached = self.redis.get(key)
            if cached:
                results[i] = json.loads(cached)
            else:
                to_calculate.append(text)
                indices_to_calculate.append(i)

        # Calculate misses in a single call
        if to_calculate:
            response = self.client.embeddings.create(
                input=to_calculate, model=model
            )
            for resp_item in sorted(response.data, key=lambda x: x.index):
                idx = indices_to_calculate[resp_item.index]
                text = to_calculate[resp_item.index]
                embedding = resp_item.embedding

                results[idx] = embedding
                key = self._cache_key(text, model)
                self.redis.setex(key, self.ttl, json.dumps(embedding))

        print(f"Cache: {len(texts) - len(to_calculate)}/{len(texts)} hits")
        return results

# Usage
cache = EmbeddingCacheRedis()
emb = cache.get_embedding("cache test")

Gestione dei Limiti di Frequenza (Rate Limits)

Il caching riduce il traffico ma non lo elimina, e un picco di traffico alla fine attiverà un RateLimitError. La risposta corretta non è ritentare immediatamente, il che peggiorerebbe la congestione, ma aspettare, raddoppiando il ritardo ogni volta: un secondo, due, quattro, otto, sedici. Cinque tentativi coprono così circa trenta secondi, assorbendo la stragrande maggioranza dei picchi temporanei, e il tentativo finale rilancia l’eccezione in modo che l’incidente venga segnalato invece di essere inghiottito silenziosamente.

import time
from openai import RateLimitError

class RobustEmbeddingClient:
    def __init__(self, max_retries: int = 5):
        self.client = OpenAI()
        self.max_retries = max_retries

    def create(
        self, input: str | list[str], model: str = "text-embedding-3-large",
        **kwargs
    ):
        """Call with exponential retry."""
        for attempt in range(self.max_retries):
            try:
                return self.client.embeddings.create(
                    input=input, model=model, **kwargs
                )
            except RateLimitError as e:
                if attempt == self.max_retries - 1:
                    raise
                wait = 2 ** attempt
                print(f"Rate limit hit, pausing for {wait}s...")
                time.sleep(wait)

Elaborazione Asincrona

Per le pipeline di ingestione, il collo di bottiglia non è il calcolo ma l’attesa di rete: il tuo programma passa la maggior parte del tempo a non fare nulla. L’elaborazione asincrona ti permette di mantenere multiple richieste in volo. Il semaforo limita intenzionalmente questo parallelismo, perché lanciare cento chiamate simultanee attiva solo i limiti di frequenza che hai appena imparato a gestire; da tre a cinque richieste concorrenti è un’impostazione sana. I testi vengono prima divisi in batch di cento e l’indice di inizio di ogni batch viaggia con il task in modo che as_completed, che restituisce i risultati fuori ordine, possa comunque posizionarli correttamente.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def generate_embeddings_async(
    texts: list[str],
    model: str = "text-embedding-3-large",
    max_concurrent: int = 5
) -> list[list[float]]:
    """Generate embeddings in parallel with a semaphore."""
    semaphore = asyncio.Semaphore(max_concurrent)
    results = [None] * len(texts)

    async def process_batch(batch_idx, batch):
        async with semaphore:
            response = await async_client.embeddings.create(
                input=batch, model=model
            )
            return batch_idx, [
                d.embedding
                for d in sorted(response.data, key=lambda x: x.index)
            ]

    # Split into batches of 100
    tasks = []
    batch_size = 100
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        tasks.append(process_batch(i, batch))

    for coro in asyncio.as_completed(tasks):
        batch_idx, embeddings = await coro
        for j, emb in enumerate(embeddings):
            results[batch_idx + j] = emb

    return results

# Usage
embeddings = asyncio.run(
    generate_embeddings_async(my_texts, max_concurrent=3)
)

Ottimizzazione dello Storage

Poi c’è il conto dell’infrastruttura. Diecimila vettori di 3.072 dimensioni in float32 occupano circa 122 MB; un milione occupa dodici gigabyte, che devono essere mantenuti in memoria affinché la ricerca rimanga veloce. La quantizzazione a int8 mappa ogni coordinata su 256 valori interi, dividendo l’ingombro per quattro fino a circa 30 MB nell’esempio sottostante. La perdita di precisione esiste ma rimane marginale rispetto ai gap di similarità con cui stai lavorando.

import numpy as np

def quantize_int8(embeddings: np.ndarray) -> tuple:
    """Quantize embeddings to int8 (4x less memory)."""
    min_val = embeddings.min(axis=1, keepdims=True)
    max_val = embeddings.max(axis=1, keepdims=True)
    scale = (max_val - min_val) / 255.0

    quantized = ((embeddings - min_val) / scale).astype(np.int8)
    return quantized, min_val, scale

def dequantize_int8(quantized, min_val, scale):
    """Restore embeddings from int8."""
    return quantized.astype(np.float32) * scale + min_val

# Size comparison
embeddings = np.random.randn(10000, 3072).astype(np.float32)
print(f"float32 : {embeddings.nbytes / 1e6:.1f} MB")  # ~122 MB

quantized, min_val, scale = quantize_int8(embeddings)
print(f"int8 :    {quantized.nbytes / 1e6:.1f} MB")    # ~30 MB

Tuttavia, la leva più semplice rimane il parametro dimensions delle API, che produce vettori più corti direttamente senza alcun post-processing da parte tua: 3.072 dimensioni pesano circa 24 KB per vettore, 1.024 dimensioni scendono a 8 KB e 256 dimensioni a 2 KB.

# 3072 dim -> ~24 KB per vector
# 1024 dim -> ~8 KB per vector  (API reduction)
# 256 dim  -> ~2 KB per vector  (API reduction)

response = client.embeddings.create(
    input="text",
    model="text-embedding-3-large",
    dimensions=1024  # 3x less storage
)

Architettura di Produzione

Assemblati, questi pezzi danno una pipeline snella: cache Redis davanti, client robusto per le chiamate che comunque passano. L’ingestione prende la strada del batch, la ricerca mette in cache anche l’embedding della query, e quest’ultimo punto non è banale, perché le query degli utenti si ripetono molto più di quanto immagini.

class ProductionPipeline:
    """RAG pipeline optimized for production."""

    def __init__(self):
        self.cache = EmbeddingCacheRedis()
        self.robust_client = RobustEmbeddingClient()

    def ingest(self, documents: list[dict]):
        """Ingestion with cache and retry."""
        texts = [d["text"] for d in documents]
        embeddings = self.cache.get_embeddings_batch(texts)
        # Store in vector database...

    def search(self, query: str, k: int = 5):
        """Search with query caching."""
        query_emb = self.cache.get_embedding(query)
        # Search in vector database...
        return query_emb

Checklist di Produzione

ElementoDescrizione
Cache RedisRiduce le chiamate API e la latenza
Retry EsponenzialeGestisce i limiti di frequenza con grazia
MonitoraggioTraccia il tasso di successo della cache, la latenza, gli errori
Elaborazione BatchElabora grandi volumi in batch asincroni
QuantizzazioneRiduce lo storage di 4 volte con int8
Riduzione delle DimensioniUsa 1024 o 512 dimensioni se la qualità lo permette
BackupEsegui regolarmente il backup di embedding e metadati
AlertingAvvisa su errori API e degrado delle prestazioni

Due righe in questa tabella non producono guadagni di prestazioni ma sono le più importanti. Monitorare il tasso di successo della cache è il tuo indicatore di salute economica: se crolla, la tua fattura triplica prima che qualcuno se ne accorga. E fare il backup degli embedding ti salva, il giorno di un incidente, dal dover ripagare e riaspettare la codifica completa del corpus.

Punti chiave

  • La cache Redis riduce costi e latenza di oltre il 90%
  • Il retry esponenziale gestisce i limiti di frequenza di OpenAI
  • L’elaborazione asincrona accelera l’ingestione di grandi corpus
  • La quantizzazione int8 riduce lo storage di 4 volte
  • La riduzione delle dimensioni alle API è la leva più semplice

Metti alla prova le tue conoscenze

Ventidue lezioni su embedding e RAG: l’essenziale sta in cinque domande.

1. Cosa cattura un embedding e come confrontiamo due testi?

Risposta: Un vettore che codifica il significato: due testi vicini nel significato hanno vettori vicini; la similarità del coseno misura questa vicinanza, indipendentemente dalle parole esatte usate.

2. Perché combinare ricerca semantica e lessicale?

Risposta: Il semantico comprende le riformulazioni ma manca i termini esatti (riferimenti, identificatori); il lessicale fa l’opposto; l’ibrido copre entrambi i punti ciechi e fonde per rango.

3. Qual è il ruolo del chunking nella qualità del RAG?

Risposta: Decisivo: segmenti che rispettano i confini delle idee producono una ricerca precisa; tagli arbitrari generano frammenti incompleti e l’intera pipeline ne eredita le conseguenze.

4. File Search integrato o RAG personalizzato: come scegliere?

Risposta: File Search per andare veloci con una pipeline gestita (chunking e ranking integrati); RAG personalizzato quando devi controllare la suddivisione, gli indici, il reranking o le fonti multiple.

5. Oltre la ricerca, nomina due usi per gli embedding.

Risposta: Classificazione e clustering (raggruppare automaticamente testi simili), raccomandazioni personalizzate, o rilevamento di anomalie e duplicati; stesso vettore, distanze diverse.

Il filo conduttore del corso: il significato diventa misurabile; ricerca, ranking e raccomandazione sono solo applicazioni. La produzione (scalabilità, caching) fa il resto.