Optimizar la indexación, el costo vectorial y la coherencia en Azure Cosmos DB

radio_button_uncheckedshort_text1. Diagnosticar la búsqueda en producción antes de agregar índices

Una plataforma de búsqueda semántica puede funcionar con pocos datos y fallar al llegar a producción. Imagina millones de elementos con metadatos, texto extraído y embeddings generados por Azure OpenAI Service. Los usuarios combinan palabras clave, intervalos de fechas, tipos y clasificación semántica, y esperan respuestas inferiores a 100 milisegundos. A escala real aumenta la latencia, se disparan las RU y las cargas recientes no siempre aparecen de inmediato.

Las causas se relacionan: la directiva predeterminada crea índices de intervalo para todas las propiedades, incluso grandes matrices de embeddings; faltan índices compuestos y algunas consultas examinan el contenedor; además, la coherencia eventual no garantiza que el autor lea inmediatamente su propia escritura. La solución parte del inventario de consultas, sus métricas y el requisito de actualización del usuario.

• Localizar filtros, ordenaciones y consultas vectoriales lentas.
• Configurar índices de intervalo y compuestos según el acceso real.
• Elegir flat, quantizedFlat o DiskANN según volumen y calidad.
• Equilibrar mejoras de lectura con costo de escritura, almacenamiento y transformación.
• Seleccionar la coherencia necesaria sin pagar por garantías superfluas.

Resumen del tema

La optimización comienza con evidencias de consulta y requisitos de actualización, no con la creación indiscriminada de índices.

radio_button_uncheckedshort_text2. Comprender la indexación automática, las familias y los modos

Un contenedor nuevo de Azure Cosmos DB for NoSQL indexa automáticamente todas las propiedades mediante índices de intervalo. Esto simplifica el desarrollo inicial porque casi cualquier filtro escalar dispone de un índice, pero cada ruta ocupa almacenamiento y añade trabajo sincrónico a las escrituras. Las cargas de IA con acceso predecible suelen beneficiarse de una directiva selectiva.

El modo coherente actualiza los índices durante la escritura y es la opción habitual cuando los datos recién ingeridos deben ser consultables. None deshabilita los índices secundarios y sirve para lecturas puntuales por id y clave de partición o cargas masivas específicas. La indexación diferida está en desuso para contenedores nuevos; los usos existentes deben migrar al modo coherente.

Resumen del tema

La directiva automática maximiza la cobertura; una directiva coherente personalizada evita almacenamiento y escritura sin utilidad.

radio_button_uncheckedshort_text3. Controlar rutas incluidas, excluidas y propiedades del sistema

