Produzione: Scalabilità e Caching
In questa pagina
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
| Elemento | Descrizione |
|---|---|
| Cache Redis | Riduce le chiamate API e la latenza |
| Retry Esponenziale | Gestisce i limiti di frequenza con grazia |
| Monitoraggio | Traccia il tasso di successo della cache, la latenza, gli errori |
| Elaborazione Batch | Elabora grandi volumi in batch asincroni |
| Quantizzazione | Riduce lo storage di 4 volte con int8 |
| Riduzione delle Dimensioni | Usa 1024 o 512 dimensioni se la qualità lo permette |
| Backup | Esegui regolarmente il backup di embedding e metadati |
| Alerting | Avvisa 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.