Index and query vector data (Redis)

Azure Managed Redis ofrece capacidades de BBDD vectorial a través de RediSearch, lo que permite guardar y querying de embeddings con una latencia medida en milisegundos.

Crear un vector index

Para poder guardar vectores necesitas definir un index schema que especifique como manejar los embeddings.

Index schema components

IMPORTANTE

El campo crítico del schema es VectorField, ya que le indica a Redis como manejar tus embeddings.

/IMPORTANTE

# Code fragment - focus on VectorField configuration
from redis.commands.search.field import TextField, VectorField
from redis.commands.search.indexDefinition import IndexDefinition, IndexType

schema = (
    TextField("title"),
    TextField("content"),
    VectorField(
        "embedding",           # Field name in your Redis hashes
        "HNSW",               # Algorithm: FLAT or HNSW
        {
            "TYPE": "FLOAT32",          # Standard for AI embeddings
            "DIM": 1536,                # Must match your model's output
            "DISTANCE_METRIC": "COSINE" # Use COSINE for text, L2 for images
        }
    )
)

redis_client.ft("idx:documents").create_index(
    fields=schema,
    definition=IndexDefinition(
        prefix=["doc:"],          # Index keys starting with "doc:"
        index_type=IndexType.HASH # HASH or JSON
    )
)

Elegir indexing algorithm

REVISAR TODOS LOS SITIOS DONDE HABLE DE ESTO Y UNIFICARLO. ES UN TEMA A LO LARGO DE LA CERTIFICACIÓN

IMPORTANTE

Compara tu query contra cada vector individual en el índice para encontrar matches exactos. garantiza perfect accuracy para encontrar NN (Nearest Neighbour), pero se vuelve muy lento a medida que tus datos crecen.

FLAT es ideal para:

  • DEV
  • prototipos
  • PROD systems con datasets pequeños
  • necesitas perfect accuracy
  • puedes aceptar query latency
# Code fragment - focus on FLAT index configuration
VectorField(
    "embedding",
    "FLAT",  # Exact nearest neighbor search
    {
        "TYPE": "FLOAT32",
        "DIM": 1536,
        "DISTANCE_METRIC": "COSINE"
    }
)

Construye un grafo de varias capas y lo navega. Encuentra ANN (Aproximate Nearest Neighbour) en ms, pero no garantiza un 100% de matches exactos.

HNSW es ideal para:

  • large datasets (> 10.000 vectores)
  • PROD systems que necesiten fast queries (<10ms)
  • si 95-99% accuracy es aceptable

La mayoría de sistemas en PROD usan HNSW por las ganancias de performance, aún con la pérdida de accuracy

# Code fragment - focus on HNSW index configuration
VectorField(
    "embedding",
    "HNSW",  # Approximate nearest neighbor search
    {
        "TYPE": "FLOAT32",
        "DIM": 1536,
        "DISTANCE_METRIC": "COSINE"
    }
)

El param EF_RUNTIME indica el número de grafos a explorar para cada query

# Code fragment - focus on runtime tuning
query = Query(
    "*=>[KNN 10 @embedding $query_vec EF_RUNTIME 100 AS score]"
).dialect(2)

/IMPORTANTE

Ingest vector data

La ingestión es el proceso de cargar los embeddings en Redis para que sean buscables. A diferencia de datos normales, los vectores necesitan cuidados especiales.

IMPORTANTE

Redis guarda los emebddings como binary blobs (byte arrays) por temas de eficiencia, lo que significa que tienes que convertir tus arrays a bytes con tobytes() antes de guardarlos.

Al añadir embeddings a index prefix (ej: doc:*) Redis automáticamente se encarga de indexarlos. No tienes que hacer nada más.

/IMPORTANTE

Store vectors with metadata

IMPORTANTE

Siempre debemos guardar vectores junto a metadatos para filtrar resultados. Redis Hash permite guardar todo junto en una single key usando hset con un mapping dictionary.

/IMPORTANTE

# Code fragment - focus on vector storage with tobytes()
import numpy as np

embedding = np.array([0.1, 0.2, 0.3, ...], dtype=np.float32)