Las expresiones de ruta deciden qué entra en el índice. /* incluye recursivamente valores escalares desde la raíz, /property/? selecciona un escalar, /array/[] cubre los elementos de una matriz y /nested/path/* cubre descendientes. Cuando hay conflicto, gana la ruta más específica, de modo que es posible excluir ampliamente y volver a incluir solo lo necesario.

• id y _ts siempre permanecen indexados en modo coherente.
• _etag se excluye de forma predeterminada y rara vez necesita un índice.
• Si la clave de partición no es /id, no se indexa automáticamente como intervalo; inclúyela cuando aparezca en filtros.
• Excluye texto extenso solo mostrado, binarios, metadatos sin consultar y matrices de embeddings.

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/tenantId/?" },
    { "path": "/documentType/?" },
    { "path": "/category/?" },
    { "path": "/uploadDate/?" }
  ],
  "excludedPaths": [
    { "path": "/*" },
    { "path": "/embedding/*" }
  ],
  "compositeIndexes": [[
    { "path": "/documentType", "order": "ascending" },
    { "path": "/uploadDate", "order": "descending" }
  ]],
  "vectorIndexes": [
    { "path": "/embedding", "type": "diskANN" }
  ]
}

Resumen del tema

Con exclusión predeterminada, incluye expresamente la clave de partición y cada propiedad usada por las consultas.

radio_button_uncheckedshort_text4. Diseñar índices de intervalo para filtros y funciones de texto

Los índices de intervalo admiten =, !=, >, <, >= y <=, además de ordenar por una propiedad. También sirven a CONTAINS, STARTSWITH, ENDSWITH, StringEquals e IS_DEFINED cuando la propiedad indexada ocupa la posición compatible. Una consulta por documentType y uploadDate necesita ambas rutas; de lo contrario, las RU aumentan con los datos examinados y no con los resultados.

Son la base para tipo, estado, categoría, fechas, puntuaciones y umbrales. No sustituyen un índice de texto completo para recuperación lingüística y no deben aplicarse a embeddings solo porque contienen números.

Resumen del tema

Usa índices de intervalo para escalares, comparaciones y ordenación simple; reserva los embeddings al índice vectorial.

radio_button_uncheckedshort_text5. Hacer coincidir índices compuestos con ORDER BY y varios filtros

Una ordenación por dos o más propiedades necesita un índice compuesto con la misma secuencia y dirección. Un índice relevanceScore DESC y uploadDate DESC también admite la inversión completa a ASC, pero no direcciones mezcladas. Cambiar la secuencia define otro índice.

Al filtrar por documentType y ordenar por uploadDate, repetir la propiedad de igualdad en ORDER BY permite que un índice compuesto resuelva el prefijo fijo y el sufijo ordenado.

SELECT * FROM c
WHERE c.documentType = 'pdf'
ORDER BY c.documentType ASC, c.uploadDate DESC

Con varios filtros, coloca primero las igualdades y al final una sola condición de intervalo. Si existen dos intervalos, el motor puede combinar dos índices compuestos que comparten los campos de igualdad y terminan en intervalos distintos. Prioriza las combinaciones frecuentes y voluminosas, no casos excepcionales.

Resumen del tema

Los índices compuestos dependen del orden: igualdades al inicio, un intervalo al final y una ordenación que coincida con la definición.

radio_button_uncheckedshort_text6. Aplicar índices de tupla y transformar directivas con seguridad

Un índice de tupla mantiene relacionados los campos del mismo elemento de una matriz. Resulta adecuado para fragmentos con posición y tokens, etiquetas con categoría y peso o eventos con fecha y tipo. Sin esta semántica, el motor no representa eficazmente que todas las condiciones deben cumplirse en el mismo miembro.

{
  "includedPaths": [
    { "path": "/*" },
    { "path": "/chunks/[]/{position, tokens}/?" }
  ]
}

Cada índice eleva la latencia y las RU de escritura porque el modo coherente lo mantiene sincrónicamente. Los cambios ejecutan una transformación asincrónica. Un índice nuevo solo ayuda al terminar; uno eliminado deja de servir consultas inmediatamente. Para reemplazar, agrega la definición nueva, espera y verifica el 100% y después quita la anterior. Supervisa el progreso en Azure Portal o mediante superficies compatibles del SDK y programa cambios grandes fuera de las horas punta.

Resumen del tema

Los índices de tupla resuelven filtros dentro del mismo elemento; el reemplazo seguro es agregar, esperar, verificar y eliminar.

radio_button_uncheckedshort_text7. Seleccionar el índice vectorial para el ámbito buscado

Los índices vectoriales aceleran VectorDistance y los índices de intervalo o compuestos atienden los metadatos. La directiva vectorial del contenedor define ruta, tipo, dimensiones y función de distancia; la directiva de indexación asigna flat, quantizedFlat o diskANN.

quantizedFlat y diskANN necesitan al menos 1.000 vectores para que su estructura optimizada sea efectiva; por debajo se ejecuta un examen completo. Una aplicación creciente puede comenzar con flat y migrar tras pruebas representativas. Excluye siempre los embeddings de la indexación de intervalo.

Resumen del tema

Elige por cantidad de candidatos, dimensiones, recuperación, latencia y RU; no hay una opción universal.

radio_button_uncheckedshort_text8. Ajustar la construcción vectorial y coordinar metadatos

Empieza con los valores predeterminados. quantizationByteSize admite 1–512 bytes: un valor mayor conserva más información y utiliza más almacenamiento. En diskANN, indexingSearchListSize admite 10–500 y su valor predeterminado es 100; aumentarlo puede mejorar la recuperación, pero encarece la construcción y la incorporación de vectores.

{
  "vectorIndexes": [{
    "path": "/embedding",
    "type": "diskANN",
    "quantizationByteSize": 64,
    "indexingSearchListSize": 150
  }]
}

Combina el índice vectorial con índices de intervalo o compuestos para categoría, departamento, tipo y fecha. El filtrado previo reduce candidatos y RU. La directiva vectorial es estructural: cambiar dimensiones, tipo o distancia normalmente requiere un contenedor compatible nuevo y migración. float16 ocupa cerca de la mitad que float32 con poco impacto habitual; int8 y uint8 exigen cuantificación evaluada. El coseno es frecuente para embeddings de texto.

Resumen del tema

Ajusta los parámetros solo con métricas de recuperación y latencia y define dimensiones, tipo y distancia antes de producción.

radio_button_uncheckedshort_text9. Medir la eficiencia y detectar índices ausentes

Las métricas convierten la lentitud en evidencia. La utilización del índice indica cuánto trabajo fue indexado; los documentos recuperados muestran cuántos elementos se leyeron para evaluar; y los documentos de salida muestran cuántos sobrevivieron. Una utilización baja o una relación recuperados/salida alta suele señalar examen, ruta ausente o índice compuesto faltante.

from azure.cosmos import CosmosClient

metrics = {}
def response_hook(headers, _):
    metrics["query"] = headers.get("x-ms-documentdb-query-metrics", "")
    metrics["ru"] = headers.get("x-ms-request-charge", "")

items = list(container.query_items(
    query="SELECT * FROM c WHERE c.documentType = @type ORDER BY c.uploadDate DESC",
    parameters=[{"name": "@type", "value": "pdf"}],
    populate_query_metrics=True,
    response_hook=response_hook
))

print(metrics["query"])
print(f'{metrics["ru"]} RUs')

Captura x-ms-request-charge, cambia una hipótesis, espera la transformación y repite el mismo ensayo. TOP limita la salida, pero no corrige un filtro sin índice. Compara percentiles y consultas representativas.

Resumen del tema

Utilización, relación recuperados/salida y cobro de RU demuestran si un índice reduce realmente el trabajo.

radio_button_uncheckedshort_text10. Equilibrar el costo de RU entre lecturas y escrituras

Las lecturas indexadas suelen consumir RU según los resultados; los exámenes crecen con los datos. Sin embargo, cada ruta e índice compuesto añade almacenamiento y RU de escritura. Búsqueda, informes y paneles de lectura intensiva justifican mayor cobertura; ingesta masiva, actualizaciones de embeddings, streaming y lotes favorecen menos índices.

• Catalogar WHERE, ORDER BY, agregaciones, combinaciones, direcciones y frecuencia.
• Cubrir los cinco a diez patrones con mayor beneficio medido.
• Excluir de los índices de intervalo texto solo mostrado, metadatos brutos y vectores.
• Probar cardinalidad, sesgo, distribución de particiones y cantidades realistas de vectores.
• Comparar RU de lectura y escritura antes de aprobar la directiva.

Los datos sintéticos uniformes ocultan categorías calientes y particiones desiguales. Carga distribuciones parecidas a producción y decide según el costo total observado.

Resumen del tema

La mejor directiva minimiza el costo completo: muchas lecturas justifican índices y muchas escrituras premian la selectividad.

radio_button_uncheckedshort_text11. Comparar los cinco niveles de coherencia y su efecto en RU

Fuerte y obsolescencia limitada leen dos réplicas, por lo que el rendimiento de lectura por RU es aproximadamente la mitad que en sesión, prefijo coherente o eventual. Las RU de escritura de la operación son iguales, pero la coherencia fuerte espera la mayoría global y aumenta la latencia. Los niveles más débiles confirman en la mayoría local antes de replicar asincrónicamente.

Resumen del tema

La coherencia equilibra actualidad, latencia, disponibilidad y costo; más fuerte no siempre es mejor.

radio_button_uncheckedshort_text12. Garantizar read-your-writes con tokens de sesión y PBS

La coherencia de sesión es apropiada cuando el usuario debe encontrar inmediatamente el documento o embedding que acaba de cargar. El token representa el avance de una partición. Una instancia del SDK lo administra automáticamente, pero los servicios distribuidos deben propagar el token de la escritura a la lectura. Otras sesiones pueden observar datos anteriores temporalmente.

from azure.cosmos import CosmosClient, ConsistencyLevel

client = CosmosClient(
    url=endpoint,
    credential=credential,
    consistency_level=ConsistencyLevel.Session
)

session = {}
def capture(headers, _):
    session["token"] = headers.get("x-ms-session-token", "")

container.create_item(body=document, response_hook=capture)

results = container.query_items(
    query="SELECT * FROM c WHERE c.category = @category",
    parameters=[{"name": "@category", "value": "proposals"}],
    session_token=session.get("token")
)

Clientes separados pueden aplicar coherencia fuerte a lecturas críticas y eventual a análisis. En varias regiones, la fuerte espera las regiones lejanas y no admite varias regiones de escritura; la obsolescencia limitada encaja mejor con una región de escritura; sesión y niveles más débiles confirman localmente. Las métricas de Obsolescencia Limitada Probabilísticamente (PBS) de Azure Monitor revelan con qué frecuencia una lectura eventual ya devuelve datos actuales y ayudan a decidir si es seguro debilitar la garantía.

Resumen del tema

Propaga tokens entre servicios para visibilidad inmediata y consulta PBS antes de debilitar la coherencia del usuario.

radio_button_uncheckedshort_text13. Laboratorio guiado: comparar índices vectoriales con datos realistas

El ejercicio de referencia propone 30 minutos para comparar flat, quantizedFlat y diskANN. Requiere una suscripción de Azure con permisos de implementación, Visual Studio Code, la versión más reciente de la CLI de Azure y Python 3.12 o posterior. Utiliza un grupo de recursos desechable.

1. Obtener los archivos iniciales y parametrizar la implementación.
2. Implementar una cuenta de Azure Cosmos DB for NoSQL con búsqueda vectorial.
3. Crear tres contenedores idénticos salvo por el índice vectorial.
4. Cargar los mismos documentos y embeddings.
5. Crear funciones de Python que ejecuten las mismas consultas VectorDistance con y sin filtros.
6. Mostrar latencia, RU y coincidencia de resultados en una aplicación Flask.
7. Repetir con al menos 1.000 vectores y selectividad realista.
8. Registrar recuperación frente a flat, latencia mediana y de cola, RU y almacenamiento y elegir según el objetivo.

No compares índices con datos, particiones, vectores o filtros diferentes. El calentamiento y las colecciones pequeñas distorsionan resultados; repite cada escenario y presenta la distribución.

Resumen del tema

Una comparación justa mantiene constantes datos y consultas y mide recuperación, latencia, RU y almacenamiento en escala realista.

radio_button_uncheckedshort_text14. Revisión razonada de la evaluación

1. Filtro documentType y orden uploadDate DESC: índice compuesto documentType ASC seguido de uploadDate DESC.
2. Unos 500.000 embeddings por partición y aproximación aceptable: diskANN está orientado a esa escala.
3. Embeddings usados solo para similitud: excluir su ruta del índice de intervalo y conservar el índice vectorial.
4. El usuario debe ver su carga: coherencia de sesión y token de escritura propagado a la lectura.
5. Baja utilización y relación recuperados/salida alta: hay examen; revisar predicados y agregar índice de intervalo o compuesto.

Los distractores reflejan errores comunes: índices de intervalo separados no resuelven la ordenación multipropiedad, deshabilitar toda indexación perjudica otras consultas, aumentar el rendimiento no crea actualidad y TOP no arregla filtrado ineficaz.

Resumen del tema

La respuesta correcta sigue la forma de la consulta, la escala vectorial, el almacenamiento, la garantía y la métrica observada.

radio_button_uncheckedshort_text15. Lista final y referencias oficiales

• Inventariar consultas antes de escribir la directiva.
• Indexar la clave de partición cuando una directiva de exclusión todavía la filtra.
• Usar índices de intervalo, compuestos, espaciales, de tupla y vectoriales solo en patrones compatibles.
• Excluir embeddings del índice de intervalo y medir el ámbito real de la búsqueda.
• Agregar el índice sustituto antes de quitar el anterior.
• Validar RU y latencia con datos realistas y transformación completa.
• Usar coherencia de sesión para visibilidad inmediata y niveles más débiles cuando se acepta retraso.

Referencias oficiales de Microsoft

1. Directivas de indexación en Azure Cosmos DB
2. Administrar directivas de indexación en Azure Cosmos DB for NoSQL
3. Búsqueda de vectores en Azure Cosmos DB para NoSQL
4. Optimizar el costo de las solicitudes en Azure Cosmos DB
5. Niveles de coherencia en Azure Cosmos DB
6. Administrar niveles de coherencia

Resumen del tema

Una búsqueda eficaz combina indexación selectiva, decisiones vectoriales medidas, transformaciones seguras y la coherencia menos costosa que conserva la experiencia requerida.