Store and retrieve embeddings (CosmosDB)

CosmosDB guarda los embeddings como document properties. Se crea un unified data model para mantener los vectores justo a los metadatos en la misma BBDD

Understand vector embeddings

Los representaciones numéricas de datos generados por modelos de embeddings. Algunos servicios como Hugging Face ofrecen APIs para usar estos modelos. Se les pasa un input de texto, imágenes o similar y devuelve vectores.

Diferentes modelos de embeddings generan vectores diferentes.

Design document structure for vector storage

Al diseñar los documentos para vector search, guardamos los embeddings como un array en las propiedades junto a todos los datos.

Una estructura de documentos bien diseñada incluye:

  • Contenido original
  • metadatos relevantes para filtrar
  • embedding vectors
{
    "id": "doc-12345",
    "title": "Troubleshooting wireless network connections",
    "content": "This guide covers common WiFi connectivity issues including connection drops, slow speeds, and authentication failures...",
    "category": "networking",
    "productId": "router-x100",
    "createdDate": "2024-06-15T10:30:00Z",
    "embedding": [0.023, -0.041, 0.067, ...]
}

Configure container vector policies

CosmosDB requiere una vector policy al crear un contenedor que se va a usar para almacenar embeddings. Esta vector policy especifica properties que se usan para búsqueda por similitud.

Antes de usar vector search hay que activar la característica en Settings > Features > Vector Search for NoSQL API o mediante az cosmosdb update --capabilities EnableNoSQLVectorSearch

ejemplo de vector policy que guarda embeddings en el path /embedding

vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/embedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}
  • path: JSON path de la propiedad dentro de los docs que almacena los embeddings
  • dataType: float32, float16, int8, uint8 (default: float32)
  • dimensiones: número de elementos del vector. debe hacer match con el modelo de embeddings
  • distanceFunction: métrica usada para calcular la distancia cosine, dotproduct, euclidean (default: cosine)

Choose a distance function

(sin más, no entrar en tanto detalle)

De ella depende lo que se entiende por contenidos “similares”.

  • Cosine similarity: mide el ángulo entre dos vectores. ideal para vectores donde la magnitud no debe afectar a la similitud.
  • Dot product: mide el ángulo y la magnitud. Para vectores que están normalizados es más rápido que cosine, pero tienen que estar normalizados.
  • Euclidean distance: mide la distancia de la línea recta entre dos vectores. Para casos donde ambos dirección y magnitud importan, pero es menos común para text embeddings.

Data types for storage efficiency

IMPORTANTE

Hay que tener en cuenta la eficiencia. float32 da mucha precisión pero es más caro de almacenar. float16 reduce el coste de almacenamiento un 50% con un impacto mínimo en search quality.

int8 y uint8 da todavía más compresión a través de la cuantización. Estos tipos solo funcionan con embeddings que han sido cuantizados (convertidos de float a int values).

Para la mayoría de AI apps, float32 es el mejor balance por simpleza. Si los costes de almacenamiento son significantes, bajar a float16, siempre que el testing determine que la búsqueda es aceptable

/IMPORTANTE

Store multiple vector types per document

IMPORTANTE

CosmosDB soporta múltiples campos de embeddings por documento. De esta manera puedes generar embeddings diferentes para el título de un documento y su contenido, o guardar ambos embeddings de texto y embeddings de imagen.

/IMPORTANTE

embedding policy que soporta dos embeddings con dimensiones y distance function diferente

vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/titleEmbedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        },
        {
            "path": "/contentEmbedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}

Configure vector indexes

Los vector indexes aceleran las búsquedas por similitud organizando los vectores para un querying eficiente. Sin un index cada query hace un full scan contra todos los vectores guardados.

CosmosDB ofrece tres vector index types

  • flat: guarda vectores en el main index y hace brute-force search. Limita los vectores a 505 dimensiones. Ideal para datasets pequeños o cuando necesitas resultados exactos.
  • quantizedFlat: comprime vectores antes del indexing (por eficiencia). Sigue siendo brute-force pero con menos latencia y coste de RU. Soporta hasta 4096 dimensiones y recomendado para datasets <= 50.000 vectores por partición física.
  • diskANN: Usa un algoritmo para búsquedas rápidas aproximadas. Soporta hasta 4096 dimensiones, y da mejor performance para datasets con millones de vectores

quantizedFlat y diskAnn requieren por lo menos de 1000 vectores antes de que el index sea efectivo. Con menos vectores hace un full scan

indexing_policy = {
    "indexingMode": "consistent",
    "automatic": True,
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        {"path": "/\"_etag\"/?"},
        {"path": "/embedding/*"}
    ],
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ]
}

es importante excluir el embedding path de includedPaths ya que los embedding arrays no se benefician de standard range indexes.

Create a container with vector policies

Al crear un contenedor para vector search tienes que especificar ambos, vector embedding policy e indexing policy. Éstas solo se pueden poner en tiempo de creación. No se pueden añadir después.

from azure.cosmos import CosmosClient, PartitionKey

# Vector embedding policy
vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/embedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}

# Indexing policy with vector index
indexing_policy = {
    "indexingMode": "consistent",
    "automatic": True,
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        {"path": "/\"_etag\"/?"},
        {"path": "/embedding/*"}
    ],
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ]
}

# Create container with vector support
container = database.create_container(
    id="knowledge-base",
    partition_key=PartitionKey(path="/category"),
    indexing_policy=indexing_policy,
    vector_embedding_policy=vector_embedding_policy
)

Additional resources

Integrated Vector Store - Azure Cosmos DB
Index and Query Vector Data in Python - Azure Cosmos DB
Azure OpenAI in Microsoft Foundry Models embeddings (classic) - Microsoft Foundry (classic) portal