redis_client.hset(
    "doc:001",
    mapping={
        "title": "Getting Started with Azure AI",
        "content": "Azure AI Services provide pre-built models...",
        "embedding": embedding.tobytes(),  # Convert NumPy array to bytes
        "category": "documentation"
    }
)

Bulk ingestion (for performance)

IMPORTANTE

No es ideal mandar cientos de millones de vectores de golpe con hset ya que la red puede ser un límite al throughput. Solucionamos estos con Pipeles, enviando batches de multiples comandos juntos en un single network trip. Todos los comandos se ejecutan de manera atómica en el server y recives las respuestas de todos a una cuando llamas execute()

/IMPORTANTE

# Code fragment - focus on bulk ingestion pattern
# Assumes `documents` is a list of dicts with 'id', 'title', 'content', 'embedding'

pipeline = redis_client.pipeline()

for doc in documents:
    vector_bytes = np.array(doc['embedding'], dtype=np.float32).tobytes()

    pipeline.hset(
        f"doc:{doc['id']}",
        mapping={
            "title": doc['title'],
            "content": doc['content'],
            "embedding": vector_bytes,
            "category": doc.get('category', 'general')
        }
    )

# Execute all HSETs in one network round-trip
pipeline.execute()

Querying por similaridad

Vector similarity usa KNN (K-Nearest Neighbours) para encontrar los vectores más similares - para COSINE distance 0.0 significa vectores idénticos mientras que 2.0 indica vectores opuestos.

Basic KNN queries

Una query KNN requiere

  • query vector (convertido a bytes)
  • número K a devolver (cuantos queremos)
  • vector field a buscar (@embedding)
  • dialect(2) (requerido para vector queries)

Ejemplo de query string

*=>[KNN 5 @embedding $query_vec as score]

la cual indica:

  • * busca todos los documentos
  • => indica vector search syntax
  • KNN 5 pide 5 NN
  • @embedding especifica que campo contiene los vectores
  • $query_vec es un placeholder para tu query vectorial
  • AS score devuelve la distancia como un campo que puedas filtrar
# Code fragment - focus on KNN query syntax
from redis.commands.search.query import Query

query_bytes = np.array(query_embedding, dtype=np.float32).tobytes()

query = (
    Query("*=>[KNN 5 @embedding $query_vec AS score]")
    .return_fields("title", "content", "score")
    .sort_by("score")
    .dialect(2)
)

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

Hybrid search: Filtrar por metadatos

Hybrid search mezcla vector similarity con metadata filters.

Ejemplo de query string con filtros

@category:{documentation}=>[KNN 3 @embedding $query_vec AS score]

la cual indica:

  • @category:{documentation} antes de => indica que filtre los matching items antes de pasar a la búsqueda vectorial
# Code fragment - focus on hybrid query syntax
hybrid_query = Query(
    "@category:{documentation}=>[KNN 3 @embedding $query_vec AS score]"
).return_fields("title", "category", "score").sort_by("score").dialect(2)

results = redis_client.ft("idx:documents").search(
    hybrid_query,
    query_params={"query_vec": query_bytes}
)

Range queries: Threshold-based retrieval

Mientras que KNN devuelve un número fijo de resultados, las range queries devuelven todos los vectores que haya a una distancia especificada.

Es útil cuando quieres todo lo que haya con un cierto nivel de similitud, independientemente de devolver un número arbitrario.

Por ejemplo: queremos todos los docs con un COSINE distance menor de 0.2, lo cual puede devolver 3 o 300

# Code fragment - focus on VECTOR_RANGE syntax
range_query = Query(
    "@embedding:[VECTOR_RANGE 0.2 $query_vec]=>{$YIELD_DISTANCE_AS: score}"
).return_fields("title", "score").sort_by("score").dialect(2)

results = redis_client.ft("idx:documents").search(
    range_query,
    query_params={"query_vec": query_bytes}
)

Understand distance metrics

ATENCION: esto moverlo a otra parte ya que es un tema multi-repetido a lo largo de toda la cert.

  • COSINE: Usar para text embeddings
  • L2 (Euclidean): Usar para image embeddings o spatial data
  • IP: Usar solo para embeddings pre-normalizados

/ATENCION: esto moverlo a otra parte ya que es un tema multi-repetido a lo largo de toda la cert.