Redis Gerenciado pelo Azure: pesquisa vetorial, HNSW, FLAT, Hash e JSON

radio_button_uncheckedshort_text1. O problema da recuperação semântica e os objetivos

Um assistente corporativo pode guardar milhões de documentos técnicos enquanto os usuários esperam uma resposta relevante em milissegundos. Palavras-chave isoladas não capturam bem a intenção; por isso, o aplicativo transforma documentos e perguntas em embeddings de alta dimensão. Conceitos relacionados ficam próximos no espaço vetorial, tornando a distância útil para pesquisa semântica, recomendações e RAG.

Uma solução de produção também precisa manter dimensão e tipo numérico, armazenar metadados pesquisáveis, escolher indexação exata ou aproximada, atualizar registros, aplicar filtros de departamento ou autorização e medir latência, recall, memória e custo. O exemplo usa 1.536 dimensões sem pressupor que todo modelo tenha esse tamanho.

• Criar esquemas vetoriais do RediSearch e ingerir embeddings com redis-py.
• Executar consultas KNN, por intervalo e híbridas com filtros de metadados.
• Escolher FLOAT32 ou FLOAT64, métrica de distância e FLAT ou HNSW a partir de medições.
• Selecionar Redis Hash ou Redis JSON e planejar migrações e reindexações seguras.
• Construir e validar um aplicativo Python de pesquisa semântica no Redis Gerenciado pelo Azure.

Resumo do tópico

Recuperação vetorial envolve um contrato completo: saída do modelo, esquema, metadados, índice, parâmetros de execução e métricas operacionais devem ser compatíveis.

radio_button_uncheckedshort_text2. Provisione o Redis Gerenciado pelo Azure para vetores

O Redis Gerenciado pelo Azure oferece pesquisa vetorial pelo módulo gerenciado RediSearch. Habilite-o na criação, pois não é possível adicionar módulos depois. A configuração atual também exige política de clustering Enterprise, política NoEviction e uma camada em memória compatível: Otimizado para Memória, Balanced ou Otimizado para Computação. Otimizado para Flash não oferece RediSearch.

Dimensione registros e sobrecarga do índice secundário. Use TLS; prefira autenticação do Microsoft Entra ID quando suportada pelo cliente; e avalie Link Privado, alta disponibilidade, diagnósticos e recuperação. Como o Azure gerencia as versões dos módulos, teste o comportamento da versão do serviço em vez de presumir um módulo instalado manualmente.

Resumo do tópico

A pesquisa vetorial começa no provisionamento: RediSearch, clustering Enterprise, NoEviction, camada compatível e memória suficiente precisam ser definidos antes.

radio_button_uncheckedshort_text3. Do conteúdo aos resultados indexados

O aplicativo divide as fontes em unidades recuperáveis, gera um embedding para cada uma e grava vetor, identidade, origem, categoria, data, locatário e controle de acesso. O RediSearch acompanha chaves do prefixo indexado e atualiza o índice secundário. A pergunta passa pelo mesmo modelo e pré-processamento antes da comparação KNN ou por intervalo.

Metadados restringem candidatos e dão rastreabilidade à resposta. Em RAG, o aplicativo recupera conteúdo e procedência, monta contexto fundamentado e o entrega ao modelo generativo. Distância vetorial classifica candidatos; ela não autoriza acesso nem comprova que uma afirmação é verdadeira.

Resumo do tópico

Use o mesmo contrato de embeddings na indexação e na consulta, guarde procedência e acesso com o vetor e trate recuperação como ranking, não como autorização.

radio_button_uncheckedshort_text4. Defina um índice vetorial sobre Redis Hash

O esquema do RediSearch descreve campos pesquisáveis e retornáveis. O campo vetorial declara algoritmo, TYPE, DIM e DISTANCE_METRIC; texto e tags habilitam filtros híbridos. IndexDefinition limita a indexação por prefixo e informa se a origem é Hash ou JSON.

