Posts Tagged - AI-200

AI-200: Azure AI Cloud Developer Associate

status: in progress

(los posts aquí contenidos han sido creados (y contienen imágenes oficiales) siguiendo los cursos oficiales self-paced de learn.microsoft.com AI-200. Para más información recomiendo seguir los mismos cursos)

Contents

Develop containerized solutions on Azure (20-25%)

  • Implement container application hosting
  • Implement container-orchestrated solutions

Develop AI solutions by using Azure data management services (25-30%)

  • Develop AI solutions by using Azure Cosmos DB for NoSQL
  • Develop AI solutions by using Azure Database for PostgreSQL
  • Integrate Azure Managed Redis in AI solutions

Connect to and consume Azure services (20-25%)

  • Develop event- and message-based AI solutions
  • Develop and implement Azure Functions

Secure, monitor, and troubleshoot Azure solutions (20-25%)

  • Implement secure Azure solutions
  • Monitor and troubleshoot Azure solutions

Microsoft official learning paths

Azure Container Registry (ACR)

Azure Container Registry es un registro privado para almacenar y distribuir contenedores y artefactos, que posteriormente pueden ser desplegados por otros servicios de Azure.

(store and manage container images in Azure Container Registry)

Azure Container Registry (ACR)
Build and run images (ACR Tasks)
Images’ versions and tags
ACR CLI


Azure App Service

Azure App Service es una plataforma para alojar webapps y APIs. Permite desplegarlas mediante contenedores (o directamente subir source code)

(deploy container images to Azure App Service)

Azure App Service
Configure container runtime
Configure app settings
Troubleshoot container apps
Azure App Service CLI

(run sidecar pattern on Azure App Service)

Sidecar pattern
Configure main and sidecar containers
Connect containers and share files
(TODO) Diagnose sidecar failures


Azure Container Apps (ACA)

Azure Container Apps permite ejecutar microservicios y jobs basados en contenedores sin tener que gestionar un clúster de K8s ni su infra subyacente

Azure Container Apps commands can require the Container Apps extension. Run az extension add --name containerapp --upgrade. Add --allow-preview true if you need such features

az login
az upgrade
az extension add --name containerapp --upgrade

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

(deploy containers to Azure Container Apps)

Environments
Deployments (CLI & YAML)
Runtime (env vars & secrets)
Pull from private registries
Verify deployments (logs & status)

(manage containers in Azure Container Apps)

Update Images (& manage revisions)
Manage container app lifecycle
Monitor logs
Health probes
Optimizar recursos de contenedor y scaling

(scale containers in Azure Container Apps)

Configure scale rules
Event-driven scaling with KEDA
KEDA scalers for custom workloads
Select resources for performance and cost
Revision modes

(run AI-generated code securely in ACA dynamic sessions)

Las aplicaciones de IA generan código para analizar datos, ejecutar cálculos o crear ficheros. Azure Container Apps dynamic sessions ofrece entornos de ejecución aislados y environments efímeros para ejecutar ese código no confiable, sin exponer la aplicación de IA ni el host

Choose dynamic session pool
Configure a secure session pool
Execute code and exchange files
Manage lifecycle and execution failures


Azure Kubernetes Service (AKS)

Azure Kubernetes Service es el servicio administrado de Kubernetes de Azure. Permite crear y operar clústeres de K8s en Azure para desplegar y gestionar aplicaciones basadas en contenedores

(deploy applications to Azure Kubernetes Service)

Create K8s deployment manifest
Como exponer apps
Deploy apps to Azure Kubernete Service

(configure applications on Azure Kubernetes Service)

Define ConfigMaps
Define Secrets
Attach persistent storage to an app

(monitor and troubleshoot applications on Azure Kubernetes Service)

Monitor app logs and metrics


Azure Cosmos DB for NoSQL

Azure Cosmos DB for NoSQL es una BBDD NoSQL distribuida y administrada por Azure, orientada al almacenamiento de documentos JSON. Permite trabajar con estructuras de datos flexibles sin definir un schema rígido. Está diseñada para baja latencia, escalabilidad horizontal y distribución geográfica

Se puede usar como BBDD vectorial

(build and query with Azure Cosmos DB for NoSQL)

Azure CosmosDB for NoSQL
Implement SDK
Queries in CosmosDB

(implement vector search with Azure Cosmos DB for NoSQL)

Store and retrieve embeddings
Vector semantic search
Combine vector similarity results with metadata filtering
Use change feed to trigger embedding refresh

(optimize queries for Azure Cosmos DB for NoSQL)

Understand Indexes
Configure range and composite indexes
Tune vector indexes for embedding workloads
Reduce RU costs with strategic indexing
(TODO) Choose consistency levels for optimal performance


Azure Database for PostgreSQL

Azure Database for PostgreSQL es un servicio de BBDD relacionales administrado por Azure. Permite usar PostgreSQL sin gestionar la infra subyacente. Azure se encarga de backups, updates y escalado

PgBouncer es una herramienta con un pool de conexión que reduce el overhead de crear conexiones constantemente, manteniendo una pool de conexiones reusables a través de las cuales enruta a los clientes. Esto reduce el overhead para apps que usan short-lived connections. Usa otro puerto (6432)

pgvector es una extensión que añade vector data types y similarity search operators a PostgreSQL. Antes de poder usar embeddings, hay que activar pgvector en la BBDD

(build and query with Azure Database for PostgreSQL)

Azure Database for PostgreSQL
Connect to PostgreSQL
Create and manage schemas
Query data
Integrate SDKs and Apps

(implement vector search with Azure Database for PostgreSQL)

pgvector - store and query embeddings
Fast vector similarity search
Manage index lifecycle and embedding updates
Run vector similarity search for semantic retrieval
(TODO) Implement retrieval patterns for RAG pipelines

(optimize vector search in Azure Database for PostgreSQL)

Tune PostgreSQL for pgvector
Choose and configure vector indexes
Optimize data layout
(TODO) Connection Optimization


Azure Managed Redis

Azure Managed Redis (puerto 10.000) es un almacén de datos en memoria diseñado para ofrecer muy baja latencia y alto rendimiento. Su uso más habitual es como caché de datos entre la app y su almacenamiento principal, aunque también se puede usar para comunicar micros en tiempo real (pub/sub y Streams), o también se puede usar como BBDD vectorial en memoria

Azure Cache for Redis (sistema viejo; puerto 6380) servicio administrado clásico de Redis en Azure, usado principalmente como caché distribuida, almacenamiento de sesiones o mensajería Pub/Sub. Está siendo desfasado por Azure Manage Redis

Redis pub/sub está diseñado para hacer broadcasting de eventos a múltiples consumidores de manera simultánea. Permite a los publishers hacer broadcast de mensajes a través de channels y a los subscribers subscribirse a estos channels para recibir mensajes. Cuando subscribes multiples servicios al mismo pub/sub channel, cada subscriber recibe cada mensaje - los mensajes se duplican. No hay garantías de entrega, puede que el mensaje llegue a todos los consumidores o puede que no llegue a ninguno

Redis Streams está diseñado para coordinar múltiples subscribers a través de consumer groups. Estos groups aseguran que cada mensaje se entregue automáticamente a un único subscriber, lo que permite un escalado horizontal sin cambiar el código. Están preparados para manejar fallos y retries

(data operations)

Azure Managed Redis
Implement data ops

(event messaging)

Redis pub/sub
Task queues (Redis Streams)
Broadcast (pub/sub) vs Coordinated distribution (Redis Streams)

(vector storage)

Index and query vector data
Choose vector types and indexing strategies
Optimize data structures for vector storage


Azure Service Bus

Azure Service Bus es un servicio de mensajería async administrado por Azure. Está diseñado para comunicar apps y micros de forma desacoplada y fiable. Se basa en queues (punto a punto) y/o topics + subscriptions (pub/sub)

(queue and process AI operations)

Azure Service Bus
Queues vs topics & subscriptions
Structure messages
Process messages reliably


Azure Event Grid

Azure Event Grid es un servicio fully managed que conecta productores y consumidores de eventos, de forma desacoplada. Event Grid está preparado para manejar millones de eventos / s con una latencia mínima (<1s)

Opera como un servicio pub-sub que enruta eventos de productores a consumidores sin tener que administrar nosotros la infraestructura. El servicio ingesta eventos de otros servicios Azure, custom apps y/o partner systems y o bien entrega esos eventos a los endpoints de los consumidores, basándose en subscription filters, o son los mismos consumidores los que hacen pull de los eventos para leer a su ritmo.

(develop event-driven AI workflows)

Azure Event Grid
Event schemas and properties
Configure delivery and retry policies
Publish custom events


Azure Functions

Azure Functions es un servicio serverless para ejecutar código bajo demanda sin tener que administrar servidores. Pueden escalar de manera automática según la carga y soportan diferentes tipos de triggers y bindings

Están pensadas para ejecutar tareas ligeras, independientes y que no mantengan estado entre ejecuciones

Azure Functions Set up local dev environment
Create triggers and bindings
Manage secrets and configurations
Configurar identity y access


Azure Durable Functions

Azure Durable Functions es una extensión de Azure Functions diseñada para procesos serverless, con estado y de larga duración.

Están pensadas para ejecutar procesos de varios pasos, cadenas o esperas largas o procesos que requieren de intervención humana

Graban cada operación y permiten hacer un replay para reconstruir el estado local que teníamos. Permiten que un workflow sobreviva a reinicios del host

Azure Durable Functions
Process independent work with fan-out/fan-in
Coordinate human approval with external events
Design reliable workflow steps


Azure Web PubSub

Azure Web PubSub es un servicio completamente administrado para comunicación en tiempo real. Sus casos de uso típicos son chats y notificaciones en tiempo real, juegos multijugador y streaming de tokens de IA/LLMs hacia el frontal. Se usa cuando el server necesita enviar información al cliente sin esperar a que este haga otra petición HTTP

// TODO: Lo dejo para más adelante. La doc oficial es muy MUY densa y es demasiado para mi ahora mismo. Está en Integrate backend services for AI Solutions > último módulo

Azure Web PubSub


Azure Key Vault

Azure Key Vault es un servicio administrado para centralizar, almacenar y proteger secretos, contraseñas, claves criptográficas y certificados, evitando hardcodearlos en código, repos o archivos de config

Permite que las apps de Azure accedan de forma controlada a estos valores mediante Entra ID y Managed Identities (RBAC)

Store and organize secrets, keys and certificates
Retrieve secrets using Azure SDK client libraries
Handle secret versioning and rotation
Implement caching strategies


Azure App Configuration

Azure App Configuration es un servicio administrado, que almacena app settings en pares clave-valor, de forma centralizada en el cloud. Permite modificar configuración dinámicamente y gestionar feature flags, hacer despliegues progresivos o experimentar sin tener que desplegar la app de nuevo

Nos evita tener que repartir params y settings entre múltiples servicios, archivos o despliegues

Azure App Configuration
Organize settings with labels and feature flags
Reference Key Vault secrets
App Configuration vs Key Vault (what to store)


OpenTelemetry

OpenTelemetry es un framework de observabilidad vendor-neutral, open-source. Provee de un set unificado de APIs, SDKs, herramientas para generar, recolectar y exportar telemetría

OpenTelemetry
Add OpenTelemetry SDK
Configure spans and traces
Export telemetry to Azure Monitor
Debug distributed flows with trace data


Azure Monitor

Azure Monitor es la plataforma central de observabilidad y monitorización central de Azure. Está diseñada para recopilar, analizar y visualizar métricas, logs y telemetría de apps e infra.

Permite conocer el estado y rendimiento de recursos, consultar logs, crear dashboards y alertas y detectar problemas antes de que afecten al usuario

Kusto Query Language (KQL) es la primary tool que se usa para hacer retrieve y analizar log data almacenada en Azure Monitor, Log Analytics, y Azure Data Explorer

Kusto Query Language (KQL)
Explore logs
Build Dashboards for App telemetry Set alerts for app failures and anomalies


Azure Insights

// TODO: add desc


Official Labs

Official labs (in python)

Read More

Explore logs (KQL)

Investigate application errors with KQL

El primer paso de una investigación debería ser entender el scope del problema: cuantos errores hay, cuando comenzaron y que tipos hay involucrados.

usamos sum() para producir accurate results cuando el sampling de Application Insights está activo

exceptions
| where timestamp > ago(24h)
| summarize exceptionCount = sum(itemCount) by bin(timestamp, 1h), type
| render timechart

Una vez encontramos el error podemos ir a más detalle para encontrar los most common exception types

agrupawr excepciones por exception type y operation name, produciendo una ranked list de las operaciones que generan más errores

exceptions
| where timestamp > ago(24h)
| summarize exceptionCount = sum(itemCount) by type, operation_Name
| top 10 by exceptionCount desc

Correlate failures across services

En una arquitectura multi servicio, una request puede viajar por muchos servicios diferentes, y un fallo en uno de ellos puede seguir la cadena y resultar en fallos en otros servicios.

Con el operation_id linkeamos todos los telemetry items de una single request distribuida. Haciendo un join a través de este operation_id podemos ver la secuencia completa de eventos que llevan a ese fallo

exceptions
| where timestamp > ago(24h)
| join kind=inner (
    requests
    | project requestName = name, requestDuration = duration, operation_Id, requestRoleName = cloud_RoleName
) on operation_Id
| project timestamp, exceptionType = type, exceptionMessage = outerMessage,
    requestName, requestDuration, cloud_RoleName = requestRoleName
| top 20 by timestamp desc
  • La columna cloud_RoleName identifica que servicio ha generado la excepción
  • La columna requestDuration revela donde ha ido lenta la request

Analyze dependency latency and failures

La tabla dependencies captura cada outgoing call como llamadas a BBDD, HTTP APIs, Azure services y otros.

Es la primera tabla que tenemos que mirar para buscar un bottleneck cuando algo es lento.

dependencies
| where timestamp > ago(24h)
| summarize avg(duration), percentiles(duration, 50, 95, 99) by target, type
| order by percentile_duration_95 desc

Percentile calculations dan un overview mas preciso que tener en cuenta solo los avg. Para ello usamos los percentiles 95th y 99th.

identificar dependencias fallidas

dependencies
| where timestamp > ago(24h)
| where success == false
| summarize failureCount = count() by target, resultCode, cloud_RoleName
| order by failureCount desc

Failure and performance views

Application Insights ofrece vistas que complementan a KQL.

La Failures view agrupa operaciones fallidas por tipo y hace display de los tipos fallidos más comunes

La performance view muestra todas las operaciones con su response time y distribuciones y request counts.

Read More

Build Dashboards for App telemetry (KQL)

Dashboards vs Workbooks

IMPORTANTE

Los dashboards difieren de los workbooks en su diseño e interaccion. Las dashboards están optimizadas para ser visuales, con tiles que se refrescan y muestran los datos automaticamente. El layout es relativamente estatico. Pones las tiles una vez y el dashboard se muestra sin intervencion humana.

Los workbooks están diseñados para una exploracion interactiva donde ajustas params para ver datos dinámicos.

Elegimos dashboards para ongoing operational monitoring y workbooks para investigación de incidentes y ad-hoc analysis.

IMPORTANTE

Azure dashboards for monitoring

Azure dashboards son una surface visual customizable en el azure portal que combina multiples recursos en una unica view.

En ellos podemos ver metrics chart, log query results, Markdown text blob o recursos de la galeria. Los equipos usan estas dashboards para tener un awareness operacional en el day-to-day monitoring para confirmar pipeline health.

Pin metrics to dashboards

Common metrics:

  • server response time (avg y percentiles)
  • failed requests
  • dependency failures (llamadas fallidas a BBDD, APIs, etc)
  • server request rate
  • availability

Pin log query results to a dashboard

Los charts de metricas están limitados a unas en especifico. Si queremos valores custom podemos hacer joins entre tablas y hacer pin de una SQL query para mostrar sus resultados en una dashboard.

ver que servicios contribuyen a los most failures

requests
| where timestamp > ago(24h)
| where success == false
| summarize failedCount = count() by cloud_RoleName
| render barchart

representar tres lineas con los percentiles

requests
| where timestamp > ago(24h)
| summarize p50 = percentile(duration, 50),
    p95 = percentile(duration, 95),
    p99 = percentile(duration, 99)
    by bin(timestamp, 1h)
| render timechart

Organize and share dashboards

Las dashboards se pueden compartir con team members. Publicarlas las hace disponibles para otros usuarios en tu organizacion mediante RBAC

Best practices

  • Separate concerns into different dashboards
  • Limit tile count
  • Use descriptive tile titles
  • Include markdown tile for context

Workbooks for interactive analysis

IMPORTANTE

Azure Monitor Workbooks son una herramienta interactiva de analisis que combinan rich text, KQL, metricas y parametros en reusable reports.

Los workbooks van más alla de dashboards y soportan user interaction: seleccionar un param value, elegir un time range. Esta interactividad hace que los workbooks sean la eleccion natural para troubleshooting, root cause analysis y cualquier escenario donde el investigador necesite ajustar el scope del analisis.

/IMPORTANTE

El Azure Portal incluye una galeria de prebuilt workbook templates organizadas por categoria para usar como starting points y customizar para tu caso.

Add query steps and visualizations

Los workbooks se construyen añadiendo steps verticalmente, donde cada step renferiza un componente del reporte final. Se cuenta como steps, text bloccks para explicaciones e instrucciones, query steps que ejecutan KQL y muestran resultado, metric steps que muestran metricas de recursos de Azure.

Ejemplo de query que funciona como un step de workbook

requests
| where timestamp > ago({TimeRange})
| summarize totalRequests = count(),
    failedRequests = countif(success == false)
    by cloud_RoleName
| extend successRate = round(100.0 * (totalRequests - failedRequests) / totalRequests, 2)
| project cloud_RoleName, totalRequests, failedRequests, successRate

La sintaxis {TimeRange} referencia un param del workbook.

Use params for interactive filtering

Como hemos visto en el paso anterior podemos hacer los workbooks interactivos, donde cada param aparece como control en el top del workbook.

Los params más comunes son:

  • time range
  • dropdown params (para filtrar por service name, environment, etc)
  • resource pìcker para elegir que Application Insight resource analizamos

Configure conditional visibility and linked content

Conditional visibility y grid link actions añaden depth a los workbooks. En vez de enseñar cada detalle upfront de a una, se pueden diseñar los workbooks para que comiencen con un resumen a alto nivel y revelen detalles solo cuando se seleccione un item especifico.

Esto se hace que se muestre o se esconda basándose en un param value que configuramos.

Grid link actions crean tablas interactivas donde al seleccionar una row hace trigger de downstream actions. Cuando configuramos una grid column como un link, hacer click en esa celda de esa column para abrir detalles end-to-end de transacciones para una request especifica, navegar a otro workbook para un analisis mas a fondo o ejecutar otras acciones.

Read More

Set alerts for app failures and anomalies (KQL)

Los dashboards y workbooks dan visibilidad en la salud de la app, pero requieren que haya alguien mirando. La alertas avisan proactivamente a tu equipo de que algo está mal y hay que arreglarlo.

Alert rule structure

Cada Azure Monitor alert rule consiste de 4 coponentes que funcionan juntos para detectar problemas y hacer trigger de respuestas.

  • Scope: recursos que se monitorizan
  • Condition: limite que determina cuando se hace trigger de la alerta
  • Action group: colección de notificaciones o automated actions que se ejecutan cuando se dispara la alerta
  • Severity: 0 (critical), 1 (Error), 2 (Warning), 3 (Informational), 4 (verbose)

Tenemos dos tipos primarios de alertas para telemetria:

  • Metric alerts: evaluan metricas de recursos en intervalos regulares. Se utilizan, por ej. para avisar cuando la CPU excede de un 80% de uso
  • Log search alerts: proveen mas flexibilidad. Se puede definir cualquier KQL query como detection logic, incluyendo joins entre tablas.

Use smart detection for anomaly identification

Azure Monitor tiene smart detection con ML que identifica patrones unusuales en tu app sin necesitar de configuración.

  • Failure anomaly: monitoriza el ratio de requests fallidas y lo compara con valores historicos
  • Performance anomaly: identifica degradacion de tiempo de respuesta, slowdowns con las dependencias o excepciones no normales

Lo mejor es usar el modo smart junto a tus reglas configuradas manualmente.

Read More

OpenTelemetry

Observability for distributed Apps

La observabilidad es la capacidad de entender el estado interno del sistema que estamos examinando, a través de examinar sus outputs externos

Cuando tienes microservicios que se interconectan, la observabilidad es esencial para poder identificar issues como latencia, request fallidas o performance degradada.

Se basa en tres pilares que se complementan entre ellos.

  • Metrics: medidas numericas agregadas a lo largo del tiempo (request counts, error rates). Te dicen que hay algo que ha cambiado.
  • Distributed tracing: Capturar el full path de una request a medida que se va moviendo por diferentes servicios. Te dicen donde ocurre el problema.
  • Logs: detallados con un timestamp. Te dan los detalles de por qué ha cambiado.

OpenTelemetry como standard

OpenTelemetry es un framework de observabilidad vendor-neutral, open-source. Provee de un set unificado de APIs, SDKs, herramientas para generar, recolectar y exportar telemetría.

  • APIs: define la interfazs para crear y administrar datos de telemetria
  • SDKs: implementan las APIs y ofrecen config options para procesar y exportar telemertia
  • Instrumentation libraries: Capturan automaticamente telemetria de frameworks y libraries. Ejemplo: Una HTTP instrumentation library que captura incoming y outgoing HTTP request details de manera automatica
  • Exportes: Serializan y transmiten la telemetria recogida a backend analysis tools.

Al ser vendor-netrual puedes enviar la misma telemetry data a Azure Monitor, Proemetheus, Grafana…

Understand traces, spans, and context propagation

Una traza representa un registro del viaje de una request a través de un sistema distribuido. Cada traza consiste en una o más operaciones individuales. Todas las operaciones juntas forman la secuencia completa para gestionar una request.

Un span es una named, timed operation dentro de una traza. Cada span captura información sobre una unidad específica de trabajo como una HTTP request, database query o llamada a una API externa. Cad span contiene:

  • trace ID
  • span ID
  • parent span ID: span ID de la parent operation que ha iniciado este span (los span root no tienen parents)
  • name
  • start and end timestamp
  • attributes: pares clave-valor
  • status: succeded/failed

La jerarquía de spans define la estructura de una traza. El root span representa el entry point al sistema (ej: una incoming HTTP request a una API gateway). Child spans representan downstream operations triggered por esa root request.

Cuando la API gateway, siguien el ejemplo, llama a un embedding service, esa llamada crea un child span. Si ese embedding service llama al vector search service, se crea orto child span bajo el embedding span. Estas relaciones forman un tree que representa visualmente todo el trabajo realizado originado desde la request original.

Context propagation es el mecanismo que carries trace y span IDs across service boudnaries. Sin context propagation, cada serviico crearia trazas sin ninguna manera de correlacionarlas.
OpenTelemetry usa el W3C TraceContext standard para progragar contexto a través de HTTP headers. Cuando un servicio llama a otro incluye un header traceparent que contiene el traceID del span que lo llama

Read More

Add OpenTelemetry SDK

Choose instrumentation approach

Azure Monitor soporta 2 primary instromentation approaches

Autoinstrumentation

Permite telemetry collection a través de config sin tener que modificar app code.

Funciona muy bien para los entornos soportados como Azure Functions o Azure Virtual Machines, pero ofrece control limitado sobre la telemetria que se recolecta, o sobre como se enriquece de datos.

Manual instrumentation

Meter el SDK en tu app code. Este approach te da full control sobre la recoleccion de telemetria, pero puede ser demasiado para situaciones simples.

Install Azure Monitor OpenTelemetry Distro

El Azure Monitor OpenTelemetry Distro es el approach recomendado para SDKs. Es una distribucion de OpenTelemetry que hace bundle del OpenTelemetry SDK con Azure Monitor exporters y librerias, en un único package.

Se distribuye como un único pip package que incluye todo

pip install azure-monitor-opentelemetry

Lo invocamos con configure_azure_monitor() en el startup. Esta llamada inicializa el tracer provider, el meter provider, el logger provider y los configura todos para exportar en Application Insights.

# Code fragment - focus on minimal OpenTelemetry setup with Azure Monitor
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

Understand automatic data collection

El Azure Monitor OpenTelemetry Distro automaticamente recoge telemetria de common frameworks y libraries sin tener que escribir codigo.

Esta recoleccion automatica incluye

  • requests library outgoing HTTP calls
  • urllib outgoing HTTP calls
  • Flask / Django / FastAPI: incoming HTTP requests
  • psycoph2: PostgreSQL database queries
  • Azure SDK: llamadas hechas a Azure a través del SDK
  • logging

Configure the connection string

Environment var

Usar la environment var APPLICATIONINSIGHTS_CONNECTION_STRING. Esto mantiene la config fuera del codigo

export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://eastus-0.in.applicationinsights.azure.com/"

Code-based conf

Pasar la connection string directamente a configure_azure_monitor()

# Code fragment - focus on code-based connection string configuration
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://eastus-0.in.applicationinsights.azure.com/"
)

Set the cloud role name

Cuando multiples servicios mandan telemetria al mismo Application Insights, cada servicio necesita un cloud role name distinto para aparecer como un nodo separado en el Application Map. Si no lo ponemos, todos los servicios aparecen como un single node.

El cloud role name deriva de service.name y service.namespace OpenTelemetry resource attributes. Juntos combinados forma el cloud role name.

como configurarlo

# Code fragment - focus on setting cloud role name via resource attributes
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.sdk.resources import Resource

configure_azure_monitor(
    resource=Resource.create({
        "service.name": "embedding-service",
        "service.namespace": "rag-pipeline",
        "service.instance.id": "embedding-instance-1",
    })
)

Read More

Export telemetry to Azure Monitor (OpenTelemetry)

Understand telemetry export to Application Insights

La pipe de export de telemetria mueve tus datos desde tu app a Application Insights siguiendo una serie de pasos.

El OpenTelemetry SDK recoge telemetria de instrumentation libraries y custom spans. El Azure Monitor exporter serializa los datos que envia al Application Insights ingestion endpoint identificado por tu connection string. Este proceso ocurre entero dentro de los limites de tu app.

La Azure Monitor OpenTelemetry Distro usa direct export by default. Esto significa que la app envia la telemetria directamente al ingestion endpoint del Application Insights, sin un intermediario.
Este approach simplifica el deployment ya que no hay infraestructura adicional.
La alternativa es usar OpenTelemetry Collector, un proceso separado que recibe telemetria de apps, la procesa y la reenvia a uno o más backends. El Collector añade complejidad operacional pero ofrece más capacidades como sampling centralizado, data transformation y multi-backend routing.

Cuando la telemetría llega a Application Insights, se mapea en diferentes tablas:

  • Server spans (SpanKind.SERVER y SpanKind.CONSUMER) aparecen en la tabla requests
  • Client, internal, producer spans (SpanKind.CLIENT, SpanKind.INTERNAL, SpanKind.PRODUCER) aparecen en la tabla dependencies
  • Log records emitidos a través de python’s logging module u OpenTelemetry logging API aparecen en la tabla traces
  • Exceptions aparecen en la tabla exceptions
  • Custom metrics aparecen en la tabla customMetrics

Configure sampling to control telemetry volume

Sampling reduce el volumen de telemetria que se envia a Application Insights, recogiendo solo un porcentaje de las trazas. Esto es esencial para apps con un gran volumen de requests y controlar los costes de ingestion.

Estrategias de sampling para traces:

  • Fixed-percentage sampling: Recoge una fixed fraction de todas las trazas. Especificas un ratio entre 0.0 y 1.0 donde 0.1 significa el 10% de las trazas
  • Rage-limited sampling: Pone un cap al number de trazas recolectadas por segundo. Especificas 1.5 donde es aprox. una traza y media cada segundo

Podemos configurar fixed-percentage sampling en codigo usando sampling_ratio param, o rate-limited sampling usando traces_per_second

# Code fragment - focus on configuring sampling via configure_azure_monitor()
from azure.monitor.opentelemetry import configure_azure_monitor

# Fixed-percentage sampling: sample approximately 10% of traces
configure_azure_monitor(
    sampling_ratio=0.1,
)

# Rate-limited sampling: sample approximately 1.5 traces per second
# configure_azure_monitor(
#     traces_per_second=1.5,
# )

Enable offline storage and automatic retries

El Azuer Monitor exporter cachea la telemetria de manera local cuando la app pierde conexion y lo reintenta durante 48 horas.

Se puede hacer override del default storage directory si necesitas la cache en un directorio especifico

# Code fragment - focus on configuring offline storage directory
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    storage_directory="/var/telemetry/rag-pipeline",
)

Verify telemetry data flow

Tras el initial setup es importante verificar que la telemetria esta llegando al Application Insights. Los datos pueden no aparecer inmediatamente ya que se hacen en batches.

Para real-time verification durante development, tenemos Live Metricos que ofrece un dashboard para hacer displays con un delay minimo.

Podemos ejecutar KQL queries en Application Insights Logs para verificar que los trace data están disponibles

devuelve las 20 requests mas recientes de la ultima hora, mostrando operation name, duration, success status y cloud role name del servicio

requests
| where timestamp > ago(1h)
| project timestamp, name, duration, success, cloud_RoleName
| order by timestamp desc
| take 20

Read More

Debug distributed flows with trace data (OpenTelemetry)

Recoger y exportar telemetría solo es util si puedes usar esos datos para encontrar y arreglar problemas

El Application Map provee de una topología visual de todos tus servicios dentro de tu aplicación distribuida, mostrando la manera en que se conectan y donde hay fallos o problemas de latencia.

Cada nodo de un mapa representa un cloud role, identificado por el resource attribute service.name configurado durante el setup.

Los limites entre nodos representan llamadas de un servicio a otro.

El Application Map muestra key metrics en cada nodo y edge, incluyendo avg response time, request count o failure rate.

Puedes usar este mapa para reducir rápidamente el área de tu investigación.

Use end-to-end transaction details

La transaction view end-to-end muestra un waterfall chart de todos los spans en una single trace, mostrando timing, duration y dependencias de cada operación.

Esta view es la primary tool para entender que pasa durante una specific request e identificar donde se ocupa el tiempo.

El waterfall chart muestra el root span en el top, representando el entry point de la request. Child spans se muestran bajo sus parent spans.

Write KQL queries to analyze trace data

El application insights almacena telemtria en las tablas de Log Analytics, a las que podemos hacer queries usando Kusto Query Language (KQL).

Las trazas se almacenan en 4 tablas primarias

  • tabla requests contiene server spans y consumer spans
  • tabla dependencies contiene client, internal y producer spans
  • tabla traces contiene log records
  • tabla exceptions contiene excepciones grabadas

Todas las tablas comparten una columna operation_id, la cual corresponden con el OpenTelemetry trace ID para poder correlacionar items que pertenecen a la misma traza distribuida

find slow requests and summarize by service

requests
| where duration > 3000
| summarize count(), avg(duration) by cloud_RoleName
| order by avg_duration desc

You can join request with their dependencies

this query connects each slow request with its downstream dependency calls

requests
| where duration > 5000
| join kind=inner (dependencies) on operation_Id
| project timestamp, requestName = name, requestDuration = duration,
    dependencyName = name1, dependencyDuration = duration1,
    dependencyTarget = target
| order by requestDuration desc

You can query custom attributes stored in customDimensions

analyzes embedding generation performance by model, showing avg and 95th-percentile durations alongside avg token counts

dependencies
| where name == "GenerateEmbedding"
| extend tokenCount = toint(customDimensions["embedding.token_count"]),
    model = tostring(customDimensions["embedding.model"])
| summarize avg(duration), percentile(duration, 95),
    avg(tokenCount) by model
| order by avg_duration desc

Read More

Configure spans and traces (OpenTelemetry)

Create custom spans with a tracer

Custom spans te permiten representar business-specific operations en tu trace data. En una RAG pipe pueden ser operaciones como generate embedding, search vector index o assemble prompt.
Estos spans aparecen en Application Insights como end-to-end transactions junto a todos los spans recogidos automaticamente.

En python usamos opentelemetry.trace como entry point para crear spans. Se llama trace.get_tracer("name") para obtener un tracer para tu servicio o componente.

create a tracer and start a custom span

# Code fragment - focus on creating a custom tracer and span
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

configure_azure_monitor()

# Equivalent to creating an instrumentation source — use once per service/component
tracer = trace.get_tracer("embedding-service")

# start_as_current_span is a context manager — the span ends automatically when the block exits
with tracer.start_as_current_span("GenerateEmbedding") as span:
    span.set_attribute("embedding.model", "text-embedding-ada-002")
    span.set_attribute("embedding.token_count", token_count)
    # Embedding generation logic
    embedding = generate_embedding(input_text)

Add attributes to spans

Span attributes enriquecen tus trace data con información contextual que ayuda a filtrar, buscar y analizar trazas.

Resources attributes - describen el servicio en si mismo y aplican a toda la telemetria de ese servicio. Configuras los atributos una unica vez durante el startup.
Span attributes - describen una operacion especifica y aplican solo al span individual. Configuras span attributes dentro del scope de un span activo para capturar detalles particulares de esa operacion.

# Code fragment - focus on adding meaningful attributes to a span
with tracer.start_as_current_span("SearchVectorIndex") as span:
    span.set_attribute("search.index_name", "product-docs")
    span.set_attribute("search.query_vector_dimension", 1536)
    span.set_attribute("search.top_k", 10)
    results = search_index(embedding)
    span.set_attribute("search.result_count", len(results))
    span.set_attribute("search.similarity_threshold", 0.78)

Cuando exportamos estos atributos a Application Insights, aparecen dentro de la columna customDimensions.

Control span kinds and status

El span kind indica el tipo de operacion que representa un span. Application Insights usa estos valores para clasificar spans como requests o dependencias.

Tipos de spans

  • SpanKind.SERVER incoming request gerstionada por el servicio
  • SpanKind.CLIENT outgoing call a un servicio o recurso externo
  • SpanKind.INTERNAL operacion interna dentro del servicio que no cruza process boundaries
  • SpanKind.PRODUCER iniciar una async op (enviar un mensaje a una queue)
  • SpanKind.CONSUMER consume una async op (recibir un mensaje de una queue)
# Code fragment - focus on setting span kind for an outgoing LLM API call
from opentelemetry.trace import SpanKind

with tracer.start_as_current_span("CallLlmApi", kind=SpanKind.CLIENT) as span:
    span.set_attribute("llm.provider", "azure-openai")
    span.set_attribute("llm.model", "gpt-4o")
    # LLM API call logic
    response = call_llm(prompt)
    span.set_attribute("llm.response_tokens", response.usage.completion_tokens)
# Code fragment - focus on recording errors and exceptions on a span
from opentelemetry.trace import Status, StatusCode

with tracer.start_as_current_span("GenerateEmbedding") as span:
    try:
        embedding = generate_embedding(input_text)
        span.set_status(Status(StatusCode.OK))
    except Exception as ex:
        span.record_exception(ex)
        span.set_status(Status(StatusCode.ERROR, "Embedding generation failed"))
        raise

Model nested operations in a trace

Nested spans crean una jerarquia parent-child que representa el flow logico de una request a traves de tu app.

En python se nestea poniendo start_as_current_span uno dentro de otro. Cuando un span comienza mientras otro span está activo, OpenTelemetry marca el activo como padre del nuevo.

nested spans model a simplified RAG pipe request flow

# Code fragment - focus on nested spans modeling a RAG pipeline request flow
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.trace import SpanKind

configure_azure_monitor()
tracer = trace.get_tracer("llm-orchestrator")

def process_query(query: str) -> str:
    with tracer.start_as_current_span("ProcessQuery", kind=SpanKind.SERVER) as root_span:
        root_span.set_attribute("query.length", len(query))

        # Child span: Generate embedding
        with tracer.start_as_current_span("GenerateEmbedding") as embed_span:
            embed_span.set_attribute("embedding.model", "text-embedding-ada-002")
            embedding = embedding_service.generate(query)
            embed_span.set_attribute("embedding.dimensions", len(embedding))

        # Child span: Search vector index
        with tracer.start_as_current_span("SearchVectorIndex") as search_span:
            search_span.set_attribute("search.top_k", 5)
            results = vector_search.search(embedding, top_k=5)
            search_span.set_attribute("search.result_count", len(results))

        # Child span: Call LLM
        with tracer.start_as_current_span("CallLlm", kind=SpanKind.CLIENT) as llm_span:
            prompt = build_prompt(query, results)
            llm_span.set_attribute("llm.prompt_tokens", count_tokens(prompt))
            response = llm_client.get_completion(prompt)
            llm_span.set_attribute("llm.response_tokens", response.usage.completion_tokens)
            return response.content

Cuando ves esto a través de Application Insights end-to-end transaction view, lo ves como un waterfall chart.
ProcessQUery aparece como el root span, con GenerateEmbedding, SearchVectorIndex y CallLLM como child spans nesteados.

Read More

Kusto Query Language (KQL)

KQL and Azure Monitor Logs

Kusto Query Language (KQL) es la primary tool que se usa para hacer retrieve y analizar log data almacenada en Azure Monitor, Log Analytics, y Azure Data Explorer. Sigue un modelo de pipe separdo por el caracter |.

Query scoping determina que tablas y nombres de columnas usamos en las queries.
Cuando abres logs desde un recurso de Application Insights, el query scope hace target de recursos usando Application Insigts table names como requests, exceptions y dependencies. Cuando se abre desde un workspace de Log Analytics usa table names como AppRequests, AppExceptions y AppDependencies.

Explore Application Insights table structure

Tablas más relevantes

  • requests almacena incoming HTTP requests con detalles como duration, response code y success status. Cada row representa una requesta
  • dependencies captura outbound calls desde tu app a BBDD, HTTP endpoints, Azure services y otros micros
  • exceptions ambas handled y unhandled
  • traces app log messages de frameworks como ILogger, log4j
  • customEvents almacena custom business events como document classified
  • customMetrics almacena custom numeric measurements como queue depth o model inference confidence score
  • performanceCounters almacena system-level metrics como CPU usage

Hay columnas que son comunes a todas las tablas:

  • timestamp
  • operation_Id linkea los items de una single distributed trace para poder seguir las requests a través de los servicios
  • cloud_RoleName identifica que servicio genera la telemetría
  • customDimension contiene una bag de propiedades dinamicas para enriquecer la telemetria con tus propios datos

Filter and select data with core operators

KQL tiene todos los filtros comunes como where, ==, etc.

Distintos tenemos:

  • project operator - selecciona columnas especificas a incluir en el output. Reduce la width de tus resultados y centra la atencion en los datos que interesan
  • take operator - devuelve un ser arbitrario de n rows de la tabla. Es util para inspeccionar el estado y calidad de los datos con un muestreo
  • top operators - devuelve las primeras n rows, sorteadas por una columna especifica
requests
| where timestamp > ago(1h)
| where success == false
| project timestamp, name, resultCode, duration, cloud_RoleName
| top 20 by duration desc

Aggregate and summarize data

El filtering visto antes muestra records individuales. Para entender trends y patrones necesitamos aggregation.

El operator summarize agrupa rows y aplica funciones de agregacion para producir summary statistics. Cada combinacion unica de valores en el by produce un output row en los results.

Los operadores comunes que funcionan con summarize son avg(), sum(), etc. Los distintos son:

  • dcount() function - estima el count de distinct values. Util para cosas como how many unique users experienced this error
  • count_distinct() - para small datasets. es mas preciso pero mas intensivo de recursos
  • percentile() function - calcula un specific percentile value. util para obtener por ejemplo latency analisys del p95
  • bin() function - agrupa valores continuos como timestamps en intervalos fijos. Ejemplo bin(timestamp, 1h) redondea cada timestamp a la hora más cercana
requests
| where timestamp > ago(24h)
| summarize requestCount = count(), avgDuration = avg(duration)
    by bin(timestamp, 1h), cloud_RoleName

Visualizar query results with the render operator

El render operator sirve para especificar chart types en la query. Añadir render como final step le dice que saque los resultados como un chart en vez de una tabla. Util para visualizar trends y comparaciones.

requests
| where timestamp > ago(24h)
| summarize requestCount = count() by bin(timestamp, 1h), cloud_RoleName
| render timechart

Read More

App Configuration vs Key Vault (what to store)

App Configuration y Key Vault sirven roles complementarios en administrar settings para apps.

Azure App Configuration

Está diseñado para app settings, en pares clave-valor, y que sean no sensibles.

Características

  • labels para diferenciar entornos
  • feature flag management
  • rollbacks
  • dynamic refresh

Esto incluye

  • endpoints
  • feature flags
  • batch sizes
  • rerty counts
  • timeout values
  • display strings

Azure Key Vault

Está diseñado para datos sensibles.

Características

  • Encripta los datos at rest con HSM-backed protection
  • loggea cada op y se puede auditar
  • fuerza expiration policies
  • automated rotation
  • provee soft-delete con purge protection

Esto incluye

  • API keys
  • connection strings
  • passwords
  • keys criptograficas
  • certificados

Ejemplos

Setting type Service Example
Configuracion nonsensitive App Configuration (direct value) OpenAI:Endpoint
Feature toggles App Configuration (feature flag) EnableBatchProcessing
API keys and tokens Key Vault (via App Configuration reference) OpenAI:ApiKey
Connection strings Key Vault (via App Configuration reference) CosmosDB:ConnectionString
Certificates Key Vault (direct access) TLS certificates for HTTPS

Anti-patterns

  • Storing secrets directly in App Configuration: always use Key Vault references for values that grant access to resources
  • Using Key Vault for non-sensitive settings
  • Duplicating settings across both services without references
  • Embedding all configuration in application code

Read More

Reference Key Vault secrets (App Configuration)

Understand Key Vault references

Una Key Vault reference es un par especial clave-valor en App Configuration, donde el valor contiene una URI que apunta a un secreto en Key Vault

El content type es especial application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8. El provider resuelve la referencia automáticamente, por lo que la app nunca llega a ver este valor. Solo ve una variable de entorno como cualquier otra.

No hay que escribir código custom, la app nunca ve diferencia o los entresijos por detrás

La App Configuration no almacena nunca el valor actual del secreto. Solo tiene el puntero donde reside en el Key Vault

Create Key Vault references

Podemos crear referencias desde el Azure Portal o con Azure CLI

az appconfig kv set-keyvault \
	--name myAppConfigStore \
	--key "OpenAI:ApiKey" \
	--secret-identifier "https://my-keyvault.vault.azure.net/secrets/openai-api-key" \
	--label "Production"

El --secret-identifier acepta la full URI y podemos incluir una versión https://my-keyvault.vault.azure.net/secrets/open-api-key/custom-version-1. Si omitimos la versión, por defecto se apunta a latest, y es lo recomendado.

También se pueden aplicar labels a las Key Vault references, por lo que podemos tener varias para separar entornos Production de por ej. Development

Configure python provider for Key Vault resolution

La library azure-appconfiguration-provider resuelve Key Vault references de manera automatica cuando le das una credencial a través del param keyvault_credential. Si pasamos un DefaultAzureCredential que autentica a ambos App Configuration y Key Vault usando la misma managed identity.

# Code fragment - focus on resolving Key Vault references through the provider
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
import os

endpoint = os.environ.get("AZURE_APPCONFIG_ENDPOINT")
credential = DefaultAzureCredential()

config = load(
    endpoint=endpoint,
    credential=credential,
    keyvault_credential=credential
)

# Regular settings and resolved Key Vault secrets are accessed the same way
model_endpoint = config["OpenAI:Endpoint"]     # Regular value from App Configuration
api_key = config["OpenAI:ApiKey"]               # Resolved from Key Vault
batch_size = config["Pipeline:BatchSize"]       # Regular value from App Configuration

Set up authentication for both services

La app identity tiene que tener permisos para ambos App Configuration y Key Vault para que las Key Vault references se resuelvan correctamente

Cada servicio usa su propio set de Azure RBAC roles y la identidad necesita por lo menos un rol en cada servicio.

IMPORTANTE

Para App Configuration la identidad necesita el rol App Configuration Data Reader, para obtener settings y referencias.

Para Key Vault la identidad necesita el rol Key Vault Secrets User para leer el secret value al que apunta la referencia.

Si tenemos apps que acceden a secretos de multiples Key Vaults, la identidad necesita el rol Key Vault Secrets User en cada vault referenciada en la configuración

/IMPORTANTE

Understand refresh behavior for Key Vault references

El provider soporta refrescar Key Vault secret values de manera independiente a otros configuration settings, a través del param secret_refresh_interval. Mientras que la Key Vault reference URI en App Configuration se mantiene sin cambiar, el secreto por debajo en Key Vault puede rotar. Este param indica cada cuanto hay que refrescar el secreto.

# Code fragment - focus on configuring independent secret refresh
config = load(
    endpoint=endpoint,
    credential=credential,
    keyvault_credential=credential,
    refresh_on=[WatchKey("Sentinel")],
    refresh_interval=60,
    secret_refresh_interval=7200  # Re-resolve Key Vault secrets every 2 hours
)

Esta separación entre refresh y secret_refresh permite comprobar cambios de config normales, de manera frecuente, y re-resolver los secretos en un ciclo más largo que se alinee con tu periodo de rotacion.

Read More

Choose real-time client delivery approach (Azure Web PubSub)

TODO: WIP. Continuar con esto más adelante en una segunda pasada

Match response channel to the operation

Un response channel determina como el navegador recibe updates. Elegimos según la client experience que necesitamos. Usar el diseño más simple que nos sea suficiente.

direct HTTP streaming

El server escribe porciones de la respuesta antes de que el resultado entero esté disponible. El navegador lee la respuesta de manera incremental a través de una streaming API.

El output channel se queda unido a esa HTTP request. Un HTTP stream no es visible tan pronto como el backend escribe un chunk. Hay capas intermedias como app frameworks o compression layers que pueden hacer buffer de la respuesta.

Server-Sent Events (SSE) for one-way event stream

Server-Sent Events (SSE) añaden un event format a una long-lived HTTP response con el content type text/event-stream. A diferencia de un stream arbritrario, SSE define campos para event data, event names y event IDs.

SSE encaja en una AI app que necesita server-to-browser progress events pero no necesita client messages en el mismo channel.

SSE es un one-way a nivel app-message. Un user puede enviar un approval o cancellation a través de otra auth HTTP request.

Read More

Store and organize secrets, keys and certificates (Key Vault)

Azure Key Vault es un servicio administrado para centralizar, almacenar y proteger información sensible, especialmente secretos, contraseñas, claves criptográficas y certificados, evitando hardcodearlos en código, repos o archivos de config.

Permite que las apps de Azure accedan de forma controlada a estos valores mediante Entra ID y Managed Identities (RBAC)

Azure Key Vault tiene 3 core capabilities:

  • Secrets management
  • Key management
  • certificate management

En todos los casos los objetos se encriptan at rest y se controla el acceso con Entra ID y RBAC

Opera en 2 tiers:

  • Standard tier: encripta keys usando libraries validadas con FIPS 140 lvl 1. Es suficiente para apps donde software-protected keys es suficiente
  • Premium tier: encripta keys usando FIPS 140-3 lvl 3 y tiene el validacion Hardware Security Modules (HSM). Se usa para cuando tienes regulatory requirements o requerimientos de compliance para HSM-protected Keys

Choose the right object type for your credentials

Secrets

Almacena string values arbitrarios hasta 25 KB - se usa para API keys, connection strings, pwd y tokens

Key Vault trata los secretos como byte sequences opacas y no fuerza ningún tipo de estructura

# Code fragment - focus on setting a secret with content_type
client.set_secret(
    "openai-api-key",
    "sk-abc123def456",
    content_type="text/plain",
    tags={"environment": "production", "team": "ai-platform"}
)

Keys

Alacena keys criptográficas para encriptar y firmar.

Key Vault ejecuta operaciones criptograficas server-side para que el material nunca abandone el limite del vault.

Lo usan AI apps que encriptan o firman datos ya que tienes mas garantias de que estos nunca se exponen ni abandonan los boundaries, comaprado vs almacenarlos en local

Certificates

Alacenan certificados junto a sus claves privadas.

Key Vault se encarga del lifecycle de los certificados con la gestión de renovar, revocar, etc.

Cuando Key Vault almacena un certificado, crea una key correspondiente y un secreto al que puedes acceder

Organize vaults and objects for AI solutions

IMPORTANTE

Vault-per-app boundary: Puedes crear vaults separadas para cada app y environment combination. Así podemos tener kv-ragpipe-dev, kv-ragpipe-staging y kv-ragpipe-prod.

Esta separación limita el daño en caso de accidente de seguridad. Una vault comprometida solo afecta a los secretos de una aplicación para un environment.

Vault-per-app boundaries también simplifica RBAC assignment porque puedes dar acceso a un equipo para DEV sin exponer las credenciales de PROD

Naming conventions: Puedes usar nombres descriptivos con guiones para encodear el resource type y el propósito cosmosdb-connection-string, openai-api-key o blob-storage-account-key.

Las vaults deben tener nombres globalmente únicos dentro de Azure.

Tags for metadata: Puedes poner tags a secretos para filtrar y administrar. Cada secreto soporta hasta 15 tags. environment=prod, team=ai-platform, rotation-policy=90-days.

IMPORTANTE

Control access with RBAC

Key Vault soporta dos modos de auth: RBAC y legacy access policies.

RBAC es el approach recomendado por su granularidad de control a nivel de Azure resource level y soporte.

Key Vault ofrece distintos data plane roles para secret management:

  • Key Vault Secrets User: Da read-only access a secret values, incluyendo poder leer private keys de certificados, que están guardadas como secretos
  • Key Vault Secrets Officer: Full management permissions a secretos (CRUD). Se asigna a operators o CI/CD pipes responsables del lifecycle management
  • Key Vault Administrator: All data plane ops sobre keys, secretos y certificados. No da control sobre el management del vault resource en si mismo o para modificar roles
  • Key Vault Reader: Da read access al vault metadata (secret names y properties) sin revelar el contenido de los secretos o las keys. Es util para monitoring y discovery tools que necesitan verificar que secretos existen sin acceder a su contenido.

IMPORTANTE

Puedes usar managed identities para app-to-vault auth. Una managed identity elimina la necesidad de guardar cualquier credencial en tu app code o conf. La app autentica contra Key Vault usando Entra ID, y RBAC determina que operaciones puede ejecutar esa identidad.

De esta forma necesitas almacenar 0 credenciales para acceder al vault, el cual contiene todo el resto de credenciales.

El rol Key Vault Contributor es un rol del control plane solo. Da permiso para hacer management del vault resource (CRUD) pero no da acceso al data plane como leer secretos, keys o certs. Usar siempre los roles del data plane para acceso a secretos

/IMPORTANTE

Protect against accidental deletion with soft delete and purge protection

Key Vault permite soft delete by default y no se puede desactivar una vez se activa. (valor por defecto de retencion = 90 dias).

Purge protection es una feature opcional que previene permanent deletion de soft-deleted objects durante el retention period. Cuando se activa esta protección NADIE puede borrar de manera permanente un secreto hasta que el periodo de retencion termina.

Read More

Handle secret versioning and rotation (Key Vault)

Cada vez que guardas un secreto con el mismo nombre en Key Vault, el vault crea una nueva versión, en vez de sobreescribir la existente. Esto es fundamental para soportar credential rotation porque permite que las credenciales nuevas y viejas coexistan durante el período de transición.

Understand how Key Vault versions secrets

Cada llamada a set_secret() con el mismo secret name crea una nueva version y le asigna un GUID unico. Llamar a get_secret() sin version param siempre devuelve la ultima version. También puedes llamar a get_secret() con una version especifica. Las versiones previas se mantienen accesibles hasta que las borras o desactivas de manera explicita.

# Code fragment - focus on creating a new version and retrieving by version ID
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
client = SecretClient(
    vault_url="https://kv-ragpipeline-prod.vault.azure.net/",
    credential=credential
)

# Create initial version
initial = client.set_secret("cosmosdb-connection-string", "AccountEndpoint=https://...")
print(f"Version 1: {initial.properties.version}")

# Create new version with updated value
updated = client.set_secret("cosmosdb-connection-string", "AccountEndpoint=https://new...")
print(f"Version 2: {updated.properties.version}")

# Retrieve latest version (returns version 2)
latest = client.get_secret("cosmosdb-connection-string")

# Retrieve specific version (returns version 1)
specific = client.get_secret("cosmosdb-connection-string",
                              version=initial.properties.version)

Como por defecto get_secret() obtiene la ultima version, tu app no tiene que saber que version usa. De esta manera con guardar una nueva version, esta ya se propaga por la app.

Los IDs son utiles para auditorias.

List and inspect secret versions

El metodo list_properties_of_secret_versions() enumera todas las versiones de un secreto especifico. Cada version incluye ID, fechas y status. Se usa para auditar rotacion.

# Code fragment - focus on listing and inspecting secret versions
versions = client.list_properties_of_secret_versions("cosmosdb-connection-string")

for version in versions:
    print(f"Version: {version.version}")
    print(f"  Created: {version.created_on}")
    print(f"  Enabled: {version.enabled}")
    print(f"  Expires: {version.expires_on}")

Tras una rotacion podemos considerar desactivar versiones previas para forzar a que la app use la nueva version. Esto lo podemos hacer llamando a update_secret_properties() con enabled=False, lo cual previene que la versión se obtenga.

Choose rotation strategy

Manual rotation

Método más simple. Creamos una nueva version en Key Vault y reiniciamos la app.

Es util para cambios infrecuentes, pero hay una ventana entre que actualizamos el secreto y la app sigue usando el viejo.

Automated Rotation with Event Grid

Key Vault se integra con Azure Event Grid para emitir eventos cuando los secretos se aproximan a su expiration date.

El evento SecretNearExpiry se lanza 30 dias antes de que expire.
El evento SecretExpired se lanza cuando ya ha expirado.

Una Azure Function u otro handler se encarga de escuchar esos eventos, genera una nueva credencial, guarda el nuevo valor y la nueva version en el Key Vault.

Esto lo automatiza enteramente el lifecycle. Resumen:

  1. Key Vault emite SecretNearExpiry event
  2. Event Grid entrega el evento al handler registrado
  3. Una Azure Function recibe el evento
  4. La function genera una nueva credencial para el target service
  5. La function guarda la nueva credencial como una nueva secret verison en el key vault

Dual-credential rotation

Para servicios que soportan dos keys activas de manera simultanea, como Storage accounts y CosmosDB.

  1. Generamos una nueva key secundaria en el target service
  2. Guardamos la nueva key como una nueva secret version en el Key Vault
  3. Esperamos a que todas las aplicaciones pillen el nuevo valor
  4. Regeneramos la vieja primary key en el target service

De esta manera garantizamos que al menos hay una credencial valida que exista siempre.

Implement zero-downtime rotation in app code

Independientemente de la estrategia seleccionada, el codigo de la app debe encargarse de la transicion entre secreto viejo y nuevo.

El patron recomendado atrapa fallos de downstream services, hace refetch del secreto desde la Key Vault y reintenta la operacion con la nueva credencial. De esta manera evitamos restarts y soportamos rotacion.

# Code fragment - focus on retry-on-auth-failure pattern for rotation
from azure.core.exceptions import HttpResponseError

def call_downstream_service(client, secret_name, max_retries=1):
    """Retrieve secret and call service, refreshing on auth failure."""
    secret_value = client.get_secret(secret_name).value

    for attempt in range(max_retries + 1):
        try:
            # Use secret_value to authenticate with downstream service
            result = connect_to_service(secret_value)
            return result
        except AuthenticationError:
            if attempt < max_retries:
                # Credential might be rotated - refresh from Key Vault
                secret_value = client.get_secret(secret_name).value
            else:
                raise

Este patron limita la performance del impacto de rotacion cuando la primera auth falla.

Set expiration dates on secrets

IMPORTANTE

La property expires_on define la expiration date. Los secretos expirados todavia existen en el key vault y se pueden obtener a través de get_secret(). La expiracion es informativo, más que un hard limit. En si misma es para indicar que se deberia de cambiar.

/IMPORTANTE

Read More

Retrieve secrets using Azure SDK client libraries (Key Vault)

La python library azure-keyvault-secrets proviene la clase SecretClient para todas las operaciones de secretos contra Azure Key Vault. Combinado con azure-identity para auth, ambos paquetes cubren la necesidad de obtener credenciales en codigo.

Install the SDK

El Key Vault secrets SDK requiere de dos packages

  • azure-keyvault-secrets para vault ops
  • azure-identity para auth
pip install azure-keyvault-secrets azure-identity

La URL de la vault sigue el patron https://<vault-name>.vault.azure.net/

la url se puede obtener desde la web o asi

az keyvault show --name <vault-name> --query properties.vaultUri

Authenticate with DefaultAzureCredential

DefaultAzureCredential de la libreria azure-identity encadena multiples auth methods en un orden definido, provando cada uno hasta que uno funciona. Esta clase funciona para desarrollo local y PROD sin cambios de codigo.

En produccion, managed identity se autentica sin credenciales almacenadas. En local, lo hace a través de Azure CLI.

Orden que sigue:

  1. EnvironmentCredentials: Lee AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET environment vars
  2. WorkloadIdentityCredential: Auth usando K8s workload identity tokens
  3. ManagedIdentityCredential: Usa Azure managed identity (system-assigned o user-assigned) attached al computer resource
  4. AzureCliCredential: Auth usando az login
  5. AzureDeveloperCliCredential: Auth usando azd auth login
  6. AzurePowerShellCredential: Auth usando Connect-AzAccount

Para servicios que corren en Azure compute resources (Container Apps, K8s o App Service) se recomienda usar managed identity como auth method. La app hace auth a Key Vault a través de Entra ID.
La managed identity necesita el rol Key Vault Secrets User.

Retrieve a secret by name

El metodo get_secret() obtiene la version actual de un secreto de la Key Vault.
El object obtenido KeyVaultSecret contiene secret value, name y properties con metadatos como la version o fechas.

# Code fragment - focus on retrieving a secret with DefaultAzureCredential
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
client = SecretClient(
    vault_url="https://kv-ragpipeline-prod.vault.azure.net/",
    credential=credential
)

secret = client.get_secret("openai-api-key")

# Access the secret value and metadata
api_key = secret.value
version = secret.properties.version
created = secret.properties.created_on
content_type = secret.properties.content_type

El secret.value contiene la secret string que tu app pasa a downstream service clients. Los properties son metadata para logging o debugging.

List secret properties

El metodo list_properties_of_secrets() enumera todos los secretos del vault - SIN OBTENER SUS VALORES.
Esto devuelve SecretProperties que contiene metadata. Se usa para hacer discovery de los secretos disponibles.

# Code fragment - focus on listing secret properties for discovery
secret_properties = client.list_properties_of_secrets()

for prop in secret_properties:
    print(f"Secret: {prop.name}, Enabled: {prop.enabled}, "
          f"Content type: {prop.content_type}")
    if prop.tags:
        print(f"  Tags: {prop.tags}")

El listado es util durante app startup para validar que todas las credenciales existen.

Handle errors and exceptions

El SDK levanta excepciones especificas para distintos escenarios. Es nuestra responsabilidad gestionarlos bien para ver cual es recuperable y cual no.

# Code fragment - focus on structured error handling for secret retrieval
from azure.core.exceptions import (
    ResourceNotFoundError,
    HttpResponseError,
    ServiceRequestError
)

def get_secret_safely(client, secret_name):
    try:
        secret = client.get_secret(secret_name)
        return secret.value
    except ResourceNotFoundError:
        # Secret doesn't exist - configuration error
        print(f"Secret '{secret_name}' not found in vault. "
              "Verify the secret name and vault configuration.")
        raise
    except HttpResponseError as e:
        # Authentication or authorization failure
        print(f"Access denied or server error for '{secret_name}': "
              f"{e.status_code} - {e.message}")
        raise
    except ServiceRequestError:
        # Network connectivity issue - may be transient
        print(f"Network error retrieving '{secret_name}'. "
              "Check connectivity to Key Vault.")
        raise

Use the async client for high-throughput apps

El modulo azure.keyvault.secrets.aio provee un SecretClient async para apps que usan asyncio. Los servicios de IA que procesan requests concurrentes se benefician de async secret retrieval porque evita bloquear el event loop durante vault calls.

# Code fragment - focus on async secret retrieval
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

async def get_ai_credentials():
    credential = DefaultAzureCredential()
    client = SecretClient(
        vault_url="https://kv-ragpipeline-prod.vault.azure.net/",
        credential=credential
    )

    async with client:
        secret = await client.get_secret("openai-api-key")

    await credential.close()
    return secret.value

Read More

Implement caching strategies (Key Vault)

Understand Key Vault throttling limits

Key Vault tiene throttling limits para proteger el servicio. Cuando esto pasa se devuelve HTTP 429 (Too Many Requests).

Para secretos, Key Vault soporta hasta 4000 GET per vault en 10s.
Los write se llevan a un limite de 300 colectivo en 10 segundos.

Son limites grandes pero que se pueden alcanzar rápidamente si una app llama get_secret() con cada input request. Esto lo solucionamos mediante caching.

Implement a time-based in-memory cache

El método más simple es guardar el secreto en memoria con un TTL. Esto se puede usar para secretos que cambian infrecuentemente. Una ventana de 15-60 mins es aceptable.

# Code fragment - focus on time-based caching pattern
import time
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

class SecretCache:
    def __init__(self, vault_url, cache_ttl_seconds=900):
        credential = DefaultAzureCredential()
        self._client = SecretClient(vault_url=vault_url, credential=credential)
        self._cache = {}
        self._cache_ttl = cache_ttl_seconds

    def get_secret(self, secret_name):
        cached = self._cache.get(secret_name)
        now = time.monotonic()

        if cached and (now - cached["timestamp"]) < self._cache_ttl:
            return cached["value"]

        secret = self._client.get_secret(secret_name)
        self._cache[secret_name] = {
            "value": secret.value,
            "timestamp": now
        }
        return secret.value

El param cache_ttl_seconds controla el tiempo en segundos.

Invalidar la cache con Azure Event Grid

Time-based caching introduce una ventana de tiempo donde la app puede usar la vieja credencial tras una rotacion.

Para ventanas más ajustadas podemos suscribirnos al evento del Key Vault SecretNewVersionCreated a través de Azure Event Grid. Cuando se crea una nueva version se lanza este evento.

Entonces invalidamos la cache local y obtenemos el nuevo.

Este métodos es útil porque la cache solo se recarga cuando realmente hay un cambio, en vez de en un timer fijo.

Choose the right cache scope

El scope de tu cache determina cuantas llamadas a Key Vault hace tu app de manera colectiva.

Per-process cache

Método más simple. Cada app instance mantiene su propia in-memory cache. Funciona muy bien para stateless services donde cada instancia gestiona de manera independiente las caches de secretos.

Shared distributed cache

Usamos un external store como Managed Redis como capa intermedia entre la app y el key vault. Un único proceso lee el secreto del Key Vault y lo escribe en la cache compartida. El resto de instancias leen de la cache.

Añade complejidad e introduce dependencias de la cache compartida. Tambien almacenamos los secretos en un store independiente fuera del Key Vault (la cache), lo cual requiere su propio control de acceso y encriptación.

Application startup preloading

Obtenemos todos los secretos en startup y los guardamos en memoria por el lifetime del proceso. Funciona muy bien para servicios contenerizados donde las instancias se reinician periodicamente, y para secretos que raramente cambian.

# Code fragment - focus on startup preloading pattern
class AppConfig:
    def __init__(self, vault_url, secret_names):
        credential = DefaultAzureCredential()
        client = SecretClient(vault_url=vault_url, credential=credential)

        self._secrets = {}
        for name in secret_names:
            secret = client.get_secret(name)
            self._secrets[name] = secret.value

    def get(self, secret_name):
        return self._secrets.get(secret_name)

# At application startup
config = AppConfig(
    vault_url="https://kv-ragpipeline-prod.vault.azure.net/",
    secret_names=["openai-api-key", "cosmosdb-connection-string",
                  "blob-storage-key"]
)

# During request processing - no vault calls
api_key = config.get("openai-api-key")

Balance cache lifetime with security requirements

El cache lifetime que decidamos depende de la frecuencia de rotacion y la ventana de tiempo que sea aceptable tener secretos caducados hasta que se renueven.

Para keys que rotan cada 90 dias, hasta 1h de TTL es aceptable.

Para keys que son criticas lo mejor es poner un TTL de 5 mins o usar event-driven invalidation a través de Event Grid.

  • High-rotation secrets (daily/weekly): 5-15 mins TTL combinado con Event Grid
  • Standard (monthly/quarterly): 30-60 min TTL. Event Grid es beneficioso pero no critico
  • Low-rotation (annual/static): Startup preloading with periodic refresh (every few hours)

Handle throttling gracefully

Cuando tu app recibe HTTP 429 como respuesta del Key Vault, implementamos exponential backoff antes de reintentar

# Code fragment - focus on logging throttling events for cache tuning
import logging

logger = logging.getLogger("keyvault")

def get_secret_with_monitoring(cache, secret_name):
    try:
        return cache.get_secret(secret_name)
    except HttpResponseError as e:
        if e.status_code == 429:
            logger.warning(
                "Key Vault throttled request for '%s'. "
                "Consider increasing cache TTL.", secret_name
            )
        raise

Read More

Design reliable workflow steps (Durable Functions)

Durable orchestration preserva el workflow progress, pero la persistencia por si sola no hace que las operaciones externas sean seguras. Los model endpoints pueden hacer throttle de requests, los storage writes pueden sufrir timeouts y un host se pueden reiniciar.

Classify failures before retrying

Los retries ayudan con los fallos que sean efimeros. Consumen recursos por lo que no se reintentar de manera indiscriminada. Clasificar los fallos ayuda a poder resolverlos:

  • Transient failure Aplicar una bounded retry policy
  • Permanent failure Validar early y enrutar el item a un terminal outcome
  • Auth failure Revisar
  • Timeout Compensar el tiempo, escalar o preservar para auditar
  • Business-rule failure Una confidence score baja o un approval rechazado podemos enrutarlo a una workflow branch explicita

Las activity functions deberian raise failures que el orchestrator necesita tratar como errores técnicos. Pueden devolver outputs estructurados para distinguir casos que no se puedan cumplir de consumir retry attempts.

Apply bounded activity retries

Durable Functions pueden hacer schedule de una actividad con una retry policy. El durable runtime graba cada intento y espera entre intentos el solo. Ponemos un maximum attempt count para que un fallo persistente eventualmente llegue al orchestrator.

en python usamos la RetryOptions API

# Code fragment - focus on a bounded activity retry
import azure.durable_functions as df

retry_options = df.RetryOptions(
    first_retry_interval_in_milliseconds=5_000,
    max_number_of_attempts=3,
)

result = yield context.call_activity_with_retry(
    "process_document",
    retry_options,
    {
        "operation_id": operation_id,
        "document_id": document["document_id"],
        "blob_url": document["blob_url"],
    },
)

NO debemos hacer nest de muchos retry layers no controladas. Calcular el maximo numero de retry attempts y tiempo combinado y configurar ambas capas de manera intencional

Enforce durable timeouts

Una retry policy limita los intentos, mientras que un timeout limita cuanto tiempo espera el workflow por un outcome. Durable timers permiten a un orchestrator expresar una deadline sin mantener recursos activos.

Un timer que gane a task_any() no cancela automaticamente una activity que ya ha comenzado. La activity puede todavia finalizar y producir external side effects. Usamos operation record o cancellation flag que el activity comprueba cuando es necesario, haciendo un eventual write idempotente. Diseñamos el workflow para ignorar un late result tras una terminal deadline.

Timeout scopes:

  • Client request timeout Bound one HTTP o SDK call dentro de una activity
  • Activity retry window Bound de attempts y delays para un durable step
  • Workflow step timeout Race durable task against durable timer
  • End-to-end deadline Stop or compensates workflow when the business process exceeds its allowed duration

Make activity side effects idempotent

IMPORTANTE

Durable Functions proveen de at-least-once activity execution. Una activity puede completar un external write y entonces ejecutarse de nuevo si el host falla antes de que el runtime grabe sus resultados.

La idempotencia asegura que repetir las mismas operaciones produce el mismo resultado, en vez de crear duplicados

Derivar una stable operation ID de orchestration input, o crear una con context.new_uuid() y lo pasamos a la activity. Usamos ese ID como database key, blob name, o cualquier otra key.

NUNCA crear operation ID con uuid.uuid4() ya que esto causaria que cada reintento parezca que es trabajo nuevo, cuando en realidad estaríamos creando duplicados

/IMPORTANTE

usamos operation ID como blob name y creamos el resultado solo cuando no exista

# Code fragment - focus on an idempotent result write
import json
from azure.core.exceptions import ResourceExistsError


def persist_result(request: dict) -> dict:
    blob_name = f"results/{request['operation_id']}.json"
    blob_client = results_container.get_blob_client(blob_name)
    payload = json.dumps(request["result"])

    try:
        blob_client.upload_blob(payload, overwrite=False)
        write_status = "Created"
    except ResourceExistsError:
        write_status = "AlreadyExists"

    return {
        "operation_id": request["operation_id"],
        "result_url": blob_client.url,
        "write_status": write_status,
    }

Compoensate completed side effects

Distributed workflows por lo general no pueden hacer rollback de varios servicios como si fuera una transacción. Tenemos que compensar manualmente cualqueir side effect.
Ejemplo: una activity podria marcar como invalid un rejected claim summary, moverlo a un quarantine container, o esconderlo de downstream consumers.

La compensación debe ser idempotente.

schedule compensation when document processing exhausts its retries. La exception se vuelve a relanzar tras compensar para que el orchestrator mantenga un failed terminal status

# Code fragment - focus on compensation after a failed durable step
try:
    result = yield context.call_activity_with_retry(
        "process_document",
        retry_options,
        process_request,
    )
except Exception:
    yield context.call_activity(
        "compensate_document",
        {
            "operation_id": process_request["operation_id"],
            "reason": "ProcessingFailed",
        },
    )
    raise

Expose terminal status and diagnostics

Cada workflow branch deberia llegar a un status como Completed, Rejected, TimedOut, Compensated o Failed.

Incluir IDs para poder trackear requests.

No hacer logging de document contents, prompts, model credentials o tokens.

Read More

Azure App Configuration

Azure App Configuration es un servicio administrado, que almacena app settings en pares clave-valor, de forma centralizada en el cloud. Permite modificar configuración dinámicamente y gestionar feature flags, hacer despliegues progresivos o experimentar sin tener que desplegar la app de nuevo.

Understand the App Configuration data model

App Configuration guarda cada setting como pares clave-valor con propiedades adicionales para poder controlar como se identifica, interpreta, y administra la setting.

  • Key: case-sensitive unicode string que identifica la setting. Soporta delimitadores como : o / Ejemplo OpenAI:Endpoint. No se fuerzan schemas sobre las keys
  • Value: unicode string que almacena el dato. El tamaño combinado de Key y Value no puede pasar de 10 KB. Se pueden meter plain strings, JSON obects, o referencias a otros recursos como Key Vault secrets
  • Label: Tag opcional que crea variantes de la misma key. Permite almacenar diferentes valores para la misma key a lo largo de environments, regiones, o versiones.
  • Content Type: Property opcional que indica como se debe interpretar el valor. application/json le dice al provider que parsee el valor como JSON object. Key Vault reference content types le dicen al provider que resuelva el valor de Azure Key Vault
  • Tags: metadatos opcionales en pares clave-valor para filtrar y organizar.

Install the python provider library

La libreria azure-appconfiguration-provider ofrece una interfaz a alto nivel para cargar config settings desde una App Configuration store, a tu python app.
Esta libreria crea un Mapping object que se comporta como un python dict.

Tambien necesitamos la libreria azure-identity para auth

pip install azure-appconfiguration-provider azure-identity

Connect and retrieve settings

La function load() acepta un endpoint parameter para la App Configuration store URL y un credential param para auth. El endpoint sigue el patrón https://<store-name>.azconfig.io

como conectar a App Configuration y hacer get de un valor

# Code fragment - focus on connecting to App Configuration and accessing a setting
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
import os

endpoint = os.environ.get("AZURE_APPCONFIG_ENDPOINT")
credential = DefaultAzureCredential()

config = load(endpoint=endpoint, credential=credential)

# Access settings using dictionary syntax
model_endpoint = config["OpenAI:Endpoint"]
batch_size = config["Pipeline:BatchSize"]

Authenticate with DefaultAzureCredential

También se soporta aqui. Prueba diferentes metodos de auth en orden hasta que uno funciona.

Select and filter keys with SettingSelector

La clase SettingSelector filtra que keys carga el provider de la store. Sin un selector, el provider carga cada par clave-valor con null label, lo que puede incluir settings de otras apps que compartan el mismo store.

Puedes usar key_filter para hacer match de keys por prefix o patron (se aceptan wildcards *) y label_filter para seleccionar settings para un entorno o version especifica.

Lo ideal es cargar solo la conf relevante al contexto actual de la app, para reducir memoria y evitar name colisions.

# Code fragment - focus on SettingSelector for filtering keys by prefix and label
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential

selects = [
    SettingSelector(key_filter="Pipeline:*", label_filter="Production")
]

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    selects=selects
)

# Only keys matching "Pipeline:*" with the "Production" label are loaded
batch_size = config["Pipeline:BatchSize"]

Puedes pasar multiples SettingSelector para cargar several groups de settings en una unica llamada. Cuando hay multiples selectores que hacen match de la misma key, el ultimo selector de la lista es el que toma prioridad

Trim key prefixes

Nombres jerarquicos como DocPipeline:OpenAI:Endpoint mantienen la conf store organizada, pero el full prefix es normalmente innecesario dentro del codigo de la app.

El param trim_prefixes borra estos prefijos al cargar la config para que a la app le queden nombres más limpios

# Code fragment - focus on trimming key prefixes for cleaner access
config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    trim_prefixes=["DocPipeline:"]
)

# Access "DocPipeline:OpenAI:Endpoint" as "OpenAI:Endpoint"
model_endpoint = config["OpenAI:Endpoint"]

Trimming es especialmente util cuando hay multiples apps que comparten un config store y cada una usa un prefijo único

Enable dynamic configuration refresh

El provider soporta refresh de config dinámicos para que tu app pueda recibir cambios desde App Configuration sin reiniciarse.

Tienes que activar el refresh especificando uno o más sentinel keys a hacer watch a través del param refresh_on.

Cuando el provider detecta un cambio en esa key que vigilamos, recarga la config entera (para mantener consistencia).
El param refresh_interval controla la frecuencia de ese check (en segundos).

# Code fragment - focus on enabling dynamic refresh with a sentinel key
from azure.appconfiguration.provider import load, WatchKey
from azure.identity import DefaultAzureCredential

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    refresh_on=[WatchKey("Sentinel")],
    refresh_interval=60
)

# Later in your application loop or request handler
config.refresh()

# Access settings - values reflect the latest from the store after refresh
batch_size = config["Pipeline:BatchSize"]

El patrón sentinel key involucra una key dedicada que hace update cuando quieres que la app recargue su config. Cambiar la sentinel key le indica al provider que hay un nuevo set de config. El métpdp refresh() del provider debe ser llamado de manera explicita. Si el refresh_interval no se ha cumplido desde el ultimo check, la llamada refresh() se ignora y devuelve sin hacer nada.

Read More

Organize settings with labels and feature flags (App Configuration)

Use labels for environment differentiation

Las labels crean variaciones de la misma key para diferentes entornos, regiones o app versions.

Una key como Pipeline:BatchSize puede tener:

  • una label Development con valor 10
  • otra label Staging con valor 50
  • otra label Production con valor 200

El nombre de la key se mantiene igual en todos los entornos, por lo que tu app solo referencia Pipeline:BatchSize independientemente del entorno donde se ejecute.

Keys sin label, realmente usan la label null, representada como \0. Estas sirven como default que aplican cuando no hay otra que la sobreescriba.

Stack key-value pairs with composition

El provider soporta cargar multiples sets de valores clave-valor en secuencia, donde later-loaded values hacen override de los valores previos, para la misma key.

Esto es la base para administrar default settings, junto a environment-specific overrides.
Primero cargas tus valroes default y los valores especificos por environment se cargan on top. Cualquier key que tenga un valor especifico por entorno usa ese override, mientras que las keys que no tengan un override, se quedan como están con sus valores por defecto.

# Code fragment - focus on key-value composition with stacking
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential
import os

endpoint = os.environ.get("AZURE_APPCONFIG_ENDPOINT")
environment = os.environ.get("APP_ENVIRONMENT", "Development")

selects = [
    SettingSelector(key_filter="*", label_filter="\0"),
    SettingSelector(key_filter="*", label_filter=environment)
]

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    selects=selects
)

# Defaults load first, then environment-specific values override matching keys
batch_size = config["Pipeline:BatchSize"]

El orden de SettingSelector importa. El segundo selector hace target de las labels del entorno y hace override de cualquier valor del primer selector.

Design key naming conventions

Una naming convention bien montada simplifica filtrar con SettingSelector. Usamos : o / para agrupar settings relacionadas por service component. Esta estructura permite filtrar por prefijo para cargar solo los settings que necesitamos.

Ejemplos:

  • OpenAI:Endpoint
  • OpenAI:DeploymentName
  • OpenAI:MaxTokens
  • CosmosDB:DatabaseName
  • CosmosDB:ContainerName

Con esta convención un componente que solo necesite OpenAI settings puede cargar keys usando key_filter="OpenAI:*"

Understand Feature Flags in App Configuration

Feature flags son pares especiales clave-valor que la App Configuration administra a través de una interfaz dedicada. Cada feature flag tiene un nombre, status (activado/desactivado) y filtros opcionales que controlan condiciones de activación.

IMPORTANTE

App Configuration almacena los feature feature flags con un key prefix .appconfig.featureflag/ y content type application/vnd.microsoft.appconfig.ff+json;charset-utf-8, pero las librerias se abstraen de todo esto para que solo vean flag names simples y booleanos.

/IMPORTANTE

Las feature flags desacoplan el feature lifecycle del deployment lifecycle. En vez de desplegar nuevo código para activar/desactivar características de nuestra app, podemos hacerlo en runtime con un flag.

Evaluate feature flags with FeatureManager

La libreria featuremanagement integra con el App Configuration provider para evaluar feature flags en runtime.

Cargas feature falgs pasando feature_flags_enabled=True para la function load() del provider, y entonces creas un FeatureManager desde la config cargada. FeatureManager tiene un metodo is_enabled() para comprobar si una feature flag especifica está activa

# Code fragment - focus on loading feature flags and evaluating them
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
from featuremanagement import FeatureManager

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    feature_flags_enabled=True
)

feature_manager = FeatureManager(config)

if feature_manager.is_enabled("UseNewEmbeddingsModel"):
    # Route to the new embeddings model
    process_with_new_model(document)
else:
    # Use the current embeddings model
    process_with_current_model(document)

IMPORTANTE

El FeatureManager evalua el estado del flag cada vez que se llama is_enabled(). Cuando se combina con dynamic refresh, esto hace que la app responda a un cambio de flag sin tener que reiniciar.

/IMPORTANTE

Refresh feature flags dynamically

El dynamic refresh de las Feature flags es independiente del refresh de otras configuration settings

Activas este feature flag refresh mediante feature_flag_refresh_enabled=True pasandoselo a load() function. Un cambio en una feature flag no triggea un refresh de otros config settings.

# Code fragment - focus on enabling dynamic refresh for feature flags
from azure.appconfiguration.provider import load, WatchKey
from azure.identity import DefaultAzureCredential
from featuremanagement import FeatureManager

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    feature_flags_enabled=True,
    feature_flag_refresh_enabled=True,
    refresh_on=[WatchKey("Sentinel")],
    refresh_interval=30
)

feature_manager = FeatureManager(config)

# In your application loop or request handler
config.refresh()

# Feature flag state reflects the latest value from the store
if feature_manager.is_enabled("UseNewEmbeddingsModel"):
    process_with_new_model(document)

Apply feature flags

Estas se pueden usar de muchas maneras

  • Progressive model rollouts: activamos nuevos modelos de manera interna a través de una feature flag, pero sin exponerlos a PROD
  • Kill switches: emergency shutoff para un proceso critico
  • A/B testing configurations
  • Staged pipe activation

Read More

Create triggers and bindings (Azure Functions)

Los triggers y los bindings ofrecen una manera declarativa de conectar funciones a servicios externos.

  • Trigger determina como se invoca la función
  • Binding mueven data into - and out of - functions a través de configuración

Cada función tiene un único trigger que determina el tipo de event source que invoca la función. Ej: HTTP requests, queue messages, timer schedules, database change feeds. El trigger también sirve como input binding, proveyendo el event data a tu función.

Los bindings son opcionales. Una función puede tener 0 o múltiples bindings de cualquier tipo. El runtime se encarga de la auth y data serialization.

Create HTTP triggers (inference endpoint)

Soportan GET, POST y otros HTTP methods.

En Python v2 se definen HTTP triggers usando @app.route(). Especificas la ruta, HTTP method y Auth level. La función recibe un HttpRequest que contiene los headers, query params y body. La función devuelve HttpResponse con el resultado.

# Code fragment - focus on HTTP trigger for an inference endpoint
import azure.functions as func
import json

app = func.FunctionApp()

@app.route(route="classify", methods=["POST"], auth_level=func.AuthLevel.FUNCTION)
def classify_document(req: func.HttpRequest) -> func.HttpResponse:
    payload = req.get_json()
    document_text = payload.get("text")

    # Call inference logic or Azure AI service
    classification = perform_classification(document_text)

    return func.HttpResponse(
        json.dumps({"category": classification}),
        status_code=200,
        mimetype="application/json"
    )

HTTP-triggered functions tienen un timeout de 230 segundos impuesto por el Azure Load Balancer. Para tareas de inferencia que tarden más, devolver un 202 Accepted con un status endpoint URL y procesar el trabajo de manera asincrona usando un Service Bus trigger (async request-repply pattern)

Authorization levels

Los Auth levels controlan quien puede invocar la función

  • anonymous no key - para development e internal health check endpoints
  • function - requiere una key function-specific enviada en functions-keys header o code query param. recomendado para PROD
  • admin - requiere la master key. reservarla para administrative operations

El uso de auth keys es una base pero, no sustituye a Entra ID.

Create Service Bus Triggers (Batch Processing)

Hacer trigger de la function cuando llega un message a la Azure Service Bus queue. Este trigger es la base para async AI processing patterns donde el work item se envia a través de una interfaz y se procesa a un ritmo independiente determinado por los compute resources.

Service Bus triggers administran de manera automática la retry logic, dead-letter management y concurrency scaling.

Service Bus ofrece features complejas como:

  • message sessions
  • duplication detection
  • scheduled delivery

En Python v2 definimos Service Bus queue triggers usando @app.service_bus_queue_trigger(). Especifica queue name y connection setting que resuelve al Service Bus namespace conn string (o identity-based conn)

# Code fragment - focus on Service Bus queue trigger for processing work items
@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
def process_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))
    document_url = job["document_url"]
    job_id = job["job_id"]

    # Perform document processing and classification
    result = extract_and_classify(document_url)

    # Store result (using output binding or SDK client)
    save_result(job_id, result)
  • Podemos configurar el concurrency behavior para Service Bus triggers en host.json
  • maxConcurrentCalls controla cuantos mensajes puede procesar cada instancia de manera simultánea - un valor de 1 asegura que cada mensaje tiene full instance resources
  • maxAutoLockRenewalDuration controla cuanto tiempo el runtime renueva el message lock (esto es, el procesamiento continúa) - debería ponerse tan alto como para cubrir tu caso más largo para que el lock no expire mientras la AI service call is WIP
  • maxDeliveryCount (default: 10) Cuando un mensaje se pasa de este valor, el Service Bus broker automáticamente lo mueve a la dead-letter sub-queue. Esta cola es para mensajes que han fallado repetidamente el procesamiento y se puede monitorizar.
{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "maxConcurrentCalls": 1,
            "maxAutoLockRenewalDuration": "00:05:00"
        }
    }
}

HTTP Function + Service Bus Function (decoupling pattern)

Un common AI pattern empareja un HTTP endpoint con un Service Bus trigger.

La HTTP function acepta un batch request, valida el input, manda los mensajes individuales a la Service Bus queue y devuelve inmediatamente. Una Service Bus triggered-function procesa entonces cada item de manera independiente ejecutando inferencias, llamando Azure AI Services y escribiendo los resultados a un storage.

Esta separación separa la ingestión del procesamiento, permitiendo que cada servicio escale a su propio ritmo.

Use output bindings to store results

Los output bindings escriben data a external service ocupándose el runtime de manejar connection management, auth y serialization basandose en la binding config.

Para AI backends, los output bindings proveen de una manera concisa de persistir inference results, processed documents y derived data a storage services.

Common output binding targets son

  • Azure Blob Storage store processed documents y binary artifacts
  • Azure Cosmos DB writing structured inference results
  • Azure Service Bus send out work to downstream processors

Service bus-triggered function que usa Blob Storage output binding para guardar processed text

# Code fragment - focus on output binding for storing results
@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
@app.blob_output(arg_name="output_blob", path="results/{rand-guid}.json", connection="AzureWebJobsStorage")
def process_and_store(msg: func.ServiceBusMessage, output_blob: func.Out[str]) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))

    result = extract_and_classify(job["document_url"])

    output_blob.set(json.dumps({
        "job_id": job["job_id"],
        "classification": result["category"],
        "confidence": result["score"]
    }))

Cuando una function necesita devolver una HTTP response y escribir a un output binding de manera simultanea, Python v2 soporta multiples outputs a través de un custom return type.
Defines la HTTP response y el output binding como properties separadas, por lo que la function puede responder al caller y persistir data en una unica invocacion

CosmosDB output bindings hacen write de JSON documents directamente a un contenedor. Especificas database name, container name, connection setting

# Code fragment - focus on Cosmos DB output binding
@app.service_bus_queue_trigger(arg_name="msg", queue_name="classification-results", connection="ServiceBusConnection")
@app.cosmos_db_output(
    arg_name="output_doc",
    database_name="ai-results",
    container_name="classifications",
    connection="CosmosDBConnection"
)
def store_classification(msg: func.ServiceBusMessage, output_doc: func.Out[func.Document]) -> None:
    result = json.loads(msg.get_body().decode("utf-8"))

    output_doc.set(func.Document.from_dict({
        "id": result["job_id"],
        "category": result["category"],
        "confidence": result["score"],
        "processed_at": datetime.utcnow().isoformat()
    }))

Connect to Azure AI services from a function

Los triggers y los binding models no cubren cada Azure service. Para servicios sin bindings dedicados puedes usar SDK clients directamente en código.

Este approach te da full access a la API del servicio y se beneficia del hosting y scaling de las Azure Functions.

Al crear SDK clients, inicializa el cliente fuera de la function handler para que persista la misma instancia entre invocaciones.

Usar DefaultAzureCredential para auth permite que el mismo código funcione localmente (usando developer credentials de Azure CLI o el IDE) y en PROD (usando la function managed identity)

# Code fragment - focus on SDK client initialization and reuse
from azure.identity import DefaultAzureCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient
import os

credential = DefaultAzureCredential()

doc_intelligence_client = DocumentIntelligenceClient(
    endpoint=os.environ["DOCUMENT_INTELLIGENCE_ENDPOINT"],
    credential=credential
)

@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
def analyze_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))

    poller = doc_intelligence_client.begin_analyze_document(
        "prebuilt-layout",
        analyze_request={"url_source": job["document_url"]},
        content_type="application/json"
    )
    result = poller.result()
    # Process extraction results...

Read More

Manage secrets and configurations (Azure Functions)

Use application settings for configuration

Los application settings son pares clave-valor que se configuran a través de:

  • Azure portal
  • Azure CLI
  • infrastructure-as-code

El runtime de las Azure Functions exponen estas settings a tu funcion como environment variables.

Azure encripta application settings at rest y lo desencripta solo cuando se inyecta en la app’s process memory, para que no se guarden en plaintext en el disco.

En python se accede a las app settings usando

  • os.environ para required settings
  • os.getenv para settings con fallback defaults

Este patron ayuda a mantener las functions environment-agnostic, ya que el mismo codigo lee config de local.settings.json en development y de las app settings en PROD.

# Code fragment - focus on reading application settings
import os

ai_endpoint = os.environ["AI_SERVICE_ENDPOINT"]
model_id = os.environ["MODEL_ID"]
confidence_threshold = float(os.getenv("CONFIDENCE_THRESHOLD", "0.85"))
max_batch_size = int(os.getenv("MAX_BATCH_SIZE", "10"))

Ignorar siempre local.settings.json del .gitignore

Reference secrets de Azure Key Vault

Las referencias a Key Vault permiten guardar valores sensibles directamente en Azure Key Vault y referenciarlos desde las app settings.

El runtime resuelve la referencia en app startup time, obtiene el secreto de la key vault y lo inyecta como environment variable, por lo que es transparente para la app.

Reference syntaxes

URI syntax - points to specific secret version (or latest)

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/AiServiceKey/)

Named syntax - uses vault name and secret name

@Microsoft.KeyVault(VaultName=myvault;SecretName=AiServiceKey)

Ambos tipos requieren que la Function App tenga una managed identity (system-assigned o user-assigned) con el rol Key Vault Secrets User en el target vault. Sin este rol, el runtime no puede obtener el secreto para la app.

Las Key Vault references se resuelven en app startup time. Al cambiar un secreto la nueva versión se usa dentro de las primeras 24 horas. Cualqueir cambio a la configuración de la app causa inmediatamente un refetch de los secretos.

Para AI backends que usen rotacion la recomendacion es usar versionless URIs para que el runtime pille la rotación automáticamente.

Los beneficioes de usar Key Vault son seguridad, centralizacion de secret management a través de multiple Function Apps y services, audir logging, separate secret ownership from app deployment. Un equipo de seguridad puede hacer management y rotar secretos sin tener que acceder a la config de la aplicacion.

Integrate with Azure App Configuration

IMPORTANTE

Azure App Configuration provee un store centralizado para non-secret configuration values y feature flags.

  • Application settings funciona bien para individual function apps.
  • App Configuration es util cuando multiples function apps o micros comparten valores comunes de config, como model endpoint URLs o feature toggles. Cambiar un setting una unica vez en App Configuration propaga este cambio a todas las apps conectadas.

/IMPORTANTE

En python se conecta a App Configuration usando una libreria a través de azure-appconfiguration-provider. Esto carga los config values en memoria y los pone disponibles para que la app los lea.

Soporta label-based filtering. Te permite cargar diferentes sets de valores para diferentes entornos.

# Code fragment - focus on loading configuration from App Configuration
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
import os

config = load(
    endpoint=os.environ["APP_CONFIG_ENDPOINT"],
    credential=DefaultAzureCredential(),
    selects=[{"key_filter": "AIBackend/*"}]
)

model_endpoint = config["AIBackend/ModelEndpoint"]
inference_timeout = int(config["AIBackend/InferenceTimeout"])

Una arquitectura comun es combinar App Configuration para nonsecret-values y Key Vault para secretos.

App Configuration soporta Key Vault references. Esto crea una configuration surface unificada para poder obtener todos los valores a través del mismo proveedor

Handle configuration in the local development workflow

Para desarrollo local necesitamos reproducir la misma config structure que corre en Azure, pero apuntando a local services y emuladores en vez de cloud resources.

El local.settings.json file hace mirror de las settings que ofrece el Azure portal.

Puedes hacer pull de current app settings de una deployed function app, a tu config local, usando Azure Functions Core Tools command. Este comando descarga todos los settings y los escribe a local.settings.json, lo cual es util para replicar PROD de manera rapida.

func azure functionapp fetch-app-settings <function-app-name>

Ya que este local.settings.json puede contener conn strings sensibles, podemos encriptar el fichero con Core Tools para proteger los secretos at rest en tu maquina. El local Functions runtime puede leer los valores, pero estos no son visibles si abres el fichero.

func settings encrypt

Para el dia a dia apuntar AzureWebJobsStorage a UseDevelopmentStorage=true para usar Azurite.

Read More

Configurar identity y access (Azure Functions)

Replace connection strings with identity-based connections

Azure Functions binding extensions soportan identity-based connections, las cuales usan la function app’s manage identity para autenticar, en vez de requerir una connection string guardada en application settings.

Este approach elimina secretos del trigger y binding configuration. En vez de guardar una full connection string que contiene account keys o shared access signatures, configuras el binding con una named connection, que incluye solo el service endpoint o account name.
El runtime se encarga de la auth de manera transparente usando la assigned managed identity.

Para preparar una identity-based connection, activa un system-assigned managed identity para la function app, entonces asignar los Azure rules necesarios para el target resource.
La function app autentica usando la identidad y no tenemos secret values que aparezcan en el app settings.
Esto es particularmente util para AI backends que conectan a multiples Azure services, ya que cada conexion adicional en la config expande el surface area para ataques.

El identity-based connection mas comun es el runtime own storage dependency. Podemos reemplazar el AzureWebJobsStorage tradicional connection string con identity-based settings, configurando el storage account name y asignando roles

AzureWebJobsStorage__accountName = mystorageaccount

El runtime autentica con la function app’s managed identity. El rol minimo requerido es Storage Blob Data Owner. Si tu app usa blob triggers, tambien necesitas Storage Queue Data Contributor y Storage Account Contributor ya que blob triggers internamente usan storage queues para blob receipts. Para Service Bus y CosmosDB, usar solo Storage Blob Data Owner es suficiente.

Usar identity-based connections for trigger y output bindings

Identity-based connection config difiere de connection string configs en la manera de hacer setup del named connection prefix. Cada binding’s connection property en function_app.py referencia un named prefix (ejemplo connection="ServiceBusConnection"). Con connection strings, creas una single app setting con el prefix name, que contiene el full connection string. Con identity-based connections, creas settings usando el prefijo con property suffixes que especifican el service endpoint.

Ejemplos:

Service Bus trigger with identity-based connection

Remplaza la Service Bus connection string, con el fully qualified namespace.
Asigna Azure Service Bus Data Receiver role a la function app’s managed identity en el Service Bus namespace. Para output bindings, asigna Azure Service Bus Data Sender role instead.

ServiceBusConnection__fullyQualifiedNamespace = mynamespace.servicebus.windows.net 
# Code fragment - focus on Service Bus trigger with identity-based connection
@app.service_bus_queue_trigger(
    arg_name="msg",
    queue_name="document-jobs",
    connection="ServiceBusConnection"
)
def process_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))
    # Process the document...

CosmosDB output binding with identity-based connection

Reemplaza la CosmosDB connection string, con el account endpoints.

Asigna el rol Csomos DB Built-in Data Contributor a la function app’s managed identity.

CosmosDBConnection__accountEndpoint = https://mycosmosaccount.documents.azure.com:443/

Cada binding extension documenta su supported identity properties y required roles. El suffix pattern difiere por servicio

  • storage bindings usan __acountName o service-specific URIs
  • CosmosDB usa __accountEndpoint
  • Messaging services usan __fullyQualifiedNamespace

Autenticar SDK clients con managed identity

Para Azure services sin dedicated binding support, creamos SDK clients directamente en function code. Estos clients se autenticar usando la misma managed identity que sirve el trigger y las binding connections.

DefaultAzureCredential provee de credential chain para entornos locales y cloud.

Inicializamos ambos el credential objhect y el service client fuera del function handler, al nivel del modulo. Esto asegura que el objeto persista entre invocaciones en la misma instancia, evitando tener que crearlo cada vez.

# Code fragment - focus on module-level client initialization
import os
from azure.identity import DefaultAzureCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.search.documents import SearchClient

credential = DefaultAzureCredential()

doc_client = DocumentIntelligenceClient(
    endpoint=os.environ["DOCUMENT_INTELLIGENCE_ENDPOINT"],
    credential=credential
)

search_client = SearchClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    index_name=os.environ["SEARCH_INDEX"],
    credential=credential
)

Secure HTTP endpoints con authorization keys

Las Azure Functions usan access keys para restringir acceso a HTTP-triggered function endpoints. Esto es especifico para Azure Functions y opera independiente de Entra ID para auth.

IMPORTANTE

Access keys son una barrera basica para evitar invokers no autorizados, pero no comprueban la caller identity ni ofrecen fine-grained acess control.

Tipos de keys

  • Function keys Scoped a una single function. Cada function puede tener multiples named keys. Se incluyen en el header x-functions-key o el query param code, al llamar a la funcion
  • Host keys Scoped a todas las funciones en la function app. Una single host key da acceso a todas las HTTP-triggered functions. Usarlas para administrative tools o monitorizacion
  • System keys Usadas por extensiones especificas o para auth de ops internas. La MCP extension usa mcp_extension system key para autenticar MCP client connections a la function app. Son managed por el runtime y no se deben compartir
  • Master key Acceso administrativo y hace override de todas las otras keys. Nunca jamas compartirla en apps

Se establece el auth level por HTTP trigger usando auth_level en @app.route()

Recordamos:

  • anonymous no requiere key (health check endpoints o funciones que manejan la auth de manera separada)
  • function erquiere function-specific key o host key (baseline for PROD)
  • admin requiere master key (administrative ops)
# Code fragment - focus on authorization levels
@app.route(route="classify", methods=["POST"], auth_level=func.AuthLevel.FUNCTION)
def classify_document(req: func.HttpRequest) -> func.HttpResponse:
    # This function requires a function key or host key to invoke
    pass

@app.route(route="health", methods=["GET"], auth_level=func.AuthLevel.ANONYMOUS)
def health_check(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("OK", status_code=200)

Las access keys son una barrea basica pero no reemplazan la auth para PROD AI endpoints. Para paps que requieran verificar al caller, juntarlo con Azure API Management o App Service Authentication (Easy Auth) on top of access keys.

  • API Management añade rate limiting, request validation y OAuth 2.0 token verification
  • Easy Auth integra Entra ID directamente en la function app

/IMPORTANTE

Read More

Azure Durable Functions

Las Azure Durable Functions permiten que un AI workflow sobreviva a reinicios del host y a long delays. Graban cada operación y permiten hacer un replay para reconstruir el estado local que teníamos antes del reinicio.

Durable workflows

Un durable workflow combina una client function, una orchestrator function y una o más activity functions.

Cuando un cliente comienza una orchestration, el Durable Task runtime graba el input y cada durable action en la orchestration history. El runtime chequea el progreso cuando el orchestrator asigna trabajo o recibe un resultado. Si el host se restartea, el runtime hace replay del history a través del orchestrator hasta que llega a la ultima accion no terminada.

Este modelo hace restore de local variables y workflow position sin que tengas que escribir ningún checkpoint.

Client Function

Una Client function comienza la orquestación, hace query del status, lo temrmina, o envía un evento externo.

Un cliente triggeado por HTTP, normalmente, devuelve una status URL que el caller usa para hacer track de long-running workflows

Orchestrator Function

Una Orchestrator function define la workflow sequence, branching rules, parallel tasks, durable waits y result aggregation.

El orchestrator pone en cola el durable work, en vez de hacer ese trabajo por si mismo

Activity Function

Una Activity function hace una unidad de trabajo no determinista como leer un blob, llamar un model endpoint, enviar una notificacion o hacer update de una BBDD

Son las que pueden ejecutar trabajo no-determinista como language libraries o Azure SDK Clients

Entity Function

Una Entity function administra una pieza de durable state state a través de operaciones explicitas.

Las Entities pueden ayudar a coordinar ese shared state. No son obligatorias. con un orchestrator y activity functions puede ser suficiente.

Keep orchestrator logic deterministic

Un orchestrator puede hacer replay muchas veces durante una workflow instance. Un codigo determinista produce la misma secuencia de durable actions con el mismo orchestration history, para que el runtime pueda hacer match de las acciones que se ha hecho replay para completar el trabajo.

Si hay trabajo no determinista puede causar que el workflow falle o se comporte de manera no predecible.

Puedes usar de manera segura calculos locales, loops sobre stable inputs y resultados devueltos por durable tasks. Usa orchestration context APIs cuando una decision requiere del current time o un identificador unico.

Ejemplos

  • context.current_utc_datetime devuelve un replay-safe time.
  • context.new_uuid() crea un ID determinista para el orchestration history

Evita las siguientes operaciones en orchestrator functions:

  • Direct HTTP, DDBB, file system o Azure SDK calls
  • Model inference o embedding requests
  • Random-number generators y nondeterministic UUID APIs
  • Language-native current time como datetime.now()
  • Block waits como time.sleep()
  • Threads, multiprocessing y async ops que el Durable Task runtime no schedulea
  • Environment-dependent decisions que pueden cambiar entre replays

ejemplo que usa orchestration-safe time para calcular una review deadline. En el replay context.current_utc_datetime devuelve el mismo valor

# Code fragment - focus on deterministic orchestration time
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_deadline = context.current_utc_datetime + timedelta(hours=24)
    review_timer = context.create_timer(review_deadline)

    yield review_timer
    return {"status": "ReviewTimedOut"}

Move model calls e input/output a activities

Activity functions no hacen replay bajo el orchestrator deterministic execution rules. Pueden llamar Azure Services, usar SDK clients, generar random values y ejecutar otras operaciones externas.

Las activities son la unidad que las Durable Functions distribuyen across workers disponibles y se reintentan segun la orchestration policy.

La separación importa para AI workloads ya que las respuestas de los modelos son no deterministas y las llamadas a servicios pueden ser lentas o tener fallos transientes. El orchestrator pasa una request estable a una activity y hace record solo del activity result.

el orchestrator hace schedule de una actividad con una compact blob reference. La activity entonces lee el documento y llama al model client configurado

# Code fragment - focus on orchestration and activity boundaries
import azure.durable_functions as df

app = df.DFApp()


@app.orchestration_trigger(context_name="context")
def document_orchestrator(
    context: df.DurableOrchestrationContext,
):
    document = context.get_input()
    result = yield context.call_activity("analyze_document", document)
    return result


@app.activity_trigger(input_name="document")
def analyze_document(document: dict) -> dict:
    document_text = read_blob_text(document["blob_url"])
    model_result = call_classification_model(document_text)
    return {
        "document_id": document["document_id"],
        "category": model_result["category"],
        "confidence": model_result["confidence"],
    }

Llamar read_blob_text() o call_classification_model() desde el orchestrator violawria la regla de ejecucion determinista. Mantener esas operaciones en analyze_document mantiene efectos externos fuera del replaying orchestrator code y permite aplicar una retry policy especifica al external work.
Activity functions tienen at-least-once execution semantics, por lo que sus efectos deben ser idempotentes.

Control data in orchestration history

Durable Functions serializan orchestration inputs, activity inputs / outputs y otros workflow state en el durable store configurado. Payloads grandes incrementar el coste de las operaciones, replay time, memory use. Evitar pasar documentos completos, imagenes, prompts, embeddings, etc, a través de una orchestration.

Para nuevas Durtable Function Apps, se recomienda Durable Task Scheduler como el managed storage provider.

Guarda datos grandes en un servicio apropiado como Durable Task Scheduler o Azure Blob Storage. Pasa una referencia y los metadatos minimos necesarios para workflow decisiones como document ID, blob URL, content type, confidence score, etc. Una activity puede leer el source content y escribir un resultado detallado, mientras que el orchestrator recibe solo el status y los campos requeridos para su next branch.

Considerar el impacto de seguridad de la durable data. No poner secretos en orchestration inputs u outputs. Usa managed identities para credenciales.

Account for replay in telemetry

El replay puede ejecutar un orchestrator’s logging más de una vez. Los mensajes duplicados pueden llevar a confusión. Usar replay-safe logging support.

# Code fragment - focus on replay-aware orchestrator logging
import logging

if not context.is_replaying:
    logging.info(
        "Scheduling document analysis for orchestration %s",
        context.instance_id,
    )

Read More

Process independent work with fan-out/fan-in (Durable Functions)

El Durable Functions fan-out/fan-in pattern se usa para operaciones independientes que no tienen por que ejecutarse secuencialmente.

Fan-out/fan-in permite hacer schedule de esas operaciones de manera simultánea, esperar a que el grupo acabe y combinar los resultados.

Este patrón puede reducir batch latency mientras que mantiene la coordinacion y los checkpoints en el durable runtime.

Identify independent work

Fan-out/fan-in funciona mejor cuando cada work item se puede completar sin cambiar los inputs ed otro item (es completamente independiente).

Algunos ejemplos son extraer texto de varios documentos, clasificar imágenes, generar embeddings para chunks separados.

La fase fan-out distribuye estas tasks a lo largo de activity executions, mientras que la fase fan-in le da al orchestrator un result set completo para la siguiente decisión.

Schedule tasks before awaiting results

El python durable functions SDK representa activity calls como durable tasks. Para fan-out, el orchestrator crea una task para cada referencia work-item y guarda las tasks en una lista. Entonces entrega context.task_all(tasks para hacer wait de cada scheduled activity y recibir los resultados.

schedule una activity por document reference. Cada activity puede leer su source blob, llamar al AI model requerido y escribir un output detallado al storage. El orchestrator recibe compact fields que puede agregar sin poner large model responses en orchestration history

# Code fragment - focus on fan-out/fan-in coordination
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    batch = context.get_input()
    tasks = []

    for document in batch["documents"]:
        tasks.append(
            context.call_activity(
                "process_document",
                {
                    "batch_id": batch["batch_id"],
                    "document_id": document["document_id"],
                    "blob_url": document["blob_url"],
                },
            )
        )

    results = yield context.task_all(tasks)

    return {
        "batch_id": batch["batch_id"],
        "processed": len(results),
        "requires_review": [
            item["document_id"]
            for item in results
            if item["confidence"] < 0.80
        ],
    }

El orden de las listas devueltas hace match con la task list, aun cuando las activities acaban en un orden distinto.
Una activity fallida causa que la task_all operation haga raise de un task failure al orchestrator. El orchestrator puede hace catch de ese error y puede elegir si falla el batch entero, compensa el trabajo completado o lo marca para investigación

Design compact fan-in results

fan-in se ejecuta dentro de una orchestrator instance, por lo que la agregación se debe mantener determinista y lightweight. Puedes contar status, seleccionar documentos por debajo de un confidence threshold o construir un summary compacto para activity outputs.

Las expensive transformations y external writes pertenecen a otra acticity

Una document-processing activity podria devolver los siguientes campos:

  • Document ID: correlacionar resultado con original work item
  • Status: success/validation failure
  • Confidence: soporta deterministic routing a un approval step
  • Result URL: apunta al full output almacenado en Blob Storage o BBDD
  • Operation ID: para idempotent updates y trazas

No devuelvas extracted text, full model prompts, large arrays of embeddings. Estos valores expanden la orchestration history y las Durable Functions los tienen que cargar durante el replay. Escribe estos resultados desde la activity a un external store y devuelve una referencia.

Si la agregacion en si misma requiere mucha CPU, memoria, IO ops - haz schedule de una AggregateResults activity tras task_all. El orchestrator puede pasar compact result references a esa activity y esperar un final summary. Este diseño preserva un small orchestration history mientras permite la agregacion del trabajo par usar normal function execution.

Bound parallel work

Un batch con miles de documentos puede hacer schedule de un gran numero de activities de a una. El durable runtime puede grabar esas tasks, pero el historial resultado y fan-in work puede volverse muy caro.
Asi mismo, un burst de trabajo puede exceder los rate limits de los modelos.

Puedes dividir inputs grandes en bounded batches y procesar los batches de uno en uno. Cada batch ejecuta sus items en paralelo, pero el workflow espera antes de asignar el siguiente grupo.

# Code fragment - focus on bounded fan-out
batch_size = 20
all_results = []

for start in range(0, len(documents), batch_size):
    current_batch = documents[start : start + batch_size]
    tasks = [
        context.call_activity("process_document", document)
        for document in current_batch
    ]
    batch_results = yield context.task_all(tasks)
    all_results.extend(batch_results)

Los Bounded Batches limitan el trabajo asignado pero no ofrecen un limite preciso de requests-por-segundo.

Scale aggregation with sub-orchestration

Un orchestrator ejecuta el fan-in step en un worker a la vez. Un solo flat fan-in puede convertirse en un cuello de botella cuando tiene que cargar y agregar muchos resultados. Sub-orchestrations te permiten crear una jerarquia en la cual child orchestration procesan particiones separadas y un padre combina sus summaries.

Por ejemplo un parent orchestration divide un claim archive grande por policy o mes.
Cada child orchestration hace fan out de su propio document activities y devuelve counts + result locations.
El parent entonces agregar esos summaries en vez de cada document result individual.

Este approach reduce la cantidad de estado manejada por una orquestacion y da a cada particion su estado independiente.

La sub-orquestacion junta coordinacion y history records, por lo que no son necesarios para small batches. Comienza con un fan-out/fan-in pattern, mide la ejecucion y el replay behavior, e introduce partitioning cuando el batch size o el coste de agregacion justifique la estructura añadida.

Read More

Coordinate human approval with external events (Durable Functions)

Algunos workflwos requieren de input por parte de una persona u otro sistema cuando el proceso automatizado termina. Las Durable Functions pueden suspender una orchestration mientras espera por un external event, y entonces recomenzar desde su durable state cuando ese event llega.

La orchestration suspendida no mantiene un worker ni una invocacion de funcion activa. Esto se recomienda para approval windows de horas a dias.

Model an approval as an external event

Un external event es un one-way message, con nombre, enviado a una instancia especifica de orquestacion. El orchestrator crea una durable task con wait_for_external_event() y cede esa task cuando necesita del event data.

Las Durable Functions extensions persisten un evento que llega al orchestrator antes de que este comience la espera, para que el workflow pueda consumir ese buffered event más tarde.

Para un document-processing workflow, una activity primero crea un approval record y notifica al adjuster asignado. El orchestrator entonces espera a un evento ApprovalResponse que contiene la decision y la identidad del reviewer.

Diseña el event contract alrededor de workflow decisions, en vez de una user-interface action. Un approval payload compacto puede contener:

  • Decision Un valor fijo como Approved o Rejected
  • Reviewer ID para auditar y correlacionar
  • Document ID el work item que el reviewer ha evaluado
  • Approval version Un valor que ayuda al workflow a rechazar una respuesta para una review request viaje
  • Comment reference URL para cargar detalles, almacenado fuera del flujo

Combina un external event con un durable timer

Un approval process necesita una deadline para que un workflow no espere de manera infinita.
Usa context.create_timer() con context.current_utc_datetime. NO USAR time.sleep() u otras APIs bloqueantes. Un durable timer graba el deadline en la orchestration history y no requiere que el worker se mantenga activo mientras no hay trabajo.

Patrón human interaction - es una carrera entre el event task contra el timer task con context.task_any(). Si el evento gana, el orchestrator lee el event result y cancela el timer. Si el timer gana, el orchestrator sigue el timeout path.

ejemplo que implementa approval, rejection y timeout outcomes. Usa un input estable y orchestration-safe time para el replay

# Code fragment - focus on the event-and-timer race
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_request = context.get_input()

    yield context.call_activity("notify_approver", review_request)

    approval_task = context.wait_for_external_event("ApprovalResponse")
    deadline = context.current_utc_datetime + timedelta(hours=24)
    timeout_task = context.create_timer(deadline)

    winner = yield context.task_any([approval_task, timeout_task])

    if winner == approval_task:
        if not timeout_task.is_completed:
            timeout_task.cancel()

        response = approval_task.result
        if response["decision"] == "Approved":
            return {"status": "Approved"}

        return {"status": "Rejected"}

    return {"status": "TimedOut"}

Una external event task no requiere cancelación después de que el timer gane. Si el workflow puede recibir otro evento con el mismo nombre despues, definimos si la app ignora ese evento tardia, lo graba para auditarlo, o lo enruta hacia orta orchestration instance nueva.

Send an event to the correct instance

Una client function usa las Durable Functions orchestration client binding para enviar un evento. El cliente debe conocer el orchestration instance ID o usar el mismo event name que el orchestrator espera. Los event names deberian ser estables.

fragmento que muestra Durable Function call tras un OK de app-specific auth y validacion. El endpoint devuelve 202 ya que el event delivery retoma la orchestration de manera asincrona

# Code fragment - focus on raising an external event
import json
import azure.functions as func
import azure.durable_functions as df

app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)


@app.route(route="approvals/{instance_id}", methods=["POST"])
@app.durable_client_input(client_name="client")
async def submit_approval(
    req: func.HttpRequest,
    client: df.DurableOrchestrationClient,
) -> func.HttpResponse:
    instance_id = req.route_params["instance_id"]
    response = req.get_json()

    reviewer = authorize_reviewer(req)
    validated_event = validate_approval_response(response, reviewer)

    await client.raise_event(
        instance_id,
        "ApprovalResponse",
        validated_event,
    )

    return func.HttpResponse(
        json.dumps({"status": "Accepted"}),
        status_code=202,
        mimetype="application/json",
    )

Handle duplicate and out-of-order responses

Diferentes servicios pueden mandar la misma decision mas de una vez. External events tienen at-least-once delivery guarantee, por lo que restarts, escalado o fallos pueden producir deliveries duplicadas. Sigue siendo nuestra responsabilidad garantizar idempotencia ya que un evento duplicado no debería crear un segundo approval record o repetir una operación downstream.

Podemos incluir un ID estable para approvals y que una actividad de manera atómica compruebe este ID para reportar si la operación ya existe.

Respuestas out-of-order requieren de una policy explicita. Evitar usar solo el orden de llegada cuando hay múltiples sistemas que pueden mandar eventos.

Choose a timeout outcome

Un timeout es un outcome pero no necesariamente un fallo técnico. El orchestrator debe elegir un terminal path y hacer schedule de cualquier update requerida, a través de activities.

Read More

Set up local dev environment (Azure Functions)

Install Azure Functions Core Tool

Para Visual Studio Code instalar la Azure Functions extension. Esta depende de Azure Functions Core Tools, la cual permite ejecutar una versión local del runtime de las Azure Functions. Tiene el mismo trigger y binding logic que corre en Azure, por lo que funciona de manera consistente entre local y cloud envs.

Gracias a ellas también puedes crear nuevas Functions desde tu local. Esto crea la function y te permite ejecutarla con func start y expone http://localhost:7071 por defecto.

Understand local project structure

El programming model Python v2 usa un single entry point file function_app.py, donde defines tus functions y sus triggers usando decorators. Este approach consolida las function definitions en un solo lugar.

Un único function_app.py funciona bien para projectos con una miriada de funciones como HTTP trigger para inferencias y queue trigger para batch processing.

A medida que el número de functions crece, se puede partir sus definiciones en files separados usando blueprints. Los blueprints permiten definir funciones en modules individuales y registrarlos en el main entry point function_app.py.

El fichero host.json contiene global runtime configs que aplican a todas las funciones de la app. Esto incluye settings como timeout durations, log levels o concurrency limits.

El fichero local.settings.json contiene app settings y conn strings para desarrollo local. El runtime lee valores del Values object en este fichero y los expone como environment vars en código.
Este fichero se excluye de git por defecto. NUNCA. COMMITEES. `local.settings.json`. N.U.N.C.A

El folder .vscode contiene config files generadas por la Azure Functions extension. El launch.json file configura el debugger, tasks.json define el build y host start.

El fichero requirements.txt (python) o package.json (Node.js) contienen las dependencias del proyecto para funcionar. El runtime instala estas dependencias durante deployment.

El fichero .funcignore especifica files y folders a exlcuir de los deployment packages, manteniendo tus artefactos con poco tamaño, omitiendo ficheros de testing, documentación, etc.

Use Azurite for Functions runtime storage dependency

Azurite provee de implementaciones locales de Azure Blob Storage, Queue Storage y Table Storage, que se comportan como si fuera un cloud service. Así, Azurite elimina la necesidad de crear un Storage account para desarrollo local

El runtime de las Azure Functions requiere una connection a un storage account (configurado a través de AzureWebJobsStorage) para coordinaciones internas. Esta dependencia existe aunque tu app use Azure Storage directamente.

Para desarrollo local puedes enrutas esta dependencia al Azurite emulator poniendo AzureWebJobsStorage como UseDevelopmentStorage=true en local.settings.json.

La manera más simple de usar Azurite es instalar su extension, la cual enciende el emulador cuando haces start del programa local.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "python"
    }
}

El valor UseDevelopmentStorage=true solo tiene efecto en local. Al lanzar la Function, Azure crea o requiere de un storage account automáticamente

Use emulators and local services for connected resources

Para servicios como BBDD, caches y otros data-level ops podemos usar emuladores y alternativas locales para poder testear y mantener los costes bajos.

Azure Cosmos DB emulator se ejecuta en local en Windows, Linux y macOS (a través de Docker). Soporta la NoSQL API y provee de un local endpoint que se comporta como el cloud service.

Azure Database for PostgreSQL no tiene un emulador, pero PostgreSQL es open source por lo que puedes instalar una instancia local.

Azure Managed Redis tampoco tiene emulador, pero Redis es open source.

Simplemente cambiamos los valores con local.settings.json.

Synchronize settings between local and Azure

La Azure Functions extension y Core Tools ofrecen maneras de sincronizar settings entre local y Azure.

En Visual Studio Code puedes hacer click derecho en la function app y seleccionar Download Remote Settings para bajarte los settings a tu local.settings.json.
También puedes Upload Local Settings para hacer push de local values a Azure.

Puedes encriptar tus local settings file con func settings encrypt para proteger secretos en tu maquina de desarrollo.

Read More

Azure Functions

El hosting plan que se elige para la Function App determina como inician las instancian, como escala la app bajo carga y cuanta memoria hay disponible.

Los dos planes enfocados a serverless AI workloads son: El Flex Consumption y el Premium plan

Cold start and why it matters for AI

Cold start es el delay que ocurre cuando la Azure Functions platform:

  • aloca una nueva instancia
  • carga el runtime
  • inicializa las dependencias de la app

Todo esto antes de que la instancia esté lista para manejar su primera request.

Cada serverless hosting plan que escala a zero sufre este cold start ya que no hay preallocated compute cuando llega la invocación inicial.

Las AI apps suelen amplificar el cold start por las grandes dependencias de grados y librerias de ML que tienen, además de los SDKs y entornos de ejecución de código.

El cold start es por instancia. Solo afecta a la primera request que se enrute a una nueva instancia.

Flex Consumption vs Premium

Son los dos planes enfocados a AI backends.

Flex Consumption

Flex consumption es el recomendado by default.

Características

  • Plan linux-only
  • scaling per-function
  • virtual network connectivity
  • memoria configurable por instancia (512 MB,2048 MB,4096 MB)
  • always-ready instances

Escala hasta 1000 instancias y cobra basado en active execution time + always-ready baseline.

El always-ready permite mantener un número mínimo de instancias calientes para funciones que sean sensibles a la latencia, mientas que otras Functions en la misma Function App se mantienen fully serverless y escaladas a 0.

Premium

Elimina el cold start del todo y mantiene siempre al menos una instancia en caliente.

Características

  • ofrece siempre al menos una pre-warmed instance
  • custom Linux image support
  • virtual network connectivity

Elige Premium cuando:

  • tus funciones se ejecutan continuamente (o casi)
  • el coste de always-on esté justificado
  • tengas cargas de computación más grandes de las que ofrece el flex
  • necesites desplegar functions usando custom container images

Otros planes

  • Dedicated (App Service) plan: cuando tienes underutilized App Service capacity ya existente y quieres ejecutar tus functions en esas instancias sin coste adicional
  • Container Apps hosting: Cuando las functions necesitan GPU access para model inference, custom OS-level packages o ejecutarse al mismo nivel que microservicios contenerizados en el mismo env
  • Consumption plan (Linux): Legacy serverless plan. Los nuevos proyectos deben usar Flex Consumption

Configure scaling and concurrency

El plan Flex Consumption introduce per-function scaling. Cada tipo de trigger escala de manera independiente basándose en su propia demanda por tipo.

Todas las HTTP functions de una Function App escalan juntas como grupo. El resto de tipos como queue triggers, timer triggers o Service Bus triggers escalan de manera independiente. Esta separacion significa que un aumento de peticiones de las queue, no compite por recursos con un aumento de las peticiones HTTP.

Instance memory el default son 2048 MB. Se puede subir a 4096 MB cuando tengamos cargas más grandes o para subir CPU-cores (van proporcionales).

Long-running AI tasks

MUY IMPORTANTE

Las HTTP functions tienen un timeout de 230 segundos impuesto por el Azure Load Balancer que no se puede cambiar, independiente del functionTimeout setting in host.json.

Todas las requests que se pasen de este tiempo devuelven un error al caller, aunque la function se puede seguir ejecutando en el backend. Esto es especialmente peligroso para las AI apps.

La recomendación es usar async request-reply pattern: La HTTP function

  1. acepta la request
  2. valida el input
  3. escribe un mensaje a la Service Bus queue
  4. devuelve inmediatamente un 202 Accepted con una URL de status

Entonces una function separada con Service Bus trigger pilla ese mensaje y ejecuta la long-running task sin ningún tipo de constraint, ya que las service bus-trigger Functions poder ejecutarse de manera indefinida en los planes Flex y Premium.

De este modo, cada componente - HTTP endpoint y Service Bus trigger - escalan de manera independiente.

/MUY IMPORTANTE

Read More

Publish custom events (Event Grid)

Create custom topic for AI events

Un custom topic tiene un user-defined endpoint donde tu app postea eventos.

Antes de poder publicar eventos, tienes que crear y configurar el topic y el schema de tus eventos.

Usa el input schema a cloudeventsschemav1_0 al crear el topic para que los eventos usen el formato standard CloudEvents.

az eventgrid topic create \
	--name ai-pipeline-events \
	--resource-group ai-platform-rg \
	--location eastus \
	--input-schema cloudeventschemav1_0

Después de crear el topic, necesitas credenciales para publicar eventos. Puedes obtener el topic endpoint y access key con Azure CLI

az eventgrid topic show \
	--name ai-pipeline-events \
	--resource-group ai-platform-rg \
	--query "endpoint" \
	--output tsv

az eventgrid topic key list \
	--name ai-pipeline-events \
	--resource-group ai-platform-rg \
	--query "key1" \
	--output tsv

Event Grid soporta 3 metodos de auth:

  • access key auth (header aeg-sas-key)
  • SAS token auth
  • Microsoft Entra ID

Construct events for AI ops

Cada custom event describe e implica un meaningful state change en tu sistema. Un evento bien construido incluye suficiente contexto como para que el consumer comience a procesar, pero sin llegar a meter todos los datos dentro. Los subscribers sacan los datos detallados de un data store usando IDs del event data.

CloudEvents event. type categoriza la op, source la fuente donde se origina, subject provee un path filtrable, data payload incluye metadatos sobre la op y una referencia donde el evento puede encontrar todos los detalles

{
    "specversion": "1.0",
    "type": "com.contoso.ai.InferenceCompleted",
    "source": "/services/content-moderation",
    "id": "evt-20250915-143000-001",
    "time": "2025-09-15T14:30:00Z",
    "subject": "/pipelines/moderation/image-classifier",
    "datacontenttype": "application/json",
    "data": {
        "requestId": "req-78901",
        "modelName": "content-classifier-v3",
        "modelVersion": "3.2.1",
        "processingDurationMs": 1250,
        "resultLocation": "https://results.blob.core.windows.net/output/req-78901.json",
        "status": "completed",
        "itemsProcessed": 1,
        "summary": {
            "classification": "safe",
            "confidence": 0.97
        }
    }
}

Al diseñar eventos:

  • Incluye IDs para correlacion: requestId o pipe run ID para tracear entre servicios distribuidos
  • Referencia resultados en vez de meterlos: Los resultados detallados van a un storage y se manda solo la referencia
  • Operational metadata: Campos como processingDurationMs o modelVersion permiten monitorizar trends
  • Provee un summary: asi los consumidores pueden tomar routing decisions sin tener que descargar el texto completo

Publish events using Event Grid SDK

El EventGridPublisherClient de la libreria azure-eventgrid maneja serializacion, atuh y retries.

crea un client y publica CloudEvent to custom topic

# Code fragment - focus on creating and sending a CloudEvent
from azure.core.credentials import AzureKeyCredential
from azure.core.messaging import CloudEvent
from azure.eventgrid import EventGridPublisherClient

endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]
key = os.environ["EVENTGRID_TOPIC_KEY"]

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(endpoint, credential)

event = CloudEvent(
    type="com.contoso.ai.InferenceCompleted",
    source="/services/content-moderation",
    data={
        "requestId": "req-78901",
        "modelName": "content-classifier-v3",
        "processingDurationMs": 1250,
        "resultLocation": "https://results.blob.core.windows.net/output/req-78901.json",
        "status": "completed"
    },
    subject="/pipelines/moderation/image-classifier"
)

client.send(event)

Para PROD usar DefaultAzureCredential para autenticar con manage identity - no usar keys

# Code fragment - focus on managed identity authentication
from azure.identity import DefaultAzureCredential
from azure.core.messaging import CloudEvent
from azure.eventgrid import EventGridPublisherClient

endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]

credential = DefaultAzureCredential()
client = EventGridPublisherClient(endpoint, credential)

Podemos publicar eventos en batches también

# Code fragment - focus on batch publishing
events = [
    CloudEvent(
        type="com.contoso.ai.StageCompleted",
        source="/services/embeddings",
        data={"pipelineRunId": "run-42", "stage": "embeddings", "status": "completed"},
        subject="/pipelines/rag/run-42"
    ),
    CloudEvent(
        type="com.contoso.ai.StageCompleted",
        source="/services/indexing",
        data={"pipelineRunId": "run-42", "stage": "indexing", "status": "completed"},
        subject="/pipelines/rag/run-42"
    )
]

client.send(events)

Publish events using REST API

Podemos publicar eventos enviando un HTTP POST directos al custom topic endpoint.

curl -X POST \
    -H "Content-Type: application/cloudevents+json; charset=utf-8" \
    -H "aeg-sas-key: $EVENTGRID_TOPIC_KEY" \
    -d '{
        "specversion": "1.0",
        "type": "com.contoso.ai.ModelRetrained",
        "source": "/services/training",
        "id": "evt-20250915-160000-001",
        "time": "2025-09-15T16:00:00Z",
        "subject": "/models/sentiment-v2",
        "datacontenttype": "application/json",
        "data": {
            "modelName": "sentiment-v2",
            "modelVersion": "2.1.0",
            "accuracy": 0.94,
            "trainingDurationMinutes": 45,
            "artifactLocation": "https://models.blob.core.windows.net/trained/sentiment-v2.1.0.tar.gz"
        }
    }' \
    "$EVENTGRID_TOPIC_ENDPOINT"

Read More

Event schemas and properties (Event Grid)

EventGrid vs CloudEvents schema

Event Grid soporta dos event schemas

  • CloudEvents v1.0 schema: recomendado para nuevas implementaciones. Event structure standard y protocol-agnostic. Este standard implica que los eventos producidos por tus AI services pueden interoperar con cualquier sistema que soporte CloudEvents, no solo Event Grid. Simplifica la integración multi-plataforma.
  • Event Grid schema (propietario): se mantiene por backward compatibility. NO se pueden intercambiar mensajes cloudevents-eventgrid

CloudEvents schema structure

IMPORTANTE

{
    "specversion": "1.0",
    "type": "com.contoso.ai.InferenceCompleted",
    "source": "/services/content-moderation",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "time": "2025-09-15T14:30:00Z",
    "subject": "/pipelines/moderation/batch-42",
    "datacontenttype": "application/json",
    "data": {
        "modelName": "content-classifier-v3",
        "requestId": "req-78901",
        "resultLocation": "https://storage.blob.core.windows.net/results/batch-42.json",
        "processingDurationMs": 1250,
        "status": "success",
        "itemsProcessed": 150
    }
}

Los atributos requeridos son:

  • specversion identifica la spec version del CloudEvents. Se pone siempre a "1.0"
  • type categoriza el evento. permite filtrar luego por event type. Se usa reverse-DNS naming convention para evitar colisiones
  • source identifica el sistema origen. Combinado con type permite identificar el contexto donde el evento ocurre
  • id es unico de este evento. Los consumers lo usan para detectar y deduplicar deliveries repetidas

Atributos opcionales:

  • subject provee de un path para filtrar. Se usa con valores jerarquicos que reflejen el contexto del evento permitiendo filtrar por prefijos y sufijos
  • time cuando ocurre el evento
  • datacontenttype formato del payload
  • data payload como tal

IMPORTANTE

Design custom event types

Los event types tienen que tener pensamiento detrás y estar bien diseñados. Cada event type tiene que representar un cambio de estado con un significado, que al menos un consumer deba conocer.

Ejemplos:

  • com.contoso.ai.InferenceCompleted
  • com.contoso.ai.EmbeddingsRefreshed
  • com.contoso.ai.AnomalyDetected
  • com.contoso.ai.ContentClassified

El event payload debe ser pequeño y estar enfocado. Incluir suficiente contexto para que el consumer pueda comenzar a procesar como por ej: resource URI, model name, processing duration y result summary.
Si necesitamos incluir muchos datos no meterlos en el payload, pasar una URL y que el consumer haga el fetch de la BBDD o storage.

Configure event type filtering

Las event subscriptions pueden filtrar eventos por type para que cada consumer reciba solo los que realmente necesita.

Puedes configurar event type filtering cuando creas una event subscription con el param --included-event-types

az eventgrid event-subscription create \
	--name inference-handler-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://inference-handler.azurewebsites.net/api/events \
	--included-event-types com.contoso.ai.InferenceCompleted

Puedes incluir múltiples event types en una única subscripción

Subject filtering (granular routing)

El field subject permite un filtrado basado en un path, usando prefijos y sufijos. Ej: /pipelines/embeddings/batch-42

De este modo los subscribers pueden filtrar eventos basándose en la jerarquía donde el evento se originó.

Subject filtering usa dos params en la event subscription

  • subjectBeginsWith: se usa para filtrar pipes o categorías específicas
  • subjectWendsWith: se usa para filtrar por tipo, versión o estado
az eventgrid event-subscription create \
	--name embeddings-sub \ 
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://embeddings-handler.azurewebsites.net/api/events \
	--subject-begins-with /pipelines/embeddings

Advanced filtering

Event Grid soporta filtros avanzados para buscar matches dentro del event body o extension attributes. Estos filtros permiten tomar decisiones de routing basándose en el contenido del event data como confidence scores, model names o processing statuses.

Tienen operadores como:

  • StringContains
  • NumberGreaterThan
  • StringBeginsWith
  • BoolEquals
  • IsNotNull

Se pueden definir hasta 25 filtros POR SUBSCRIPCIÓN

crea una subscription que recibe solo eventos donde data.status es igual a "flagged"

az eventgrid event-subscription create \ 
	--name flagged-content-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://review-service.azurewebsites.net/api/events \
	--advanced-filter data.status StringIn flagged

Para AI events, los filtros avanzados permiten hacer target de escenarios especificos y tomar decisiones sobre:

  • Confidence-based routing: Podemos enrutar los eventos a diferentes consumers según el confidence score
  • Model-specific subscriptions: Enrutar según el modelo
  • Status-based workflows: Crear workflows con diferentes consumers o pasos según el estado

Configure input and output schema

Al crear un custom topic el param input-schema controla los schemas que el topic acepta.

IMPORTANTE

Con este valor a cloudeventsschemaV1_0 aceptamos eventos con formato CloudEvents

az eventgrid topic create \
	--name ai-events \
	--resource-group ai-platform-rg \
	--location eastus \
	--input-schema cloudeventschemav1_0

Al crear la event subscription el param event-delivery-schema controla el formato de entrega al handler. Event Grid puede intercambiar entre Event Grid schema y CloudEvents schema durante la entrega, pero no se soporta CloudEvents-to-EventGrid conversion.

/IMPORTANTE

Read More

Configure delivery and retry policies (Event Grid)

How Event Grid delivers events

Event Grid entrega eventos enviando un HTTP POST al subscriber’s endpoint. El subscriber tiene que responder con un status code 20x para hacer acknowledge. Cualquier otra respuesta o ninguna durante el timeout period, hace trigger de un retry.
Event Grid espera 30s para la respuesta después de la entrega de un mensaje. Si el endpoint no responde, se encola el mensaje para retry.

Retry and error handling

Cuando Event Grid recibe un error como respuesta, evalúa el error type y decide si lo reintenta o no. No todos los errores se reintentan.

Los siguientes errores NO se reintentan ya que son issues permanentes:

  • 400 Bad Request: el event payload está mal formado
  • 413 Entity Too Large: el evento excede el size limit del endopint
  • 403 Forbidden

Para webhook endpoints un 401 Unauthorized NO se reintenta. Para Azure resource endpoints, 401 y 404 se reintentan tras 5 minutos

Para otro tipo de errores los reintentos son exponenciales. A los siguientes tiempos se les añade un randomizer para que no ocurran de golpe.

  1. 10s
  2. 30s
  3. 1m
  4. 5m
  5. 10m
  6. 30m
  7. 1h
  8. 3h
  9. 6h
  10. Cada 12 to 24h

Retry policy settings

Hay dos params para controlar el retry (se establecen al crear un event subscription):

(se para cuando se cumpla el primero)

  • Maximum number of attempts: default 30
  • Event TTL en minutos: default 24h
az eventgrid event-subscription create \
	--name moderation-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://moderation-service.azurewebsites.net/api/events \
	--max-delivery-attempts 5 \
	--event-ttl 30

Dead-letter destinations (undeliverable events)

Cuando Event Grid agota todos los retry attempts o el TTL del evento expira, se envia el evento no entregado a la dead-letter destination. Dead-lettering está disabled by default.

Para activarlo tienes que especificar un Azure Blob Storage container como dead-letter endpoint al crear la event subscription.

az eventgrid event-subscription create \
	--name moderation-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://moderation-service.azurewebsites.net/api/events \
	--max-delivery-attempts 5 \
	--event-ttl 30 \
	--deadletter-endpoint /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{storage-account}/blobServices/default/containers/dead-letters

Cada evento marcado como dead-letter incluye propiedades que ayudan a entender por qué ha fallado.

  • deadLetterReason ejemplo MaxDeliveryAttemptsExceeded o MaxRetryDurationExceeded
  • deliveryAttempts numero de reintentos
  • lastDeliveryOutcome el resultado del last delivery NotFound, TimedOut, Busy
  • publishTime tiempo en el que Event Grid acepto el evento
  • lastDeliveryAttemptTime

La aparición de dead-letter events indican problemas sistémicos que necesitan investigación. Un batch de dead-letter events puede indicar cambios de URL o fallos generales.

Se puede crear una event subscription al Blob Storage container que contiene las dead-letters. Así puedes notificar un monitoring service cuando llega una nueva dead-letter, permitiendo alertas automáticas o reprocesados.

Transient failures

El mecanismo de retry de Event Grid se encarga automáticamente de los fallos transientes.

Tenemos que diseñar endpoints que soporten este patrón:

  • devolver 200-204 para OK. 503 si el servicio está temporalmente overloaded. 400 para fallos permanentes que no queremos que se reintenten
  • Implementar procesamiento idempotente: Llevar un track de los event IDs ya procesados. Event Grid’s at-least-once guarantee significa que los consumidores pueden recibir el mismo evento más de una vez
  • Procesar (o hacer ack) rápidamente: si tu proceso de inferencia tarda +30s devuelve un 202 (Accepted) inmediatamente y procesa el evento asíncronamente

Output batching (high-throughput workloads)

Usamos batches para sistemas que generan o procesan un gran volumen de requests. Se configura batching en el event subscription con 2 params:

  • Maximum events per batch: 1-5000
  • Preferred batch size (kbs): 1-1024. Un evento que se pase de este tamaño se entrega en su propio batch

IMPORTANTE

Batching usa all-or-none delivery. El handler devuelve un success code para el batch entero. Si algún evento del batch falla, todos se reprocesan. Esto significa que tienes que diseñar el sistema para procesar eventos en batches o rechazar todos.

/IMPORTANTE

Monitor delivery outcomes

Event Grid publica metrics a través de Azure Monitor para tener visibilidad del estado del sistema.

  • Delivery success count
  • Delivery failure count
  • Matched events: eventos que hacen match de al menos un subscription filter
  • Dropped events: eventos que hacen match de una subscripcion pero se pasan de retry limits, sin dead-lettering
  • Dead-lettered events: eventos enviados a dead-letter destination después de un número exhaustivo de retries

Read More

Process messages reliably (Service Bus)

Reliable message processing asegura que la AI pipe tenga en cuenta y sepa manejar crasheos de micros, modelos que devuelven errores o payloads que contiene unexpected data.

Receive modes

Service Bus ofrece distintos receive modes que controlar como los brokers manejan el acknowledgment del message delivery. Esto es si priorizamos throughput o garantías de entrega.

Receive-and-delete mode

En receive-and-delete mode, Service Bus elimina el mensaje de la cola inmediatamente cuando se entrega el mensaje al consumidor. Si el consumer se crashea después de recibir el mensaje, pero antes de completar la entrega, el sistema pierde ese mensaje.

Este escenario ofrece el throughput más alto porque elimina el lock y el viaje de vuelta del ack.

Solo es para escenarios donde una pérdida ocasional del mensaje es aceptable y la prioridad es la velocidad de entrega

Ejemplo: telemetría en tiempo eral o non-critical logging - si perdemos algunas entradas no pasa nada

Peek-lock mode

IMPORTANTE

Es el modo por defecto y el recomendado para AI workloads

/IMPORTANTE

Service Bus pone un lock al mensaje durante una cantidad de tiempo configurable y lo envía al consumer, sin eliminarlo de la cola. El consumer debe marcar un estado explícito para el mensaje (complete, abandon, dead-letter, defer) durante la duración de este lock.

Si el lock expira antes de obtener un estado, Service Bus quita el lock y marca el mensaje como disponible para otro consumer. Este proceso en 2 fases asegura mínimo un procesamiento.

El trade-off de peek-lock es un menor throughput comparado con receive-and-delete. Para la mayoría de apps, este overhead es un mal menor.

ejemplo de peek-lock receive w. complete y dead-letter settlements

# Code fragment - focus on peek-lock receive with settlement
import json
from azure.servicebus import ServiceBusClient, ServiceBusReceiveMode
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    with client.get_queue_receiver(
        queue_name="inference-requests",
        receive_mode=ServiceBusReceiveMode.PEEK_LOCK,
        max_wait_time=30
    ) as receiver:
        for msg in receiver:
            try:
                payload = json.loads(str(msg))
                result = run_inference(payload)
                save_result(result, payload.get("document_id"))
                receiver.complete_message(msg)
            except json.JSONDecodeError:
                receiver.dead_letter_message(
                    msg,
                    reason="MalformedPayload",
                    error_description="Message body is not valid JSON"
                )
            except ModelNotFoundError:
                receiver.dead_letter_message(
                    msg,
                    reason="UnsupportedModel",
                    error_description=f"Model {payload.get('model')} is not available"
                )
            except TransientServiceError:
                receiver.abandon_message(msg)

estados disponibles

Complete

Método complete_message() lo marca como procesado OK y lo quita de la queue de manera permanente.

Abandon

Método abandon_message() hace release del lock sin quitar el mensaje de la queue, haciéndolo inmediatamente entregable a otro consumer.

Se suele abandonar un mensaje cuando hay un error transiente que se puede procesar bien en un retry, como un timeout o errores de red.

IMPORTANTE

Cada vez que un mensaje se abandona Service Bus incrementa el count de entrega, si este llega a un límite, el mensaje eventualmente se mueve a dead-letter.

/IMPORTANTE

Dead-letter

Método dead_letter_message() mueve el mensaje a la sub-queue dead-letter con una reason string y un error description.

Un mensaje se marca como dead-letter cuando hay un error no recuperable que hace que no se pueda procesar.

Marcarlo como dead-letter lo quita de la queue normal y lo preserva en otra queue para que lo investiguemos.

Ejemplo: JSON mal formado

Defer

Método defer_message() mantiene el mensaje en la queue pero lo borra de regular delivery. Solo puedes hacer retrieve de ese mensaje después por su sequence number usando receive_deferred_messages().

IMPORTANTE

Esto se utiliza para escenarios donde el consumer no puede procesar un mensaje en ese momento, pero si que podrá después más tarde, o cuando los mensajes necesitan un orden específico pero llegan desordenados.

/IMPORTANTE

Handle poison messages with max delivery count

Service Bus trackea cuantas veces se hace deliver de cada message. Cuando el delivery count se pasa del param max_delivery_count de la queue (default is 10), Service Bus automáticamente mueve el mensaje a la dead-letter queue con la razón MaxDeliveryCountExceeded.
Este mecanismo previene que mensajes que fallan constantemente bloqueen la queue.

Poniendo un valor más bajo (de 3 a 5) los poison messages se envían a la dead-letter más rápido, liberando capacidad para mensajes sanos.
Con un valor más alto los errores transientes tienen más posibilidades de arreglarse solos.

Monitor and process dead-letter queue

La dead-letter queue (DLQ) es una sub-queue que tiene toda queue y subscription

Mantiene los messages que expiran, se pasan del max delivery count, o que la app marca explicitamente como dead-letters. La DLQ existe automaticamente y no hay que crearla. Los mensajes en la DLQ persisten hasta que explicitamente los recibes y los completas.

Cada dead-letter message contiene dead_letter_reason y dead_letter_error_description que explican por qué se han movido allí. Para los mensajes que se pasan del max delivery count, la razón es MaxDeliveryCountExceeded. Para los mensajes que la app manda explicitamente a la DLQ se pasa la razón en la string dead_letter_message()

Monitorizar la DLQ es crítico ya que puede indicar cosas como un formato nuevo que no se puede procesar o un deployment de un modelo que no funciona.

Se puede poner alertas en Azure Monitor sobre la DLQ para hacer tracking del número de mensajes.

Accedes a la DLQ usando sub_queue=ServiceBusSubQueue.DEAD_LETTER

# Code fragment - focus on receiving and inspecting dead-letter messages
from azure.servicebus import ServiceBusClient, ServiceBusSubQueue
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    with client.get_queue_receiver(
        queue_name="inference-requests",
        sub_queue=ServiceBusSubQueue.DEAD_LETTER,
        max_wait_time=10
    ) as dlq_receiver:
        for msg in dlq_receiver:
            print(f"Dead-letter reason: {msg.dead_letter_reason}")
            print(f"Error description: {msg.dead_letter_error_description}")
            print(f"Correlation ID: {msg.correlation_id}")
            print(f"Delivery count: {msg.delivery_count}")
            print(f"Body: {str(msg)}")
            # Inspect and decide whether to resubmit or discard
            dlq_receiver.complete_message(msg)

Reprocess dead-lettered messages

Después de arreglar el fallo raíz del problema, se pueden volver a mandar los dead-letter messages a la cola original

El patrón conlleva

  1. leer cada mensaje de la DLQ
  2. crear UN NUEVO MENSAJE con el mismo body y properties
  3. volver a mandarlo a la queue original
  4. completar el dead-letter message para eliminarlo de la DLQ
# Code fragment - focus on resubmitting dead-lettered messages
with client.get_queue_receiver(
    queue_name="inference-requests",
    sub_queue=ServiceBusSubQueue.DEAD_LETTER,
    max_wait_time=10
) as dlq_receiver:
    with client.get_queue_sender("inference-requests") as sender:
        for msg in dlq_receiver:
            # Create a new message with the original body and properties
            new_message = ServiceBusMessage(
                body=msg.body,
                content_type=msg.content_type,
                correlation_id=msg.correlation_id,
                application_properties=msg.application_properties
            )
            sender.send_messages(new_message)
            dlq_receiver.complete_message(msg)

Con scripts de reprocesado automático podemos volver a mandar los DLQ messages en bulk o batches.

Manage lock duration for long-running AI ops

IMPORTANTE

Algunas ops como procesar docs muy grandes necesitan más tiempo del default lock duration. Este valor es configurable hasta 5 minutos, con un default de 1 minuto.

Si el lock expira antes de que el consumer resuelva el mensaje, este mensaje se marca como available para otro consumer, lo que duplica el procesamiento.

Para operaciones que se puedan pasar del lock duration hay dos opciones

  • extender el lock llamando a receiver.renew_message_lock() periodicamente durante el reprocesado
  • Usar la clase AutoLockRenewer la cual automáticamente renueva el lock en background las veces configuradas (es la opción más simple)

/IMPORTANTE

# Code fragment - focus on automatic lock renewal for long-running processing
from azure.servicebus import ServiceBusClient, AutoLockRenewer
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    renewer = AutoLockRenewer()
    with client.get_queue_receiver(
        queue_name="inference-requests",
        max_wait_time=30
    ) as receiver:
        for msg in receiver.receive_messages():
            # Renew the lock for up to 10 minutes
            renewer.register(receiver, msg, max_lock_renewal_duration=600)
            result = run_long_inference(msg)
            receiver.complete_message(msg)
    renewer.close()

Para operaciones realmente largas que consistemente se salten el tiempo y haya que extenderlo, es recomendable un approach en 2-fases

  1. El consumer recibe el mensaje, almacena la request en algún tipo de store persistente y lo marca como completado
  2. Un proceso standalone se encarga de coger las requests de ese store persistente e ir procesándolas a su ritmo

Este approach se salta el lock management y usa la queue solo para un reliable initial delivery

Read More

Azure Event Grid

Azure Event Grid es un servicio fully managed que conecta productores y consumidores de eventos, de forma desacoplada. Event Grid está preparado para manejar millones de eventos / s con una latencia mínima (<1s).

Opera como un servicio pub-sub que enruta eventos de productores a consumidores sin tener que administrar nosotros la infraestructura. El servicio ingesta eventos de otros servicios Azure, custom apps y/o partner systems y o bien entrega esos eventos a los endpoints de los consumidores, basándose en subscription filters, o son los mismos consumidores los que hacen pull de los eventos para leer a su ritmo.

Soporta dos modos de delivery:

  • push delivery: envía eventos al endpoint que especifiques. (ej: webhook, Azure Function, Service Bus queue)
  • pull delivery: permite a tu consumer app conectarse a Event Grid y leer eventos a su propio ritmo

Ambos modelos sirven modelos de arquitectura diferentes. La elección se basa en si los consumidores aceptan incoming HTTP requests o queremos que consuman eventos a demanda.

Event grid se integra con otros servicios de Azure a través de system topics y soporta custom app events a través de custom topics.
Esta combinación permite a tu app reaccionar a ambos tipos de eventos usando la misma infraestructura.

  • application-level: se completa una inferencia; un modelo acaba su entrenamiento
  • infrastructure-level: un blob aparece en un storage; una container image se envía al registry

Core components of Event Grid architecture

Events

Un event es una lightweight notification que describe un state change. Los eventos indican que algo ha ocurrido sin transportar el recurso completado entero (ej: “blob created”; “model training completed”). Si el consumer necesita los detalles del mensaje completo, el mismo hace retrieve del recurso.

Este diseño mantiene los eventos pequeños y rápidos de entregar.

Cada evento contiene metadata, que identifica que ha ocurrido, donde y cuando. El event body incluye un data payload con detalles de la operacion, pero el payload se espera que sea pequeño y compacto. (ej: la creación de un blob solo conllevaria el blob URL y el content type, pero no el blob en si mismo)

Event sources

Los event sources son servicios de Azure o custom apps que emiten eventos. Servicios como Blob Storage o Container Registry automáticamente publican eventos como system topics.

Custom apps pueden publicar eventos sobre custom topics que tu mismo crees. Una misma app puede actuar como ambos productor y consumidor.

Topics

Los topics son endpoints que reciben eventos de los productores. Hay de varios tipos

  • System topics: Event Grid crea system topics automaticamente para eventos de servicios de Azure. Cuando creas una event subscription para un recurso de Azure, el system topic aparece automaticamente. No puedes publicar directamente a system topics porque están restringidos para servicios de Azure.
  • Custom topics: user-defined endpoints donde tus custom apps envían eventos. Creas tu propio custom topic, configuras el input schema y publicas eventos al endpoint
  • Namespace topics: parte del Event Grid namespace resource y soporta ambos push y pull delivery. Namespace topics ofrecen capacidades adicionales como MQTT support y tienes más control sobre el consumo de eventos

No hay por que usar exclusivamente uno. Una app normal puede usar ambos por ej system y custom topics.

Event subscriptions

Un event subscription es un recurso de configuración que define que eventos vas a recibir de un determinado topic y donde se tienen que enviar.

Cada subscripcion especifica un topic en el que escucha, con filtros opcionales para seleccionar eventos, y un endpoint de destino (el event handler). Puedes crear multiples subscripciones sobre el mismo topic para filtrar eventos a diferentes handlers. Los filtros permiten reducir y seleccionar los eventos que cada subscripcion recibe por: event type, subject path o data attributes.

Event handlers

Los event handlers son los servicios de destino que reciben y procesan eventos.

Event Grid soporta varios handler types para push delivery:

  • Azure Functions: lightweight stateless event processing
  • Azure Event Hubs: ingesta eventos en una pipe de high-throughput
  • Azure Service Bus queues y topics: queues donde necesitas procesar con un orden
  • Webhooks: envia eventos a cualquier endpoint HTTP (incluidos custom services)
  • Azure Storage queues: Queue events para async processing por consumers

How AI architectures benefit from event-driven patterns

Los AI workflows conllevan muchos componentes loose coupled que necesitan coordinarse y comunicarse sin dependencias. Event-driven architecture pushea notificaciones a las partes interesadas tal y como ocurren los cambios.

Cuando llega un nuevo dataset al Blob Storage, Event Grid notifica inmediatamente a la pipe correspondiente, en vez de esperar un tiempo determinado para comprobar cambios. Este cambio reduce la latencia de minutos a segundos.

Event-driven también mejora el aislamiento de fallos. Si un consumidor experiencia un fallo, otros consumidores continúan recibiendo y procesando eventos de manera independiente.

Apply event-driven patterns to AI workload

Reactive data processing

Te subscribes a Blob Storage events (Microsoft.Storage.BlobCreated) como triggers para una AI pipe cada vez que hay nuevos datos o llegan docs. La pipe recibe el evento, hace retrieve del blob usando la URL del event data y procesa el evento.

Este patrón funciona para escenarios como document ingestion, RAG pipe, image classification o dataset preparation para model retraining.

Pipeline stage coordination

Multi-step AI pipes se benefician de custom events que señalen cambios entre transiciones.

Cuando un paso de la generacion de embeddings se completa, se envia un evento que hace trigger del proximo paso. Cada paso oepra independientemente y escala basandose en su propio workload.

Model lifecycle management

Puedes publicar custom events para model training completion, validar resultados y hacer promotions. Los servicios se subscriben a estos eventos para hacer update de sus endpoints, refrescar caches o enviar notificaciones

Read More

Structure messages (Service Bus)

El cómo estructuramos un mensaje determina como de eficientemente podemos procesar las requests. Con una buena estructura puedes hacer debug de los fallos, incluir metadatos para routing y tracking, y mantenernos dentro de los límites de nuestro tier de Service Bus.

Message anatomy

Un message de Service Bus se compone de:

  • body: lleva el payload. primary data que quieres transmitir
  • app properties: custom key-value metadata. util para enrutar, filtrar y trackear
  • system properties: propiedades añadidas por Service Bus o el SDK. Ejemplo message_id

Serializar prompts y model params

Podemos estructurar el body de un mensaje como JSON payload con todos los campos que necesita el consumer

El campo message_id se usa para identificar mensajes dentro de Service Bus. Si se activa duplicate detection en la queue, se usa este ID para descargar duplicados. Generar siempre un ID único por mensaje para evitar problemas de duplicación

# Code fragment - focus on creating a message with a JSON payload
import json
import uuid
from azure.servicebus import ServiceBusMessage

request_payload = {
    "prompt": "Extract the contract parties and effective date from this document.",
    "model": "gpt-4o",
    "temperature": 0.1,
    "max_tokens": 2000,
    "document_id": "doc-2025-0142"
}

message = ServiceBusMessage(
    body=json.dumps(request_payload),
    content_type="application/json",
    message_id=str(uuid.uuid4()),
    correlation_id="req-abc-12345",
    application_properties={
        "model_name": "gpt-4o",
        "priority": "standard",
        "document_type": "contract"
    }
)

Track requests w. correlation IDs

El correlation_id ofrece end-to-end request tracking a lo largo de la pipe. Debemos generar un ID único para cada request, ya que el mismo ID sigue al request desde el producer que lo encola, al consumer que lo procesa y al results store.

Al hacer debug de una inferencia fallida, puedes buscar los logs, colas y result stores por el correlation_id y ver el full lifecycle de la request.

# Code fragment - focus on propagating trace context in application properties
from opentelemetry import trace

current_span = trace.get_current_span()
span_context = current_span.get_span_context()

message = ServiceBusMessage(
    body=json.dumps(request_payload),
    correlation_id=correlation_id,
    application_properties={
        "traceparent": f"00-{format(span_context.trace_id, '032x')}-{format(span_context.span_id, '016x')}-01",
        "model_name": "gpt-4o"
    }
)

Handle large payloads with the claim-check pattern

Service Bus Standard tier soporta solo mensajes de 256 KB - el premium soporta hasta 100 MB.

El claim-check pattern permite separar el payload del mensaje. El producer encola un payload demasiado grande a Azure Blob Storage (u otro storage persistente) y envía al Service Bus un mensaje que contiene solo la blob URI como referencia.

De este modo el body se mantiene pequeño y solo mandamos la URL junto a los metadatos que necesitemos. El processor obtiene la el payload del storage usando la misma URI, y opcionalmente, borra el blob.

Esto también reduce los costes del broker throughput ya que hace las transferencias realmente pequeñas, y se puede usar en el Standard tier

# Code fragment - focus on the claim-check pattern for large payloads
import json
from azure.storage.blob import BlobServiceClient
from azure.servicebus import ServiceBusMessage

# Producer: upload the large payload to Blob Storage
blob_service = BlobServiceClient(
    account_url="https://<storage-account>.blob.core.windows.net",
    credential=credential
)
container_client = blob_service.get_container_client("documents")
blob_client = container_client.get_blob_client("doc-2025-0142.pdf")
blob_client.upload_blob(large_document_bytes)

# Send a claim-check message with the blob URI
claim_check = {
    "blob_uri": f"https://<storage-account>.blob.core.windows.net/documents/doc-2025-0142.pdf",
    "document_id": "doc-2025-0142",
    "model": "gpt-4o",
    "operation": "extract"
}

message = ServiceBusMessage(
    body=json.dumps(claim_check),
    content_type="application/json",
    correlation_id="req-abc-12345",
    application_properties={"pattern": "claim-check"}
)

Message TTL

La propiedad time_to_live define el tiempo de expiracion de un mensaje.

Cuando los mensajes expiran se pueden enrutar a la dead-letter queue paras ver los mensajes que no se procesaron a tiempo

# Code fragment - focus on setting time-to-live
from datetime import timedelta
from azure.servicebus import ServiceBusMessage

# Real-time classification: expire after five minutes
urgent_message = ServiceBusMessage(
    body=json.dumps(request_payload),
    time_to_live=timedelta(minutes=5)
)

# Batch processing: expire after 24 hours
batch_message = ServiceBusMessage(
    body=json.dumps(batch_payload),
    time_to_live=timedelta(hours=24)
)

Para batch processing donde la latencia no importa tanto es importante poner un TTL grande u omitirlo y usar el default de la queue

Batch messages for throughput

Cuando necesitamos enviar varias requests de a una usamos ServiceBusMessageBatch para agrupar mensajes en una única operación. Batchear reduce el numero de network round trips entre la app y el Service Bus broker.

El SDK administra el batch size automáticamente, asegurando que el total batch no se pasa del maximum size para tu tier.

El add_message() lanza MessageSizeExceededError cuando el mensaje se pasaría del batch size limit.

# Code fragment - focus on batch message sending
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.servicebus.exceptions import MessageSizeExceededError
import json

with client.get_queue_sender("inference-requests") as sender:
    batch = sender.create_message_batch()

    for request in pending_requests:
        message = ServiceBusMessage(
            body=json.dumps(request),
            content_type="application/json"
        )
        try:
            batch.add_message(message)
        except MessageSizeExceededError:
            # Batch is full, send the current batch and start a new one
            sender.send_messages(batch)
            batch = sender.create_message_batch()
            batch.add_message(message)

    # Send any remaining messages in the last batch
    if len(batch) > 0:
        sender.send_messages(batch)

Read More

Queues vs topics & subscriptions (Service Bus)

La primera decisión de ARQ con Azure Service Bus debe ser si usamos queues o topics + subscriptions.

Queues vs Topics

IMPORTANTE

Usamos queues cuando:

  • un único consumer necesita actuar en cada mensaje: Una pipe de doc extraction recibe un prompt, ejecuta un modelo, devuelve resultados
  • we want competing consumers for horizontal scaling: multiples consumers hacen pull de la misma queue. Service Bus asegura que cada mensaje solo es entregado a un único worker
  • no hay otros servicios que necesiten el mismo mensaje: el mensaje representa una task que se da por completado cuando un consumer lo ha procesado

Usamos topics + subscriptions cuando:

  • multiples servicios independientes reaccionan al mismo mensaje: una inferencia completa hace trigger de notificaciones, audit logs, dashboards y KPIs que se actualizan simultaneamente
  • necesitas content-based routing: Diferentes consumers reciben diferentes subsets de mensajes basándose en propiedades como priority level o document type
  • quieres añadir nuevos consumers sin modificar el producer: podemos crear nuevas subscriptions en cualquier momento sin tener que tocar el código del producer

/IMPORTANTE

Queues (single consumer)

Una queue de Service Bus entrega cada message a un único consumidor. Cuando tienes múltiples consumidores leyendo de la misma cola, Service Bus se asegura que cada mensaje sea procesado por un único consumidor.

Puedes escalar horizontalmente añadiendo más consumidores sin cambiar código. Cada consumidor se conecta de manera independiente a la queue, hace pull de los mensajes y los procesa.

Hay dos modos para controlar el ack:

  • Receive-and-delete mode: Service Bus borra el mensaje de la queue tan pronto como ha sido entregado
  • Peek-lock mode (default): Service Bus bloquea el message por una cantidad de tiempo y espera a que el consumidor explicitamente la complete, la abandone o lo marque como dead. Es el modo recomendado ya que provee at-least-once delivery. Si un consumer se crashea durante el procesado, el lock expira y el Service Bus lo vuelve a mandar a otro consumer

Las queues usan FIFO y se pueden usar para multi-step pipelines donde todos los pasos se deben ejecutar en orden

Topics + subscriptions (multiple consumers independientes)

Un Service Bus topic acepta mensajes de producers y distribuye copias a cada consumer subscrito. Cada subscripcion actua como una cola virtual independiente con sus propios consumidores.

Esté patrón se usa para escenarios donde múltiples servicios necesitan reaccionar al mismo evento de manera independiente. Ejemplo: terminamos el análisis de un documento y necesitamos notificar una alerta al usuario, un log para la BBDD para poder auditar, un aviso para el sistema de KPIs, etc. Cada subscripción procesa la copia del mensaje de manera independiente, por lo que un fallo en un sistema no afecta al resto.

Los Topics desacoplan los producers de los consumers. El producer publica mensajes a un topic sin saber cuantas subscripciones existen o lo que cada consumer hace con los mensajes. Puedes añadir nuevas subscripciones sin modificar código. Es muy util para comenzar con las necesidades y requisitos actuales y añadir nuevos servicios a medida que los necesitas sin modificar el código del resto.

Filter messages with subscription rules

Las subscriptions soportan filter rules que seleccionan messages según basándose en propiedades, permitiendo enrutar mensajes selectivamente sin escribir esa lógica en cada consumer.

IMPORTANTE

Service Bus evalúa filter rules al broken level, por lo que los mensajes que no hagan match con los filtros de una subscripción nunca se entregan a la subscripción de ese consumer.

Hay 3 tipos de filtros

  • Boolean filters: TrueFilter (default) acepta todos los mensajes; FalseFilter rechaza todos los mensajes
  • SQL filters: usa SQL-like expressions para evaluar contra app y system properties del mensaje
  • Correlation filters: matchean contra specific property values. Son más eficientes que los filtros SQL para exact-match scenarios

Se puede hacer tag de messages con app properties como model_name, priority o document_type y cada subscripción recibe solo mensajes que hacen match de ese filtro.

/IMPORTANTE

Ejemplo: filtramos por priority=high para enrutar peticiones urgentes a una VM con capacidad de GPU reservada.

# Code fragment - focus on creating a subscription rule with the management client
from azure.servicebus.management import ServiceBusAdministrationClient, SqlRuleFilter

admin_client = ServiceBusAdministrationClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
)

admin_client.create_rule(
    topic_name="inference-results",
    subscription_name="high-priority",
    rule_name="filter-high-priority",
    filter=SqlRuleFilter("priority = 'high'")
)

Send messages with queue/topic senders

El SDK azure-servicebus usa el mismo ServiceBusClient para ambos queues y topics.

  • get_queue_sender() envía a una queue
  • get_queue_receiver() queue el consumer

  • get_topic_sender() publica en un topic
  • get_subscription_receiver() subscribe el consumer

En el receiving side, un subscription consumer se conecta a una subscripción específica en un topic. Cada subscripcion mantiene su propia copia de los mensajes, por lo que consumir de una subscripcion no afecta a la disponibilidad de mensajes de otras subscripciones.

ServiceBusClient se usa junto a with statements para asegurar que las conexiones se cierran. Es lo mismo que llamar manualmente a client.close()

# Code fragment - focus on sending to a queue versus a topic
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    # Send to a queue (point-to-point)
    with client.get_queue_sender("inference-requests") as queue_sender:
        queue_sender.send_messages(
            ServiceBusMessage("queue message body")
        )

    # Send to a topic (publish-subscribe)
    with client.get_topic_sender("inference-results") as topic_sender:
        topic_sender.send_messages(
            ServiceBusMessage("topic message body")
        )
# Code fragment - focus on receiving from a subscription
with client.get_subscription_receiver(
    topic_name="inference-results",
    subscription_name="notifications"
) as receiver:
    for msg in receiver:
        print(str(msg))
        receiver.complete_message(msg)

Read More

Azure Service Bus

Azure Service Bus es un broker managed que provee de queuing y pub/sub para apps distribuidas. Sirve de capa de conexión media entre productores y consumidores. Por debajo usa AMQP (Advanced Message Queuing Protocol). Soporta ordering y detecta duplicados.

Tiene dos tipos de funcionamiento:

  • queues (point-to-point delivery)
  • topics + subscriptions (pub/sub o broadcast)

Cada service bus reside dentro de un namespace que sirve como contenedor y provee de allocation capacity. Puedes crear múltiples queues y topics dentro de un mismo namespace, y cada namespace tiene su propio endpoint en la forma <namespace-name>.servicebus.windows.net.

Para autenticar usa SAS (Shared Access Signatures) o Entra ID.

Why to use messaging

Las AI inference ops tienen una latencia no predecible, lo cual no está hecho para sync requests. Un documento simple puede tardar 2s y uno complejo 5m.

Messaging provee de un desacoplamiento entre producer y consumer. El producer envía un message al Service Bus queue y devuelve directamente un acknowledgment (ack) al cliente.
El consumer hace retrieve de los mensajes de la queue a su propio ritmo.

Este desacoplamiento permite escalar horizontalmente de manera independiente.

Core messaging patterns

Load leveling

El load leveling pattern usa una queue para absorber burst de requests, permitiendo a los consumidores que procesen a un ritmo estable.

Durante un pico de tráfico los mensajes se acumulan en la cola en vez de poner estrés a los consumers. Simplemente trabajan en el backlog independientemente del tamaño de este.

Competing consumers

El competing consumers pattern pone varios consumers como recibidores de una misma queue. El Service Bus entrega cada mensaje a un solo consumidor, por lo que los consumers leen de la misma cola sin procesar duplicar trabajo.

Cada consumer procesa a su propio maximum rate y podemos añadir más consumidores para incrementar el throughput sin ahcer cambios de código.

Si un consumer se crashea, como no ha hecho ack de la task, esta se pone como disponible para otros workers.

Temporal decoupling

El temporal decoupling pattern significa que los productores y los consumidores no tienen que estar online de manera simultánea. Un producer puede encolar requests con todos los consumers offline (por mantenimiento, deployment, etc).

Los mensajes se persisten en la cola hasta que los consumers vuelven y los procesan.

Esto se usa para critical AI platforms.

Manage backpressure with queue depth monitoring

Si la queue incrementa demasiado los mensajes se acumulan. En vez de tratar esto como un problema, podemos usarlo como nuestro trigger que nos indique cuando tenemos que escalar consumers.

Azure Monitor provee de métricas para revisar active message count para cada queue, y puedes activar alertas cuando superen un umbral custom

Azure Container Apps y Azure Functions soportan KEDA-based scalers que automáticamente añaden processing instances basandose en el Service Bus queue length

Service Bus Tiers

Standard Tier

Soporta queues, topics y subscriptions con recursos compartidos con otros tenants. Mensajes hasta 256 KB y variable throughput basado en la carga. Versión cost-effective.

Premium Tier

Ofrece recursos dedicados, por lo que tu workload no comparte con otros tenants. Soporta mensajes hasta 100 MB al usar AMQP (1 MB para HTTP). Ofrece latencia predecible y VNET integration / private endpoints. También ofrece availability zones.

Read More

Optimize data structures for vector storage (Redis)

Hash storage es más rápido y usa menos memoria porque los vectores se guardan como compact binary blobs.

Usar Hash cuando:

  • Tienes datos flat y simples, sin nested objects
  • necesitas maxima query performance
  • priorizas memory efficiency
  • tu modelo de datos no necesita objetos nesteados

JSON storage añade overhead debido al array structure, pero ofrece más flexibilidad.

Usar JSON cuando:

  • tus datos necesitan estructuras nested
  • necesitas almacenar múltiples vectores por item
  • tu aplicación ya usa JSON
  • la flexibilidad es más importante que la raw performance

Using Redis Hash for vectors

IMPORTANTE

Redis Hash es una data structure que guarda la información como pares clave-valor en una single key (ej: product:12345), similar a un diccionario. Cuando usas Hash para vector storage, tus embeddings se convierten en un campo (guardados como binary bytes) junto a otros datos. Hash es muy buena en performance y memory eficiente. Ofrece las queries más rápidas y el menor consumo de memoria.

/IMPORTANTE

Storing vectors in hash

# Code fragment - focus on Hash storage
import numpy as np

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

redis_client.hset(
    "product:12345",
    mapping={
        "name": "Wireless Mouse",
        "price": "29.99",
        "category": "electronics",
        "embedding": embedding.tobytes()  # Store vector as bytes
    }
)

Creating an index for Hash-based vectors

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

schema = (
    TextField("name"),
    NumericField("price"),
    TextField("category"),
    VectorField("embedding", "HNSW", {
        "TYPE": "FLOAT32",
        "DIM": 1536,
        "DISTANCE_METRIC": "COSINE"
    })
)

redis_client.ft("idx:products").create_index(
    fields=schema,
    definition=IndexDefinition(
        prefix=["product:"],
        index_type=IndexType.HASH
    )
)

Using Redis JSON for vectors

IMPORTANTE

Redis JSON guarda los datos como JSON documents, permitiendo guardar información jerárquica con nested objects y arrays.

A diferencia de Hash que está flatted, JSON te permite estructurar datos complejos de forma natural. Esta flexibilidad viene con un overhead mayor de memoria y query time comparado con Hash.

/IMPORTANTE

Storing vectors in JSON

Al guardar vectors en JSON, conviertes tu NumPy array a Python list usando tolist()

# Code fragment - focus on JSON storage
import redis.commands.json as json_commands

document = {
    "name": "Wireless Mouse",
    "price": 29.99,
    "category": "electronics",
    "embedding": embedding.tolist(),  # Convert to list for JSON
    "specs": {
        "color": "black",
        "wireless": True,
        "battery": "AA"
    }
}

redis_client.json().set("product:12345", "$", document)

Creating an index for JSON-based vectors

hay una diferencia con $. para los field names y as_name param para query references

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

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

redis_client.ft("idx:products").create_index(
    fields=schema,
    definition=IndexDefinition(
        prefix=["product:"],
        index_type=IndexType.JSON
    )
)

Read More

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.

Read More

Choose vector types and indexing strategies (Redis)

Vector data types

Redis usa FLOAT32 o FLOAT64, lo cual impacta en la memoria que consumen tus vectores (junto a la dimensionalidad de los embeddings) y en la precisión de las búsquedas semánticas,

IMPORTANTE

Para la mayoría de AI apps FLOAT64 no provee de ninguna mejora respecto a FLOAT32 porque los modelos no dan valores tan precisos. Para standard work se debe usar FLOAT32

/IMPORTANTE

# Code fragment - focus on vector data type configuration
VectorField(
    "embedding",
    "HNSW",
    {
        "TYPE": "FLOAT32",  # Standard choice for AI embeddings
        "DIM": 1536,
        "DISTANCE_METRIC": "COSINE"
    }
)

Match embeddings dimensions

La dimensionalidad tiene que ser la misma en Redis y en el embedding’s model output

# Code fragment - focus on dimension matching
embedding_models = {
    "small-model": 384,
    "medium-model": 768,
    "large-model": 1536,
    "xlarge-model": 3072,
}

# Create index matching your model
VectorField(
    "embedding",
    "HNSW",
    {
        "TYPE": "FLOAT32",
        "DIM": 1536,  # Must match model output
        "DISTANCE_METRIC": "COSINE"
    }
)

Distance metrics

IMPORTANTE

Para la mayoría de AI apps que envuelven texto, usaremos COSINE

  • COSINE: mide el ángulo entre vectores, ignorando la magnitud. Se usa para text embeddinsg y semantic similarity (OpenAI y lo que la mayoría de LLMs esperan)
  • L2 (Euclidean): mide la distancia recta en el espacio vectorial. Se usa para image embeddings y spatial data donde importan ambos la dirección y la magnitud
  • IP (Inner product): Computa el dot product entre vectores. Se usa solo cuanto tenemos embeddings pre-normalizados o modelos espacializados que lo requieren.

/IMPORTANTE

Es importante tener en cuenta la distancia para la que está entrenado el embeddings model - hay modelos que necesitan distance metrics específicas.

# Code fragment - focus on distance metric selection

# For text embeddings (most common)
VectorField("embedding", "HNSW", {
    "TYPE": "FLOAT32",
    "DIM": 1536,
    "DISTANCE_METRIC": "COSINE"  # Use for OpenAI, Cohere, Sentence Transformers
})

# For image embeddings
VectorField("image_embedding", "HNSW", {
    "TYPE": "FLOAT32",
    "DIM": 768,
    "DISTANCE_METRIC": "L2"  # Use for vision models
})

Read More

Broadcast (pub/sub) vs Coordinated distribution (streams)

Imagina que tienes tres worker services procesando requests.

Con pub/sub si suscribes a los 3 workers al mismo channel, cada worker recibe cada mensaje, lo que crea duplica el procesamiento.

Con Streams consumer groups cada request va a un solo worker, distribuyendo la carga de trabajo automáticamente.

Choosing the right approach

IMPORTANTE

Usa pub/sub cuando:

  • Todos los subscribers necesiten procesar el mismo mensaje (cache invalidation, config updates, notifications)
  • No necesites garantias de entrega o acknowledgments
  • Cada subscriber ejecuta acciones diferentes basados en el mismo evento

Usa Stream consumer groups cuando:

  • Cada mensaje deba ser procesado por exactamente un worker (task queues, job processing)
  • Si que necesites garantias de entrega o acknowledgments
  • Necesites escalar el procesamiento añadiendo más consumidores
  • Necesites poder manejar fallos y reasignar tareas

/IMPORTANTE

Pub/Sub: Broadcast to all subscribers

Cuando subscribes multiples servicios al mismo pub/sub channel, cada subscriber recibe cada mensaje. Redis pub/sub está diseñado para hacer broadcasting de eventos a múltiples consumidores de manera simultánea.

How broadcast distribution works

Redis delivers each published message to all active subscribers of that channel.

Si tienes 5 consumidores subscritos al channel ai:models:updated y publicas un mensaje en ese canal, los 5 servicios reciben el mismo mensaje de manera simultánea

# Publisher service
redis_client.publish('ai:cache:invalidate', 'embeddings-v2')

# All of these subscribers receive the message:
# - Subscriber 1 (API server instance 1)
# - Subscriber 2 (API server instance 2)
# - Subscriber 3 (Background worker)
# - Subscriber 4 (Analytics service)

Casos de uso

IMPORTANTE

Este diseño es intencional y es útil para escenarios específicos.

Usa pub/sub cuando necesites que todos tus servicios reaccionen al mismo evento de manera simultánea

  • Cache invalidation across microservices: publicamos en un channel para asegurar que cada instancia y cada microservicio recibe la señal de invalidar caché
# Model update service
def update_model(model_id, new_version):
    save_model_to_storage(model_id, new_version)
    # Notify all API instances to clear cache
    redis_client.publish('ai:models:cache:invalidate',
                        f'{model_id}:{new_version}')

# Each API instance subscribes and clears its own cache
pubsub = redis_client.pubsub()
pubsub.subscribe('ai:models:cache:invalidate')
for message in pubsub.listen():
    if message['type'] == 'message':
        clear_local_model_cache(message['data'])
  • Configuration updates for distributed services: Cuando al cambiar un param o una feature flag queremos que todos los servicios actualicen su conf
  • Real-time monitoring and metrics collection: podemos conectar multiples monitoring systems al mismo canal para que todos reciban los mismos datos sin interferir entre ellos
  • Event notification: Cuando un user completa una interacción y necesitamos avisar a múltiples servicios de manera simultánea

/IMPORTANTE

Cuando causa problemas

IMPORTANTE

No uses pub/sub cuando necesites:

  • Process tasks that should only run once: si tienes 3 consumers subscritos a un channel y publicas un mensaje, los 3 consumers procesan la misma request.
  • Load balancing across workers: pub/sub no distribuye mensajes - los duplica. No sirve para escalar horizontalmente.
  • Queue-like work distribution: pub/sub no garantiza que los mensajes han sido consumidos y no da acknowledgments. pub/sub es fire-and-forget. Los mensajes puedes ser procesados múltiples veces o ninguna - no hay manera de saberlo

/IMPORTANTE

Streams: Coordinated work distribution

Usar Streams cuando necesitas coordinar multiples subscribers para evitar duplica processing y distribuir carga de trabajo. Redis Streams consumer groups resuelven este problema. A diferencia de pub/sub, los consumer groups aseguran que cada mensaje vaya a un único subscriber.

How consumer groups distribute work

Los consumer groups particionan el Stream entre los group members. Cuando múltiples workers leen del mismo consumer group, Redis reparte automáticamente y asigna diferentes mensajes a diferentes workers. Cada mensaje se entrega a un único consumer en el grupo.
Esto ocurre automáticamente, no tienes que balancear nada.

# Setup: Create a consumer group once
redis_client.xgroup_create('ai:inference:queue', 'workers', '0', mkstream=True)

# Worker 1 gets messages 1, 3, 5
# Worker 2 gets messages 2, 4, 6
# Worker 3 gets messages 7, 8, 9

# All workers use the same group name but different consumer names
messages = redis_client.xreadgroup(
    groupname='workers',  # Same group
    consumername=f'worker-{worker_id}',  # Unique per worker
    streams={'ai:inference:queue': '>'},
    count=10
)

Setting up consumer groups in your worker services

Lo normal es crear el consumer group una única vez durante la inicialización de la App, y a partir de entonces que cada worker instance lea del mismo group.

cada worker obtiene tasks diferentes de manera automática, lo que permite un escalado horizontal

# Application startup code (runs once per deployment, not per instance)
def setup_worker_infrastructure():
    try:
        redis_client.xgroup_create(
            'ai:document:analysis',
            'analysis-workers',
            '0',  # Start from beginning
            mkstream=True  # Create stream if doesn't exist
        )
    except redis.ResponseError as e:
        # Group already exists, which is fine
        if 'BUSYGROUP' not in str(e):
            raise

# Worker processing loop (runs on each worker instance)
def process_documents():
    worker_id = f"{os.getenv('HOSTNAME')}-{os.getpid()}"

    while True:
        messages = redis_client.xreadgroup(
            groupname='analysis-workers',
            consumername=worker_id,
            streams={'ai:document:analysis': '>'},
            count=5,
            block=5000
        )

        for stream, tasks in messages:
            for task_id, task_data in tasks:
                analyze_document(task_data)
                redis_client.xack('ai:document:analysis',
                                 'analysis-workers',
                                 task_id)

Understand the > symbol and consumer positions

Al leer del consumer group el símbolo > le comunica a Redis que te dé nuevos mensajes que no hayan sido entregados todavía a ningún consumidor.

esto es lo que permite work distribution. Cuando worker-1 lee con > obtienes mensajes que worker-2 no recibe. Redis hace track de que mensajes se entregan a que consumidores

# Read only NEW messages not yet delivered to any consumer
redis_client.xreadgroup('workers', 'worker-1',
                       {'ai:queue': '>'}, count=10)

También podemos especificar un ID para leer de una posición específica, lo cual es útil para manejar pending messages.

# Read messages pending for this specific consumer
redis_client.xreadgroup('workers', 'worker-1',
                       {'ai:queue': '0'}, count=10)

Scaling workers dynamically

Una de las ventajas principales de los consumer groups es que permiten escalar horizontalmente sin cambios de código. Solo con escalar los micros es suficiente ya que automaticamente se distribuye el trabajo

# This same code runs on 2 workers or 20 workers
# Redis automatically distributes work based on how many workers are reading

def worker_main():
    setup_worker_infrastructure()  # Idempotent group creation

    worker_id = generate_unique_worker_id()

    while True:
        tasks = fetch_next_tasks('workers', worker_id)
        process_tasks(tasks)
        acknowledge_completion(tasks)

Handling failures and task reassignment

Los consumer groups tienen built-in mechanism para manejar fallos de los consumidores. Cuando un consumidor (worker) se crashea mientras procesa una task, esa task se queda en la lista de pendientes y se puede reasignar a otro healthy worker.

Detecting and claiming stuck tasks

Usa XPENDING para encontrar tasks que llevan en progreso demasiado tiempo y usa XCLAIM para reasignarlas.

# In a separate monitoring/health-check service or worker
def reassign_abandoned_tasks():
    # Check for tasks pending more than 5 minutes
    pending = redis_client.xpending_range(
        'ai:inference:queue',
        'workers',
        '-', '+',
        count=100
    )

    current_time = int(time.time() * 1000)

    for task in pending:
        task_id = task['message_id']
        idle_time = current_time - task['time_since_delivered']

        # Task processes for more than 5 minutes, likely stuck
        if idle_time > 300000:
            # Claim it for reprocessing
            redis_client.xclaim(
                'ai:inference:queue',
                'workers',
                f'recovery-worker-{os.getpid()}',
                300000,
                message_ids=(task_id,)
            )

            # Now process it
            reprocess_stuck_task(task_id)

Implement automatic retry in workers

Cada worker puede hacer check de sus propias tasks en startup, permitiendo automatic recovery después de los restarts.

def worker_startup_recovery():
    worker_id = get_worker_id()

    # Check if this worker holds any pending tasks from before crash
    pending = redis_client.xpending_range(
        'ai:inference:queue',
        'workers',
        '-', '+',
        count=100
    )

    # Filter for tasks assigned to this consumer
    my_pending = [p for p in pending if p['consumer'] == worker_id]

    # Retry each pending task
    for task in my_pending:
        try:
            retry_task(task['message_id'])
            redis_client.xack('ai:inference:queue', 'workers',
                            task['message_id'])
        except Exception as e:
            log_error(f"Retry failed for {task['message_id']}: {e}")

Read More

Task queues with Redis Streams

Redis Streams es una manera de implementar task queues y event processing en backend services. Se usa cuando necesitas encolar requests, coordinar pipes multi-proceso o gestionar long-running ops.
Los Streams te dan la durabilidad y la coordinacion que pub/sub no da.

Redis Streams

Los Streams son append-only task queues donde añades items y los consumers hacen pull de los items de la cola.

Puedes usar

  • XADD para añadir tasks
  • XREADGROUP para hacer pull de tasks en tu worker
  • XACK para marcar tasks como completas

IMPORTANTE

La diferencia de listas con los Streams es que estos trackean que consumidor ha procesado que task, y permiten retries automáticos si tu servicio se crashea.

/IMPORTANTE

What devs get from Streams

  • task survive crashes: cuando hay un reinicio, no pierdes las tasks no procesadas. Estas siguen en el Stream.
  • automatic retry handling: si tu codigo se crashea mientras procesa una task, esa task se pone como disponible para reintentarla automaticamente
  • built-in work distribution: cuando escalas a múltiples workers, Stream consumer groups automaticamente distribuyen tasks a lo largo de instancias sin duplicar trabajo
  • processing history: puedes hacer queries para ver que ha pasado en la pipe, hacer un replay para debuggear o que servicios nuevos se pongan al dia con datos historicos
  • simple async patterns: Los handlers pueden añadir tasks a los streams y volver inmediatamente mientras background workers procesan tasks a su ritmo

Stream task structure

Cada task que añades a un Stream obtiene su ID auto-generado y puede contener cualquier campo que necesites. Piensa que es como añadir un JSON object a una cola.

este ID se asegura que las tasks se procesan en orden

# Adding an AI processing task
stream_id = redis.xadd('ai:inference:requests', {
    'user_id': '12345',
    'model': 'gpt-4',
    'prompt': 'Summarize this document...',
    'priority': 'high'
})
# Returns ID like: '1699980000000-0'

Scaling with multiple workers

Cuando haces deploy de multiples instancias, los consumer groups se aseguran de que cada task solo vaya a un único worker. Creas un grupo una única vez y entonces cada worker instance lee del mismo grupo.

ahora puedes escalar horizontalmente - añade más worker instances para compartir la carga

# In your worker deployment/startup code
try:
    redis.xgroup_create('ai:inference:requests', 'workers', id='0', mkstream=True)
except redis.ResponseError:
    pass  # Group already exists

# In your worker's processing loop (runs on each instance)
while True:
    tasks = redis.xreadgroup('workers', 'worker-instance-1',
                             {'ai:inference:requests': '>'},
                             count=10, block=5000)
    for task_id, task_data in tasks:
        process_ai_task(task_data)
        redis.xack('ai:inference:requests', 'workers', task_id)

Cuando usar Streams

Redis Streams son ideales para escenarios donde queremos reliability y la persistencia de las tasks es importante.

  • API endpoints que encolan requests: En vez de bloquear la API mientras espera una request lo podemos en una cola y devolvemos el ID automáticamente. Los background workers lo procesan y hacen update de los resultados
  • Multi-step processing pipelines: Cuando procesar requiere multiples pasos todos en orden (extraer - analizar - resumir). Si cualquier paso falla, no pierdes progreso
  • Worker services que escalan horizontalmente: los streams distribuyen automaticamente el trabajo
  • Long running operations que necesitan retry
  • System requiring processing history: cuando necesitamos un historial para ver que ha pasado y cuando

Code Examples

Adding AI tasks to a queue

Usa XADD para añadir a un Stream. Cada task tiene un ID unico.

# Your API handler code
def queue_inference_request(user_prompt, model_name):
    task_id = redis.xadd('ai:inference:queue', {
        'prompt': user_prompt,
        'model': model_name,
        'user_id': current_user.id,
        'requested_at': datetime.now().isoformat()
    })
    return task_id

Processing tasks in your worker service

Worker services usan XREADGROUP para hacer fetch de tasks desde un Stream y XACK para marcarlas como completadas.

# Worker service processing loop
def process_ai_tasks():
    # One-time setup: create consumer group
    try:
        redis.xgroup_create('ai:inference:queue', 'workers', id='0', mkstream=True)
    except:
        pass  # Already exists

    # Main processing loop
    while True:
        # Get up to 5 tasks, wait 5 seconds if queue empty
        messages = redis.xreadgroup(
            groupname='workers',
            consumername=f'worker-{os.getpid()}',
            streams={'ai:inference:queue': '>'},
            count=5,
            block=5000
        )

        for stream, tasks in messages:
            for task_id, task_data in tasks:
                try:
                    # Do your AI processing
                    result = run_inference(task_data['prompt'], task_data['model'])
                    save_result(task_id, result)

                    # Mark task complete
                    redis.xack('ai:inference:queue', 'workers', task_id)
                except Exception as e:
                    # Task stays in pending, will retry
                    log_error(f"Task {task_id} failed: {e}")

Handling failed tasks

Usa XPENDING para encontrawr tasks que han estado procesando demasiado tiempo y XCLAIM para reasignarlas. Esto se encarga de casos donde los workers se crashean a medio del proceso.

# Check for tasks that have been pending too long (stuck/crashed)
def retry_stuck_tasks():
    pending = redis.xpending('ai:inference:queue', 'workers', '-', '+', 10)

    for task in pending:
        task_id = task['message_id']
        idle_time = task['time_since_delivered']

        # If task pending more than 5 minutes, reassign it
        if idle_time > 300000:  # milliseconds
            redis.xclaim('ai:inference:queue', 'workers',
                        f'worker-{os.getpid()}', 0, [task_id])

Monitoring queue health

Usa XINFO para obtener metricas de Stream queues. Estos datos son utiles para dashboards y alertas.

# Get Stream metrics for your application dashboard
def get_queue_stats():
    info = redis_client.xinfo_stream('ai:documents:queue')
    groups = redis_client.xinfo_groups('ai:documents:queue')

    return {
        'total_tasks': info['length'],
        'pending_tasks': groups[0]['pending'],
        'consumers': groups[0]['consumers']
    }

Trade-offs a considerar

  • Memory management es TU responsabilidad: A diferencia de pub/sub donde los mensajes desaparecen despues de ser entregamos, Stream tasks se mantienen en memoria hasta que tu los borrar. Para high-volume queues necesitas encargarte de limpiar
# Trim to most recent 10,000 tasks when adding new ones
redis.xadd('ai:inference:queue', task_data, maxlen=10000, approximate=True)

# Or trim periodically in your worker after acknowledging tasks
if task_count % 100 == 0:  # Every 100 tasks
    redis_client.xtrim('ai:documents:queue', maxlen=10000, approximate=True)
  • Slighty higher latency than pub/sub: Streams añaden unos ms de latencia por la persistencia y el ack tracking. Si necesitas esos ms de latencia, usa pub/sub
  • Más complejidad: Necesitas gestionar consumer groups, ack, y pending task checks. Pub/sub es más simple pero a cambio obtienes esa erliability
  • Tasks no auto-expiran: Las tasks completadas se quedan en el Steram hasta que se borran

Read More

Redis pub/sub

Azure Managed Redis incorpora messaging capabilities a través del patrón publish/subscribe (pub/sub). Esto permite comunicación asíncrona en tiempo real entre diferentes partes de tu AI app.

Este modelo permite a los publishers enviar mensajes a named channels sin tener detalles de quién los va a recibir, o sin saber si hay alguien escuchando. Los subscribers pueden escuchar uno o más canales y recibir los mensajes publicados, creando una loosely coupled, event-driven AI architecture.

Redis pub/sub es útil en AI apps donde los componentes necesitan reaccionar inmediatamente a eventos sin bloqueos.

Como funciona pub/sub

  • at-most-once delivery: los mensajes se entregan a los subscribers que están activamente conectados cuando se publica el mensaje. No hay garantías si un subscriber se desconecta temporalmente.
  • no message persistence: los mensajes existen solo en memoria mientras se distribuyen a los subscribers. Una vez entregados no se guardan por Redis. Esto lo hace ideal para real-time notifications pero no es util para escenarios que requieren persistencia de mensajes
  • fire-and-forget: Los publishers no saben si hay subscribers que reciben los mensajes. Este desacoplado lo hace muy fuerte para el escalado, pero significa que no hay confirmación
  • high throughput

Límites a considerar

  • No message durability: Los mensajes que llegan cuando no hay subscribers escuchando se pierden para siempre. Si un subscriber se desconecta temporalmente, se pierde los mensajes que hayan llegado mientras estaba offline
  • No delivery guarantees: Los publishers no saben si alguien recibe los mensajes correctamente. Si todos los subscribers están offline, los mensajes se pierden
  • Memory-only operation: Los mensajes solo se mantienen en memoria, nunca en disco. Redis pub/sub no es útil para escenarios que requieren de persistencia de los mensajes, un orden procesado o replay capabilities

Cuando usar pub/sub

Usarlo cuando necesites:

  • coordinación en tiempo real con latencia sub-millisecond
  • broadcasting updates a multiples componentes de manera simultanea
  • un loose coupling entre micros
  • high throughput messages
  • simple event distribution
  • parallel processing triggers

Channel naming and patterns

Los canales en Redis son strings

ai:conversations:123       # Conversation-specific AI events
ml:model:predictions       # ML model prediction results
ai:training:status         # Model training status updates
embeddings:cache:refresh   # Vector embedding cache updates

Redis soporta pattern matching para los subscriptores, permitiendo a los componentes escuchar en múltiples canales relacionados

ai:conversations:*        # All conversation AI events
ml:models:*:status       # All model status updates
ai:*:predictions        # All AI prediction events

Code examples

publish events

Usa PUBLISH para enviar messages a channels.

# Publish a cache invalidation event
def notify_model_updated(model_name, version):
    message = f"{model_name}:{version}"
    redis_client.publish('ai:models:updated', message)

# Publish embedding refresh notification
def notify_embeddings_refreshed(collection_id):
    redis_client.publish('ai:embeddings:refresh', collection_id)

subscribe to channels in worker services

Usa SUBSCRIBE para escuchar a canales específicos. Los subscriben son servicios que corren en background y reaccionan a eventos

# Subscribe to specific channels
pubsub = redis_client.pubsub()
pubsub.subscribe('ai:models:updated', 'ai:embeddings:refresh')

# Listen for messages
for message in pubsub.listen():
    if message['type'] == 'message':
        channel = message['channel']
        data = message['data']

        if channel == 'ai:models:updated':
            # Clear model cache
            clear_model_cache(data)
        elif channel == 'ai:embeddings:refresh':
            # Refresh embedding cache
            refresh_embeddings(data)

use pattern subscriptions

Usa PSUBSCRIBE para subscribirte a múltiples canales con pattern matching. Esto es útil cuando quieres escuchar en todos los canales de una categoría.

# Subscribe to all AI-related channels
pubsub = redis_client.pubsub()
pubsub.psubscribe('ai:*')

# Handle messages from any AI channel
for message in pubsub.listen():
    if message['type'] == 'pmessage':
        pattern = message['pattern']  # 'ai:*'
        channel = message['channel']  # Actual channel name
        data = message['data']

        print(f"Received on {channel}: {data}")
        handle_ai_event(channel, data)

broadcasting to WebSocket clients

Combina pub/sub con WebSocket connections para pushear eral-time updates to browser clients

from fastapi import FastAPI, WebSocket
import redis.asyncio as redis
import asyncio

app = FastAPI()

# Background task to listen for Redis pub/sub messages
async def redis_listener(websocket: WebSocket):
    redis_client = redis.Redis(
        host='your-redis.redis.cache.windows.net',
        port=<PORT>,
        password='your-access-key',
        ssl=True,
        decode_responses=True
    )

    async with redis_client.pubsub() as pubsub:
        await pubsub.subscribe('ai:predictions:ready')

        async for message in pubsub.listen():
            if message['type'] == 'message':
                # Forward Redis message to WebSocket client
                await websocket.send_json({
                    'type': 'prediction',
                    'data': message['data']
                })

@app.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: str):
    await websocket.accept()
    await redis_listener(websocket)

Read More

Implement data ops (Redis)

IMPORTANTE

Azure Managed Redis soporta standard Redis commands para data ops. Redis soporta varios tipos de datos más allá de strings.

Data type Ops
string operations String ops (SET, GET, MSET, MGET) funcionan con texto o datos serializados. ATENCIÓN: Al usar decode_responses=True en la conexión, Redis automáticamente convierte byte responses en strings. Para datos binarios como imágenes poner decode_responses=False para trabajar con raw bytes.
hash operations Redis Hashes (HSET, HGET, HGETALL) guarda pares clave-valor. Es ideal para representar datos estructurados. Los hashes son más memory-efficient que guardar cada campo como una key separada.
list operations Redis Lists (LPUSH/RPUSH, LPOP/RPOP, LRANGE) son colecciones ordenadas de strings, perfectas para queues, activity feeds o items recientes. Soporta ambos stack LIFO y queue FIFO.
numeric operations Redis proporciona incrementos y decrementos atómicos (INCR, DECR, INCRBY, DECRBY) que funcionan con string values numéricos. Al ser atómicos lo hace ideal para contadores, rate limits y distributed counting scenarios with race conditions. Los valores se guardan como strings pero Redis los trata como ints para estas operaciones

/IMPORTANTE

Usamos la librería redis-py. Soporta ambos sync y async ops.

Uso standard de Redis

import redis

# Create a Redis client
r = redis.Redis(
    host='your-redis-instance',
    port=10000,
    ssl=True,
    decode_responses=True,  # Convert byte responses to strings automatically
    password='your-access-key'
)

Para PROD podemos usar Entra ID con redis-entraid

import redis
from azure.identity import DefaultAzureCredential
from redis_entraid.cred_provider import create_from_default_azure_credential

# Create credential provider using DefaultAzureCredential
credential_provider = create_from_default_azure_credential(
    ("https://redis.azure.com/.default",),
)

# Create a Redis client with Azure Entra ID authentication
r = redis.Redis(
    host='your-redis-instance',
    port=10000,
    ssl=True,
    decode_responses=True,  # Convert byte responses to strings automatically
    credential_provider=credential_provider
)

Basic data ops

Get and Set ops

obtener y guardar valores

# Store a value
result = r.set('user:1001:name', 'Alice Smith')
print(f"SET operation successful: {result}")  # Returns True

# Retrieve the value
name = r.get('user:1001:name')
print(f"Retrieved name: {name}")  # Output: Alice Smith

Los Hashes guardan multiples pares clave-valor en una sola key. Ideal para estructuras como user profiles

# Store multiple fields in a hash
r.hset('user:1001', mapping={
    'name': 'Alice Smith',
    'email': 'alice@example.com',
    'age': '28'
})

# Retrieve a single field
name = r.hget('user:1001', 'name')
print(f"Name: {name}")  # Output: Alice Smith

# Retrieve all fields
user_data = r.hgetall('user:1001')
print(f"User data: {user_data}")  # Returns dict with all fields

Multiple key ops

Cuando necesitas trabajar con multiples string keys de manera simultanea usa MSET y MGET para mejor performance.

# Set multiple keys at once
r.mset({
    'user:1001:name': 'Alice Smith',
    'user:1001:email': 'alice@example.com',
    'user:1001:age': '28'
})

# Get multiple values at once
values = r.mget('user:1001:name', 'user:1001:email', 'user:1001:age')
print(f"User data: {values}")  # Returns list of values

Para Hash ops, multiple key ops puede involucrar trabajar con multiple hash keys

# Using pipeline for multiple hash operations (efficient)
pipe = r.pipeline()
pipe.hgetall('user:1001')
pipe.hgetall('user:1002')
results = pipe.execute()
# Returns list of dicts, one for each hash

# Or retrieve specific fields from multiple hashes
pipe = r.pipeline()
pipe.hget('user:1001', 'name')
pipe.hget('user:1002', 'name')
names = pipe.execute()
# Returns list of names: ['Alice Smith', 'Bob Jones', 'Carol White']

Check Key existence

Antes de sacar o actualizar datos verificar que existen con EXISTS - se puede usar con todos los tipos de datos

# Check if a key exists
if r.exists('user:1001:name'):
    print("Key exists")

# Check multiple keys
count = r.exists('user:1001:name', 'user:1001:email', 'user:9999:name')
print(f"Number of existing keys: {count}")  # Returns 2

Delete ops

Borramos keys de la cache con DELETE cuando los datos ya no se necesitan o se vuelven obsoletos. DELETE funciona para todos los tipos de data types. Borra la key y sus datos asociados.

# Delete a single key
result = r.delete('user:1001:name')
print(f"Keys deleted: {result}")  # Returns count of deleted keys

# Delete multiple keys
result = r.delete('user:1001:email', 'user:1001:age')
print(f"Keys deleted: {result}")

Working with expiration

Es crucial poner expiration times para que se invaliden automaticamente. EXPIRE, SETEX, TTL funcionan con todos los data types.

Set value with expiration

Usamos SETEX para hacer set de un string value y su fecha de expiracion en una sola operacion atomica. Para otros datos como Hashes o Listas primero se guardan los datos, luego se usa EXPIRE para añadir fecha de expiración.

# Set a key with 60-second expiration
r.setex('session:abc123', 60, 'user_data')

# Alternative: Set value with expiration in milliseconds
r.psetex('temp:data', 5000, 'temporary_value')  # Expires in 5000ms

Add expiration to existing keys

Añadimos fecha de expiracion a todas las keys que ya existen en cache. Usamos EXPIRE, PEXPIRE, EXPIREAT. Funcionan con todos los tipos de datos

# Set a key without expiration
r.set('user:1002:preferences', 'dark_mode')

# Add 3600-second (1 hour) expiration
r.expire('user:1002:preferences', 3600)

# Set expiration in milliseconds
r.pexpire('user:1002:preferences', 3600000)

# Set expiration at specific Unix timestamp
import time
expire_at = int(time.time()) + 7200  # 2 hours from now
r.expireat('user:1002:preferences', expire_at)

Check y manage TTL

Monitorizamos el TTL para saber cuando expiran las keys. TTL, PTTL, PERSIST funcionan con todos los tipos de datos.

# Get TTL in seconds
ttl = r.ttl('user:1002:preferences')
if ttl == -1:
    print("Key exists but has no expiration")
elif ttl == -2:
    print("Key does not exist")
else:
    print(f"Key expires in {ttl} seconds")

# Get TTL in milliseconds
ttl_ms = r.pttl('user:1002:preferences')
print(f"Key expires in {ttl_ms} milliseconds")

# Remove expiration (persist the key)
r.persist('user:1002:preferences')

Cache invalidation patterns

Una cache efectiva asegura que tu app sirve datos frescos y mantiene una buena performance.

Time-based invalidation

La manera más simple. Usamos TTL para expirar automaticamente los datos de la cache después de un tiempo.

def cache_database_query(query_key, query_function, ttl=300):
    """
    Cache database query results with automatic expiration.

    Args:
        query_key: Cache key for the query
        query_function: Function that executes the database query
        ttl: Time to live in seconds (default: 5 minutes)
    """
    # Check if result is cached
    cached_result = r.get(query_key)
    if cached_result:
        print("Cache hit")
        return cached_result

    # Execute query and cache result
    print("Cache miss - executing query")
    result = query_function()
    r.setex(query_key, ttl, result)
    return result

# Usage example
def get_product_details():
    # Simulate database query
    return "Product: Laptop, Price: $999"

product_data = cache_database_query('product:12345', get_product_details, ttl=600)

Manual invalidation on update

Cuando los datos cambian, hacemos update o remove de los datos en cache de manera explicita para mantener consistencia

def update_user_profile(user_id, new_data):
    """
    Update user profile and invalidate related cache entries.
    """
    # Update database (simulated)
    save_to_database(user_id, new_data)

    # Invalidate all related cache keys
    cache_keys = [
        f'user:{user_id}:profile',
        f'user:{user_id}:summary',
        f'dashboard:user:{user_id}'
    ]
    deleted = r.delete(*cache_keys)
    print(f"Invalidated {deleted} cache entries")

def save_to_database(user_id, data):
    # Placeholder for database operation
    pass

Cache-aside pattern with expiration

Implementar el patrón cache-aside (lazy loading) con expiración automática para optimal cache usage

def get_user_data(user_id, ttl=3600):
    """
    Retrieve user data using cache-aside pattern.

    Args:
        user_id: User identifier
        ttl: Cache expiration in seconds (default: 1 hour)
    """
    cache_key = f'user:{user_id}:data'

    # Try to get from cache
    cached_data = r.get(cache_key)
    if cached_data:
        return cached_data

    # Cache miss - fetch from database
    user_data = fetch_from_database(user_id)

    # Store in cache with expiration
    if user_data:
        r.setex(cache_key, ttl, user_data)

    return user_data

def fetch_from_database(user_id):
    # Placeholder for database query
    return f"User data for {user_id}"

Pattern-based invalidation

Borramos multiples keys relacionadas usando pattern matching con el comando SCAN (no KEYS, lo cual bloquea el server)

def invalidate_user_cache(user_id):
    """
    Invalidate all cache entries for a specific user.
    Uses SCAN for non-blocking pattern matching.
    """
    pattern = f'user:{user_id}:*'
    cursor = 0
    deleted_count = 0

    while True:
        cursor, keys = r.scan(cursor, match=pattern, count=100)
        if keys:
            deleted_count += r.delete(*keys)
        if cursor == 0:
            break

    print(f"Invalidated {deleted_count} keys for user {user_id}")

# Usage
invalidate_user_cache(1001)

Best practices

  • Use connection pooling: La libreria redis usa automaticamente connection pooling, pero es algo que se puede configurar
  • Handle errors gracefully
  • Choose appropiate TTL values
    • Frequent chaging data: 1-5 mins
    • Moderate change rate: 15-60 mins
    • Relative stable data: 1-24 hours
    • Static reference data: +24 hours

Read More

Azure Managed Redis

Azure Managed Redis es un data store en memoria basado en Redis Enterprise. La versión Enterprise mejora la performance y fiabilidad de la community edition. Es managed, por lo que microsoft opera el servicio.

Azure Managed Redis puede mejorar la performance y escalabilidad de una aplicación que tiene un uso heavy de backend data stores, ya que al almacenar los datos frecuentes en la memoria del servidor permite leer más rápido.

Common caching strategies

Data Cache

Los datos se guardan en la caché al ser pedidos por una petición. Cuando la aplicación necesita datos primero mira si están en la caché de Redis. Si los datos no se encuentran, los saca de la BBDD y los almacena en Redis para queries posteriores.

Cuando la app hace cambios en los datos, tiene que invalidar o actualizar la caché correspondiente para mantener consistencia. El servicio soporta un TTL para borrar automáticamente datos viejos y hay eviction policies para cuando Redis se queda sin memoria.

Content cache

Almacenamos el contenido estático de la web como headers, footers, banners, nav menus. Estos rara vez cambian por lo que se pueden cachear. Reduce el server processing time y loading. Permite a los web servers servir más usuarios de forma concurrente.

Session store

Session store es útil para shopping carts, user preferences, auth tokens y otros datos user-specific que la web mantiene a través de requests. Se usa la caché para esto ya que guardar datos directamente en las cookies impacta negativamente a la performance.

La solución típica es guardar un session ID en la cookie, y usar esta ID para hacer retrieve de todos los datos de la sesión. Una implementación tradicional lee esto de la BBDD, pero Redis es más rápido leyendo esto de la memoria.

Redis Tiers

  • Memory Optimized: necesitas memoria pero no CPU (ratio memoria-vCPU de 8:1). Lower price point.
  • Balanced (Memory + Compute): (ratio memoria-vCPU de 4:1). Ideal para standard workloads
  • Compute Optimized: necesitas CPU pero no memoria (ratio memoria-vCPU de 2:1). Ideal para apps que necesitan la mejor performance

Redis Libraries

Client library Language
StackExchange.Redis C#/.NET
Lettuce Java
node_redis Node.JS
redis-py Python

Reddis supports two clustering policies

  • Enterprise clustering policy - all client libraries support it
  • OSS (Open Source Software) clustering policy - it depends by client library - check that it supports it

Commands

Microsoft manages the conf and management of Redis, which disables some commands by default

(no entro en detalle en esto de momento)

Development best practices

Data design and performance

  • use smaller values: divide larger data chunks into multiple keys with smaller values
  • handle large responses: optimize for many small values, increase VM size (higher bandwidth)
  • use pipelining: choose clients that support Redis pipelining for better network efficiency
  • avoid expensive operations: Don’t use KEYS in PROD; use SCAN for iterating over keys

Network and connectivity

  • co-locate resources: place Redis and app instances in the same Azure region
  • use hostnames: rely in hostnames instead of public UP addresses
  • enable TLS

Monitoring and scaling

Monitorizar estas métricas y escalar cuando pasen del 75%

  • Used memory %
  • CPU usage
  • Connected Clients
  • Network bandwidth

Configuration

  • Choose the right tier: based on memory, balanced or compute
  • Enable high availability: Use high availability for PROD workloads; disable for DEV envs
  • Implement data protection: Enable data persistence for quick recovery or use import/export for periodic backups

Read More

Tune PostgreSQL for pgvector

(leer este post muy por encima; saber más o menos para que son, pero esto es ya mucho detalle; doc og)

pgvector compute and memory requirements

Los cálculos de distancias vectoriales son muy diferentes a una BBDD tradicional. Para una búsqueda vectorial de proximidad con 1536 dimensiones cada búsqueda conlleva 1536 operaciones con floats. Buscar en 1.000.000 de vectores sin un índice, requiere de 1.5 billion operaciones por query.

Esto también depende de la función de distancia que escojamos:

  • L2 (Euclidean) distance <-> - es la más costosa computacionalmente hablando
  • Cosine distance <=> - relación coste/performance media. Recomendada a usar para recommendation engines y semantic search ya que procesa vectores de diferentes magnitudes de manera consistente
  • Inner product <#> - es la más rápida pero necesita vectores pre-normalizados. A utilizar si tenemos vectores normalizados ya que requiere menos computación (muchos modelos de OpenAI ya devuelven los vectores normalizados)

IMPORTANTE

Los vectores consumen más almacenamiento que otras columnas de una BBDD relacional. Un vector de 1536 dimensiones guardado como float4 con 1.000.000 de productos necesita 6 GB solo para la columna de los vectores. PostgreSQL carga estos vectores en memoria cuando se hacen operaciones con ellos.

Vectores con más dimensiones ofrecen mejor resolución semántica, pero también aumentan dramaticamente los requisitos de memoria y computacionales. Un vector de 3072 dimensiones requiere x4 el trabajo para cálculos de distancia y x2 de espacio de almacenamiento respecto a vectores con 1536 dimensiones.

/IMPORTANTE

Memory config for vector workloads

La memoria del server de PostgreSQL afecta en gran medida a la vector query performance. Con un buen tuning los indices vectoriales y los datos frecuentemente leidos, se mantienen en memoria.

param shared_buffers

IMPORTANTE

El param shared_buffers controla la shared memory cache donde se guardan estos datos. Para trabajos vectoriales esta cache debería ser lo suficientemente grande como para almacenar todos tus indices vectoriales y hot data. Un cache hit ratio por debajo de 99% indica que shared_buffers puede ser muy pequeño.
Se ajusta automáticamente según tu tier Postgres en Azure, pero se puede ajustar dentro de los limites del tier.
Para apps de búsquedas vectoriales, comenzar con un 25% de la memoria disponible, monitorizar y aumentar / reducir

/IMPORTANTE

-- Check current setting
SHOW shared_buffers;

-- View buffer cache hit ratio
SELECT
    sum(heap_blks_hit) / (sum(heap_blks_hit) + sum(heap_blks_read)) AS cache_hit_ratio
FROM pg_statio_user_tables;

param work_mem

El param work_mem controla la memoria disponible para query ops individuales como sorts y hash joins. Se usa especialmente en vector similarity queries, especialmente las que combinan vector search con filtering y ordering.

El default (4 MB) es muy pequeño para vector ops que deben ordenar resultados por similarity.

-- con cuidado
SET work_mem = '256MB'

Usarlo con cuidado ya que esto aplica a por operacion y por conexión. Se puede configurar por session level para queries específicas y no globalmente

param effective_cache_size

El param effective_cache_size le dice al query planner cuanta memoria hay disponible para caching. Settearla al 75% del total system memory. Valores más altos animan al planner a usar indices, lo cual es beneficioso para vector search.

El query planner toma decisiones sobre como ejecutar queries basandose en cost estimates. Tunearlos para SSD storage modernos mejora el vector query planning

*(Azure PostgreSQL usa SSDs, por esto es todo este toquetear params).

param random_page_cost

El param random_page_cost estima el coste de leer una random disk page relativa a una page secuencial. Tiene un default de 4.0. Bajarlo a 1,1-1,5 anima al planner a usar index scans.

SET random_page_cost = 1.1;

param effective_io_concurrency

El param effective_io_concurrency dice cuantas I/O ops concurrentes puede manejar el sistema. Settearla a 200 para mejorar performance para queries que combinan vector similarity con metadata filtering

param parallel_tuple_cost

Los params parallel_tuple_cost y parallel_setup_cost controlan la ejecución paralela de queries. Las Vector ops se benefician de ella en escaneos secuenciales de tablas grandes.

SHOW parallel_tuple_cost;
SHOW parallel_setup_cost;
SHOW max_parallel_workers_per_gather;

Configure pgvector-specific parameters

IVFFlat params

Al usar indices IVFFlat el param ivfflat.probes controla cuantas particiones (listas) se buscan por query. Aumentarla sube el recall value por queries pero las hace más lentas. Es un balanceo complicado.

-- Configure IVFFlat search depth
SET ivfflat.probes = 10;

-- Execute vector search
SELECT id, name, embedding <=> $1 AS distance
FROM products
ORDER BY embedding <=> $1
LIMIT 10;

HNSW params

El param hnsw.ef_search controla el tamaño de la dynamic candidate list durante la búsqueda. Valores más grandes exploran más partes del grafo a costa de velocidad.

Monitor and measure performance

NUNCA HACER TUNING SIN MEDIR ANTES Y DESPUÉS.

Usar el comando EXPLAIN ANALYZE para ver como PostgreSQL ejecuta una query y ver sus timings. Para queries vectoriales, esto indica si se usan los indices y donde se ocupa el tiempo.

Si ves scans secuenciales y esperas indices, comprobar los operadores y que se usen.

Hay veces que PostgreSQL decide no usar indices disponibles. Esto puede ocurrir en queries que devuelven una gran parte de la tabla (index overhead excede el sequential scan, outdated statistics o distance op distinto del que tiene el indice)

Best practices for pgvector tuning

  • Establish baselines first: Measure antes de hacer cambios, measure después y comparar
  • Change only one param at a time and measure again
  • Test with production-like data
  • Monitor for regressions: con el tiempo la performance se puede degradar
  • Document your settings: documentar que cambias, por que y que efecto ha tenido

Read More

Scale for high-volume workloads (PostgreSQL)

Vertical scaling on Azure

Azure Database for PostgreSQL ofrece 3 compute tiers cada uno con diferentes recursos

Tier vCores Memoria por vCore Ideal para
Burstable 1-20 2 GB DEV; low-traffic
General purpose 2-96 4 GB Balanced PROD
Memory optimized 2-96 8 GB Large working sets; vector workloads

Escalar verticalmente hasta que encuentres hard limits o el coste sea prohibitivo. Entonces escalar horizontalmente.

Read replicas for query distribution

Read replicas mantiene copias de tu BBDD primaria que pueden encargarse de read queries de manera independiente.

El server primario se encarga de read y write, mientras que las réplicas se encargan solo de read. Puedes tener hasta 5 replicas por primaria y las réplicas se pueden localizar en diferentes Azure regions. Cada replica tiene su propio connection endpoint, por lo que la App debe gestionar las queries correctamente.

No todas las vector search se benefician por igual del cacheo. Los mejores candidatos tienen alta frecuencia, low change rates y espacios vectoriales similares.

Ejemplos de poor caching candidates:

  • arbitrary vector similarity queries
  • rapidly changing data
  • queries with many filter combinations

se recomienda cachear embedding lookups y recomendaciones pre-computadas

import redis
import json

redis_client = redis.Redis(host='your-cache.redis.cache.windows.net',
                          port=6380, ssl=True, password='your-key')

def get_product_embedding(product_id):
    cache_key = f"embedding:{product_id}"
    cached = redis_client.get(cache_key)

    if cached:
        return json.loads(cached)

    # Fetch from database
    embedding = fetch_embedding_from_db(product_id)

    # Cache for 1 hour
    redis_client.setex(cache_key, 3600, json.dumps(embedding))
    return embedding

Monitor capacity

Se puede hacer track de database-level metrics con Azure Monitor

  • CPU percentage
  • memory percentage
  • storage IO percentage
  • active connections
  • query metrics incluing P95/P99 latency
  • etc

Read More

Optimize data layout (PostgreSQL)

Vector storage considerations

Las dimensiones de los modelos afectan al espacio que necesitamos para almacenamiento.

Dimensiones 1M vectors size
384 1.5 GB
768 3 GB
1536 6 GB
3072 12 GB

Para un product catalog de 1M de vectores usando 3072 necesitamos 12 GB de almacenamiento solo para vectores. Si además usamos un HNSW index esto se incrementa por un 50%.

IMPORTANTE

A menores dimensiones menos requisitos de almacenamiento y computacion. Un consejo es especificar las dimensiones en la definición de la columna, ya que esto aporta validación. Si intentar insertar vectores de diferentes dimensiones, falla con un error en vez de subtle bug de mismatched embedding models.

Si tenemos items con varias columnas de embeddings (por ejemplo titulo e imagen), cada columna necesita su propio index.

NO SE PUEDE CREAR UN SINGLE INDEX QUE CUBRA VARIAS VECTOR COLUMNS

CREATE TABLE products (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    title_embedding vector(768),      -- Text embedding model
    image_embedding vector(512),       -- Image embedding model
    category_id INTEGER,
    price NUMERIC(10,2)
);

-- Create separate indexes for each embedding type
CREATE INDEX ON products USING hnsw (title_embedding vector_cosine_ops);
CREATE INDEX ON products USING hnsw (image_embedding vector_cosine_ops);

/IMPORTANTE

Metadata data types: structured columns vs JSONB

Usa columnas estructuradas (INTEGER, TIMESTAMP, etc.) cuando los atributos sean conocidos en tiempo de diseño, filtres u ordenes frecuentemente por atributos específicos o la query performance sea crítica

CREATE TABLE products (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    embedding vector(1536),
    category_id INTEGER NOT NULL,
    price NUMERIC(10,2) NOT NULL,
    in_stock BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    brand TEXT,
    rating NUMERIC(2,1)
);

JSONB guarda datos semi-estructurados como JSON Binario, lo que ofrece flexibilidad y atributos dinámicos. JSONB provee de schema flexibility, easy evolution y nested structure, PERO tiene query overhead, límites para indices y las estadísticas son menos precisas.

JSONB se usa para contenido dinámico o que raramente se filtra u ordena donde valoramos más esa flexibilidad en el schema.

 CREATE TABLE products (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    embedding vector(1536),
    -- Structured columns for common filters
    category_id INTEGER NOT NULL,
    price NUMERIC(10,2) NOT NULL,
    in_stock BOOLEAN DEFAULT true,
    -- JSONB for dynamic attributes
    attributes JSONB DEFAULT '{}'
);

Metadata indexes for filtered searches

Los indices de metadatos complementar a los indices vectoriales acelerando la fase de filtrado de queries. Sin un indice apropiado de metadatos, PostgreSQL puede necesitar escanear todas las rows para aplicar filtros antes de la búsqueda vectorial.

Un single-column index se encarga de matches exactos Un composite index gestiona filter combinations. Son los más efectivos pero tienen sus limites.

Un índice (category_id, price) se activará si buscamos por WHERE category_id = 5 y también con WHERE category_id = 5 AND price < 100 pero no se activará con WHERE price < 100

-- Single-column index for exact matches
CREATE INDEX idx_products_category ON products (category_id);

-- Composite index for common filter combinations
CREATE INDEX idx_products_category_price ON products (category_id, price);

Indices parciales

Podemos crear indices parciales. Esto son indices que un tamaño reducido pero que igualmente mejoran la performance para queries filtradas.

Por ejemplo si tenemos una app donde la mayoría de queries se ejecutan con WHERE in_stick = true podemos crear un indice parcial cuyo target sea justo esas qeuries

CREATE INDEX idx_products_instock ON products (category_id) WHERE in_stock = true

Indices JSONB

(se puede, pero no me voy a meter en este cristo para la cert)

Tablas particionadas (large datasets)

Las tablas grandes (recomendado >10.000.000 rows) se pueden particional en tablas más pequeñas y manejables. Para vector workloads particionar puede mejorar la performance y simplificar el mantenimiento.

Cada partición tiene sus propios indices. Si creamos un indice en la tabla padre, automaticamente se crea en todas las particiones.

-- Create partitioned table
CREATE TABLE user_interactions (
    id BIGSERIAL,
    user_id BIGINT NOT NULL,
    embedding vector(768),
    created_at TIMESTAMP NOT NULL,
    interaction_type TEXT
) PARTITION BY RANGE (created_at);

-- Create partitions for each month
CREATE TABLE user_interactions_2025_01
    PARTITION OF user_interactions
    FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');

Read More

Connection Optimization (PostgreSQL)

(de momento lo dejo aqui; continuar)

Cada conexión consume server memory, requiere auth overhead y cuenta contra el server limit.

Connection overhead

El crear una nueva conexión a PostgreSQL conlleva 50-200 ~ ms. Para una app que maneje miles de requests / s, esto puede ser muy costoso.

Azure PostgreSQL limita las conexiones según el tier (burstable permite 50 conexiones, la más cara 5.000)

Connection pooling with PgBouncer

PgBouncer es un connection pooler en el puerto 6432 que está entre tu app y PostgreSQL. Mantiene una pool de DDBB connections a la que se conectan los clientes para las peticiones, lo que reduce el número de conexiones requeridas.

La connection string usa el formato postgresql://user:password@myserver.postgres.database.azure.com:6432/mydb

IMPORTANTE

Burstable tier NO soporta PgBounder

/IMPORTANTE

az postgres flexible-server parameter set \
	--resource-group myResourceGroup \
	--server-name myserver \
	--name pgbouncer.enabled \ 
	--value true

PgBounder soporta varios modos de pooling

  • Sesion mode - un cliente mantiene la server connection para toda la sesión. Esto provee una minimal connection reduction
  • Transaction mode - el cliente mantiene la conexión solo durante la transacción. Entre transacciones (commit o rollback) la connection vuelve a la pool. Este modo funciona bien para la mayoría de aplicaicones y reduce los requerimientos de conexiones
  • Statement mode - un cliente obtiene una conexion solo para statements individuales. Es el mejor para vector search workloads.

PgBounder ofrece varios params

  • pgbouncer.default_pool_size 20-50 dependiendo de concurrency needs
  • pgbouncer.max_client_conn +5000 para high-traffic apps
  • pgbouncer.pool_mode (transaction)
  • pgbouncer.query_wait_timeout (30-120s)

Application-level connection pooling

Aparte de PgBouncer tu app puede hacer manage de la connection pool directamente con psycopg_pool. Esto da más finer control y se integra mejor, aparte te permite revisar connection lifecycle, idle timeout y health checks.

Combinado con PgBouncer app pools gestionan local connection management mientras que PgBouncer se encarga del server-side.

from psycopg_pool import ConnectionPool

# Create a connection pool
pool = ConnectionPool(
    conninfo="postgresql://user:password@myserver.postgres.database.azure.com:6432/mydb",
    min_size=5,      # Minimum connections to maintain
    max_size=20,     # Maximum connections allowed
    max_idle=300,    # Close idle connections after 5 minutes
    max_lifetime=3600  # Recycle connections after 1 hour
)

# Use connections from the pool
def search_similar_products(query_embedding, limit=10):
    with pool.connection() as conn:
        with conn.cursor() as cur:
            cur.execute("""
                SELECT id, name, embedding <=> %s AS distance
                FROM products
                ORDER BY embedding <=> %s
                LIMIT %s
            """, (query_embedding, query_embedding, limit))
            return cur.fetchall()

Session management for AI workloads

Efficient SDK usage patterns

Connection resilience

Read More

Choose and configure vector indexes (PostgreSQL)

Los indices vectoriales permiten busquedas rapidas de similaridad organizando vectores en data structures que evitan la necesidad de comparar vector a vector con cada query.

Vector index fundamentals (NN vs ANN)

Sin un índice, las búsquedas necesitan un scan secuencial que compare vector a vector. Estos scans secuenciales calculan el nearest neighbour (NN), garantizando un true closest vector a costa de performance y query time que escala linearmente con el tamaño de la tabla.

En vez de NN search, podemos hacer indices de approximate nearest neighbour (ANN) lo cual cambia esa perfect accuracy por queries dramáticamente más rápidas. ANN usa data structures para encontrar vectores que son probablemente (pero no garantizado) de los más próximos. Con ANN el query time crece logarítmicamente o sublinear con el tamaño de la tabla.

La precisión de ANN se mide como recall. Si pides los 10 resultados más próximos y te entrega 8, se dice que tiene un recall de un 80%. Para AI apps un 95-99% es aceptable.

cuando es necesario implementar índices

Table size Index benefit
<10.000 rows limitado; secuential scans pueden ser suficientemente rápidos
10.000 - 100.000 moderado; los índices reducen la latencia bastante
100.000 - 1.000.000 significante; se requieren índices para uso interactivo
> 1.000.000 obligatorio; sin índices las queries son realmente lentas

IVFFlat (Inverted File Flat) index

Los IVFFlat index particionan vectores en clusters y entonces buscan solo los clusters relevantes para una query. Este approach reduce el search space, manteniendo una precisión razonable.

Durante la index creation, pgvector clusteriza tus vectores en un número especifico de listas, donde cada lista contiene vectores que son similares entre ellos. Al hacer una query, pgvector identifica las listas cuyos centroids son más próximos al query vector, y entonces calcula la distancia solo con los vectores de esas listas. Si tu query calcula distancia sobre 10 listas, habiendo un total de 1000, has reducido efectivamente el search space en un 99%.

Estos índices ofrecen fast build times, lower memory usage y runtime tunability, PERO requieren training data. Con pocos datos no funcionan, tienen un lower recall ceilling y necesitan hacer rebuilding cuando los datos cambian significativamente.

IMPORTANTE

Al crear el índice especificamos el numero de listas y el operador a usar. Hay que usar un operador de distancia en las queries que haga match con el puesto en el índice.

caso clase operador
cosine distance vector_cosine_ops <=>
euclidean distance vector_l2_ops <->
negative inner product vector_ip_ops <#>

/IMPORTANTE

-- Create IVFFlat index for cosine distance
CREATE INDEX ON products
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 1000);
numero de productos numero de listas a crear
<100.000 rows 100
100.000 - 1.000.000 1.000
1.000.000 - 10.000.000 4.000 - 10.000

El param ivfflat.probes controla cuantas listas se buscan por query. Valores más altos pueden mejorar el recall pero también incrementar el query time.

HNSW (Hierarchical Navigable Small World) index

Los HNSW index organizan vectores en una multi-layer graph structure que permite una navegación eficiente desde cualquier starting point al NN.

HNSW construye un grafo donde cada vector es un nodo conectado a su NN. El grafo tiene multiples capas, donde las capas mas altas contienen menos nodos y sirven como express lanes para navegar. Cuando haces una query, HNSW comienza con un punto fijo de entrada en la top layer, se mueve hacia el query vector usando las capas superiores y luego refina los resultados con las capas más densas.

Estos índices ofrecen un higher recall rate (+99%), no training dependency y performance consistente, PERO requieren más uso de memoria, longer build times y fixed parameters (cambiar m o ef_construction requiere reconstruir el índice).

Al crear un HNSW index especificamos:

  • el número de conexiones que cada nodo mantiene con otros nodos m. Valores más altos crean un grafo más denso con mejor recall pero más consumo de memoria y longer build times.
  • el construction search width ef_construction controla la search width durante la construccion del indice. Valores más altos resultan en un indice de mejor calidad, pero aumentan el build time. Este param solo afecta al build time y calidad del grafo resultante.

Aplican las mismas reglas de operadores que para IVFFlat:

caso clase operador
cosine distance vector_cosine_ops <=>
euclidean distance vector_l2_ops <->
negative inner product vector_ip_ops <#>
-- Create HNSW index for cosine distance
CREATE INDEX ON products
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

El param hnsw.ef_search controla el search width en query time (similar a probes para IVFFlat). Este valor debería ser por lo menos tan grande como el número de resultados de tus queries (LIMIT clause)

Choose an index type

IVFFlat

Requisitos

  • memory budget limitado
  • build time tolerance low
  • 90-95% recall es aceptable
  • data update frequency incluye frequent bulk updates

Ejemplo de IVFFlat: app con large catalogs con updates frecuentes donde añadimos o hacemos update de muchos productos en batch, o si tenemos una memoria limitada.

HNSW

Requisitos

  • tenemos mucha memoria
  • podemos tolerar longer build times
  • necesitamos 99% recall
  • el workload son mayormente reads con pocos updates

Ejemplo de HNSW: recommendation engine. Necesitamos high recall para que los usuarios vean todos los productos y sub-10ms query latency para mucho concurrencia.

Create and maintain indexes

Index building bloquea la tabla a writes, por defecto. Para PROD usar CONCURRENTLY para permitir writes durante index building. Tomará más tiempo y requiere más recursos, pero evita downtime.

-- Build index without blocking writes
CREATE INDEX CONCURRENTLY idx_products_embedding
ON products USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

Los indices se degradan con el tiempo por lo que hay que monitorizar síntomas como la latencia regularmente y estar atento a cuando haga falta reconstruirlos.

REINDEX INDEX CONCURRENTLY idx_products_embedding

Read More

Run vector similarity search for semantic retrieval (PostgreSQL)

Effective semantic retrieval combina vector similarity con metadata filtering, distance thresholds y query patterns.

Combine vector search con metadata filters

Raramente deberiamos ejecutar búsquedas sobre el corpus de documentos completo. Por lo general queremos resultados filtrados por categoria, fechas, autor, etc.

El resto es combinar vector similarity con filtros, manteniendo una query performance aceptable

Podemos añadir un WHERE para filtrar documentos. Primero se filtra y luego se calcula la distancia solo para los docs filtrados.

SELECT id, title, embedding <=> $1 AS distance
FROM documents
WHERE category = 'contracts'
  AND practice_area = 'corporate'
  AND created_at > '2024-01-01'
ORDER BY embedding <=> $1
LIMIT 10;

“To maintain performance with filtered queries, create B-tree indexes on columns you frequently filter”

Para queries que siempre combinan columnas específicas se recomienda usar composite indexes, ya que pueden ser más eficientes que multiple single-column indexes.

Implement distance thresholds

Usar LIMIT devuelve los top N most similar docs independientemente de su similitud real. Usar distance thresholds asegura un minimum quality filtrando resultados que caigan por debajo del límite.

Podemos filtrar por distancia con un WHERE . Esta query devuelve como máximo N docs, pero solo si cumplen con el límite. Si no hay docs cercanos, devuelve vacío.

SELECT id, title, embedding <=> $1 AS distance
FROM documents
WHERE embedding <=> $1 < 0.4
ORDER BY embedding <=> $1
LIMIT 10;

El distance thresholds necesita entender los datos. Primero deberiamos analizar los datos y calcular distancias y queries para ver resultados relevantes.

Por ejemplo para cosine distance los thresholds caen entre 0.3 (estricto; alta precisión) y 0.6 (lenient; high recall)

Retrieve documents with content for context

Si necesitamos sacar datos y metadatos de varias tablas, es mejor hacerlo todo de una operación en un single round trip

SELECT
    d.id,
    d.title,
    d.content,
    d.embedding <=> $1 AS distance,
    a.name AS author_name
FROM documents d
JOIN authors a ON d.author_id = a.id
WHERE d.embedding <=> $1 < 0.5
ORDER BY d.embedding <=> $1
LIMIT 5;

Handle multi-vector queries

Algunos escenarios requieren encontrar documentos similares en varias columnas de vectores. En esos casos podemos hacer un average de los vectores para producir un embedding combinado que representa “el centro” de esos embeddings.

busca documentos similares en ambos aspectos y los rankea por su proximidad combinada en ambas queries

WITH
merger_results AS (
    SELECT id, embedding <=> $1 AS distance FROM documents ORDER BY embedding <=> $1 LIMIT 20
),
environmental_results AS (
    SELECT id, embedding <=> $2 AS distance FROM documents ORDER BY embedding <=> $2 LIMIT 20
)
SELECT d.id, d.title,
       (COALESCE(mr.distance, 1) + COALESCE(er.distance, 1)) / 2 AS combined_score
FROM documents d
LEFT JOIN merger_results mr ON d.id = mr.id
LEFT JOIN environmental_results er ON d.id = er.id
WHERE mr.id IS NOT NULL OR er.id IS NOT NULL
ORDER BY combined_score
LIMIT 10;

La busqueda hibrida combina vector similarity con keyword-based full-text search para capturar ambos contenido semántico y relevancia léxica.

PostgreSQL tiene ts_rank for scoring keyword matches. Podemos combinar esto con vector distance (convertida a similarity score) para hybrid ranking. El weight determina cuanto de cada señal contribuye al resultado final

SELECT
    id,
    title,
    (1 - (embedding <=> $1)) * 0.7 +
        ts_rank(to_tsvector('english', content), plainto_tsquery('english', $2)) * 0.3 AS hybrid_score
FROM documents
WHERE to_tsvector('english', content) @@ plainto_tsquery('english', $2)
   OR embedding <=> $1 < 0.5
ORDER BY hybrid_score DESC
LIMIT 10;

“To speed up keyword matching, create a GIN index on the full-text search vector. For frequently searched columns, storing the tsvector in a generated column avoids recomputing it for every query”

Read More

pgvector - store and query embeddings (PostgreSQL)

Enable pgvector extension

La extensión pgvector añade el vector data type y similarity search operators a PostgreSQL. Antes de poder usar embeddings, hay que activar pgvector en la BBDD

comando para activar pgvector

CREATE EXTENSION IF NOT EXISTS vector;

verificar que se ha instalado

SELECT * FROM pg_extension WHERE extname = 'vector'

Design schemas for vector storage

Un buen diseño combina embeddings con los metadatos de la app necesarios para filtrar y mostrar.

Cuando defines una columna de vector, tienes que especificar el número de dimensiones vector(n)

ejemplo de creación que guarda el embedding en la misma tabla que los metadatos

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    category TEXT,
    practice_area TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    embedding vector(1536)
);

si tenemos múltiples embeddings (titulo vs contenido) podemos guardarlos en la misma tabla

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    title_embedding vector(384),
    content_embedding vector(1536)
);

Insert and update embeddings

Para apps con cambios frecuentes quizás es mejor regenerar los embeddings en batches durante off-peak hours y no actualizarlos en tiempo real.

ejemplo de single insert vectores

INSERT INTO documents (title, content, category, practice_area, embedding)
VALUES (
    'Corporate Merger Agreement Template',
    'This agreement outlines the terms and conditions for the merger of...',
    'contracts',
    'corporate',
    '[0.0123, -0.0456, 0.0789, -0.0321, ...]'::vector
);

ejemplo de batch insert vectores

INSERT INTO documents (title, content, category, embedding)
VALUES
    ('Document 1', 'Content...', 'legal', '[...]'::vector),
    ('Document 2', 'Content...', 'legal', '[...]'::vector),
    ('Document 3', 'Content...', 'legal', '[...]'::vector);

ejemplo de update con vectores

UPDATE documents
SET content = 'Updated document content...',
    embedding = '[0.0234, -0.0567, ...]'::vector,
    updated_at = NOW()
WHERE id = 42;

Query vectors with distance ops

pgvector provee de tres distance operators para medir similitud entre vectores. Cada uno calcula un tipo diferente.

L2 distance (Euclidean distance)

L2 distance (distancia euclideana) mide la línea recta entre dos vectores en el espacio vectorial. Es el operador <->. Cuando más pequeños los valores más similares son los vectores.

Funciona muy bien cuando la magnitud de los vectores conlleva significado.

SELECT id, title, embedding <-> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;

Cosine distance

Cosine distance mide el ángulo entre dos vectores, ignorando sus magnitudes. Es el operador <=>. Los valores van del rango 0 (dirección idéntica) a 2 (direcciones opuestas).

Cosine distance es la opción más común para text embeddings porque se centra en la dirección del significado y no en la longitud del vector.

SELECT id, title, embedding <=> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;

Negative inner product

Calcula el dot product de dos vectores y lo hace negativo. Es el operador <#>.

Negative inner product es útil para maximum inner product search, donde larger dot products indica vectores más similares. La negación lo convierte a una distancia donde valores más pequeños son mejores.

SELECT id, title, embedding <#> '[0.0123, -0.0456, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 10;

Vector data types and precision

pgvector ofrece tres data types para guardar vectores, cada uno con un storage y performance diferente.

Para la mayoría de casos es mejor usar el standard vector type. Si necesitamos ahorrar espacio, y solo después de comprobar que la precisión es suficiente, podemos usar halfvec

vector type

vector type almacena elementos como single-precision (32-bit) floats. Es el standard para la mayoría de casos y da buen balance de precisión y almacenamiento.

halfvec

halfvec type almacena elementos como half-precision (16-bit) flaots. Reduce el almacenamiento a la mitad comparado con vector, manteniendo suficiente precisión para al mayoría de similarity search tasks.

Usa halfvec cuando el almacenamiento sea un problema y hayas verificado que la precisión reducida no impacta tus búsquedas

CREATE TABLE documents_compact (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    embedding halfvec(1536)
);

sparsevec

sparsevec type almacena sparse vectors donde la mayoría de elementos son cero. En vez de guardar todas las dimensiones, solo guarda los nonzero values y sus posiciones.

Este tipo es útil para modelos que producen sparse embeddings.

CREATE TABLE sparse_documents (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    embedding sparsevec(10000)
);

Read More

Manage index lifecycle and embedding updates (PostgreSQL)

Los índices vectoriales y los embeddings necesitan ongoing maintenance a medida que tus datos van evolucionando.

Monitor index health and performance

PostgreSQL tiene system views y funciones que revelan si los indices se están usando, cuanto espacio consumen y si las queries se ejecutan como se espera.

La view pg_stat_user_indexes muestra usage patterns para los índices. Si un index muestra cero scans, puede que las queries no la estén usando. Un high scan count confirma que el índice funciona como deberia.

SELECT
    schemaname,
    relname AS table_name,
    indexrelname AS index_name,
    idx_scan AS times_used,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
FROM pg_stat_user_indexes
WHERE indexrelname LIKE '%embedding%'
ORDER BY idx_scan DESC;

Más allá de las usage statistics, tenemos EXPLAIN ANALYZE para ejecutarlo periodicamente sobre queries representativas, donde debemos hacer un seguimiento del execution time a lo largo del tiempo. Si una query sube de tiempo y los datos no han cambiado, puede que el indice se haya degradado.

Podemos monitorizar el build de un index con pg_stat_progress_create_index, ya que este puede llevar horas.

Rebuild indexes when data distribution change

ANN indexes optimizan su estructura interna basandose en data distribution en el momento que se crea. Cuando se añade un 20-30% de datos nuevos, nuevos dominios o caracteristicas diferentes, el indice ya no particiona los vectores de manera optima. Esta degradacion se presenta como una mayor query latency y/o peores resultados.

Para PROD donde no podemos tener downtime, usamos CREATE INDEX CONCURRENTLY para crear un replacement index sin bloquear queries. Toma más tiempo y recursos, pero la app continua sirviendo requests.

  1. Crear el indice con un nombre temporal
  2. Comprobar que funciona con EXPLAIN ANALYZE
  3. Borrar el índice viejo
  4. Hacer un rename al nuevo para que lo sustituya
-- Create new index concurrently (doesn't block queries)
CREATE INDEX CONCURRENTLY documents_embedding_new_idx
ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- Verify the new index works, then swap
DROP INDEX documents_embedding_idx;
ALTER INDEX documents_embedding_new_idx RENAME TO documents_embedding_idx;

Para sistemas que pueden tolerar interrupciones tenemos REINDEX INDEX documents_embedding_idx es más simple pero bloquean queries durante el rebuild

Update embeddings efficiently

Cuando el source content cambia, los embeddings asociados ya no representan el contenido, por lo que hay que sincronizarlos.

Para updates ocasionales, podemos updatear los embeddings en la misma transacción que el contenido para mantener todo consistente. Es más simple y garantiza consistencia, pero añade latencia a cada update.

Para Apps con cambios muy frecuentes de contenido podemos usar batches. Se marcan los documentos que necesitan un update de embeddings usando un flag y luego los actualizamos todos en batches. Esto reduce los costes y mejora la latencia del sistema, pero durante un tiempo el contenido puede estar desactualizado y mostrar resultados desfasados.

Para algunas Apps puede ser necesario hacer una regeneración periódica y no solo cuando el contenido cambie. Implementamos esto como scheduled jobs.

-- Add a column to track embedding status
ALTER TABLE documents ADD COLUMN embedding_stale BOOLEAN DEFAULT FALSE;

-- When content changes, mark for embedding update (fast)
UPDATE documents
SET content = 'New content...', embedding_stale = TRUE, updated_at = NOW()
WHERE id = 42;

-- Background job processes stale embeddings in batches
SELECT id, content FROM documents WHERE embedding_stale = TRUE LIMIT 100;

-- After generating embeddings externally, update in bulk
UPDATE documents
SET embedding = data.embedding, embedding_stale = FALSE
FROM (VALUES (1, '[...]'::vector), (2, '[...]'::vector)) AS data(id, embedding)
WHERE documents.id = data.id;

Handle embedding model changes

Si hacemos un upgrade a un nuevo modelo de embeddings tenemos que regenerar todos los embeddings, ya que modelos diferentes producen vectores diferentes (y puede que con un numero diferente de dimensiones).

No se pueden mezclar embeddings de modelos diferentes en una misma columna

Migration strategy

Migrar a un nuevo embedding model requiere planificarlo bien. No puedes hacer un overwrite de los embeddings y ya porque la app devolvería resultados inconsistentes mientras la migración esté en progreso.

El método más seguro es crear una nueva columna paralela donde metemos los nuevos embeddings que se van generando hasta que este listo y validado y podamos cambiar una columna por otra.

  1. Creamos la nueva columna
  2. Creamos el indice para la columna nueva
  3. Llenamos la columna con embeddings
  4. Update de las app queries para usar la nueva columna
  5. Borramos la columna y el indice viejos

Manage storage and cleanup

Los vectores consumen mucho espacio. Un vector de 1536 dimensiones con 1.000.000 de documentos consume 6 GB solo en vector data, más el espacio de los índices.

Reclaim space after updates

Al hacer update o borrado de rows, PostgreSQL no reclama inmediatamente el espacio en disco. Para vector tables con actualizaciones periodicas de vectores esto se puede agravar bastante. Este espacio muerto se puede reclamar con:

-- Standard vacuum (runs concurrently)
VACUUM documents;

-- Full vacuum (reclaims more space but locks the table)
VACUUM FULL documents;

Con tablas con heavy update actividy lo podemos configurar automáticamente

autovacuum cuando el 5% de las filas son modificadas

ALTER TABLE documents SET (
    autovacuum_vacuum_scale_factor = 0.05,
    autovacuum_analyze_scale_factor = 0.02
);

Read More

Implement retrieval patterns for RAG pipelines (PostgreSQL)

(muchisimo detalle - quizas para una segunda vuelta segun vea los examenes de prueba)

Retrieval augmented generation (RAG) mejora las respuestas del modelo, cogiendo contexto relevante de tus datos. El retriever escanea tu knowledge base y devuelve documentos que el LLM usa para generar grounded content.

RAG architecture and retriever role

RAG sigue un patron de 3 pasos:

  1. Query embedding: convertimos la pregunta del user en vectores usando un embedding model
  2. Retrieval: buscamos en la BBDD vectorial documentos similares al query embedding
  3. Generation: Pasamos los documentos obtenidos al LLM como contexto para generar una respuesta

En esta arquitectura, PostgreSQL es el retriever. Si el retriever saca documentos irrelevantes, al LLM le falta contexto para responder y puede generar información correcta. Si en cambio no encuentra documentos, la respuesta puede estar incompleta.

Design schemas for RAG workloads

RAG apps funcionan con chunks (no con documentos enteros).

Separate documents and chunks

Usamos dos tablas. Una para source documents y otra para chunks con embeddings

  • Flexible retrieval: puedes sacar chunks individuales o reconstruir documentos
  • Source tracking: Cada chunk linkea a su documento entero, para citaciones
  • Efficient storage: Document metadata se almacena una unica vez, no duplicada por chunk
  • Easy updates: Reemplazar un doc significa borrar todos sus chunks
CREATE TABLE source_documents (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    source_url TEXT,
    document_type TEXT,
    ingested_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE document_chunks (
    id SERIAL PRIMARY KEY,
    document_id INTEGER REFERENCES source_documents(id) ON DELETE CASCADE,
    chunk_index INTEGER NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536),
    token_count INTEGER,
    start_char INTEGER,
    end_char INTEGER,
    UNIQUE (document_id, chunk_index)
);

Add metadata for filtering and context

Incluir metadata para poder filtrar

CREATE TABLE document_chunks (
    id SERIAL PRIMARY KEY,
    document_id INTEGER REFERENCES source_documents(id) ON DELETE CASCADE,
    chunk_index INTEGER NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536),
    token_count INTEGER,
    section_title TEXT,
    page_number INTEGER,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

Crear indices para RAG query patterns

Vector similarity indexes (IVFFlat o HNSW) permite fast embedding lookups. RAG workloads también se benefician de B-tree indexes.

Estos indexes ayudan al hacer retrieve de chunks, al unir de vuelta los source documents para citaciones, y al filtrar u ordenar dentro de un documento por chunk position. Sin estos indices se hace un escaneo de todos los chunks para cada query

-- B-tree index for document lookups (speeds up JOINs to source_documents)
CREATE INDEX document_chunks_document_id_idx
ON document_chunks (document_id);

-- Composite index for chunk ordering (supports context window queries)
CREATE INDEX document_chunks_doc_chunk_idx
ON document_chunks (document_id, chunk_index);

Implement chunk retrieval for context building

diseñar un RAG es un balanceo entre:

  • obtener suficiente contexto relevante
  • mantenerte dentro de los token limits
  • dar suficiente contexto al LLM para entender cada chunk

Read More

Fast vector similarity search (PostgreSQL)

A medida que los vector datasets crecen, las similarity queries que escaneen cada fila pueden volverse demasiado lentas. Esto se soluciona mediante vector indexes.

IMPORTANTE

Sin un index, pgvector ejecuta exact nearest-neighbor search. La BBDD calcula la distancia entre el query vector y cada vector de la tabla, entonces devuelve las filas con las distancias más pequeñas. Esto garantiza encontrar el nearest neighbor verdadero, pero el coste computacional crece con el número de filas.

/IMPORTANTE

Para tablas pequeñas (<10.000 rows) sirve el exact nearest-neighbour pero lo que a una tabla con 100.000 vectores le puede llevar 500 ms, a una tabla con 1.000.000 de vectores le puede llevar 5s.

Approximate nearest-neightbour (ANN) search intercambia precisión perfecta por mejora en velocidad. ANN organiza vectores en estructuras que permiten a la BBDD examinar solo un subset de vectores durante las queries. Los resultados pueden fallar a veces y dejarse algunos true nearest neighbours, pero las queries se completan en milisegundos independientemente del tamaño de la tabla.

Choose IVFFlat when:

  • memory usage is a concern
  • faster index builds for frequently changing data
  • trade query performance for lower resource usage
  • slightly lower recall

Choose HNSW when:

  • query performance is your primary concern
  • high recall (99%) with low latency
  • your dataset doesn’t change frequently
  • memory constraints aren’t severe

Inverted File Flat (IVFFlat) indexes

IVFFlat particiona vectores en clusters durante la creación del index. Cuando haces una query, la BBDD identifica los clusters más cercanos a tu query vector y busca solo dentro de esos clusters, en vez de escanear la tabla entera.

Cada cluster tiene un centroid. Esto es la posición media de todos los vectores del cluster. Cuando ejecutas una query, pgvector calcula distancias desde tu query a cada centroid, identifica los clusters más cercanos y busca solo en ellos.

el param lists controla el número de clusters. luego el param vector_cosine_ops tiene que ser el mismo que el distance operator que usemos para las queries <=>, etc

CREATE INDEX documents_embedding_idx ON documents
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
Operator class Distance opwerator Use case
vector_12_ops <-> L2 Euclidean distance
vector_cosine_ops <=> Cosine distance
vector_ip_ops <#> Negative inner product

IVFFlat indexes requiere que existan datos para entrenar al clustering algorithm. Crear un index en una tabla vacía produce un index que no se puede usar para queries - primero cargar los datos, luego crear el índice. Si la distribución de datos cambia significativamente después de añadir datos puede ser necesario hacer un rebuild del índice

Hierarchical Navigable Small World (HNSW) indexes

HNSW indexes usan una graph structure multi-capa para similarity search. Tiene una mejro performance que IVFFlat, aunque consume más memoria y tiene longer build times.

HNSW construye una graph estructure navegable, en vez de particionar vectores en clusters (como have IVFFlat). HNSW construye un grafo donde cada vector es un nodo conectado a su nearest neighbours, organizados en múltiples capas.
La top layer contiene la menor cantidad de nodos espaciados lejos unos de otros. Cada capa a un nivel más bajo contiene más nodos con conexiones más densas, y la última capa contiene todos los nodos.

Cuando haces una query, el algoritmo comienza en la top layer y navega por el grafo, moviéndose a lower layers a medida que se acerca al query vector. Es un coarse-to-fine approach which narrows down the search space.

el param m es el número máximo de conexiones por nodo en el grafo. el param ef_construction controla el width de la búsqueda durante index building - valores más altos crean indices de mayor calidad pero son más lentos de construir. para PROD usar valores 100-200

CREATE INDEX documents_embedding_idx ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

A diferencia de IVFFlat, los indices HNSW se pueden crear en tablas vacías - se hace update de la graph structure a medida que se insertan nuevas filas

Read More

Query data (PostgreSQL)

PostgreSQL-specific filtering

PostgreSQL extiende el SQL estandard con más operadores.

El operador ILIKE es como LIKE pero ya case-insentive sin tener que hacer un LOWER.

También permite controlar cómo aparecen ordenados los null values en los resultados con NULLS FIRST o NULL LAST

Con COALESCE devuelve el primer valor no null de sus args. Se usa para proveer de default values en los resultados o para handlear nullable columns COALESCE(title, 'Untitled')

Query JSONB data

PostgreSQL’s JSONB type almacena datos estructurados que no se pueden meter en un schema fijo. AI apps usan JSONB normalmente para metadatos, config, model params o estructuras de respuesta variable.

PostgreSQL provee de operadores especializados para JSON content:

  • -> extrae un JSON element como JSON
  • ->> extrae un JSON element como texto (para comparisons y display)
  • #> devuelve JSON para nested paths
  • #>> devuelve texto para nested paths

Ejemplos:

  • metadata->>'status' extrae el status field como texto
  • checkpoint_data#>>'{results,0,score}' navega un nested path para obtener el valor específico

Existence and containment operators enable efficient filtering

  • ? comprueba key existence
  • @> tests containment

Ejemplos:

  • WHERE metadata ? 'priority'
  • WHERE checkpoint_data @> '{"status": "completed"}'

Cuando JSONB contiene arrays, podemos usar jsonb_array_elements para expandirlas y filtrar o agregar

-- Find conversations tagged with 'support'
SELECT DISTINCT c.*
FROM conversations c,
     jsonb_array_elements_text(c.metadata->'tags') AS tag
WHERE tag = 'support';

Efficient pagination with keyset pagination

Una paginación tradicional con OFFSET se vuelve lenta en tablas grandes porque PostgreSQL debe escanear y descartar todas las rows que salta. Cargar la página 1000 con 20 rows por página requiere escanear 20.000 rows y descartar 19.980.

Keyset pagination (also calle cursor-based pagination) usa WHERE para saltar rows, lo cual tiene una performance consistente independientemente de como de profundo pagines.

En vez de tracklear page numbers, trackeas el último valor que has visto y filtras desde ahí. Este approach requiere un unique, sortable column (o combinacion de ellas). Tu página debe almacenar los sort values de la última fila y pasarlos a la siguiente query.

(incluir id en ambos ORDER BY y WHERE gestiona los empates cuando múltiples filas tienen el mismo timestamp)

-- First page: get the 20 most recent messages
SELECT id, conversation_id, content, created_at
FROM messages
ORDER BY created_at DESC, id DESC
LIMIT 20;

-- Next page: filter by the last seen timestamp and id
SELECT id, conversation_id, content, created_at
FROM messages
WHERE (created_at, id) < ('2024-06-15 10:30:00', 12345)
ORDER BY created_at DESC, id DESC
LIMIT 20;

Common Table Expressions (CTEs)

INVESTIGAR Y PROBAR ESTO. VER SI ES SQL native o de Postgre. Me puede ayudar mucho en mi dia a dia

CTEs definen named temporary result sets que existen solo durante la ejecución de una query. Mejoran la legibilidad y te permiten crear queries complejas paso a paso.

WITH recent_conversations AS (
    SELECT id, user_id, started_at
    FROM conversations
    WHERE started_at > CURRENT_DATE - INTERVAL '7 days'
),
message_stats AS (
    SELECT conversation_id, COUNT(*) AS message_count, MAX(created_at) AS last_message_at
    FROM messages
    GROUP BY conversation_id
)
SELECT rc.user_id, rc.started_at, COALESCE(ms.message_count, 0) AS message_count
FROM recent_conversations rc
LEFT JOIN message_stats ms ON rc.id = ms.conversation_id;

Recursive CTEs query tree structures like task hierarchies, org chats o threaded conversations. Consisten de un base case (anchor) y un recursive case que referencia al CTE en si mismo. Incluir siempre un depth limit u otra condicion de finalizacion para prevenir infinite loops

WITH RECURSIVE task_tree AS (
    -- Base case: start with the parent task
    SELECT id, parent_id, title, 1 AS depth
    FROM tasks WHERE id = 1
    UNION ALL
    -- Recursive case: find children of current level
    SELECT t.id, t.parent_id, t.title, tt.depth + 1
    FROM tasks t
    INNER JOIN task_tree tt ON t.parent_id = tt.id
    WHERE tt.depth < 10
)
SELECT * FROM task_tree ORDER BY depth, id;

AI apps a menudo necesita hacer retrieve de conversation threads donde los mensajes referencian parent messages

WITH RECURSIVE thread AS (
    -- Start with the root message
    SELECT id, parent_id, content, role, 0 AS depth
    FROM messages
    WHERE id = :root_message_id

    UNION ALL

    -- Get all replies
    SELECT m.id, m.parent_id, m.content, m.role, t.depth + 1
    FROM messages m
    INNER JOIN thread t ON m.parent_id = t.id
    WHERE t.depth < 50
)
SELECT * FROM thread ORDER BY depth, id;

INSERT with RETURNING

RETURNING hace retrieve de valores de filas insertadas, updateadas o borradas en un single round trip. Es esencial para obtener IDs autogenerados, timestamps o computed defaults sin una query separada

-- Get the generated ID after inserting a conversation
INSERT INTO conversations (user_id, session_id)
VALUES ('user123', 'sess_abc')
RETURNING id;

-- Get multiple generated values
INSERT INTO messages (conversation_id, role, content)
VALUES (1, 'user', 'Hello')
RETURNING id, created_at;

-- Use RETURNING with UPDATE
UPDATE tasks SET status = 'completed', completed_at = CURRENT_TIMESTAMP
WHERE id = 5
RETURNING id, status, completed_at;

Upserts with ON CONFLICT

INSERT ... ON CONFLICT se encarga de gestionar UNIQUE contraint violations, permitiendo al upsert insertar nuevas filas o actualizar las ya existentes.

Cuando hay un conflicto en una UNIQUE constraint, puedes actualizar la existing row con nuevos valores usando DO UPDATE

Con DO NOTHING hacemos skip de rows que violarian constraints

A DO UPDATE se le puede añadir WHERE para filtrar

INSERT INTO user_preferences (user_id, preference_key, preference_value)
VALUES ('user123', 'theme', 'dark')
ON CONFLICT (user_id, preference_key)
DO UPDATE SET
    preference_value = EXCLUDED.preference_value,
    updated_at = CURRENT_TIMESTAMP;

Practical patterns for AI apps

Retrieve conversation history with metadata for context building

WITH conversation_context AS (
    SELECT c.id, c.session_id, c.metadata->>'model' AS model
    FROM conversations c
    WHERE c.session_id = :session_id AND c.ended_at IS NULL
)
SELECT cc.session_id, cc.model, m.role, m.content, m.created_at
FROM conversation_context cc
INNER JOIN messages m ON cc.id = m.conversation_id
ORDER BY m.created_at
LIMIT 50;

Show recording task checkpoints with state management using upsert

INSERT INTO task_checkpoints (task_id, step_number, checkpoint_data)
VALUES (:task_id, :step_number, :checkpoint_json::jsonb)
ON CONFLICT (task_id, step_number)
DO UPDATE SET checkpoint_data = EXCLUDED.checkpoint_data, updated_at = CURRENT_TIMESTAMP
RETURNING id, created_at, (xmax = 0) AS is_new;

Show a paginated search with JSONB filters

SELECT c.id, c.session_id, c.started_at, c.metadata->>'status' AS status
FROM conversations c
WHERE c.user_id = :user_id
  AND c.metadata @> :filter_json::jsonb
  AND (c.started_at, c.id) < (:last_started_at, :last_id)
ORDER BY c.started_at DESC, c.id DESC
LIMIT 20;

Read More

Integrate SDKs and Apps (PostgreSQL)

Python integration con psycopg

psycopg es la libreria recomendada de PostgreSQL para Python. Se conecta mediante connection strings o params individuales.

import psycopg

# Connection string format
conn = psycopg.connect("postgresql://user:password@myserver.postgres.database.azure.com/mydb?sslmode=require")

# Individual parameters
conn = psycopg.connect(host="myserver.postgres.database.azure.com", dbname="mydb",
                       user="myuser", password="mypassword", sslmode="require")

Context managers se aseguran que las conexiones están correctamente cerradas, aún cuando ocurren exceptions.

Las queries parametrizadas en python se usan mediante %s

el outer with hace management de la conexión, el inner with hace management de cursor

with psycopg.connect(connection_string) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT * FROM conversations WHERE id = %s", (conversation_id,))
        row = cur.fetchone()

Usar fetchone() cuando esperas una single row. Usar fetchall() para result sets que iterar

Connection management best practices

IMPORTANTE

  • set appropriate timeouts to prevent the app hanging when the database is unreachable or queries run longer than expected
    • connection timeouts control how long the client waits to establish a connection
    • statement timeouts limit query execution time
  • implement retry logic with exponential backoff
    • catch OperationalError for connectiosn and timeouts
    • don’t retry on constraint violations or syntax errors - those require code changes, not retries
  • always close connections when you’re done with them

/IMPORTANTE

conn = psycopg.connect(
    connection_string,
    connect_timeout=10,
    options="-c statement_timeout=30000"  # milliseconds
)

Error handling strategies

IMPORTANTE

Unique contraints, FK y check constraints dan errores específicos cuando se violan. Capturar estos errores UniqueViolation, ForeignKeyViolation y CheckViolation para dar feedback. Siempre hacer un rollback de una transacción después de una contraint violation.

Los deadlocks ocurren cuando dos transacciones se esperan la una a la otra. PostgreSQL los detecta y los elimina, lo que devuelve DeadlockDetedted. Hacer rollback y retry.
Manejar LockNotAvailable de forma similar cuando hay un timeout esperando a un lock que no llega.

/IMPORTANTE

Performance considerations

No insertar rows solas si se puede. Hacer batches. Usar executemany para insertar unos cientos de miles de rows. Para datasets grandes (+10.000 rows) usar el COPY command.

with cur.copy("COPY messages (conversation_id, role, content) FROM STDIN") as copy:
    for record in records:
        copy.write_row(record)

Prepared statements pueden mejorar performance para queries que se ejecutan con diferentes params.

Crear database connections es caro en performance. Usar connection pools para utilizar conexiones reutilizables

from psycopg_pool import ConnectionPool

pool = ConnectionPool(connection_string, min_size=1, max_size=10)

with pool.connection() as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT * FROM messages WHERE conversation_id = %s", (id,))

Read More

Create and manage schemas (PostgreSQL)

Database and schema organization

PostgreSQL organiza los objetos en una jerarquía:

  • el server instance contiene una o múltiples BBDD
  • las BBDD contienen schemas
  • los schemas contienen tablas y otros objetos

Un schema provee de un namespace para poder organizar objetos. El schema por defecto es public, que es el que se asigna cuando no especificas uno diferente.

IMPORTANTE

Usar databases separadas cuando queremos aislamiento total y completo entre datasets, cuando diferentes apps compartan server pero no quieres que accedan a los datos de la otra, o cuando quieres backups independientes.

Usar schemas separados dentro de una misma database cuando objetos relacionados necesitan referenciarse a través de FK, cuando quieras ejecutar queries con JOIN a través de namespaces, o cuando quieras una separación lógica sin tener un aislamiento total

/IMPORTANTE

Crear tablas

En este ejemplo id define una PK con BIGSERIAL PRIMARY KEY, la cual es autom-incremental

CREATE TABLE conversations (
    id BIGSERIAL PRIMARY KEY,
    session_id UUID NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    started_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    ended_at TIMESTAMP WITH TIME ZONE,
    metadata JSONB DEFAULT '{}'::jsonb
);

Data types relevantes para AI apps

IMPORTANTE

  • JSONB: almacena JSON data en un formation binario que soporta indexing y querying eficiente. Usar JSONB cuando la estructura de datos varía entre records, necesites guardar nested objects o arrays, o necesites schema flexibility
  • TEXT and VARCHAR: ambos son para texto. TEXT no tiene límite y VARCHAR(n) enfuerza un máximo. No hay diferencia de performance.
  • TIMESTAMP WITH TIME ZONE: Usar siempre TIMESTAMPTZ para datos de tiempo que operen a través de time zones.
  • BYTEA: almacena binary data como byte array. Se usa para small binary objects que necesitan ser almacenados junto a datos relacionales. Para large binary files usar Azure Blob Storage con una referencia en la BBDD
  • SERIAL and BIGSERIAL: pseudo-types que crean ints auto-incrementales. PostgreSQL crea automáticamente una sequencia y pone un valor default. Usar BIGSERIAL par tablas que excedan de 2 billion rows.

/IMPORTANTE

Define relationships

IMPORTANTE

FK establecen relaciones entre tablas y fuerzan integridad referencial. Cuando defines una FK, PostgreSQL enfuerza que existen los valores en la columna referida.

One-to-many: conecta una single row de una tabla con multiple rows en otra. Ejemplos: Una conversación tiene múltiples mensajes; Un user tiene múltiples sesiones;

CREATE TABLE messages (
    id BIGSERIAL PRIMARY KEY,
    conversation_id BIGINT NOT NULL REFERENCES conversations(id),
    role VARCHAR(50) NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    content TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Many-to-many: requieren de una junction table que referencia ambas tablas relacionadas. Ejemploss: las conversaciones pueden tener múltiples tags, y los tags pueden aplicarse a múltiples conversaciones

la composite PK fuerza que cada combinación aparezca una única vez

CREATE TABLE conversation_tags (
    conversation_id BIGINT REFERENCES conversations(id) ON DELETE CASCADE,
    tag_id BIGINT REFERENCES tags(id) ON DELETE CASCADE,
    PRIMARY KEY (conversation_id, tag_id)
);

Las acciones referenciales definen lo que pasa cuando haces update o delete de una fila referenciada

  • RESTRICT (default): previene la operación si la referencia existe
  • CASCADE: borra o hace update de las referencias
  • SET NULL: pone la FK a null
  • SET DEFAULT: pone la FK con el default
  • ON DELETE CASCADE: usarla con cuidado - si borramos una conversación borraremos también automáticamente todos los mensajes, lo que puede borrar muchos más datos de los que hubiéramos querido si las relaciones son complejas

/IMPORTANTE

Index basics

Los indices son estructuras que aceleran data retrieval con el coste de más almacenamiento y writes más lentos. PostgreSQL crea automáticamente indices para PKs y UNIQUE contraints.

el orden de las columnas en un indice compuesto importa, ya que se aplica a queries que filtren solo por los primeros items, pero no a las que solo filtren por los últimos

CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
CREATE INDEX idx_messages_created_at ON messages(created_at);
CREATE INDEX idx_messages_conversation_created ON messages(conversation_id, created_at);

Schema management commands

si algo va mal, puedes usar ROLLBACK para no cambiar el schema, ya que las operaciones son transaccionales

BEGIN;
ALTER TABLE conversations ADD COLUMN category VARCHAR(100);
CREATE INDEX idx_conversations_category ON conversations(category);
COMMIT;

Read More

Connect to PostgreSQL

Una conexión requiere de:

  • host (server FQDN <server-name>.postgres.database.azure.com)
  • puerto (5432 conexiones directas; 6432 PgBouncer)
  • database name
  • username (username@servername para Entra auth)
  • pwd (static o Entra token)

Auth methods

Azure Database for PostgreSQL soporta dos tipos de autenticación:

  • Microsoft Entra (OAuth 2.0 tokens)
  • PostgreSQL native auth (user & pwd)

Microsoft Entra

Para conectar las Entra identities necesitamos obtener un token de https://ossrdbms-aad.database.windows.net

El proceso es:

  • La app pide un token de Entra ID
  • Entra valida la identidad y devuelve un token
  • La app se conecta a PostgreSQL usando el token como pwd
  • PostgreSQL valida el token contra el Entra administrator configurado

en python se usa azure-identity library para obtener tokens. DefaultAzureCredential prueba automáticamente multiples auth methods en orden (Entra ID, Azure CLI credentials, etc)

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default")
# Use token.token as the password in your connection string

TLS/SSL config

PostgreSQL clients usa sslmode param para controlar la encriptación y validar certificados. Tiene los siguientes modos:

  • disable: Azure rechaza conexiones con este modo
  • allow: Encripta si el server lo requiere, pero no valida certificados
  • prefer: Encripta si el server lo soporta, pero no valida certificados
  • require: Fuerza la encriptación, pero no valida certificados
  • verify-ca: Fuerza la encriptación y valida el server certificate
  • verify-full: Fuerza la encriptación, valida el ser certificate, y confirma que el certificate hostname hace match con el server

Para PROD usar verify-full para verificar que el server es genuino y real

Connection pooling con PgBouncer

PgBouncer solo está disponible para General Purpose y Memory optimized compute tiers. PgBouncer usa el puerto 6432

PgBouncer es una herramienta con un pool de conexión que reduce el overhead de crear conexiones constantemente, manteniendo una pool de conexiones reusables a través de las cuales enruta a los clientes. Esto reduce el overhead para apps que usan short-lived connections

activar pgBouncer

az postgres flexible-server parameter set \
	--resource-group myResourceGroup \
	--server-name myserver \
	--name pgbounder.enabled \
	--value true

tras activarlo, debemos usar el puerto 6432

postgresql://user@myserver.postgres.database.azure.com:6432/mydb?sslmode=require

Network access considerations

IMPORTANTE

Azure Database for PostgreSQL soporta dos modelos de networking:

  • public access (firewall rules): el server tiene una IP pública y las firewall rules controlan que clientes se pueden conectar
  • private access (VNet integration): el server solo tiene una IP privada dentro de una red virtual de Azure. Solo te puedes conectar desde recursos dentreo de la misma red, peered networks, o a través de VPN/ExpressRoute. Se usa para PROD envs.

/IMPORTANTE

Connection string examples

# Basic connection with SSL required
postgresql://myuser:mypassword@myserver.postgres.database.azure.com/mydb?sslmode=require

# Connection with certificate verification
postgresql://myuser:mypassword@myserver.postgres.database.azure.com/mydb?sslmode=verify-full&sslrootcert=/etc/ssl/certs/ca-certificates.crt

# Connection through PgBouncer (note port 6432)
postgresql://myuser:mypassword@myserver.postgres.database.azure.com:6432/mydb?sslmode=require

Read More

Explore Azure Database (PostgreSQL)

Azure Database for PostgreSQL es una BBDD relacional administrada por Azure. Microsoft se encarga de administrar hardware, parches, backups y high availability.

Con AI apps se usa para las que necesitan guardar datos relacionales junto a operaciones vectoriales.

Arquitectura y deployment options

Azure Database for PostgreSQL separa compute y storage en componentes independientes. La database engine corre en una Linux VM, mientras que los datos residen en Azure managed storage. Esto permite un escalado independiente y ofrece durabilidad a través de replicas redundantes.

Hay 3 tiers:

  • Burstable: baseline CPU performance con la habilidad de bursts por encima cuando se necesita. Se usa para dev envs, apps pequeñas o workloads que no necesitan una CPU a siempre a tope. B-series VM
  • General Purpose: balance de compute y memory resources para PROD workloads. Para apps que requieren response times predecibles. D-series VM
  • Memory Optimized: da un ratio más alto de memoria-to-CPU para datasets que necesiten mucha memoria. E-series VM

Los tiers si se pueden cambiar más adelante para adaptarse a tus necesidades

Managed service capabilities

El servicio se encarga de crear automáticamente los backups y los guarda en zone-redundant storage en otras regiones. Default retention es de 7 días, que se puede extender hasta 35.

Point-in-time restore te permite recuperar la BBDD a cualquier momento donde haya backups. Esto crea un nuevo server con todos los datos ercuperados.

También incluye built-in PgBouncer, un pool de conexión que reduce el overhead de crear conexiones constantemente, manteniendo una pool de conexiones reusables.

PgBouncer NO está disponible en Burstable tier

Supported PostgreSQL extensions

Algunas de las extensiones soportadas que son útiles para AI apps:

  • pgvector: activa los vector data types y similarity search ops. Permite guardar embeddings junto a los datos relacionales y hacer búsquedas al nearest neighbor.
  • pg_trgm: provee trigram-based text similarity functions. Se usa para fuzzy text matching, autocomplete features y encontrar strings similares sin matches exactos
  • hstore: añade key-value data type para guardar sets de pares key-value dentro de un único PostgreSQL value. Útil para semi-structured data que no requiere toda la flexibilidad de JSONB.

Puedes activar otras extensiones disponibles con CREATE EXTENSIONS

Read More

Understand Indexes (CosmosDB)

CosmosDB usa indexes para ejecutar queries eficientemente sin tener que escanear todos los contenedores.

Automatic index behaviour

By default CosmosDB hace un index de todas las propiedades en cada documento. Así las queries con cualquier propiedad pueden usar los índices inmediatamente sin configurar nada.

IMPORTANTE

Esto tiene trade-offs que son importantes cuando tu AI app escala. Cada índice consume almacenamiento y añade overhead a las write ops. Para aplicaciones que almacenan embedding arrays o texto sobre el que nunca se hacen queries, la default policy indexa datos sin necesidad.

/IMPORTANTE

Explorar index types

CosmosDB soporta múltiples tipos de índices, cada uno optimizado para query patterns diferentes. Estos 4 son los más relevantes para optimizar AI workloads.

  • Range index: soporta equality queries =, range queries <, <=, >, >=, != y ORDER BY en single properties. Soporta string functions como CONTAINS, STARTSWITH, ENDSWITH, IS_DEFINED y StringEquals. Usar (por ej) para filtrar documentos por type, status, date range.
  • Composite index: optimiza queries que ordenan o filtran por múltiples propiedades de manera simultánea. CosmosDB requiere un composite index que haga match exacto con la secuencia de propiedades y la sort direction.
  • Spatial index: permite geospatial queries functions ST_DISTANCE, ST_WITHIN, ST_INTERSECTS. Para AI apps que incorporan filtros por localización geográfica.
  • Vector index: Acelera búsquedas por similitud usando VectorDistance function (flat, quantizedFlat, diskAnn - está en otro post más en detalle)

Indexing mode

CosmosDB soporta dos indexing modes que controlar cuando y como se actualizan los indices

  • Consistent: el indice se actualiza de manera síncrona con cada write op. Las queries siempre reflejan el último estado. Modo por defecto.
  • None: Indexing desactivado en el contenedor. Puede mejorar la write performance para bulk ops, pero las queries sin indices ejecutan full scans. Solo para escenarios específicos donde nunca haces queries por propiedades secundarias

Index storage costs

Index size contribuye al total storage consumido por el contenedor. Esto depende de:

  • Cuantas propiedades tenemos indexadas: cada indice individual incrementa el coste. Tambien si tenemos estructuras nesteadas con muchos niveles
  • Cardinalidad: Propiedades con valores muy distintos entre ellos (o únicos) como IDs o timestamps requieren indices mucho más grandes que propiedades más similares.
  • Array elements: Cuando los arrays se indexan, cada elemento se indexa por si mismo. Arrays grandes con muchos elementos aumentan mucho el index storage.

IMPORTANTE

Para AI apps los embedding arrays pueden contener cientos de miles de valores numéricos. Si incluimos estas arrays en range indexes aumenta el gasto de almacenamiento muchisimo y esto no nos da ninguna ventaja a la hora de hacer queries. Las búsquedas vectoriales deben usar vector indexes. Excluir embedding paths de range indexes puede reducir el coste de almacenamiento substancialmente.

/IMPORTANTE

Incluir y excluir property paths

Indexing policies usan path expressions para especificar que propiedades se indexan. El sistema soporta wildcards

  • /* incluye todas las propiedades desde el root
  • /propertyName/? indexa el valor en la propiedad especificada
  • /arrayName/[] indexa los elementos dentro del array
  • /nested/path/* indexa todas las propiedades bajo el nested path

IMPORTANTE

A la hora de incluir y excluir paths que entran en conflicto, el más específico gana. Esto permite excluir grandes porciones del document tree a la vez que incluyes propiedades específicas que sean necesarias

/IMPORTANTE

indexa todas las propiedades (solo excluye _etag system property)

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/*" }
  ],
  "excludedPaths": [
    { "path": "/\"_etag\"/?" }
  ]
}

ejemplo de una selective indexing policy que indexa solo las propiedades usadas en las queries. Excluye por defecto todos los valores con /* mientras que las más específicas tienen preferencia

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/title/?" },
    { "path": "/category/?" },
    { "path": "/createdDate/?" },
    { "path": "/metadata/*" }
  ],
  "excludedPaths": [
    { "path": "/*" }
  ]
}

System property indexing

CosmosDB maneja los indices de algunas propiedades automaticamente.

  • id y _ts siempre se indexan y no se puede deshabilitar
  • _tag siempre se excluye. Se puede incluir manualmente pero es bastante raro que sea necesario.

La propiedad id sirve de identificador dentro de una partición.

Read More

Tune vector indexes for embedding workloads (CosmosDB)

Las AI apps que almacenan embeddings usan vector indexes para ejecutar búsquedas por similitud eficientes. Elegir el tipo correcto de vector index según tu workload afecta a la latencia, accuracy y RU/s consumidos.

Vector indexes in the indexing policy

Los vector indexes trabajan y residen junto a los range, composite y spatial indexes, dentro de la misma indexing policy.

Mientras que los otros tipos de indexes soportan filtering y sorting, los vector index aceleran las queries de similitud.

Antes de añadir un vector index hay que definir la vector policy para el contenedor que especifica las embedding properties.

ejemplo completo de indexing policy

este ejemplo muestra detalles importantes: el embedding path se tiene que excluir en excludedPaths para prevenir range indexing del embedding array. El vectorIndexes define un diskAnn index para los embeddings. Tenemos range y composite indexes que soportan metadata filters que podemos usar junto al vector search

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

Select appropiate vector index type

CosmosDB ofrece 3 tipos de vector index.

Flat index - small datasets

Hace brute-force k-nearest neighbour search, comparando el query vector contra cada indexed vector. Da 100% accuracy porque evalua contra todos los vectores SIN aproximacion

Cuando usar flat index:

  • datasets pequeños con un vector count por partición física modesto
  • escenarios donde los query filters reducen significativamente el espacio de busqueda antes de la comparacion vectorial
  • apps que requieren una accuracy garantizada donde aproximar resultados no es aceptable

Limitaciones:

  • Max 505 dimensiones por vector
  • Latencia y consumo de RU/s más alto para large datasets porque se compara cada vector

Ejemplo: Los usuarios siempre filtran por categoría y cada categoría tiene unos pocos de cientos de documentos

QuantizedFlat index - medium datasets

Comprime vectores usando quantization antes de guardarlos en el índice. Reduce storage requirements y mejora query throughput al coste de un accuracy algo reducido

Cuando usar quantizedFlat:

  • datasets medianos con 1k - 50k vectores por particion fisica
  • apps donde es aceptable cambiar algo de accuracy por una mejor performance
  • escenarios donde combinamos metadata filters con vector search para reducir el set de candidatos

Características:

  • Soporta hasta 4096 dimensiones
  • Hace brute-force search sobre quantized vectors
  • Menor latencia y consumo de RU/s que flat index con resultados comparables de accuracy
  • Requiere minimo 1000 vectores antes de que el indice sea efectivo

Ofrece un balance de accuracy contra performance. Por lo general devuelve los mismos resultados que el flat index, pero ocasionalmente la quantization puede causar diferencias menores

DiskANN - large datasets

Aproxima al nearest neighbour mediante algoritmos de Microsoft. Crea estructuras de datos especializadas que permiten una fast vector search sin tener que comparar contra cada vector.

Cuando usar DiskAnn:

  • datasets grandes con >50k vectores por particion fisica
  • apps que requieren la menor latencia posible
  • workloads donde la eficiencia de RU/s es critica

Características:

  • Soporta hasta 4096 dimensiones
  • Tiene la menor latencia y RU/s cost
  • Mantiene una high accuracy
  • Requiere de al menos 1000 vectores antes de que el indice sea efectivo

Se recomienda para PROD AI apps con colecciones grandes de embeddings

Plan for vector policy immutability

Las vector policies no se pueden modificar después de la creación de un contenedor. Si queremos cambiarlas después, tenemos que crear un contenedor nuevo y migrar los datos.

Read More

Reduce RU costs with strategic indexing (CosmosDB)

RU/s consumption impacta directamente en el coste de tus workloads con CosmosDB. Queries que usen indices consumen RU/s proporcionalmente al result size, mientras que queries que hacen full scans consumen RU/s proporcionalmente al data size.

Analyze query patterns BEFORE deisgning indexes

Antes de diseñar indices hay que entender como la app hace query de los datos. Haz review de las queries e identifica que propiedades aparecen en los WHERE, ORDER BY y funciones agregadas.

  • Filter properties: ¿Que propiedades aparecen en el WHERE? ¿Son equalidad = o rangos >?
  • Sort properties: ¿Que propiedades aparecen en el ORDER BY y con que orden?
  • Property combination: Que propiedades aparecen juntas? Algunas filtran por una propiedad y luego ordenan por otra?
  • Access frequency: Con que frecuencia se ejecutan cada una? priorizar las más frecuentes

Usar query metrics para identificar que indices hacen falta

CosmosDB ofrece query metrics para ver como de eficientes son las queries al usar indices. Si hay queries que tienen una mala performance, las metricas pueden ayudar a identificarlas.

El SDK devuelve las siguientes metricas:

  • index utilization: porcentaje de la query que usa indexes vs scanning
  • retrieved document count: numero de documentos obtenidos del storage. Comparar los obtenidos del storage vs los devueltos. Una diferencia alta indica un filtrado ineficiente
  • output document count: Numero de documentos devueltos en los resultados

ejemplo que obtiene las métricas

from azure.cosmos import CosmosClient

client = CosmosClient(endpoint, credential)
database = client.get_database_client("documents-db")
container = database.get_container_client("documents")

query = "SELECT * FROM c WHERE c.documentType = @type ORDER BY c.uploadDate DESC"
parameters = [{"name": "@type", "value": "pdf"}]

# Use response_hook to capture query metrics from response headers
query_metrics_output = {}

def response_hook(headers, results):
    query_metrics_output["metrics"] = headers.get("x-ms-documentdb-query-metrics", "")
    query_metrics_output["request_charge"] = headers.get("x-ms-request-charge", "")

results = container.query_items(
    query=query,
    parameters=parameters,
    populate_query_metrics=True,
    response_hook=response_hook
)

# Process results (this triggers the query execution and response_hook callback)
items = list(results)

# Access captured query metrics
print(f"Query metrics: {query_metrics_output.get('metrics', '')}")
print(f"Request charge: {query_metrics_output.get('request_charge', '')} RUs")

Excluir properties no usadas en las queries

IMPORTANTE

Las propiedades que la app lee pero no se usan para filtrar NO. NECESITAN. INDICES. Excluir datos como large text fields, binary data o array embeddings que almacenamos y mostramos pero no filtramos por ellos.

/IMPORTANTE

Incluir partition key en el index

La partition key enruta queries a particiones específicas. Aún así las queries que filtran por partition keys también se benefician de range indexes dentro de cada partición.

CosmosDB no indexa la partition key automáticamente cuando usas exclude-by-default.

Design composite indexes for common query combinations

Composite indexes dan los mayores beneficios para queries usadas frecuentemente. Analizar que combinaciones de propiedades aparecen juntas y crear composite indexes para esos patrones.

Priorizar composite indexes por:

  • Query frequency: queries que se ejecutan miles de veces al dia tienen prioridad sobre otras que apenas se ejecutan
  • Data volume: Queries con large datasets consumen más RU/s según su tamaño
  • Filter complexity: Queries con multiples filtros con alta cardinalidad se benefician más

Cada composite index añade overhead a las write ops. Crear docenas de composite indexes para edge cases aumenta el coste de escritura y no tiene por que mejorar el de lectura. Hacer focus en los 5-10 patrones de queries que más impacto tengan

Write-heavy vs read-heavy workloads

No todas las apps se benefician de igual manera de los indices. Una app que escriba mucho y apenas lea le perjudica tener indices. En cambio una app que apenas escribe y solo lee puede ver util crear muchos composite index para todos los casos.

Monitor index transformation progress

Al crear un indice, este no toma efecto hasta que el proceso de transformation termina en background. Asi podemos monitorizar el progreso del transformation para saber cuanto lleva

# Check indexing progress through container properties
container_properties = container.read()
indexing_policy = container_properties.get("indexingPolicy", {})

# The Azure portal shows transformation progress as a percentage
# SDK access provides the policy but not real-time progress
# Use Azure portal or CLI for detailed progress monitoring

Read More

Configure range and composite indexes (CosmosDB)

Una AI apps puede ejecutar en una misma query una búsqueda semántica y filtrar por metadatos. Estas queries requieren configuraciones específicas de índices para ser eficientes. Si se hace mal puede aumentar drásticamente la latencia y el consumo de RU al tener que escanear múltiples contenedores.

Design range indexes for filter ops

Range indexes soportan los filtros más comunes para AI apps. Queries que filtran documentos por type, status, categoria o rangos de fechas usan range indexes para no tener que escanear el contenedor entero.

query que usa range indexes para filtrar por tipo y fecha

SELECT * FROM c
WHERE c.documentType = 'pdf'
  AND c.uploadDate > '2024-01-01'

Si ambos documentType y uploadDate tienes range indexes, CosmosDB usa los indices para encontrar documentos de manera eficiente. Sin índices la query hace un scan de la partición entera, consumiendo RU/s proporcional al tamaño y el result size

Configure composite indexes for multi-property sorting

Usamos composite indexes para queries que ordenan los resultados por múltiples propiedades. El composite index tiene que hacer match exacto de la secuencia de propiedades y la sort direction dentro del ORDER BY

añadimos los composite indexes

{
  "compositeIndexes": [
    [
      { "path": "/relevanceScore", "order": "descending" },
      { "path": "/uploadDate", "order": "descending" }
    ]
  ]
}

query que hace sort usando el índice creado

SELECT * FROM c
ORDER BY c.relevanceScore DESC, c.uploadDate DESC

IMPORTANTE

Un composite index que se declara con ambos DESC también soporta que ambos sean ASC. Lo que no soporta son orders mixtos como uno con DESC y otro con ASC. Esto requiere de otro indice

/IMPORTANTE

Optimize queries with both filters and ORDER BY

Muchas queries filtran por una propiedad y ordenan por otra. Estas queries se pueden optimizar incluyendo la propiedad filtrada dentro del ORDER BY

añadimos un composite index

{
  "compositeIndexes": [
    [
      { "path": "/documentType", "order": "ascending" },
      { "path": "/uploadDate", "order": "descending" }
    ],
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/relevanceScore", "order": "descending" }
    ]
  ]
}

query que NO usa el índice

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

si añadimos la propiedad documentType al ORDER BY, permitimos que use el composite index

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

Use composite indexes for multi-property filters

IMPORTANTE

queries que filtran por múltiples propiedades se pueden beneficiar de composite indexes. Al diseñar composite indexes con filtros, los equality filters = tienen que ir primero en la definición. Cada composite index soporta COMO MUCHO un range filter, que tiene que ser el último en el índice.

/IMPORTANTE

añadimos el composite index

{
  "compositeIndexes": [
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/department", "order": "ascending" },
      { "path": "/createdDate", "order": "ascending" }
    ]
  ]
}

query que usa el composite index

SELECT * FROM c
WHERE c.category = 'reports'
  AND c.department = 'finance'
  AND c.createdDate > '2024-06-01'

Si una query necesita multiples range filters, entonces necesitas multiples composite indexes, porque cada uno solo soporta un range filter

Tuples indexes for array element filtering

Usamos los tuple indexes para mejorar la eficiencia de las queries cuando filtramos por múltiples propiedades que están dentro de arrays.

Ejemplo: tenemos un documento que guarda text chunks con información de la posición

{
  "id": "doc-123",
  "title": "Annual Report 2024",
  "chunks": [
    { "position": 0, "text": "Executive summary...", "tokens": 150 },
    { "position": 1, "text": "Financial highlights...", "tokens": 200 },
    { "position": 2, "text": "Market analysis...", "tokens": 180 }
  ]
}

Un tuple index en el array chunks mejora la eficiencia de la query, indexando las combinaciones de propieades en cada array element

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

Tenemos una query que encuentra chunks en posiciones específicas con minimum token count filters

SELECT c.id, chunk.text
FROM c
JOIN chunk IN c.chunks
WHERE chunk.position >= 0
  AND chunk.position < 3
  AND chunk.tokens > 100

Balance read/write performance

Esto resume muy bien el beneficio y el problema de trabajar con índices. Prestarle mucha atención y aprenderlo de memoria

IMPORTANTE

Cada index aumenta la write latency y el consumo de RU/s porque CosmosDB actualiza los indices de manera sincrona durante las write ops. AI apps con un alto volumen de throughput tienen que balancear el index coverage con la write performance.

Guidelines:

  • Include only queries properties: Si una propiedad se guarda pero nunca aparece en filtros de queries o sorting, excluirla del indice
  • Analyze query frequency: Crear composite indexes para queries que se ejecutan frecuentemente. Queries que solo ocurren de vez en cuando no justifican el write overhead del indice adicional
  • Monitor RU consumption: Comaprar el coste en RU/s antes y después de crear el indice. Si los writes son muy dominantes, es mejor tener pocos indices que realmente se aprovechen
  • Use selective indexing: En vez de incluir siempre todas las propiedades con /*, incluir explicitamente solo las que realmente queramos

/IMPORTANTE

Index transformation behaviour

  • Añadir indices: No hacen efecto hasta que se termina de crear y actualizar
  • Eliminar indices: Hace efecto inmediato al borrarlo
  • Reemplazar indices: Añadir primero el indice nuevo y esperar a que haga efecto. Borrar entonces el viejo. Esto asegura que las queries siempre tengan un indice que las soporte.

Read More

Choose consistency levels for optimal performance (CosmosDB)

(esto me parece demasiado a fondo para el examen)

CosmosDB consistency levels controlan el trade-off entre data freshness, latencia, throughput y disponibilidad.

Niveles de consistencia

Ordenadas de strongest a weakest.

Strong consistency

Los reads siempre devuelve el write más reciente.

Cuando el cliente escribe data a una region, un read desde cualquier region devuelve ese valor. Aumenta la latencia para multi-region accounts.

Read More

Use change feed to trigger embedding refresh (CosmosDB)

Es importante mantener los embeddings actualizados y sincronizados con el contenido actual. Si tenemos los embeddings desactualizados y el contenido de los documentos cambia, estaremos haciendo búsquedas en los embeddings sobre contenido que ya no existe.

Change feed

El change feed es un log persistente y ordenado de todos los inserts y updates de un contenedor. Las aplicaciones se suscriben al feed y procesan los cambios en tiempo real tal como pasan, lo que permite arquitecturas event-driven donde los updates a los embeddings ocurren a la vez que los cambios en los documentos

Un buen mecanismo de sincronización de embeddings debe tener:

  • persistent record: los cambios se almacenan y se procesan incluso si la App está offline
  • delivery ordenado: los cambios dentro de una partition key llegan en orden
  • Just-once opportunity: Cada cambio aparece una única vez en el feed
  • Automatic enablement: el change feed está enabled by default en todos los contenedores

Push / pull modes

CosmosDB ofrece dos maneras de consumir el change feed.

  • push model (entrega cambios a tu codigo automaticamente)
    • built-in partition management y load balancing a lo largo de múltiples instancias
    • es más sencillo
    • mejor para CD
  • pull model (eres tu quien hace pull de los cambios)
    • más control de cuando y como se integran los cambios
    • menos consumo
    • sin dependencias externas
    • util para batch refreshes

Para PROD el push model es más seguro y simple. Usar Azure Functions o el change feed processor library para implementar el push model

Azure Functions for change feed processing

IMPORTANTE

Azure Functions ofrecen la integración más simple con el change feed. El CosmosDB trigger invoca automáticamente la función cuando los documentos cambian, se encarga del partition management y mantiene checkpoints para seguir el progreso

/IMPORTANTE

regenera embeddings cuando los documentos cambian en el knowledge container

import azure.functions as func
from openai import AzureOpenAI
from azure.cosmos import CosmosClient
import os

app = func.FunctionApp()

@app.cosmos_db_trigger(
    arg_name="documents",
    container_name="knowledge-base",
    database_name="support-db",
    connection="CosmosDBConnection",
    lease_container_name="leases",
    create_lease_container_if_not_exists=True
)
def refresh_embeddings(documents: func.DocumentList):
    if not documents:
        return

    # Initialize clients
    openai_client = AzureOpenAI(
        api_key=os.environ["OPENAI_API_KEY"],
        api_version="2024-02-01",
        azure_endpoint=os.environ["OPENAI_ENDPOINT"]
    )

    cosmos_client = CosmosClient.from_connection_string(
        os.environ["CosmosDBConnection"]
    )
    container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")

    for doc in documents:
        # Check if content that affects embeddings changed
        if should_refresh_embedding(doc):
            # Generate new embedding from updated content
            text_content = f"{doc.get('title', '')} {doc.get('content', '')}"

            response = openai_client.embeddings.create(
                input=text_content,
                model="text-embedding-ada-002"
            )

            # Update document with new embedding
            doc["embedding"] = response.data[0].embedding
            container.upsert_item(doc)

def should_refresh_embedding(doc):
    """Determine if the document needs a new embedding."""
    # Always refresh if no embedding exists
    if "embedding" not in doc or doc["embedding"] is None:
        return True

    # Check for content-related fields that affect embeddings
    # In a full implementation, compare against the previous version
    return True

La config del trigger especifica el contenedor a monitorizar knowledge-base, la BBDD support-db y el lease container leases para hacer tracking del progreso. La opción create_lease_container_if_not_exists crea automaticamente el lease container si se necesita.

Lease Container

El change feed processor (usado por Azure Functions triggers) requiere un contenedor separado para almacenar leases. Los leases hacen tracking de que particiones ownea cada instancia del processor y el track del progreso de cada particion. Esto da:

  • Checkpointing: Si el processing falla o se reinicia, lo retoma desde el último checkpoint en vez de comenzar de nuevo.
  • Coordination: Multiples processor instances se dividen las particiones, permitiendo un escalado horizontal
  • Failover: Si una instancia falla, otras adquieren su lease y continúan

Asegurarse que el lease container tiene un nombre diferente de los data containers. Múltiples funciones monitorizando el mismo data container pueden compartir un lease container si se usa leaseContainerPrefix

Selective embedding refresh

Refrescar los embeddings para cada documento es caro. Podemos implementar lógica para selective refresh para actualizar los embeddings solo cuando haya cambios en el contenido semántico.

comparar versiones de un doc para ver si es necesario un refresh

def should_refresh_embedding(current_doc, previous_doc=None):
    """
    Determine if document changes require new embeddings.
    Returns True if content affecting embeddings has changed.
    """
    # New document always needs embedding
    if previous_doc is None:
        return "embedding" not in current_doc

    # Check fields that contribute to the embedding
    content_fields = ["title", "content", "description", "summary"]

    for field in content_fields:
        current_value = current_doc.get(field, "")
        previous_value = previous_doc.get(field, "")

        if current_value != previous_value:
            return True

    # Metadata-only changes don't need new embeddings
    # Examples: category changes, status updates, access permission changes
    return False

Para PROD podemos hacerlo mediante un hash del contenido usado para generar un embedding. De esta forma es más eficiente. Al refrescar el contenido, actualizamos el hash

import hashlib

def compute_content_hash(doc):
    """Compute hash of content used for embedding generation."""
    text_content = f"{doc.get('title', '')} {doc.get('content', '')}"
    return hashlib.sha256(text_content.encode()).hexdigest()

def should_refresh_embedding(doc):
    """Check if content hash changed since last embedding."""
    current_hash = compute_content_hash(doc)
    stored_hash = doc.get("contentHash", "")

    return current_hash != stored_hash

High-volume changes

Para aplicaciones con cambios de embeddings frecuentes o mucho volumen es necesario tomar una estrategia:

  • Batch API calls: Agrupamos llamadas por batches
  • Rage limiting and backoff: Retry logic con backoff exponencial
  • Queue-based processing: Escribir cambios en un Azure Queue Storage y procesarlos con una función aparte. Esto hace decoupling de change detection y embedding generation, por lo que podemos hacer scaling por separado.
  • Prioritized refresh: priorizar documentos de alta prioridad vs baja prioridad y que vayan por separado con límites separados

Pull model con Python SDK

Esto lo hacemos mediante query_items_change_feed(). El continuation token guarda la posición en el change feed entre runs. Se puede guardar de manera persistente para asegurarse de no perder el por donde ibamos, y tener que reprocesar todo de nuevo.

from azure.cosmos import CosmosClient

cosmos_client = CosmosClient(endpoint, credential)
container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")

def process_change_feed_batch():
    """Process a batch of changes using the pull model."""

    # Read changes from the beginning or from a continuation token
    change_feed_iterator = container.query_items_change_feed(
        start_time="Beginning"  # Or use a stored continuation token
    )

    continuation_token = None

    for page in change_feed_iterator.by_page():
        for change in page:
            if should_refresh_embedding(change):
                new_embedding = generate_embedding(change.get("content", ""))
                change["embedding"] = new_embedding
                change["contentHash"] = compute_content_hash(change)
                container.upsert_item(change)

        # Store continuation token for next batch
        continuation_token = change_feed_iterator.continuation_token

    # Save continuation_token for next run
    return continuation_token

Handle errors (idempotency)

Nuestra app tiene que ser idempotente. En algunas ocsasiones el change feed puede enviar varias veces el mismo cambio en casos de fallo. Debemos asegurarnos de que solo aplicamos los cambios una única vez.

Read More

Vector semantic search (CosmosDB)

Una vez tienes un container con documentos, los cuales contienen embeddings, ya podemos ejecutar queries por similitud vectorial para encontrar contenido semánticamente relacionado. Esto se hace mediante la función VectorDistance

Función VectorDistance

La función VectorDistance es el core de la búsqueda vectorial en CosmosDB. Calcula la similitud entre los embeddings de un documento y el vector de una query.

VectorDistance(c.embedding, [0.1, -0.2, 0.3, ...])

params

  • vector_1: document’s embedding path
  • vector_2: query vector
  • bool: brute-force search?

Basic vector search queries

IMPORTANTE

Una vector search query obtiene documentos ordenados por si similitud. INCLUIR SIEMPRE TOP N. Sin él devolvería todos los documentos, cobrando por ello.

/IMPORTANTE

SELECT TOP 10
	c.id,
	c.title,
	c.category,
	VectorDistance(c.embedding, @queryVector) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.embedding, @queryVector)

Para poder ejecutar una búsqueda vectorial hay que convertir la query del usuario a embeddings, usando el mismo modelo con el que hemos generado los embeddings del documento.

from openai import AzureOpenAI

# User's search query
query_text = "How do I fix WiFi connection problems?"

# Generate query embedding using the same model as documents
openai_client = AzureOpenAI(
    api_key=api_key,
    api_version="2024-02-01",
    azure_endpoint=endpoint
)

response = openai_client.embeddings.create(
    input=query_text,
    model="text-embedding-ada-002"
)
query_embedding = response.data[0].embedding

# Execute vector search
query = """
    SELECT TOP 10
        c.id,
        c.title,
        c.category,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

results = container.query_items(
    query=query,
    parameters=[{"name": "@queryVector", "value": query_embedding}],
    enable_cross_partition_query=True
)

for item in results:
    print(f"{item['title']} - Score: {item['SimilarityScore']:.4f}")

Usar queries parametrizadas

Lo ideal es usar queries parametrizadas para pasar los embeddings mediante @queryVector

  • Esto hace hit con la cache
  • evita problemas con long query strings
parameters = [
    {"name": "@queryVector", "value": query_embedding}
]

results = container.query_items(
    query=query,
    parameters=parameters,
    enable_cross_partition_query=True
)

Interpretar similarity scores

La score depende de la distance function que haya configurado. Para cosine similarity:

  • +1.0: vectores idénticos
  • 0.7-0.9: contenidos MUY similares
  • 0.5-0.7: contenidos moderadamente similares
  • 0.1-0.5: contenidos poco similares
  • 0 o negativo: contenidos completamente diferentes

Para AI apps debemos filtrar contenido para quitar low-quality matches. Un límite mínimo de 0.7 filtra contenido altamente relevante, mientras que con 0.5 obtenemos contenido moderadamente relevante.

filtrar solo resultados >= 0.7

SELECT TOP 10
    c.id,
    c.title,
    VectorDistance(c.embedding, @queryVector) AS SimilarityScore
FROM c
WHERE VectorDistance(c.embedding, @queryVector) > 0.7
ORDER BY VectorDistance(c.embedding, @queryVector)

Control result count for different scenarios

El TOP N determina cuantos resultados devuelve la query. El valor óptimo depende según la app:

  • RAG applications: 5-10 resultados para obtener contexto relevante
  • User-facing search: 10-20 resultados siempre con paginación. Si un user no encuentra lo que quiere puede paginar más
  • Recommendation systems: 3-5 contenidos similares altamente relevantes

Por defecto las queries vectoriales usan el vector index configurado para beneficiarse de la velocidad. Las búsquedas mediante indexes pierden un poco de accuracy para obtener mejoras de performance. Si queremos revertir esto para una query podemos volver a una búsqueda de fuerza bruta pasando true como el tercer parámetro de VectorDistance

SELECT TOP 5
    c.title,
    VectorDistance(c.embedding, @queryVector, true) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.embedding, @queryVector, true)

Usarlo muy de vez en cuando ya que:

  • Compara la query vectorial contra cada documento del contenedor
  • Consume bastante más RUs que una query indexada
  • Tiene más latencia, especialmente para large datasets
  • Escala muy malamente cuantos más datos tengamos

Reservarlo para evaluation o testing, o cuando trabajamos con datasets pequeños donde nos dé igual la performance y el coste.

Optimize query performance

  • Elegir el index type correcto: diskANN es más potente pero más caro que quantizedFlat
  • Limitar result count: Usar TOP N. Pedir 100 resultados si el user solo ve 10 gasta recursos
  • Usar partition keys: incluir la partition key en las queries si se puede
  • Obtener solo campos necesarios: no pedir ampos que no se usan
  • Monitorizar RU consumption

Read More

Combine vector similarity results with metadata filtering (CosmosDB)

Las AI apps reales no usan búsqueda semántica pura. Muchas veces se combinan con filtros por categoría, fechas, permisos, etc. CosmosDB permite integrar queries vectoriales con queries tradicionales en una única query.

Add WHERE clauses to vector queries

Puedes combinar ambas. Los filtros se ejecutan antes o durante el cálculo de la distancia vectorial.

encontrar documentos semánticamente similares pero solo dentro de la categoría establecida y después de JAN 2026

query = """
    SELECT TOP 10
        c.id,
        c.title,
        c.category,
        c.createdDate,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    WHERE c.category = @category
        AND c.createdDate > @startDate
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

results = container.query_items(
    query=query,
    parameters=[
        {"name": "@queryVector", "value": query_embedding},
        {"name": "@category", "value": "networking"},
        {"name": "@startDate", "value": "2026-01-01T00:00:00Z"}
    ],
    enable_cross_partition_query=True
)

Pre-filtering and post-filtering

Al combinar filtros dentro de una misma query, el query optimizer determina si aplican antes de la comparación vectorial (pre-filtering) o después (ranking)

  • pre-filtering: reduce el espacio a buscar antes de la comparación vectoria. Si filtras 1.000 docs de un total de 100.000, la query vectorial solo se compara contra esos 1.000. Mejora la eficiencia al eliminar documentos
  • post-filtering: aplica filtros después de la query vectorial. Asegura una calidad pero puede devolver menos resultados de los pedidos si hay docs que fallan el filtro.

Optimize queries with partition keys

Al incluir la partition key en el WHERE, CosmosDB enruta solo a una única partición, en vez de escanear todas. Esto reduce mucho el consumo de RU y la latencia. Diseñar las particiones con esto en mente.

query = """
    SELECT TOP 10
        c.id,
        c.title,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    WHERE c.category = @category
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

# Query routes to single partition
results = container.query_items(
    query=query,
    parameters=[
        {"name": "@queryVector", "value": query_embedding},
        {"name": "@category", "value": "networking"}
    ],
    partition_key="networking"
)

Combine vector and full-text search - hybrid queries

Podemos combinar ambas en búsquedas híbridas usando Reciprocal Rank Fusion (RRF). RRF mergea rankings de diferentes scoring functions en un único result set unificado. Los documentos que rankean altos en ambos aparecen arriba, mientras que los que rankean solo en una, siguen apareciendo en los resultados.

Antes de usar la búsqueda híbrida, configurar el container con ambos una vector policy y una full-text policy.

{
    "defaultLanguage": "en-US",
    "fullTextPaths": [
        {
            "path": "/content",
            "language": "en-US"
        }
    ]
}

la indexing policy tiene que incluir ambas

{
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ],
    "fullTextIndexes": [
        {"path": "/content"}
    ]
}

con esto configurado, podemos usar ambas mediante ORDER BY RANK RRF

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.embedding, @queryVector),
    FullTextScore(c.content, @searchTerm1, @searchTerm2)
)

Controlar hybrid search weights

Puedes ajustar los weights de cuanto pesa cada uno en los ranks finales de la RRF.

esta query da el doble de valor a la vector search, que a la full-text search

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.embedding, @queryVector),
    FullTextScore(c.content, @searchTerm1, @searchTerm2),
    [2, 1]
)
  • higher vector weight: prioriza semantic understanding
  • higher full-text weight: prioriza exact keyword matches
  • equal weights: un buen punto de salida para búsquedas generales

Para el caso que tengamos múltiples embeddings por documento podemos usar RRF para buscar en múltiples espacios vectoriales

busca semántica en documentos por su título o contenido

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.titleEmbedding, @queryVector),
    VectorDistance(c.contentEmbedding, @queryVector)
)

Performance trade-offs

Queries híbridas complejas con filtros consumen más RU/s que queries vectoriales simples.

  • Filtra selectivamente: Elimina documentos antes de buscar
  • Hybrid search costs more: Combinar VectorDistance con FullTextScore requiere consumir lo de ambas. Usarlo cuando haya beneficio claro.
  • Index all filter properties: Usar la clave de partición en el WHERE
  • Test with PROD data volumes
  • Monitor query metrics

Read More

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

Read More

Querying CosmosDB

CosmosDB for NoSQL soporta un lenguaje SQL-like optimizado para documentos JSON.

SELECT and filter results with WHERE

Las queries operan en un single container.

realmente es muy parecido a SQL aunque está muy limitado, por lo menos hasta donde llegué a usar yo en 2023

CosmosDB soporta los operadores =, !=, <, <=, >, >=, AND, OR, NOT

SELECT * FROM products p
WHERE p.categoryId = "electronics" AND p.price < 500

También soporta funciones como CONTAINS, STARTSWITH, ENDSWITH, UPPER, LOWER

SELECT * FROM products p
WHERE CONTAINS(p.name, "Speaker") AND p.price BETWEEN 50 AND 200

También IN y NOT IN para comparar contra listas

SELECT * FROM products p
WHERE p.category IN ("electronics", "appliances", "computers")

Read More

Implement SDK (CosmosDB)

Conectar usando el SDK

La clase CosmosClient es el punto de entrada. Solo pones el account endpoint y credenciales al crear el cliente, y usas el mismo para acceder a BBDD y contenedores.

from azure.cosmos import CosmosClient

# Code fragment - focus on client initialization
endpoint = "https://mycosmosaccount.documents.azure.com:443/"
key = "<your-account-key>"

client = CosmosClient(endpoint, credential=key)

Choose authentication method

Azure CosmosDB soporta dos métodos de auth:

  • account keys: secretos compartidos que dan full access a los recursos dentro de la cuenta. CosmosDB proporciona claves primarias y secundarias, lo que permite rotación sin downtime. Las claves NO se integran con access policies condicionales.
  • Entra ID: ideal para PROD. Usa RBAC. Asignas roles a usuarios, groups, service principals o managed identities y puedes dar acceso específicos a nivel de account, database o container.

La clase DefaultAzureCredential simplifica Entra ID auth seleccionando las credenciales apropiadas según el entorno. En local usa tu Azure CLI. En los entornos usa managed identity.

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

# Code fragment - focus on Entra ID authentication
endpoint = "https://mycosmosaccount.documents.azure.com:443/"
credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

Read More

Azure CosmosDB for NoSQL

Azure CosmosDB usa una estructura jerárquica para organizar y administrar los datos.

En CosmosDB se crea una account que sirve como top-level management unit. Ésta ofrece un endpoint único https://<account-name>-documents.azure.com:443 para todas las conexiones API y SDK. Cada subscripción de Azure puede contener múltiples cuentas de CosmosDB, lo que permite separar las BBDD por entornos.

Por defecto una Azure CosmosDB account puede contener hasta 500 bases de datos y contenedores combinados

Las AI apps suelen organizar los contenedores por área funcional. Lo suyo es separar por user data, product catalogs e inference results en contenedores diferentes dentro de la misma BBDD.

Un contenedor representa la unidad fundamental de escalabilidad y contiene tus JSON documents. Cada contenedor requiere de una partition key que determine como se distribuyen los datos a lo largo de las particiones físicas.

Los containers son schema-agnostic, por lo que diferentes items dentro del mismo contenedor pueden tener diferente estructura <- es la gracia de NoSQL

Read More

Troubleshoot pods and services (AKS)

Use kubectl describe to inspect pods and events

The command kubectl describe command gives you detailed information about a pod including events.

kubectl get pods -n ai-workloads
kubectl describe pod <pod-name> -n ai-workloads

Debug using kubectl exec

kubectl exec -it <pod-name> -n ai-workloads -- /bin/sh

Inspect services using kubectl

kubectl get service -n ai-workloads
kubectl describe service <service-name> -n ai-workloads
kubectl get endpointslices -l kubernetes.io/service-name=<service-name> -n ai-workloads

Validate service-to-pod connectivity

kubectl get service -n ai-workloads
kubectl describe service inference-api -n ai-workloads
kubectl get endpointslices -l kubernetes.io/service-name=inference-api -n ai-workloads

Read More

Monitor app logs and metrics (AKS)

Ver logs de AKS

Se pueden ver:

  • Azure portal: puedes ver logs en tiempo real
  • kubectl logs para ver container logs directamente del pod.
kubectl get pods -n ai-workloads
kubectl logs <pod-name> -n ai-workloads
kubectl logs -f <pod-name> -n ai-workloads

# pod con múltiple containers
kubectl logs <pod-name> -c inference-api -n ai-workloads

Ver resource metrics

Con kubectl

kubectl top nodes
kubectl top pods -n ai-workloads

Best practices

  • Comenzar por el portal para un overview visual: usar monitoring tab y container insights para ver un estado rápido del cluster
  • Usar logs en tiempo real
  • Combinar el portal con kubectl: el portal para ver trends e históricos. kubectl para queries específicas

Read More

Como exponer apps (AKS)

Un service provee un endpoint estable para acceder a la aplicación. Sin los services, los pods usan internal IPs que cambian cuando se reinician. Los services abstraen de estas IPs y proporcionan IPs persistentes que los clientes externos pueden usar y redirigen tráfico a los Pods

El propio servicio se encarga de gestionar la carga entre los Pods y hace que si uno se crashea, el tráfico pase a otra réplica.

Elegir el tipo de servicio correcto

Elegir según la App sea interna o externa

ClusterIP (default)

Para cuando solo se necesita IPs internas dentro del cluster. Los Pods acceden al servicio usando el servicio de nombre de DNS.

Ejemplos de uso:

  • La app sirve a otros pods dentro del cluster
  • No necesitas acceso externo

Ejemplo: Tu Vector DDBB se ejecuta en dos Pods y ambos tienen que estar disponibles para otro pod que lo consume

Read More

Deploy apps to Azure Kubernete Service

Una vez tenemos los manifiestos de deployments y services, se envían al cluster con kubectl apply. K8s se encarga del resto.

Deploy con kubectl apply

El comando kubectl apply es la herramienta principal para hacer despliegues a AKS.

# Code fragment - focus on kubectl apply commands
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

# Or deploy both in one command:
kubectl apply -f deployment.yaml -f service.yaml

# Or deploy all YAML files in a directory:
kubectl apply -f .

El comando es asíncrono. Devuelve al instante pero puede tardar unos momentos en hacer los cambios

Read More

Create K8s deployment manifest (AKS)

Recordatorio unidades core de K8s

  • Pod: unidad desplegable más pequeña de K8s. Un pod es un wrapper de tu app contenerizada (por ej: una Docker image que contiene tu python API). Por lo general no se ejecuta directamente.
  • Deployment: Define cuantas réplicas (pods) ejecuta tu aplicación. Si el pod se crashea, el deployment lo reinicia automáticamente por tí. Mediante el deployment especificas la container image, requisitos de recursos, variables de entorno y otra conf (en un YAML)
  • Servicios: proveen los endpoints estables y persistentes para acceder a tus Pods. Los servicios usan labels par saber a que Pods redirigir tráfico.
  • Kubectl: CLI de K8s

Manifest structure

Un K8s deployment manifest es un YAML que indica a AKS como ejecutar la aplicación contenerizada. Especifíca la container image, número de réplicas, recursos y conf.

overview de un manifiesto. se explican en detalle más abajo

# Code fragment - focus on Deployment manifest structure
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-inference-api     # Name of your Deployment
  namespace: default          # Kubernetes namespace (default is fine for most scenarios)
spec:
  replicas: 2                # Number of Pods to run
  selector:
    matchLabels:
      app: inference-api     # Label selector—Deployment manages Pods with this label
  template:
    metadata:
      labels:
        app: inference-api   # Pod label—must match selector above
    spec:
      containers:
      - name: api
        image: myregistry.azurecr.io/inference-api:v1.0
        ports:
        - containerPort: 8080 # Port your app listens on inside the container
        resources:
          requests:
            memory: "2Gi"
            cpu: "1000m"      # 1 CPU core
          limits:
            memory: "4Gi"
            cpu: "2000m"
        env:
        - name: MODEL_NAME
          value: "gpt-4"
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: api-secrets
              key: api-key

Read More

Define Secrets (AKS)

En los secrets almacenamos los valores sensibles, como cadenas de conexión y API keys. Los secretos mantienen estos valores fuera del control de versiones y de las container images

Crear un secreto

Se puede crear un secreto directamente con kubectl create secret o desde ficheros secret.yaml

K8s ofrece diferentes tipos de secretos

  • kubernetes.io/dockerconfigjson para container registry credentials
  • kubernetes.io/tls para certificados TLS y keys
kubectl create secret generic app-secrets \
  --from-literal=DB_CONNECTION="Host=db;User=app;Password=secure" \
  --from-literal=API_KEY="your-api-key"

Read More

Define ConfigMaps (AKS)

Los ConfigMaps se usan para guardar config no sensible como feature flags o service endpoints. Estos ConfigMaps luego se inyectan en las imágenes y el source code.

Define a ConfigMap

Un ConfigMap es un recurso que guarda config data como valores clave-valor.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
data:
  FEATURE_X_ENABLED: "true"
  SERVICE_ENDPOINT: "https://api.example.com"
  # File-like configuration can use multi-line values
  app.config: |
    log_level=info
    timeout_seconds=30

Read More

Attach persistent storage to an app (AKS)

Cuando hacemos un restart de un Pod sus datos se pierden. Para guardar datos que deben sobrevivir a un Pod restart tenemos los PersistentVolume (PV) y PersistentVolumeClaim (PVC)

En AKS Azure provee de múltiples opciones de almacenamiento incluyendo CSI drivers, los cuales integran Azure storage services y Azure Container Storage

Se declara un PCV para pedir storage con una capacidad especificada.

Choose a persistent volume option

AKS soporta dos approaches para persistent storage.

Azure Container Storage Interface (CSI) drivers integran Azure Storage con AKS. Los CSI drivers provisionan

  • Azure Disk para single-node block storage
  • Azure Files para shared file access a través de múltiples Pods
  • Azure Blob para large unstructured datasets

Define a PersistentVolumeClaim (PVC)

Un PersistentVolumeClaim es una request de storage. Especificas cuanta capacidad y que modos de acceso necesitas.

Los modos de acceso incluyen

  • ReadWriteOnce: single-node access
  • ReadWriteMany: shared-access across multiple nodes
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: default

Read More

Revision modes (Azure Container Apps)

Los revision modes en ACA determinan como la app gestiona los deployments y como coexisten múltiples versiones. El mode que elijas afecta a:

  • scaling behavior
  • traffic distribution
  • deployment strategies

Revisions y scaling

IMPORTANTE

Una revision es una captura inmutable de una versión de una container app

Read More

Manage lifecycle and execution failures (Azure Container Apps)

Dynamic sessions evita mucho del trabajo necesario para asignar y limpiar entornos aislados, pero el AI backend sigue siendo el dueño del ciclo de vida de una request. Es necesario distinguir transport failures de code failures, manejar expired states y evitar repetir operaciones con efectos secundarios.

Plan for ephemeral session state

Una session se mantiene mientras reciba requests. Cada request reinicia el tiempo de cooldown. Cuando este acaba, ACA elimina la session y todos sus ficheros temporales.

Una request posterior puede usar el mismo ID, pero este creará una nueva empty session.

El backend puede pedir info de una session para obtener info de creación, último acceso o expiración

GET <POOL_MANAGEMENT_ENDPOINT>/session?identifier=<SESSION_ID>&api-version=2025-02-02-preview
Authorization: Bearer <ACCESS_TOKEN>

Diseñar cada workflow para que pueda reconocer que faltan estados o ficheros temporales. Por ej: si el code analysis reporta que /mnt/data/op-data.csv no existe, puede ser necesario que el backend lo vuelva a subir a la session actual

Read More

Execute code and exchange files (Azure Container Apps)

El AI backend interactúa con las dynamic sessions a través de la session pool management API. El backend autentica con Entra ID y solo manda código y ficheros autorizados al environment aislado

Authenticate the backend

Cada request a management API requiere de un bearer token de Entra ID. La calling identity necesita del rol ContainerApps Session Executor. Puedes asignar este rol con scope de la session pool para que la identidad no pueda ejecutar código en pools no relacionadas.

az role assignment create \
	--role "Azure ContainerApps Session Executor" \
	--assignee <BACKEND_PRINCIPAL_ID> \
	--scope <SESSION_POOL_RESOURCE_ID>

El app code puede usar DefaultAzureCredential en ambos local y azure environments.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
access_token = credential.get_token(
	"https://dynamicsessions.io/.default"
).token

Lo ideal es pedir un token cada vez que la app prepara una llamada, y no cachearlo indefinidamente.

Read More

Configure a secure session pool (Azure Container Apps)

La config de una session pool determina cuantas AI requests se pueden ejecutar de manera simultánea, durante cuanto tanto se mantienen los datos efímeros y si el código ejecutado puede acceder a redes externas.

Set pool capacity

Podemos controlar el número de sesiones que corren de manera simultánea en las settings con maxConcurrentSessions. Cada user activo o cada conversación con un agente puede requerir su propia sesión, por lo que el número real depende del uso simultáneo esperado, más que de del número de usuarios.

Del mismo modo podemos reducir la latencia de inicio manteniendo siempre un numero de instancias en caliente con readySessionInstances. Hay que tener en cuenta que reducen la latencia pero incrementa el precio.

este ejemplo limita el máximo de sesiones a 20 y mantiene siempre 2 calientes y listas

{
  "properties": {
    "scaleConfiguration": {
      "maxConcurrentSessions": 20,
      "readySessionInstances": 2
    },
    "customContainerTemplate": {
      "containers": [
        {
          "name": "document-executor",
          "image": "contoso.azurecr.io/document-executor:1.0",
          "probes": [
            {
              "type": "Startup",
              "httpGet": {
                "path": "/ready",
                "port": 8080
              },
              "periodSeconds": 5,
              "failureThreshold": 30
            },
            {
              "type": "Liveness",
              "httpGet": {
                "path": "/health",
                "port": 8080
              },
              "periodSeconds": 10,
              "failureThreshold": 3
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 8080
      }
    }
  }
}

Read More

Choose dynamic session pool (Azure Container Apps)

(dejo partes de esto para una segunda vuelta ya que ahora mismo me parece demasiado complicado y mucho mucho detalle)

Session execution boundary

Cada session asignada se ejecuta en su propia sandbox Hyper-V-aislada (la ejecución de código se aísla de procesos, file system, host y otras sesiones). Esto permite ejecutar código generado por IA, aislado de todo lo importante.

flujo de como el backend mantiene access control, mientras que la session pool procesa el código aislado

User request
    |
    v
AI application ---- model or orchestration layer
    |
    | validated code, files, and application-generated identifier
    v
Dynamic session pool
    |
    v
Isolated session ---- execution result and generated files

El backend autentica con la pool y manda el trabajo en nombre del usuario. Los usuarios finales no reciben pool access tokens ni reciben IDs que puedan dirigirse a la sesión de otros usuarios.

La sesión mantiene un estado de ejecución efímero, mientras que la app almacena inputs y resultados persistentes fuera de la pool.

Esto se hace porque si ejecutáramos código arbitrario de IA en el mismo contenedor que la app principal, el código generado competería por recursos (CPU/memoria) con el programa principal, y podrá acceder a ficheros, credenciales o env vars.

Crear un contenedor separado para cada request tampoco lo soluciona, ya que suma tiempo el tiempo de iniciar el contenedor a cada imagen y empeora el lifecycle

Read More

Choose resources for performance and cost (Azure Container Apps)

Resource allocation en ACA afecta a ambos, performance y coste. Cada réplica consume CPU y memoria, y la combinación de recursos y de réplicas determinan la capacidad y el coste total del sistema.

Entender resource allocation

IMPORTANTE

ACA asigna CPU y memoria por contenedor. Hay una regla: la memoria tiene que ser (en GiB) por lo menos el doble que núcleos de CPU. Si asignas 0.5 CPU cores, tienes que asignar mínimo 1.0 GiB de memoria.

El coste se basa en el consumo en CPU-seconds y GiB-seconds.

Hay que tener en cuenta que aumentar los recursos por réplica aumenta el coste, pero si esto reduce el número de réplicas que necesitas, puede que al final sea más barato. Hay que encontrar el balance.

Cuando una réplica se pasa del límite de memoria que tiene asignada, la plataforma mata y reinicia la réplica. La CPU funciona de manera diferente, cuando una réplica se pasa, el sistema le hace throttling pero NO la mata.

/IMPORTANTE

Read More

KEDA scalers for custom workloads (Azure Container Apps)

Azure Container Apps (ACA) soporta un gran rango de KEDA scalers fuera de servicios de Azure. Estos scalers permiten tener event-driven scaling basado en Apache Kafka, Redis queue depth y muchos más servicios.

Explorar available KEDA scalers

ACA soporta cualquier ScaledObject basado en KEDA scalers. Estos soportan muchas más herramientas de las aquí puestas como PostgreSQL, MongoDB y APIs externas. Cada scaler monitoriza un event source específico y reporta métricas que derivan en decisiones sobre el escalado.

Configurar Apache Kafka scaling

Kafka es una plataforma event-driven. Permite transportar, almacenar y procesar grandes volúmenes de eventos de forma continua. Se basa en los conceptos Producer/Consumer/Topic

Los triggers de Kafka para el escalado se basan en consumer group lag. El scaler analiza el lag del consumer group y cuando este incrementa, el scaler aumenta las réplicas para procesar más rápido y reducir el backlog.

Los key metadata params para Kafka scaling incluye bootstrapServers, consumerGroup, topic y lagThreshold. Este último permite especificar el lag por partición que hace trigger del escalado. Si ponemos un threshold de 100 y detecta que el consumer group tiene 500 mensajes de lag a lo largo de todas las particiones, el scaler calcula que hacen falta 5 réplicas.

IMPORTANTE

Al igual que los Event Hubs, las particiones de Kafka afectan a su escalado máximo efectivo. Cada partición solo puede tener un consumer activo por consumer group, por lo que solo es efectivo tener tantas réplicas como consumer groups tengamos.

/IMPORTANTE

scale:
  minReplicas: 1
  maxReplicas: 50
  rules:
    - name: kafka-scaling
      custom:
        type: kafka
        metadata:
          bootstrapServers: "kafka-broker:9092"
          consumerGroup: "order-consumers"
          topic: "orders"
          lagThreshold: "100"
        auth:
          - secretRef: kafka-credentials
            triggerParameter: sasl

Read More

Event-driven scaling with KEDA (Azure Container Apps)

IMPORTANTE

Event-driven scaling permite a tus container apps responder a señales externas más allá del tráfico HTTP.

Azure Container Apps se puede integrar con KEDA (Kubernetes Event-driven autoscaling) para escalar basándose en queues, event streams y otros servicios de Azure.

/IMPORTANTE

Understand KEDA integration

Azure Container Apps usa KEDA para monitorizar external event sources y ajustar el número de réplicas basándose en métricas de servicios externos.

La plataforma ajusta las configuraciones del scaler de KEDA a reglas de Container Apps.

Se pueden configurar custom scalers en Container Apps, estos siguen el KEDA ScaledObject specification pattern.

Especificas lo siguiente y la plataforma hace un poll cada 30 segundos:

  • scaler type
  • metadata params (configures connection and thresholds)
  • authentication settings

Microsoft mantiene azure-native scalers como:

  • Azure Service Bus
  • Azure Event Hubs
  • Azure Storage Queue
  • Azure Blob Storage
  • Azure Log Analytics
  • Azure Monitor
  • También se soportan community-maintained scalers para sources de eventos non-Azure

Event-driven scaling soporta scale-to-zero, haciéndolo ideal para background processing workloads. Si no hay mensajes - escala a 0 réplicas. Cuando llegan eventos, se hace trigger automático del scale-up

Read More

Configure scale rules (Azure Container Apps)

Azure Container Apps usa scale rules declarativas para hacer management de un escalado horizontal. Sólo defines las condiciones y ACA se encarga de todo.

Podemos escalar por:

  • HTTP rules
  • TCP rules
  • Memory/CPU rules
  • Custom metric rules

Scale definitions

Scale definitions se compone de 3 partes:

  • limits: define el número mínimo y máximo de réplicas permitido por container app
  • rules: especifican los triggers que determinan cuándo tiene lugar el escalado
  • behaviour: describe como la plataforma toma decisiones de escalado en el tiempo, incluyendo timing y algoritmos

El escalado de Azure Container Apps (ACA) funciona a través de KEDA (Kubernetes Event-driven Autoscaling). Cuando configuras reglas, la plataforma traduce tus settings a KEDA specifications que ajustan el número de replicas acordes

Read More

ACA Update Images (& manage revisions)

Usar tags y digests intencionalmente

Las tags son convenientes para iteraciones rápidas porque puedes reusar nombres como dev o staging, pero estas pueden cambiar con el tiempo.

Los digests son identificadores inmutables que aportan trazabilidad para PROD.

Update una container app para crear una nueva revisión

Cuando haces update de la imagen de una container app, se crea una nueva revisión con la template actualizada. Se puede verificar la salud de esta revision antes de asignarle tráfico. Esto evita redirigir tráfico en PROD a una revision que falle, por ej., en el startup.

hacer update de la referencia a una imagen

az containerapp update \
	--name <app-name> \
	--resource-group <resource-group> \
	--image myregistry.azurecr.io/myapp@sha256:<digest>

después del update, inspeccionamos la template del contenedor para confirmar el cambio de imagen

az containerapp show \
	--name <app-name> \
	--resource-group <resource-group> \
	--query properties.template.containers

Read More

Optimizar recursos de contenedor y scaling (Azure Container Apps)

En Azure Container Apps, se ajustan los recursos por réplica y se escalan los límites juntos.

Per-replica sizing y coste total

Container Apps escala añadiendo o quitando réplicas. La CPU y la memoria se configura por-réplica y afectan al coste directo de la misma. El coste total es una combinación del tamaño por-réplica y el número de réplicas requerido para manejar la carga máxima.

  • Para APIs de AI es importante medir la latencia junto a concurrencia y ver si hay CPU throttling.
  • Para background workers es importante medir el throughput y controlar los límites de memoria, que pueden causar reinicios.

update de límites de CPU y memoria

az containerapp update \
	--name <app-name>
	--resource-group <resource-group> \
	--cpu <cores> \
	--memory <size>

Read More

Monitor logs (Azure Container Apps)

el acceso a logs depende de la configuración del entorno de tu Container Apps. Validar que el entrono esté conectado a Log Analytics o log streaming (para ver en tiempo real)

Log streaming (diagnóstico en tiempo real)

az containerapp logs show \
	--name <app-name> \
	--resource-group <resource-group> \
	--follow

Read More

Manage container app lifecycle (Azure Container Apps)

Decidir entre stop, restart y escale-to-zero

No es lo mismo stop que scale-to-zero. Stop es parar del todo la app, para por ejemplo, asegurar que la app no crea replicas mientras se investiga un incidente. Scale-to-zero se puede usar en un approach event-driven con tráfico intermitente.

Restart es útil para limpiar errores transientes, pero hay que tener en cuenta que deriva en un incremento de cold-start-frequency a los usuarios, por lo que hay que hacerlo con intencionalidad.

# ejemplos de los 3 comandos
az containerapp start --name <name> --resource-group <rg>
az containerapp stop  --name <name> --resource-group <rg>
az containerapp restart --name <name> --resource-group <rg>

Read More

Configure health probes (Azure Container Apps)

Las health probes protegen a tus usuarios previniendo que el tráfico alcance replicas no sanas. Son especialmente útiles para APIs de IA para que dé tiempo a que se carguen los modelos de IA, se caliente la cache y carguen las dependencias.

Readiness vs liveness

IMPORTANTE

Readiness responde a la pregunta ¿Puede esta replica recibir tráfico ahora mismo? - si falla, la plataforma no debe redirigir tráfico a esa réplica.

Liveness responde a la pregunta ¿Está sano este proceso o hay que matarlo? - si falla, la plataforma mata y reinicia la réplica

/IMPORTANTE

Read More

Verify deployments (Azure Container Apps)

In Azure Container Apps you can verify deployments through logs, revisions and replica status.

Los logs de Container Apps pueden incluir logs de tu contenedor o logs de sistema (la plataforma)

Confirmar app config e ingress

Antes de entrar a mirar logs, revisar la app config e ingress settings para revisar cosas como que se esté usando un ingress interno cuando se requiere uno externo.
También se puede obtener el FQDN para poder enviar una health check request

az containerapp show -n ai-api -g rg-aca-demo

Read More

ACA Runtime (env vars & secrets)

Environment variables (nonsensitive settings)

You can add settings during create

az containerapp create -n ai-api -g rg-aca-demo \
	--environment aca-env-demo \
	--image myregistry.azurecr.io/ai-api:v1 \
	--ingress external --target-port 8000 \
	--env-vars LOG_LEVEL=info FEATURE_EMBEDDINGS=true

Or you can update or remove existing ones

az containerapp update -n ai-api -g rg-aca-demo \
	--set-env-vars LOG_LEVEL=debug

Read More

Pull from Private Registries (Azure Container Apps)

Un registry privado permite controlar quien tiene acceso a las imágenes.

Azure Container Apps soporta:

  • para cualquier registry privado: auth con user & pwd
  • si el registry es Azure Container Registry, managed identity

Configurar user & pwd

If you’re using ACR, then the CLI may infer credentials if you omit them

az containerapp registry set -n ai-api -g rg-aca-demo \
	--server myregistry.azurecr.io \
	--username myUser \
	--password myPassword

Read More

Environments (Azure Container Apps)

Azure Container App se organiza en environments. Estos entornos son sandboxes donde se ejecutan uno o más contenedores.

Se pueden usar para separar o agrupar servicios, o por entornos típicos

  • DES
  • UAT
  • PROD

Son límites lógicos. Los servicios no pueden conectarse entre entornos.

Crear e inspeccionar un entorno

# creamos un RG
az group create \
	--name rg-aca-demo
	--location centralus
	
# creamos un entorno
az containerapp env create \
	--name aca-env-demo \
	--resource-group rg-aca-demo \
	-- location centralus
	
# inspeccionarlo
az containerapp env show \
	--name aca-env-demo \
	--resource-group rg-aca-demo

Read More

ACA Deployments (CLI & YAML)

Deploy quickly

El mejor comando para prototipos o probar el servicio es az containerapp up

(crea el environment y publica el contenedor)

az containerapp up \
	--name my-container-app \
	--resource-group rg-aca-demo \
	--location centralus \
	--environment aca-env-demo \
	--image mcr.microsoft.com/k8se/quickstart:latest \
	--target-port 80 \
	--ingress external \
	--query properties.configuration.ingress.fqdn

Si se usa una referencia para la container image, el repositorio tiene que estar en lower case. Si no, puede haber fallos de pull que se vean como errores de autenticación

Read More

Sidecar pattern (App Service)

Un sidecar es un contenedor auxiliar que corre en el mismo entorno que el contenedor principal. Los sidecars añaden capacidades como IA, telemetría o caching sin tener que añadir esas capacidades a la imagen principal.

Este entorno compartido crea sinergias entre los contenedores, pero el patrón no sustituye el caso para múltiples servicios independientes.

Sidecar execution model

Una Service App que use el patrón sidecar tiene un solo contenedor principal y hasta 9 contenedores sidecar.

App Service gestiona a todos los contenedores como si fueran una única aplicación y solo el contenedor principal recibe tráfico HTTP externo. Los sidecars se mantienen alcanzables a través de la red compartida.

Cada contenedor tiene su propia imagen, comando de startup y configuración propia.

Ciclo de vida

  • App Service hace start y stop de todos los contenedores como una única app
  • Cuando se escala cada instancia tiene su set formado por el contenedor principal y sus sidecars - al quitar escalado y remover una instancia, se quita todo su set (contenedor principal + sidecars)
  • Un config deployment puede actualizar una imagen de sidecar de manera independiente de la imagen principal, pero la nueva configuración pertenece a la misma App

Read More

Connect containers and share files (App Service)

Los sidecars se comunican a través de un shared network namespace por lo que la main app puede llamar procesos sin necesitar un endpoint de servicio aparte. Los contenedores también comparten el volumen /home para file exchange.

Conectar a través del shared network namespace

Todos los contenedores se conectan a través de localhost:<port>

ejemplo que crea un HTTP client para el local model endpoint que está en un sidecar

import asyncio

import httpx

MODEL_ENDPOINT = "http://localhost:11434/v1/chat/completions"

async def request_completion(messages: list[dict[str, str]]) -> dict:
    timeout = httpx.Timeout(10.0, connect=2.0)
    async with httpx.AsyncClient(timeout=timeout) as client:
        async with asyncio.timeout(30.0):
            response = await client.post(
                MODEL_ENDPOINT,
                json={"model": "support-model", "messages": messages},
            )
        response.raise_for_status()
        return response.json()

Read More

Configure main and sidecar containers (App Service)

Create a sidecar-enabled app

Crear una app en un plan de Linux existente. --sitecontainers-app reemplaza el viejo DOCKER|<image>.

az webapp create \
	--name <app-name> \
	--resource-group <resource-group> \
	--plan <app-service-plan>
	--sitecontainers-app

También se puede modificar una app que ya exista

az webapp sitecontainers convert \
	--mode sitecontainers \
	--name <app-name> \
	--resource-group <resource-group>

Read More

Troubleshoot containerized apps (App Service)

Container logs

App Service captura el output de los contenedores a stdout y stderr. Se puede activar container logging para persistir estos logs y hacerlos accesibles a través del portal y CLI.

Si los activamos mediante filesystem los podemos acceder en /home/LogFiles

Log stream

Log Stream nos da acceso en tiempo real al output del contenedor. Muestra el output de todas las instancias que haya e incluye IDs para diferenciarlas.

Diagnostic console (Kudu)

Kudu (SCM site) es una consola avanzada de diagnóstico para App Service. Da acceso a app configs, log files en storages y endpoints de diagnóstico

Se accede mediante un site separado de la app y requiere autenticación para hacer management de la web

https://<app-name>.scm.azurewebsites.net

Read More

Configure container runtime (App Service)

El container runtime controla como el App Service ejecuta el container. Estas settings afectan a:

  • container startup
  • network config
  • file system behavior
  • health monitoring

Startup commands

App Service corre containers usando el entrypoint y los comandos definidos en el Dockerfile. Se puede hacer un override de estos defaults con un custom startup command

Escenarios donde esto puede ser necesario:

  • Pasar args que sean específicos por entorno
  • Run database migrations antes de ejecutar la aplicación
  • Start múltiples procesos dentro del contenedor
  • Override default framework configs

Este startup command reemplaza las instrucciones CMD del Dockerfile.

az webapp config set \
	--resource-group myResourceGroup \
	--name myDocumentProcessor \
	--startup-file "gunicorn --bind=0.0.0.0:8000 --workers=4 app:application"
	
	# opción para shell
	--startup-file "/bin/bash -c 'python migrate.py && gunicorn app:application'"

Read More

Configure app settings (App Service)

App settings

Settings clave-valor que se inyectan como variables de entorno. Se encriptan todos los valores y solo se desencriptan al inyectarlos en el contenedor.

declaración

az webapp config appsettings set \
	--resource-group myResourceGroup \
	--name myDocumentProcessor \
	--settings \
		STORAGE_ACCOUNT_NAME=mystorageacc \
		LOG_LEVEL=INFO \
		MAX_DOCUMENT_SIZE_MB=50

uso en Python, incluyendo default values

import os

storage_account = os.environ.get('STORAGE_ACCOUNT_NAME')
log_level = os.environ.get('LOG_LEVEL', 'WARNING')
max_size = int(os.environ.get('MAX_DOCUMENT_SIZE_MB', 10))

App settings que contengan : se convierten en __. Por ejemplo ConnectionStrings:DefaultConnection pasa a ser ConnectionStrings__DefaultConnection

Read More

Azure App Service CLI

Deploy to App Service

From ACR

Crear el webapp y asignar la container image usando ACR como registry.

az webapp create \
	--resource-group myResourceGroup \
	--plan myAppServicePlan \
	--name myDocumentProcessor \
	--container-image-name myregistry.azurecr.io/docprocessor:v1

From other container registries

public image containers from Docker Hub. (para repos privados se añade user & pwd).

az webapp create \
	--resource-group myResourceGroup \
	--plan myAppServicePlan \
	--name myWebApp \
	--container-image-name nginx \
	--docker-registry-server-url https://index.docker.io/v1/

Read More

Azure App Service

Azure App Services es una fully managed platform para ejecutar contenedores sin tener que encargarse de la infraestructura.

Permite ejecutar custom Linux containers como webapps (web applications).
Seleccionas una container image del registry y App Service se encarga de la provisión, load balancing y escalado.

Container image sources

Cuando creas una webapp, puedes seleccionar de donde se hace el pull de la container imagen.

  • Azure Container Registry (ACR): es el recomendado para PROD. Se integra con Entra ID para autenticación. Cuando seleccionas ACR, especificas el registro, como te autenticas, el nombre y la tag de la imagen
  • Otro container registry: cualquiera público como Docker Hub, GitHub Container Registry o self-hosted

Read More

Image tagging and versioning (Azure Container Registry)

Las diferentes estrategias de tagging afectan directamente al mantenimiento, deployment reliability, capacidades de rollback

Tagging strategies

Las tags son una manera humana de referenciar contenedores de imágenes.

Stable tags

Stable tags como latest, develop, v1, v1.2 se reutilizan entre múltiple image pushes y cuando se hace un overwrite de la tag, esta se quita de la imagen vieja y se pone en la nueva.

Es útil para las siguientes situaciones

  • security updates: si se hace un patch se actualiza automáticamente a la versión con el fix
  • Separar entornos: el entorno de DEV siempre contendrá la imagen develop
  • CI/CD: cuando el cliente deba tener siempre la última versión

La gran desventaja que tiene es la inconsistencia. Nodos diferentes pueden hacer un pull de la misma tag en momentos diferentes y recibir imágenes diferentes.

Unique tags

Las tags únicas como v.1.2.0-build456 no se reutilizan. Cada image push genera una nueva tag y se preservan todas las anteriores en el registry

Es útil para las siguientes situaciones

  • PROD deployments: cada nodo del cluster hace pull de la misma imagen
  • rollback: es fácil volver a una imagen determinada
  • auditorias y compliance: demuestra que imagen específica estaba desplegada durante un incidente

Read More

Build and run images (ACR Tasks)

ACR Tasks permite descargar sobre Azure la responsabilidad de hacer build de container images sin requerir una instalación local de Docker. Esto soluciona el problema de builds inconsistentes entre ordenadores diferentes.

En vez de hacer build local de imágenes y hacer push al registry, envías tu código a ACR y dejas que Azure se encargue del build process. Esto nos otorga:

  • Builds consistentes: sin problemas de “en mi ordenador funciona”
  • Sin necesitar tener Docker instalado localmente
  • CI/CD integration: se puede hacer trigger al hacer push de un commit, mediante cronjobs, etc.
  • Soporte multi-plataforma: soporta Linux, Windows y ARM

Quick tasks

Las Quick tasks son la manera más rápida de hacer build y push de una sola container image.

Quick tasks son ideales cuando necesitas hacer una build de manera inmediata o para una única vez y no necesitas persistencia

El comando az acr build envía el source code a ACR, hace build de la imagen en el cloud y hace push al registry. Es similar docker build y docker push pero en Azure

# el . final indica que el directorio sobre el que se ejecuta es el actual
az acr build \ 
	--registry myregistry \
	--image inference-api:v1.0.0 \
	.

El mismo comando acepta varios contextos de donde obtener el código

  • local directory
  • git repository
  • remote tarball: archivos comprimidos en un server remoto accesible mediante URL
# ejemplo haciendo retrieve de un github repository
az acr build \
	--registry myregistry \
	--image inference-api:v1.0.0 \
	https://github.com/myorg/inference-api.git

Read More

ACR CLI

(repo de Microsoft para descargar un proyecto de Python, el cual crea un ACR)

El comando az acr build forma las quick tasks de ACR - es la manera fácil y rápida de hacer push del source code, hacer build de la imagen en el cloud y hacer push al registry.

# para ./api debes ejecutar esto en el local del repo
# $ACR_NAME es el nombre del registry, que debe estar creado en Azure antes de hacer esto
# con v1.0.0 seleccionamos el tag con el que guardamos la imagen
az acr build \
	--registry $ACR_NAME \
	--image inference-api:v1.0.0 \
	./api

Verificar que la imagen existe en el registro listado repositorios y tags

# listar repositorios del ACR
az acr repository list \
	--name $ACR_NAME \
	--output table
	
# listar tags del ACR
az acr repository show-tags \
	--name $ACR_NAME \
	--repository inference-api \
	--output table

Read More

Azure Container Registry (Azure Container Registry)

Azure Container Registry (ACR) es un managed, private Docker registry service que almacena y distribuye container images y artefactos.

A diferencia de los registries públicos nos otorga:

  • control directo sobre el acceso
  • geo-replicación (global distribution)
  • integración con servicios de Azure como AKS y Azure Container Apps

Para AI workloads, ACR ofrece:

  • private storage: mantén en tu Azure environment
    • las imágenes que contienen los modelos
    • pre-processing containers
    • inference APIs
  • geo-replicación: multiples regiones para menor latencia
  • integration: se conecta directamente a AKS, Azure Container Apps y Azure App Service. Deployments más fáciles
  • content formats: almacena docker images, helm charts y artefactos en un mismo registry

Niveles:

  • basic: development y learning scenarios
  • standard: más almacenamiento y mejor rendimiento para PROD
  • premium: geo-replicación, endpoints privados y rendimiento empresarial

Componentes de ACR

ACR usa una jerarquía en 3 niveles para organizar el contenido

azure registry hierarchy

Read More

AI-200 Labs

Labs oficiales de Microsoft

Azure Container Registry (ACR)

Azure App Service
Azure App Service - Sidecar pattern for AI

Azure Container App (ACA)
Azure Container App (ACA) - diagnosticar un fallo
Azure Container App (ACA) - KEDA triggers (autoscaling)
Azure Container App (ACA) - execute AI code securely in dynamic sessions

Azure Kubernetes Service (AKS) - deploy de una AI inference API
Azure Kubernetes Service (AKS) - configurar una app
Azure Kubernetes Service (AKS) - troubleshoot apps

Azure CosmosDB for NoSQL - build a RAG document store
Azure CosmosDB for NoSQL - build semantic search application
Azure CosmosDB for NoSQL - optimize query performance with vector indexes

Azure Database for PostgreSQL - build agent tool backend
Azure Database for PostgreSQL - implement vector search
Azure Database for PostgreSQL - optimize vector search

Azure Managed Redis - perform data ops
Azure Managed Redis - pub/sub events
Azure Managed Redis - implement semantic search

Azure Service Bus - process messages

Azure Event Grid - publish and receive events

Azure Functions - create MCP server
Azure Durable Functions - build durable doc-processing workflow

Azure Key Vault - manage secrets
Azure App Configuration - retrieve settings and secrets

OpenTelemetry - instrument an app
Azure Monitor - query logs with KQL

Read More