Produção: Escalabilidade e Cache
Nesta página
Objetivos
- Otimizar o desempenho de um sistema de embeddings em produção
- Implementar cache para reduzir custos e latência
- Gerir a escalabilidade e a alta disponibilidade
Desafios de Produção
Durante o desenvolvimento, chamar a API da OpenAI para cada pedido não é um problema: poderá fazer dez chamadas por dia. Em produção, esse mesmo código esbarra simultaneamente em três barreiras. Primeiro, o custo: cada chamada é faturada, e uma reindexação completa de um corpus é paga integralmente sempre que é executada. Segundo, a latência: uma ida e volta pela rede de 100 a 300 ms por pedido soma-se ao tempo de pesquisa e de geração, e o utilizador sente a soma dos três. Por fim, os limites de taxa: a OpenAI limita o número de chamadas por minuto — um limite que nunca verá no desenvolvimento, mas que atingirá no dia do lançamento.
Os três problemas têm, em grande parte, a mesma solução: não chamar a API quando não for necessário.
Cache de Embeddings
Um embedding é determinístico: o mesmo texto com o mesmo modelo devolve sempre o mesmo vetor. Isso torna o cache altamente eficaz aqui, muito mais do que para um LLM generativo. Para uma aplicação com tráfego moderado, o decorador lru_cache da biblioteca padrão é suficiente e requer apenas duas linhas. O valor de retorno é convertido numa tupla porque o lru_cache exige valores hashable; essa é a única particularidade a conhecer.
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:
"""Cache LRU para embeddings (tupla porque é hashable)."""
response = client.embeddings.create(input=text, model=model)
return tuple(response.data[0].embedding)
# Utilização - a 2.ª chamada é instantânea
emb1 = embedding_cache("Hello world") # Chamada à API
emb2 = embedding_cache("Hello world") # Do cache
Este cache desaparece em qualquer reinício e não é partilhado entre processos: assim que executar duas instâncias atrás de um balanceador de carga, cada uma reconstrói o seu próprio. O Redis resolve ambos os problemas. A chave é um hash do par modelo-texto, o que impede que uma alteração de modelo sirva vetores antigos, e um TTL de trinta dias limita o crescimento do armazenamento.
O método get_embeddings_batch merece atenção redobrada, pois é ele que faz a diferença durante a ingestão. Não verifica o cache texto a texto: separa as falhas (misses), envia-as numa única chamada à API e, em seguida, reinsere cada resultado na sua posição original usando indices_a_calculer. Num lote de mil documentos onde novecentos já são conhecidos, passa de uma chamada por documento para uma única chamada para os cem restantes.
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 dias
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)
# Verificar cache
cached = self.redis.get(key)
if cached:
return json.loads(cached)
# Gerar e colocar em 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]]:
"""Lote com cache parcial."""
results = [None] * len(texts)
to_calculate = []
indices_to_calculate = []
# Verificar cache para cada texto
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)
# Calcular as falhas numa única chamada
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
# Utilização
cache = EmbeddingCacheRedis()
emb = cache.get_embedding("cache test")
Gestão de Limites de Taxa
O cache reduz o tráfego, mas não o elimina, e um pico de tráfego acabará por desencadear um RateLimitError. A resposta correta não é tentar imediatamente — o que agravaria a congestão —, mas esperar, duplicando o atraso de cada vez: um segundo, dois, quatro, oito, dezasseis. Cinco tentativas cobrem assim cerca de trinta segundos, o que absorve a vasta maioria dos picos temporários, e a tentativa final volta a lançar a exceção para que o incidente seja reportado em vez de ser silenciosamente ignorado.
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
):
"""Chamada com repetição exponencial."""
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"Limite de taxa atingido, pausa de {wait}s...")
time.sleep(wait)
Processamento Assíncrono
Para pipelines de ingestão, o gargalo não é o cálculo, mas a espera pela rede: o seu programa passa a maior parte do tempo sem fazer nada. O processamento assíncrono permite manter vários pedidos em curso. O semáforo limita intencionalmente este paralelismo, porque lançar cem chamadas simultâneas apenas ativa os limites de taxa que acabou de aprender a gerir — três a cinco pedidos concorrentes é uma configuração saudável. Os textos são primeiro divididos em lotes de cem, e o índice inicial de cada lote viaja com a tarefa para que o as_completed, que devolve resultados fora de ordem, os possa ainda colocar corretamente.
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]]:
"""Gerar embeddings em paralelo com um semáforo."""
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)
]
# Dividir em lotes de 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
# Utilização
embeddings = asyncio.run(
generate_embeddings_async(my_texts, max_concurrent=3)
)
Otimização do Armazenamento
Depois, há a fatura da infraestrutura. Dez mil vetores de 3.072 dimensões em float32 ocupam cerca de 122 MB; um milhão ocupa doze gigabytes, que devem ser mantidos na memória para que a pesquisa permaneça rápida. A quantização para int8 mapeia cada coordenada para 256 valores inteiros, dividindo a pegada por quatro para cerca de 30 MB no exemplo abaixo. A perda de precisão existe, mas permanece marginal comparada com as lacunas de similaridade com as quais está a trabalhar.
import numpy as np
def quantize_int8(embeddings: np.ndarray) -> tuple:
"""Quantizar embeddings para int8 (4x menos memória)."""
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):
"""Restaurar embeddings a partir de int8."""
return quantized.astype(np.float32) * scale + min_val
# Comparação de tamanho
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
No entanto, a alavanca mais simples continua a ser o parâmetro dimensions da API, que produz vetores mais curtos diretamente, sem qualquer pós-processamento da sua parte: 3.072 dimensões pesam cerca de 24 KB por vetor, 1.024 dimensões descem para 8 KB e 256 dimensões para 2 KB.
# 3072 dim -> ~24 KB por vetor
# 1024 dim -> ~8 KB por vetor (redução na API)
# 256 dim -> ~2 KB por vetor (redução na API)
response = client.embeddings.create(
input="text",
model="text-embedding-3-large",
dimensions=1024 # 3x menos armazenamento
)
Arquitetura de Produção
Montadas, estas peças dão um pipeline enxuto: cache Redis à frente, cliente robusto para as chamadas que conseguem passar mesmo assim. A ingestão segue a via dos lotes, a pesquisa coloca em cache até o embedding da consulta — e este último ponto não é trivial, porque as consultas dos utilizadores repetem-se muito mais do que imagina.
class ProductionPipeline:
"""Pipeline RAG otimizado para produção."""
def __init__(self):
self.cache = EmbeddingCacheRedis()
self.robust_client = RobustEmbeddingClient()
def ingest(self, documents: list[dict]):
"""Ingestão com cache e repetição."""
texts = [d["text"] for d in documents]
embeddings = self.cache.get_embeddings_batch(texts)
# Armazenar na base de dados vetorial...
def search(self, query: str, k: int = 5):
"""Pesquisa com cache de consultas."""
query_emb = self.cache.get_embedding(query)
# Pesquisar na base de dados vetorial...
return query_emb
Lista de Verificação de Produção
| Elemento | Descrição |
|---|---|
| Cache Redis | Reduzir chamadas à API e latência |
| Repetição Exponencial | Gerir limites de taxa graciosamente |
| Monitorização | Acompanhar taxa de acertos no cache, latência, erros |
| Processamento em Lotes | Processar grandes volumes em lotes assíncronos |
| Quantização | Reduzir armazenamento em 4x com int8 |
| Redução de Dimensões | Usar 1024 ou 512 dimensões se a qualidade o permitir |
| Cópia de Segurança | Fazer backup regular de embeddings e metadados |
| Alertas | Alertar sobre erros na API e degradação de desempenho |
Duas linhas nesta tabela não produzem ganho de desempenho, mas são as mais importantes. Monitorizar a taxa de acertos no cache é o seu indicador de saúde económica: se colapsar, a sua fatura triplica antes que alguém perceba. E fazer backup dos embeddings poupa-o, no dia de um incidente, de ter de pagar novamente e de esperar pela codificação completa do corpus.
Pontos-chave
- O cache Redis reduz custos e latência em mais de 90%
- A repetição exponencial gere os limites de taxa da OpenAI
- O processamento assíncrono acelera a ingestão de grandes corpora
- A quantização int8 reduz o armazenamento em 4x
- A redução de dimensões na API é a alavanca mais simples
Teste os Seus Conhecimentos
Vinte e duas lições sobre embeddings e RAG: o essencial cabe em cinco perguntas.
1. O que captura um embedding e como comparamos dois textos?
Resposta: Um vetor que codifica significado: dois textos próximos em significado têm vetores próximos — a similaridade do cosseno mede esta proximidade, independentemente das palavras exatas utilizadas.
2. Por que combinar pesquisa semântica e lexical?
Resposta: A semântica compreende reformulações, mas falha nos termos exatos (referências, identificadores); a lexical faz o oposto — a híbrida cobre ambos os pontos cegos e funde por classificação.
3. Qual é o papel do chunking na qualidade do RAG?
Resposta: Decisivo: segmentos que respeitam as fronteiras das ideias produzem uma pesquisa precisa; cortes arbitrários geram fragmentos incompletos — e todo o pipeline herda isso.
4. Pesquisa de Ficheiros Integrada ou RAG personalizado: como escolher?
Resposta: Pesquisa de Ficheiros para avançar rapidamente com um pipeline gerido (chunking e classificação integrados); RAG personalizado quando precisa de controlar a divisão, os índices, a reclassificação ou múltiplas fontes.
5. Para além da pesquisa, nomeie duas utilizações para embeddings.
Resposta: Classificação e agrupamento (agrupar automaticamente textos semelhantes), recomendações personalizadas ou deteção de anomalias e duplicados — mesmo vetor, diferentes distâncias.
O fio condutor do curso: o significado torna-se mensurável — pesquisa, classificação, recomendação são apenas aplicações. A produção (escalabilidade, cache) faz o resto.