from redis.commands.search.field import TagField, TextField, VectorField
from redis.commands.search.indexDefinition import IndexDefinition, IndexType

schema = (
    TextField("title"),
    TagField("department"),
    VectorField("embedding", "HNSW", {
        "TYPE": "FLOAT32",
        "DIM": 1536,
        "DISTANCE_METRIC": "COSINE",
        "M": 16,
        "EF_CONSTRUCTION": 200,
    }),
)

client.ft("idx:documents").create_index(
    schema,
    definition=IndexDefinition(
        prefix=["doc:"],
        index_type=IndexType.HASH,
    ),
)

O exemplo usa HNSW, FLOAT32, 1.536 dimensões e distância de cosseno. M e EF_CONSTRUCTION afetam conectividade, memória, construção e recall. O prefixo doc: impede que chaves alheias entrem no índice. A criação do esquema deve ser uma etapa versionada de implantação com reversão, não uma ação implícita em toda inicialização.

Resumo do tópico

O índice deve combinar algoritmo, tipo, dimensão, métrica, metadados, estrutura de origem e prefixo em um esquema estável.

radio_button_uncheckedshort_text5. Armazene vetores e metadados corretamente

Campos vetoriais em Hash usam blobs binários compactos. Converta a saída para o dtype exato do índice, confira o formato unidimensional e só então use tobytes(). Os demais campos continuam legíveis. Um embedding FLOAT32 de 1.536 valores ocupa 6.144 bytes antes da sobrecarga dos objetos Redis, metadados, replicação e índice.

import numpy as np

embedding = np.asarray(model_embedding, dtype=np.float32)
if embedding.shape != (1536,):
    raise ValueError("The embedding must contain exactly 1536 values")

client.hset("doc:917", mapping={
    "title": "Model deployment runbook",
    "department": "engineering",
    "content": "Operational steps for model deployment...",
    "embedding": embedding.tobytes(),
})

Divergências de dimensão ou dtype podem invalidar a indexação ou a consulta. Não corte, preencha ou reinterprete vetores silenciosamente. Registre modelo e versão nos metadados; uma troca de modelo normalmente requer campo ou índice separado até que vetores e clientes adotem o novo contrato.

Resumo do tópico

No Hash, serialize o dtype exato, valide DIM, preserve metadados úteis e versione o contrato de embeddings.

radio_button_uncheckedshort_text6. Ingestão em lotes, atualizações e visibilidade

Uma ida à rede por documento custa caro em uma carga grande. O pipeline do redis-py agrupa comandos. transaction=False deixa claro que o objetivo é reduzir viagens, não criar uma única transação tudo-ou-nada. Use lotes limitados para não pressionar memória do cliente, filas do servidor e tentativas.

with client.pipeline(transaction=False) as pipe:
    for document in documents:
        vector = np.asarray(document["embedding"], dtype=np.float32)
        pipe.hset(f'doc:{document["id"]}', mapping={
            "title": document["title"],
            "department": document["department"],
            "content": document["content"],
            "embedding": vector.tobytes(),
        })
    responses = pipe.execute()

# Batching reduces network round trips; it does not make the whole load atomic.
assert all(result >= 0 for result in responses)

O RediSearch mantém o índice conforme as chaves mudam. Depois da carga, confira contagens e consultas representativas. Chaves determinísticas tornam repetições idempotentes. Registre falhas de execute(), use recuo e observe transições de modelo. O ganho do pipeline depende de rede, carga e payload; meça em vez de prometer um multiplicador fixo.

Resumo do tópico

Pipelines reduzem viagens, chaves determinísticas protegem tentativas e validações pós-carga comprovam que o índice está utilizável.

radio_button_uncheckedshort_text7. Execute uma consulta KNN

KNN pede uma quantidade fixa de vizinhos. A sintaxe informa K, campo vetorial, parâmetro binário e alias da distância. Retorne apenas os campos necessários e ordene pela distância. Consultas vetoriais usam dialeto 2; versões recentes do redis-py já o solicitam, mas declará-lo torna o exemplo explícito.

from redis.commands.search.query import Query

query_vector = np.asarray(query_embedding, dtype=np.float32).tobytes()
query = (
    Query("*=>[KNN 5 @embedding $query_vec AS vector_distance]")
    .return_fields("title", "department", "vector_distance")
    .sort_by("vector_distance")
    .dialect(2)
)

results = client.ft("idx:documents").search(
    query,
    query_params={"query_vec": query_vector},
)

Com COSINE, menor distância significa maior proximidade: zero indica direção idêntica e o valor pode se aproximar de dois para direções opostas. O score não é probabilidade universal. Calibre limites com exemplos rotulados do modelo, idioma, domínio e estratégia de fragmentação reais.

Resumo do tópico

KNN devolve os K registros mais próximos; envie o vetor como bytes, ordene pelo alias e interprete distância apenas dentro de uma carga calibrada.

radio_button_uncheckedshort_text8. Combine similaridade e filtros de metadados

A pesquisa híbrida restringe candidatos pelos metadados e os classifica pela distância vetorial. É possível limitar por produto, departamento, locatário e classificação permitida. Portanto, filtros fazem parte da correção e da segurança, não são apenas uma otimização.

query = (
    Query(
        "@department:{engineering}=>"
        "[KNN 3 @embedding $query_vec AS vector_distance]"
    )
    .return_fields("title", "department", "vector_distance")
    .sort_by("vector_distance")
    .dialect(2)
)

Valores de tags com caracteres reservados precisam ser escapados ou modelados com cuidado. Aplique predicados obrigatórios de autorização no servidor e revalide o retorno no aplicativo. Meça seletividade: bons filtros podem acelerar a comparação, mas distribuição enviesada ou índice inadequado muda a latência.

Resumo do tópico

Consultas híbridas unem restrições obrigatórias e ranking vetorial; campos devem ser indexados, escapados e tratados como parte da fronteira de autorização.

radio_button_uncheckedshort_text9. Use VECTOR_RANGE para limites de distância

KNN tenta retornar uma quantidade fixa mesmo quando os vizinhos são ruins. VECTOR_RANGE devolve todos os registros dentro de uma distância máxima, podendo retornar nenhum. Isso atende cache semântico, detecção de duplicidade e RAG que precisa recusar uma resposta sem fonte suficientemente próxima.

query = (
    Query(
        "@embedding:[VECTOR_RANGE $radius $query_vec]"
        "=>{$YIELD_DISTANCE_AS: vector_distance}"
    )
    .return_fields("title", "vector_distance")
    .sort_by("vector_distance")
    .dialect(2)
)

results = client.ft("idx:documents").search(
    query,
    query_params={"radius": 0.20, "query_vec": query_vector},
)

Defina o raio com dados de avaliação. O mesmo número muda de significado entre COSINE, L2, IP e modelos diferentes. A consulta por intervalo com HNSW também aceita EPSILON, ampliando a exploração e potencialmente o recall ao custo de tempo.

Resumo do tópico

Use KNN para K candidatos ranqueados e VECTOR_RANGE quando a regra é aceitar apenas itens dentro de um limite calibrado.

radio_button_uncheckedshort_text10. Faça tipo numérico e dimensões coincidirem

FLOAT32 é a escolha normal para embeddings e reduz pela metade o payload em relação a FLOAT64. Redis atuais podem expor tipos quantizados adicionais, mas o Redis Gerenciado pelo Azure controla a versão do módulo; confirme compatibilidade e recall antes de adotá-los. O módulo-fonte concentra-se em FLOAT32 e FLOAT64.

DIM vem do modelo: 384, 768, 1.024, 1.536 e 3.072 são exemplos, não opções intercambiáveis. Índice, registro e consulta precisam ter a mesma quantidade de elementos e tipo. Mudar de modelo exige re-embedding e reindexação planejados.

Resumo do tópico

FLOAT32 é o padrão usual; DIM e dtype precisam coincidir exatamente no modelo, bytes armazenados, esquema e consulta.

radio_button_uncheckedshort_text11. Escolha COSINE, L2 ou produto interno

O contrato do modelo e a avaliação determinam a métrica. Uma opção matematicamente válida ainda pode classificar mal se o modelo foi treinado para outra comparação. Normalize somente quando o modelo e a métrica exigirem.

Resumo do tópico

Use a métrica esperada pelo modelo e valide a qualidade de recuperação com perguntas rotuladas e representativas.

radio_button_uncheckedshort_text12. FLAT exato versus HNSW aproximado

FLAT compara a pergunta com todo vetor e produz busca exaustiva. É simples e exato, porém cresce linearmente. HNSW constrói um grafo navegável em camadas e visita nós promissores. Em escala, costuma reduzir bastante a latência, aceitando que uma busca aproximada pode perder um vizinho verdadeiro.

Limiares como dez mil ou um milhão de registros são heurísticas, não garantias. Dimensão, camada, seletividade, concorrência, recall e memória alteram a transição. Use FLAT como referência exata ao medir recall do HNSW.

Resumo do tópico

FLAT é exaustivo; HNSW troca parte do recall por latência escalável. Escolha com benchmarks, não por uma contagem fixa.

radio_button_uncheckedshort_text13. Ajuste e avalie HNSW

M aumenta conexões do grafo e tende a melhorar navegação, consumindo memória. EF_CONSTRUCTION amplia vizinhos analisados na construção, elevando tempo e frequentemente recall. EF_RUNTIME controla candidatos em cada KNN: valores maiores tendem a melhorar recall e aumentar latência. Padrões são somente pontos de partida.

query = Query(
    "*=>[KNN 10 @embedding $query_vec EF_RUNTIME $ef AS vector_distance]"
).sort_by("vector_distance").dialect(2)

for ef_runtime in (10, 50, 100, 200):
    started = time.perf_counter()
    result = client.ft("idx:documents").search(
        query,
        query_params={
            "query_vec": query_vector,
            "ef": ef_runtime,
        },
    )
    latency_ms = (time.perf_counter() - started) * 1000
    evaluate(ef_runtime, latency_ms, result.docs)

Crie um conjunto rotulado e meça latências p50, p95 e p99, throughput, memória, duração da construção e recall@K contra FLAT. Teste concorrência e filtros reais. Escolha a configuração de menor custo que cumpra o objetivo e repita após mudanças de modelo, dados, camada ou tráfego.

Resumo do tópico

Ajuste M e EF_CONSTRUCTION na construção e EF_RUNTIME na consulta; compare recall com FLAT e meça cauda de latência, vazão e memória.

radio_button_uncheckedshort_text14. Modele vetores em Hash ou Redis JSON

Hash representa um registro plano e guarda o vetor em bytes compactos; é um bom padrão quando o esquema é simples e memória e operações diretas importam. Redis JSON preserva objetos e matrizes aninhados; o vetor é uma matriz numérica, mas a consulta continua enviando bytes. JSONPath e aliases deixam o esquema pesquisável legível.

from redis.commands.json.path import Path

document = {
    "name": "Wireless headset",
    "price": 99.90,
    "category": "electronics",
    "specs": {"color": "black", "wireless": True},
    "embedding": embedding.tolist(),
}
client.json().set("jdoc:12345", Path.root_path(), document)

schema = (
    TextField("$.name", as_name="name"),
    TagField("$.category", as_name="category"),
    VectorField("$.embedding", "HNSW", {
        "TYPE": "FLOAT32", "DIM": 1536,
        "DISTANCE_METRIC": "COSINE",
    }, as_name="embedding"),
)

Resumo do tópico

Escolha Hash para registros planos compactos e JSON para documentos aninhados; origem, representação e IndexDefinition devem coincidir.

radio_button_uncheckedshort_text15. Migre estruturas e versões de índice com segurança

Converter Hash em JSON muda o tipo da chave e o índice. Uma migração segura grava documentos sob novo prefixo, cria índice JSON, valida contagens e consultas, troca leitores de modo controlado e mantém a origem durante a janela de reversão. Sobrescrever uma chave Hash com JSON não é um plano seguro.

# Write transformed documents under a new prefix; do not overwrite Hash keys.
for key in client.scan_iter(match="product:*"):
    source = client.hgetall(key)
    vector = np.frombuffer(source[b"embedding"], dtype=np.float32)
    target = {
        "name": source[b"name"].decode(),
        "price": float(source[b"price"]),
        "category": source[b"category"].decode(),
        "embedding": vector.tolist(),
    }
    client.json().set(f"j{key.decode()}", Path.root_path(), target)

# Build and validate the JSON index, then switch reads deliberately.
# Keep the old index until validation and rollback windows are complete.

A mesma estratégia azul-verde atende mudança de modelo: novo campo ou prefixo, índice versionado, backfill, comparação, corte e remoção posterior. Monitore falhas de indexação, memória, gravações rejeitadas, latência e recall.

Resumo do tópico

Use novos prefixos e índices versionados, valide antes do corte e preserve reversão até provar o novo caminho.

radio_button_uncheckedshort_text16. Laboratório guiado: implemente pesquisa semântica

O exercício-fonte cria um recurso compatível com Enterprise, baixa arquivos iniciais, completa a lógica Python, carrega vetores, grava vetores com metadados, recupera por chave, calcula similaridade de cosseno e procura produtos relacionados. Reserve cerca de 40 minutos após preparar o ambiente.

Pré-requisitos

• Assinatura do Azure com permissão para criar a camada e configuração necessárias do Redis Gerenciado pelo Azure.
• Visual Studio Code, Python 3.12 ou posterior, CLI do Azure atual e extensão redisenterprise.
• Recurso com RediSearch, clustering Enterprise, NoEviction, TLS e capacidade adequada.
• Conjunto inicial com modelo, dimensões, dtype e métrica documentados.

az extension add --name redisenterprise
az redisenterprise show   --resource-group <resource-group>   --cluster-name <cache-name>

python -m venv .venv
# Activate the virtual environment for your shell.
python -m pip install --upgrade redis numpy azure-identity
python app.py

1. Conecte com segurança e confirme PING.
2. Crie índice Hash versionado e verifique o esquema.
3. Carregue amostras em pipelines limitados e confira contagens.
4. Implemente leitura por chave e cosseno independente para testes.
5. Execute KNN, KNN filtrado e VECTOR_RANGE com exemplos conhecidos.
6. Compare FLAT e HNSW em latência e recall e registre os parâmetros.
7. Exclua o recurso de laboratório ao terminar, se ele não for mais necessário.

Resumo do tópico

O laboratório comprova o ciclo inteiro: recurso seguro, esquema correto, ingestão, leitura, cálculo, consultas semânticas e escolha medida do índice.

radio_button_uncheckedshort_text17. Revisão da avaliação e checklist de produção

Em produção, confirme módulo e camada, contrato do modelo, filtros obrigatórios, prefixos, automação de versões, folga de memória, TLS, identidade, rede, ingestão limitada, tentativas idempotentes, painéis, alertas, suíte rotulada de relevância e reversão. Nenhum número isolado de latência, recall ou tamanho substitui testes com vetores e tráfego reais.

1. Microsoft Learn: embeddings e pesquisa vetorial no Redis Gerenciado pelo Azure
2. Microsoft Learn: documentação do Redis Gerenciado pelo Azure
3. Redis: conceitos e parâmetros da pesquisa vetorial
4. Redis: indexar e consultar vetores com redis-py
5. Microsoft Learn: referência de az redisenterprise

Resumo do tópico

Memorize o contrato: COSINE é comum em texto, FLOAT32 é o padrão, HNSW é a opção aproximada escalável, Hash atende registros planos e toda decisão de produção precisa ser medida e protegida.