Azure Index
Azure Meta
Azure CLI
Azure Naming Strategy
Azure Functions
Azure Functions - Introduction
Azure Functions - Fundamentals
CosmosDB
Azure AD B2C
Azure AD B2C
Azure AD B2C - Personal Notes
Azure AD B2C - JWK
Azure CLI
Azure Naming Strategy
Azure Functions - Introduction
Azure Functions - Fundamentals
Azure AD B2C
Azure AD B2C - Personal Notes
Azure AD B2C - JWK
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
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
cloud_RoleName identifica que servicio ha generado la excepciónrequestDuration revela donde ha ido lenta la requestLa 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
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.
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 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.
Common metrics:
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
Las dashboards se pueden compartir con team members. Publicarlas las hace disponibles para otros usuarios en tu organizacion mediante RBAC
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.
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.
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:
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.
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.
Cada Azure Monitor alert rule consiste de 4 coponentes que funcionan juntos para detectar problemas y hacer trigger de respuestas.
Tenemos dos tipos primarios de alertas para telemetria:
Azure Monitor tiene smart detection con ML que identifica patrones unusuales en tu app sin necesitar de configuración.
Lo mejor es usar el modo smart junto a tus reglas configuradas manualmente.
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.
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.
Al ser vendor-netrual puedes enviar la misma telemetry data a Azure Monitor, Proemetheus, Grafana…
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:
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
Azure Monitor soporta 2 primary instromentation approaches
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.
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.
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()
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 callsurllib outgoing HTTP callspsycoph2: PostgreSQL database queriesloggingUsar 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/"
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/"
)
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",
})
)
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:
SpanKind.SERVER y SpanKind.CONSUMER) aparecen en la tabla requestsSpanKind.CLIENT, SpanKind.INTERNAL, SpanKind.PRODUCER) aparecen en la tabla dependencieslogging module u OpenTelemetry logging API aparecen en la tabla tracesexceptionscustomMetricsSampling 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:
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,
# )
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",
)
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
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.
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.
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
requests contiene server spans y consumer spansdependencies contiene client, internal y producer spanstraces contiene log recordsexceptions contiene excepciones grabadasTodas 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
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)
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.
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 servicioSpanKind.CLIENT outgoing call a un servicio o recurso externoSpanKind.INTERNAL operacion interna dentro del servicio que no cruza process boundariesSpanKind.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
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.
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.
Tablas más relevantes
requests almacena incoming HTTP requests con detalles como duration, response code y success status. Cada row representa una requestadependencies captura outbound calls desde tu app a BBDD, HTTP endpoints, Azure services y otros microsexceptions ambas handled y unhandledtraces app log messages de frameworks como ILogger, log4jcustomEvents almacena custom business events como document classifiedcustomMetrics almacena custom numeric measurements como queue depth o model inference confidence scoreperformanceCounters almacena system-level metrics como CPU usageHay columnas que son comunes a todas las tablas:
timestampoperation_Id linkea los items de una single distributed trace para poder seguir las requests a través de los servicioscloud_RoleName identifica que servicio genera la telemetríacustomDimension contiene una bag de propiedades dinamicas para enriquecer la telemetria con tus propios datosKQL 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 interesantake operator - devuelve un ser arbitrario de n rows de la tabla. Es util para inspeccionar el estado y calidad de los datos con un muestreotop operators - devuelve las primeras n rows, sorteadas por una columna especificarequests
| where timestamp > ago(1h)
| where success == false
| project timestamp, name, resultCode, duration, cloud_RoleName
| top 20 by duration desc
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 errorcount_distinct() - para small datasets. es mas preciso pero mas intensivo de recursospercentile() function - calcula un specific percentile value. util para obtener por ejemplo latency analisys del p95bin() function - agrupa valores continuos como timestamps en intervalos fijos. Ejemplo bin(timestamp, 1h) redondea cada timestamp a la hora más cercanarequests
| where timestamp > ago(24h)
| summarize requestCount = count(), avgDuration = avg(duration)
by bin(timestamp, 1h), cloud_RoleName
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
App Configuration y Key Vault sirven roles complementarios en administrar settings para apps.
Está diseñado para app settings, en pares clave-valor, y que sean no sensibles.
Características
Esto incluye
Está diseñado para datos sensibles.
Características
Esto incluye
| 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 |
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
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
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
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
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.
TODO: WIP. Continuar con esto más adelante en una segunda pasada
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.
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) 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.
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:
En todos los casos los objetos se encriptan at rest y se controla el acceso con Entra ID y RBAC
Opera en 2 tiers:
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"}
)
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
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
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
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:
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 Contributores 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
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.
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.
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.
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.
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.
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:
SecretNearExpiry eventPara servicios que soportan dos keys activas de manera simultanea, como Storage accounts y CosmosDB.
De esta manera garantizamos que al menos hay una credencial valida que exista siempre.
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.
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
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.
El Key Vault secrets SDK requiere de dos packages
azure-keyvault-secrets para vault opsazure-identity para authpip 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
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:
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET environment varsaz loginazd auth loginConnect-AzAccountPara 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.
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.
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.
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
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
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.
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.
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.
El scope de tu cache determina cuantas llamadas a Key Vault hace tu app de manera colectiva.
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.
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.
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")
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.
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
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.
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:
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.
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
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:
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,
}
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
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.
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.
App Configuration guarda cada setting como pares clave-valor con propiedades adicionales para poder controlar como se identifica, interpreta, y administra la setting.
: o / Ejemplo OpenAI:Endpoint. No se fuerzan schemas sobre las keysapplication/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 VaultLa 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-identitypara auth
pip install azure-appconfiguration-provider azure-identity
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"]
También se soporta aqui. Prueba diferentes metodos de auth en orden hasta que uno funciona.
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
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
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.
Las labels crean variaciones de la misma key para diferentes entornos, regiones o app versions.
Una key como Pipeline:BatchSize puede tener:
Development con valor 10Staging con valor 50Production con valor 200El 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.
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.
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:EndpointOpenAI:DeploymentNameOpenAI:MaxTokensCosmosDB:DatabaseNameCosmosDB:ContainerNameCon esta convención un componente que solo necesite OpenAI settings puede cargar keys usando key_filter="OpenAI:*"
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.
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
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)
Estas se pueden usar de muchas maneras
Los triggers y los bindings ofrecen una manera declarativa de conectar funciones a servicios externos.
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.
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)
Los Auth levels controlan quien puede invocar la función
anonymous no key - para development e internal health check endpointsfunction - requiere una key function-specific enviada en functions-keys header o code query param. recomendado para PRODadmin - requiere la master key. reservarla para administrative operationsEl uso de auth keys es una base pero, no sustituye a Entra ID.
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:
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)
host.jsonmaxConcurrentCalls controla cuantos mensajes puede procesar cada instancia de manera simultánea - un valor de 1 asegura que cada mensaje tiene full instance resourcesmaxAutoLockRenewalDuration 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 WIPmaxDeliveryCount (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"
}
}
}
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.
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
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()
}))
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
DefaultAzureCredentialpara 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...
Los application settings son pares clave-valor que se configuran a través de:
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 settingsos.getenv para settings con fallback defaultsEste 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.jsondel.gitignore
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.
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.
IMPORTANTE
Azure App Configuration provee un store centralizado para non-secret configuration values y feature flags.
/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
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.
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.
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:
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...
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
__acountName o service-specific URIs__accountEndpoint__fullyQualifiedNamespacePara 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
)
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
x-functions-key o el query param code, al llamar a la funcionmcp_extension system key para autenticar MCP client connections a la function app. Son managed por el runtime y no se deben compartirSe 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.
/IMPORTANTE
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.
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.
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
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
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
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.
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 historyEvita las siguientes operaciones en orchestrator functions:
datetime.now()time.sleep()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"}
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.
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.
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,
)
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.
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.
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
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:
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.
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.
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.
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.
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:
Approved o RejectedUn 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.
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",
)
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.
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.
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.
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.
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=truesolo tiene efecto en local. Al lanzar la Function, Azure crea o requiere de un storage account automáticamente
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.
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.
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 es el delay que ocurre cuando la Azure Functions platform:
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.
Son los dos planes enfocados a AI backends.
Flex consumption es el recomendado by default.
Características
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.
Elimina el cold start del todo y mantiene siempre al menos una instancia en caliente.
Características
Elige Premium cuando:
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).
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
202 Accepted con una URL de statusEntonces 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
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:
aeg-sas-key)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:
requestId o pipe run ID para tracear entre servicios distribuidosprocessingDurationMs o modelVersion permiten monitorizar trendsEl 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
DefaultAzureCredentialpara 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)
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"
Event Grid soporta dos event schemas
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 colisionessource identifica el sistema origen. Combinado con type permite identificar el contexto donde el evento ocurreid es unico de este evento. Los consumers lo usan para detectar y deduplicar deliveries repetidasAtributos opcionales:
subject provee de un path para filtrar. Se usa con valores jerarquicos que reflejen el contexto del evento permitiendo filtrar por prefijos y sufijostime cuando ocurre el eventodatacontenttype formato del payloaddata payload como talIMPORTANTE
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.InferenceCompletedcom.contoso.ai.EmbeddingsRefreshedcom.contoso.ai.AnomalyDetectedcom.contoso.ai.ContentClassifiedEl 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.
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
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íficassubjectWendsWith: se usa para filtrar por tipo, versión o estadoaz 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
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:
StringContainsNumberGreaterThanStringBeginsWithBoolEqualsIsNotNullSe 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:
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
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.
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:
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.
Hay dos params para controlar el retry (se establecen al crear un event subscription):
(se para cuando se cumpla el primero)
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
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 MaxRetryDurationExceededdeliveryAttempts numero de reintentoslastDeliveryOutcome el resultado del last delivery NotFound, TimedOut, BusypublishTime tiempo en el que Event Grid acepto el eventolastDeliveryAttemptTimeLa 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.
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:
Usamos batches para sistemas que generan o procesan un gran volumen de requests. Se configura batching en el event subscription con 2 params:
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
Event Grid publica metrics a través de Azure Monitor para tener visibilidad del estado del sistema.
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.
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.
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
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)
Método complete_message() lo marca como procesado OK y lo quita de la queue de manera permanente.
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
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
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
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.
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)
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
# 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.
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
receiver.renew_message_lock() periodicamente durante el reprocesadoAutoLockRenewer 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
Este approach se salta el lock management y usa la queue solo para un reliable initial delivery
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:
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.
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)
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.
Los topics son endpoints que reciben eventos de los productores. Hay de varios tipos
No hay por que usar exclusivamente uno. Una app normal puede usar ambos por ej system y custom topics.
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.
Los event handlers son los servicios de destino que reciben y procesan eventos.
Event Grid soporta varios handler types para push delivery:
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.
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.
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.
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
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.
Un message de Service Bus se compone de:
message_idPodemos estructurar el body de un mensaje como JSON payload con todos los campos que necesita el consumer
El campo
message_idse 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"
}
)
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"
}
)
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"}
)
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
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()lanzaMessageSizeExceededErrorcuando 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)
La primera decisión de ARQ con Azure Service Bus debe ser si usamos queues o topics + subscriptions.
IMPORTANTE
Usamos queues cuando:
Usamos topics + subscriptions cuando:
/IMPORTANTE
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:
Las queues usan FIFO y se pueden usar para multi-step pipelines donde todos los pasos se deben ejecutar en orden
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.
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
TrueFilter (default) acepta todos los mensajes; FalseFilter rechaza todos los mensajesSe 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'")
)
El SDK azure-servicebus usa el mismo ServiceBusClient para ambos queues y topics.
get_queue_sender() envía a una queueget_queue_receiver() queue el consumer
get_topic_sender() publica en un topicget_subscription_receiver() subscribe el consumerEn 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)
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:
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.
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.
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.
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.
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.
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
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.
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.
Hash storage es más rápido y usa menos memoria porque los vectores se guardan como compact binary blobs.
Usar Hash cuando:
JSON storage añade overhead debido al array structure, pero ofrece más flexibilidad.
Usar JSON cuando:
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
# 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
}
)
# 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
)
)
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
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)
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
)
)
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.
Para poder guardar vectores necesitas definir un index schema que especifique como manejar los embeddings.
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
)
)
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:
# 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:
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_RUNTIMEindica 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
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
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"
}
)
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()
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.
Una query KNN requiere
@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 syntaxKNN 5 pide 5 NN@embedding especifica que campo contiene los vectores$query_vec es un placeholder para tu query vectorialAS 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 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}
)
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}
)
ATENCION: esto moverlo a otra parte ya que es un tema multi-repetido a lo largo de toda la cert.
/ATENCION: esto moverlo a otra parte ya que es un tema multi-repetido a lo largo de toda la cert.
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"
}
)
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"
}
)
IMPORTANTE
Para la mayoría de AI apps que envuelven texto, usaremos COSINE
/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
})
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.
IMPORTANTE
Usa pub/sub cuando:
Usa Stream consumer groups cuando:
/IMPORTANTE
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.
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)
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
# 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'])
/IMPORTANTE
IMPORTANTE
No uses pub/sub cuando necesites:
/IMPORTANTE
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.
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
)
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)
> symbol and consumer positionsAl 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)
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)
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.
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)
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}")
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.
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 tasksXREADGROUP para hacer pull de tasks en tu workerXACK para marcar tasks como completasIMPORTANTE
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
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'
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)
Redis Streams son ideales para escenarios donde queremos reliability y la persistencia de las tasks es importante.
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
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}")
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])
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']
}
# 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)
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.
Usarlo cuando necesites:
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
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)
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)
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)
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)
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
)
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
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']
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
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}")
Es crucial poner expiration times para que se invaliden automaticamente. EXPIRE, SETEX, TTL funcionan con todos los data types.
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
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)
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')
Una cache efectiva asegura que tu app sirve datos frescos y mantiene una buena performance.
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)
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
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}"
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)
redis usa automaticamente connection pooling, pero es algo que se puede configurarAzure 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.
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.
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 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.
| Client library | Language |
|---|---|
| StackExchange.Redis | C#/.NET |
| Lettuce | Java |
| node_redis | Node.JS |
| redis-py | Python |
Reddis supports two clustering policies
Microsoft manages the conf and management of Redis, which disables some commands by default
(no entro en detalle en esto de momento)
KEYS in PROD; use SCAN for iterating over keysMonitorizar estas métricas y escalar cuando pasen del 75%
(leer este post muy por encima; saber más o menos para que son, pero esto es ya mucho detalle; doc og)
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:
<-> - es la más costosa computacionalmente hablando<=> - relación coste/performance media. Recomendada a usar para recommendation engines y semantic search ya que procesa vectores de diferentes magnitudes de manera consistente<#> - 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
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.
shared_buffersIMPORTANTE
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;
work_memEl 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
effective_cache_sizeEl 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).
random_page_costEl 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;
effective_io_concurrencyEl 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
parallel_tuple_costLos 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;
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;
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.
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)
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 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:
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
Se puede hacer track de database-level metrics con Azure Monitor
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
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 '{}'
);
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);
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
(se puede, pero no me voy a meter en este cristo para la cert)
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');
(de momento lo dejo aqui; continuar)
Cada conexión consume server memory, requiere auth overhead y cuenta contra el server limit.
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)
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
PgBounder ofrece varios params
pgbouncer.default_pool_size 20-50 dependiendo de concurrency needspgbouncer.max_client_conn +5000 para high-traffic appspgbouncer.pool_mode (transaction)pgbouncer.query_wait_timeout (30-120s)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()
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.
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 |
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.
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:
m. Valores más altos crean un grafo más denso con mejor recall pero más consumo de memoria y longer build times.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)
Requisitos
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.
Requisitos
Ejemplo de HNSW: recommendation engine. Necesitamos high recall para que los usuarios vean todos los productos y sub-10ms query latency para mucho concurrencia.
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
Effective semantic retrieval combina vector similarity con metadata filtering, distance thresholds y query patterns.
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.
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)
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;
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”
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'
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)
);
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;
pgvector provee de tres distance operators para medir similitud entre vectores. Cada uno calcula un tipo diferente.
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 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;
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;
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
vectortype. Si necesitamos ahorrar espacio, y solo después de comprobar que la precisión es suficiente, podemos usarhalfvec
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 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 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)
);
Los índices vectoriales y los embeddings necesitan ongoing maintenance a medida que tus datos van evolucionando.
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.
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 CONCURRENTLYpara crear un replacement index sin bloquear queries. Toma más tiempo y recursos, pero la app continua sirviendo requests.
EXPLAIN ANALYZE-- 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_idxes más simple pero bloquean queries durante el rebuild
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;
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
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.
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.
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
);
(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 sigue un patron de 3 pasos:
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.
RAG apps funcionan con chunks (no con documentos enteros).
Usamos dos tablas. Una para source documents y otra para chunks con embeddings
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)
);
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()
);
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);
diseñar un RAG es un balanceo entre:
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:
Choose HNSW when:
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
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
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')
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 pathsEjemplos:
metadata->>'status' extrae el status field como textocheckpoint_data#>>'{results,0,score}' navega un nested path para obtener el valor específicoExistence and containment operators enable efficient filtering
? comprueba key existence@> tests containmentEjemplos:
WHERE metadata ? 'priority'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';
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;
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;
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;
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 NOTHINGhacemos skip de rows que violarian constraints
A
DO UPDATEse le puede añadirWHEREpara 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;
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;
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. Usarfetchall()para result sets que iterar
IMPORTANTE
OperationalError for connectiosn and timeouts/IMPORTANTE
conn = psycopg.connect(
connection_string,
connect_timeout=10,
options="-c statement_timeout=30000" # milliseconds
)
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
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,))
PostgreSQL organiza los objetos en una jerarquía:
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
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
);
IMPORTANTE
TEXT no tiene límite y VARCHAR(n) enfuerza un máximo. No hay diferencia de performance.TIMESTAMPTZ para datos de tiempo que operen a través de time zones.BIGSERIAL par tablas que excedan de 2 billion rows./IMPORTANTE
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 existeCASCADE: borra o hace update de las referenciasSET NULL: pone la FK a nullSET DEFAULT: pone la FK con el defaultON 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
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);
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;
Una conexión requiere de:
<server-name>.postgres.database.azure.com)5432 conexiones directas; 6432 PgBouncer)username@servername para Entra auth)Azure Database for PostgreSQL soporta dos tipos de autenticación:
Para conectar las Entra identities necesitamos obtener un token de https://ossrdbms-aad.database.windows.net
El proceso es:
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
PostgreSQL clients usa sslmode param para controlar la encriptación y validar certificados. Tiene los siguientes modos:
Para PROD usar
verify-fullpara verificar que el server es genuino y real
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
IMPORTANTE
Azure Database for PostgreSQL soporta dos modelos de networking:
/IMPORTANTE
# 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
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.
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:
Los tiers si se pueden cambiar más adelante para adaptarse a tus necesidades
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
Algunas de las extensiones soportadas que son útiles para AI apps:
Puedes activar otras extensiones disponibles con CREATE EXTENSIONS
CosmosDB usa indexes para ejecutar queries eficientemente sin tener que escanear todos los contenedores.
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
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 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.ST_DISTANCE, ST_WITHIN, ST_INTERSECTS. Para AI apps que incorporan filtros por localización geográfica.VectorDistance function (flat, quantizedFlat, diskAnn - está en otro post más en detalle)CosmosDB soporta dos indexing modes que controlar cuando y como se actualizan los indices
Index size contribuye al total storage consumido por el contenedor. Esto depende de:
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
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 pathIMPORTANTE
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": "/*" }
]
}
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.
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.
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
excludedPathspara prevenir range indexing del embedding array. ElvectorIndexesdefine undiskAnnindex 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" }
]
}
CosmosDB ofrece 3 tipos de vector index.
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:
Limitaciones:
Ejemplo: Los usuarios siempre filtran por categoría y cada categoría tiene unos pocos de cientos de documentos
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:
Características:
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
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:
Características:
Se recomienda para PROD AI apps con colecciones grandes de embeddings
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.
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.
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.
WHERE? ¿Son equalidad = o rangos >?ORDER BY y con que orden?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:
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")
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
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.
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:
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
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.
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
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.
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
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
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
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
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
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:
/*, incluir explicitamente solo las que realmente queramos/IMPORTANTE
(esto me parece demasiado a fondo para el examen)
CosmosDB consistency levels controlan el trade-off entre data freshness, latencia, throughput y disponibilidad.
Ordenadas de strongest a weakest.
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.
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.
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:
CosmosDB ofrece dos maneras de consumir el change feed.
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
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.
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:
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
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
Para aplicaciones con cambios de embeddings frecuentes o mucho volumen es necesario tomar una estrategia:
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
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.
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
VectorDistanceLa 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
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}")
Lo ideal es usar queries parametrizadas para pasar los embeddings mediante @queryVector
parameters = [
{"name": "@queryVector", "value": query_embedding}
]
results = container.query_items(
query=query,
parameters=parameters,
enable_cross_partition_query=True
)
La score depende de la distance function que haya configurado. Para cosine similarity:
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)
El TOP N determina cuantos resultados devuelve la query. El valor óptimo depende según la app:
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:
Reservarlo para evaluation o testing, o cuando trabajamos con datasets pequeños donde nos dé igual la performance y el coste.
diskANN es más potente pero más caro que quantizedFlatTOP N. Pedir 100 resultados si el user solo ve 10 gasta recursosLas 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.
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
)
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)
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"
)
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)
)
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]
)
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)
)
Queries híbridas complejas con filtros consumen más RU/s que queries vectoriales simples.
VectorDistance con FullTextScore requiere consumir lo de ambas. Usarlo cuando haya beneficio claro.WHERECosmosDB guarda los embeddings como document properties. Se crea un unified data model para mantener los vectores justo a los metadatos en la misma BBDD
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.
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:
{
"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, ...]
}
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
}
]
}
float32, float16, int8, uint8 (default: float32)cosine, dotproduct, euclidean (default: cosine)(sin más, no entrar en tanto detalle)
De ella depende lo que se entiende por contenidos “similares”.
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,
float32es el mejor balance por simpleza. Si los costes de almacenamiento son significantes, bajar afloat16, siempre que el testing determine que la búsqueda es aceptable
/IMPORTANTE
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
}
]
}
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
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.
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
)
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
CosmosDB for NoSQL soporta un lenguaje SQL-like optimizado para documentos JSON.
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")
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)
Azure CosmosDB soporta dos métodos de auth:
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)
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
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
kubectl exec -it <pod-name> -n ai-workloads -- /bin/sh
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
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
Se pueden ver:
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
Con kubectl
kubectl top nodes
kubectl top pods -n ai-workloads
kubectl: el portal para ver trends e históricos. kubectl para queries específicasUn 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 según la App sea interna o externa
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:
Ejemplo: Tu Vector DDBB se ejecuta en dos Pods y ambos tienen que estar disponibles para otro pod que lo consume
Una vez tenemos los manifiestos de deployments y services, se envían al cluster con kubectl apply. K8s se encarga del resto.
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
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
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
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 credentialskubernetes.io/tls para certificados TLS y keyskubectl create secret generic app-secrets \
--from-literal=DB_CONNECTION="Host=db;User=app;Password=secure" \
--from-literal=API_KEY="your-api-key"
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.
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
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.
AKS soporta dos approaches para persistent storage.
Azure Container Storage Interface (CSI) drivers integran Azure Storage con AKS. Los CSI drivers provisionan
Un PersistentVolumeClaim es una request de storage. Especificas cuanta capacidad y que modos de acceso necesitas.
Los modos de acceso incluyen
ReadWriteOnce: single-node accessReadWriteMany: shared-access across multiple nodesapiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
storageClassName: default
Los revision modes en ACA determinan como la app gestiona los deployments y como coexisten múltiples versiones. El mode que elijas afecta a:
IMPORTANTE
Una revision es una captura inmutable de una versión de una container app
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.
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.csvno existe, puede ser necesario que el backend lo vuelva a subir a la session actual
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
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.
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.
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
}
}
}
}
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
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.
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
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.
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.
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
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
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:
Microsoft mantiene azure-native scalers como:
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
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:
Scale definitions se compone de 3 partes:
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
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.
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
En Azure Container Apps, se ajustan los recursos por réplica y se escalan los límites juntos.
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.
update de límites de CPU y memoria
az containerapp update \
--name <app-name>
--resource-group <resource-group> \
--cpu <cores> \
--memory <size>
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)
az containerapp logs show \
--name <app-name> \
--resource-group <resource-group> \
--follow
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>
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.
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
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)
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
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
Un registry privado permite controlar quien tiene acceso a las imágenes.
Azure Container Apps soporta:
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
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
Son límites lógicos. Los servicios no pueden conectarse entre entornos.
# 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
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
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.
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.
Muchas veces un error de sidecar parece un error del main-container ya que este fallará al acceder.
(ahora mismo no voy a aprenderme todo esto porque me parece secundario de los secundarios y útil en un 0.1% de los casos. Lo dejo aquí de todos modos para una segunda pasada si me da tiempo)
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.
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()
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>
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 nos da acceso en tiempo real al output del contenedor. Muestra el output de todas las instancias que haya e incluye IDs para diferenciarlas.
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
El container runtime controla como el App Service ejecuta el container. Estas settings afectan a:
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:
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'"
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
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
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/
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.
Cuando creas una webapp, puedes seleccionar de donde se hace el pull de la container imagen.
Las diferentes estrategias de tagging afectan directamente al mantenimiento, deployment reliability, capacidades de rollback
Las tags son una manera humana de referenciar contenedores de imágenes.
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
developLa 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.
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
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:
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
# 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
(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
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:
Para AI workloads, ACR ofrece:
Niveles:
ACR usa una jerarquía en 3 niveles para organizar el contenido

Microsoft Foundry IQ es una managed knowledge layer para agentes y aplicaciones de IA.
Conecta datos (tanto estructurados como no estructurados) de empresa y datos de la web en bases de conocimiento reutilizables.
Usa agentic retrieval para devolver información relevante y permission-aware con sus referencias.
Es una capa más que tenemos disponible para nuestros agentes
| Componente | Proposito |
|---|---|
| Knowledge base | Top level resource. Identifica una colección de Knowledge sources y controla su comportamiento. Acepta prompts de sistema para establecer prioridades o de donde sacar los datos para cada query. (Ejemplo: Azure AI Search Service) |
| Knowledge source | Una conexión a contenido indexado o remoto. (Ejemplo: SP, Azure SQL DDBB, Azure Storage, etc.) |
| Agentic retrieval | Retrieval process. En el prompt al agente se le debe indicar cuando debe usar la base de conocimiento. |
Text analysis es el proceso de extraer información útil de un bloque de texto no estructurado mediante NLP como puede ser:
En Foundry tenemos dos aproximaciones para text analysis:
Podemos usarlos directamente out-of-the-box para:
Los modelos generalistas se recomiendan cuando necesites aplicar varias de estas técnicas a la vez
Azure Language is a NLP service for specific text analysis tasks. These analyzers return structured, deterministic output - making them well-suited for automated pipelines where we want consistent results.
Azure Language capabilities:
given this text
¡Hola! Me llamo Josefo y vivo en Madrid, España
we would get
| Language | ISO 6391 code | Confidence score |
|---|---|---|
| Spanish | es | 1.00 |
given this text
“Maria Garcia called from 020 7946 0958 and asked to send documents to 42 Market Road, London, UK, SW1A 1AA.”
we would get
| Text | Category |
|---|---|
| Maria Garcia | Person |
| 020 7946 0958 | Phone number |
| 42 Market Road, London, UK, SW1A 1AA | Address |
AI agents use models as its brain to reason and plan, and they also use tools to perform tasks, which are added as MCP servers.
Open standard que define como se conectan los agentes de IA a tools externas y data sources. MCP es un universal adapter para poder conectar agentes a MCP servers que exponen unas capacidades de una manera standard.
MCP usa una arquitectura cliente-servidor
Cuando un agente se conecta a un servidor MCP, puede descubrir que tools ofrece ese servidor e invocarlas como necesite.
Un MCP server puede responder a una petición:
Some regions may not be supported for some MCP servers. It happened to me with Azure Language MCP and Spain Central

Let’s create an application that uses the OpenAI Python SDK. For that we need to have created before:
Install the main library
pip install openai
Create a config file .env
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/openai/v1/
MODEL_DEPLOYMENT_NAME=gpt-4.1-mini
API_KEY=<your-foundry-key>
Create the app logic
import os
from dotenv import load_dotenv
from openai import OpenAI
# Load environment variables from .env file
load_dotenv()
endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
api_key = os.getenv("API_KEY")
deployment_name = os.getenv("MODEL_DEPLOYMENT_NAME")
# Create the client object
client = OpenAI(
base_url=endpoint,
api_key=api_key
)
# Make a request using the client
message = client.responses.create(
model=deployment_name,
input="",
)
# Print the results
print(f"Sentiment: {message.output[0]}")
Install it
pip install azure-ai-textanalytics
Adapt the config
AZURE_LANGUAGE_ENDPOINT=https://<your-resource>.cognitiveservices.azure.com/
API_KEY=<your-foundry-key>
App code for language detection
# Import packages
import os
from dotenv import load_dotenv
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient
# Load environment variables from .env file
load_dotenv()
endpoint = os.getenv("AZURE_LANGUAGE_ENDPOINT")
key = os.getenv("API_KEY")
# Create the client
client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))
# Make a request using the method for LANGUAGE DETECTION
text = "¡Hola! Me llamo Josefina y vivo en Madrid, España."
result = client.detect_language([text])[0]
# Print the results
print(f"Language : {result.primary_language.name}")
print(f"ISO code : {result.primary_language.iso6391_name}")
print(f"Confidence : {result.primary_language.confidence_score:.2f}")
Or if we modify the method called, for PII
# Make a request using the method for PII
text = "Maria Garcia called from 020 7946 0958 and asked to send documents to 42 Market Road, London, UK, SW1A 1AA."
result = client.recognize_pii_entities([text])[0]
# Print the results
print("Redacted text:", result.redacted_text)
print("\nEntities found:")
for entity in result.entities:
print(f" {entity.text} | category={entity.category} | confidence={entity.confidence_score}")
We split speech in two capabilities:
Speech-to-text software includes multiple models
Go to Build > Services and there we can choose the one we want to use

Then if we open Speech-to-text, you can speak there and test the service

It’s also possible to use it through the SDK for application’s usage.
Install the SDK
pip install azure-cognitiveservices-speech
App code
import azure.cognitiveservices.speech as speechsdk
# Set up the speech config using resource endpoint
endpoint_url = "ENDPOINT"
speech_key = "FOUNDRY_KEY"
speech_config = speechsdk.SpeechConfig(
subscription=speech_key,
endpoint=endpoint_url
)
# Create a recognizer with microphone input
audio_config = speechsdk.audio.AudioConfig(use_default_microphone=True)
speech_recognizer = speechsdk.SpeechRecognizer(
speech_config=speech_config,
audio_config=audio_config
)
# Event handlers
def recognized_handler(evt):
print(f"Recognized: {evt.result.text}")
def recognizing_handler(evt):
print(f"Recognizing: {evt.result.text}")
# Connect event handlers
speech_recognizer.recognized.connect(recognized_handler)
speech_recognizer.recognizing.connect(recognizing_handler)
# Start continuous recognition
speech_recognizer.start_continuous_recognition()
print("Say something...")
# Keep the program running
input("Press Enter to stop...")
speech_recognizer.stop_continuous_recognition()
When using the SDK it’s possible to perform real-time or batch transcription of audio which work as async jobs with audios you’ve saved.
Batches usually should be immediate but they work on a best-effort basis. Normally they start within minutes of the request but this is NOT guaranteed
A text-to-speech solution usually requires:
To synthesize speech the system typically:

code example
import os
import azure.cognitiveservices.speech as speechsdk
# This example requires environment variables named "FOUNDRY_KEY" and "ENDPOINT"
speech_config = speechsdk.SpeechConfig(subscription=os.environ.get('FOUNDRY_KEY'), endpoint=os.environ.get('ENDPOINT'))
audio_config = speechsdk.audio.AudioOutputConfig(use_default_speaker=True)
# The neural multilingual voice can speak different languages based on the input text.
speech_config.speech_synthesis_voice_name='en-US-Ava:DragonHDLatestNeural'
speech_synthesizer = speechsdk.SpeechSynthesizer(speech_config=speech_config, audio_config=audio_config)
# Get text from the console and synthesize to the default speaker.
print("Enter some text that you want to speak >")
text = input()
speech_synthesis_result = speech_synthesizer.speak_text_async(text).get()
if speech_synthesis_result.reason == speechsdk.ResultReason.SynthesizingAudioCompleted:
print("Speech synthesized for text [{}]".format(text))
elif speech_synthesis_result.reason == speechsdk.ResultReason.Canceled:
cancellation_details = speech_synthesis_result.cancellation_details
print("Speech synthesis canceled: {}".format(cancellation_details.reason))
if cancellation_details.reason == speechsdk.CancellationReason.Error:
if cancellation_details.error_details:
print("Error details: {}".format(cancellation_details.error_details))
print("Did you set the speech resource key and endpoint values?")
Azure Speech incluye un VoiceLive Service el cual permite construir agentes conversacionales. Esta API permite tener conversaciones en tiempo real.
VoiceLive Service API reune todo para que el agente pueda escuchar y pueda responder.

Esto también se puede usar programáticamente mediante el SDK
pip install azure-ai-voicelive
Cada vez hay más modelos multimodales los cuales aceptan ambos textos e imágenes. Esto reduce la necesidad de tener vision pipelines separadas.
Foundry soporta el uso de modelos multimodales desde la web (Azure OpenAI API).
Instalar el sdk
pip install openai
Ejemplo de código
import os
from openai import OpenAI
# Environment variables you set locally or in your app service:
FOUNDRY_KEY = "... your key ..."
ENDPOINT = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
MODEL_NAME = "your-model-deployment-name" # e.g., "gpt-4.1-mini" deployed as "my-vision-deploy"
client = OpenAI(
api_key=os.getenv("FOUNDRY_KEY"),
base_url=os.getenv("ENDPOINT"),
)
image_url = ""
response = client.responses.create(
model=os.getenv("MODEL_NAME"), # your deployment name
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is in this image? Provide 3 bullet points."},
{"type": "input_image", "image_url": image_url}
],
}
],
)
print(response.output_text)
Foundry contiene modelos especiales para generación de imagen
Todos estos modelos se pueden usar desde Foundry o con el SDK
Código App
import os
import base64
from openai import OpenAI
# Required environment variables (example names)
FOUNDRY_KEY="..."
ENDPOINT="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
MODEL_NAME="your-gpt-image-deployment-name" # e.g., "gpt-image-1"
client = OpenAI(
api_key=os.environ["FOUNDRY_KEY"],
base_url=os.environ["ENDPOINT"],
)
prompt = "A modern flat illustration of a robot holding a potted plant, clean vector style, pastel colors."
response = client.responses.create(
model=os.environ["MODEL_NAME"], # your deployment name in Foundry
input=prompt,
tools=[{"type": "image_generation"}],
)
image_base64 = next(
item.result for item in response.output
if item.type == "image_generation_call"
)
with open("foundry_generated.png", "wb") as f:
f.write(base64.b64decode(image_base64))
print("Saved: foundry_generated.png")
Foundry contiene modelos especiales para generación de imagen
Se puede usar la REST interface para integrar el servicio de generación de videos con una aplicación
ejemplos curl
crear video
curl -X POST "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/videos" \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d '{
"model": "sora-2",
"prompt": "A cinematic close-up of raindrops sliding down a neon-lit window at night.",
"size": "1280x720",
"seconds": "8"
}'
poll status
curl -X GET "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/videos/{video_id}" \
-H "api-key: $AZURE_OPENAI_API_KEY"
download video
curl -L "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/videos/{video_id}/content?variant=video" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
--output output.mp4
LEARN what Azure Content Understanding is and how it works
Azure Content Understanding goes beyond simple OCR text extraction. It follows a schema-based extraction of fields and values.
It follows this workflow
Un analyzer es una unidad de Azure Content Understanding la cual:
Una vez estructurado un analyzer se encarga de que un schema sea reusado de manera consistente para cada request. Un analyzer produce resultados predecibles en JSON.
Azure Content Understanding ofrece prebuilt analyzers o se pueden customizar. A alto nivel:
Azure provee de 4 categorías de servicios:
(Azure se organiza en)

Un tenant es la base de una organización en Azure Cloud. Microsoft crea un tenant cuando una compañía se registra en Azure y cada tenant es independiente de otros.
El tenant incluye:
Microsoft Foundry es un PaaS unificado para construir, administrar y hacer deployment de AI apps y agentes. Consolida modelos, orquestación de agentes, monitoring y governanza en una plataforma.
Foundry ofrece muchas capacidades, incluyendo el elegir uno de muchos modelos, usar estos modelos para construir agentes, conectar esos agentes a herramientas e integrar knowledge usando Foundry IQ (punto de acceso centralizado para data sources)

Para empezar con Foundry hay que crear un Foundry resource, el cual provee de acceso a:
Un Foundry project es un workspace dentro de ese resource donde construyes AI apps, agentes y evaluaciones:
De normal tenemos un Foundry resource para un equipo o departamento, y muchos Foundry projects dentro, cada uno enfocado a un caso de uso de IA distinto
Microsoft Foundry has a model catalog that includes various model types
Each model entry includes:

LEARN THIS definition:
Foundation models are large, pretrained models that provide general language, reasoning or multimodal capabilities out of the box. These models can be deployed immediately or customized through fine-tuning, and serve as the base layer for building AI apps.
Los agentes son aplicaciones que usan la IA generativa. La IA agentica se aleja de prompts individuales y en vez de eso define comportamientos consistentes (workflows) que se pueden reutilizar a través de aplicaciones y servicios.
Un agente en Foundry consta de:
Los agentes pueden:
Las Tools en Foundry permiten a un modelo ejecutar acciones llamando a sistemas externos. Representan acciones ejecutables (navegar internet, query a BBDD, usar un MCP server)
En Foundry las tools forman la base de las acciones para los agentes. Se pueden configurar centralmente en el Foundry Tool Catalog
(gráfico obtenido de la referencia para visualizar como se organizan los recursos en azure)

Los resource groups son como directorios. Se les puede asignar múltiples a cada recurso.
La estrategia para los nombres que yo utilizo que y mejor me sirve a la hora de buscar y entender recursos es:
resource type - app name - region - env - counter
ejemplo:
azurefunction-spotiguard-spainwest-dev-01
Organize Azure resources using management group, tags, naming convention – AzureDays
log into/out of tenant
az login
az logout
see & select accounts
# ver subscripcion seleccionada
az account show
# ver todas subscripciones disponibles
az account list
# seleccionar suscripcion
az account set --subscription {id}
see & manage resource-groups
az group list
az group delete --name {name}
# once we're logged-in with az login into the right account
az aks get-credentials --resource-group {some-resource-group} --name {aks_name} --overwrite-existing
# now we can execute kubectl commands
kubectl get deployments --all-namespaces=true
Se me ha quedado un backup atascado que no me dejaba borrarlo por la web. Con CLI hay que desregistrarlo y luego ya se puede borrar
# we should be able to see the resource
az backup container list -g learn-with-ai -v vault-xx00xxxx --backup-management-type AzureStorage
# unregister
az backup container unregister -g learn-with-ai -v vault-xx00xxxx --backup-management-type AzureStorage
In Azure AD B2C you’ve two ways to provide identity UX:
For the most common identity tasks. Things like:
They’re config files that define the behaviour of your Azure AD B2C tenant UX. They can be fully edited by an identity developer to complete many different tasks.
It’s fully configurable and policy-driven.
Each user journey is defined by a policy. You can build as many or as few policies as you need.
Defined by several XML files that refer to each other in a hierarchical chain.
The starter pack comes with pre-built policies.
Each starter pack includes:
A claim provides temporary storage of data during an Azure AD B2C policy execution. It can store info about the user, such as first name, last name… or any other claim obtainer from the user or other systems. The claim schema is the place where you declare your claims.
When a policy runs, B2C sends and receives claims to and from internal and external parties, then sends a subset of these claims to your relying party app as part of the token.
Claims transformation are predefined functions to convert a given claim into another one, evaluate a claim or set a claim value.
They allow you to define business logic with path through which users will follow to gain access to your application. The user is taken through this journey to retrieve the claims that are to be presented to your app.
A user journey is built from a sequence of orchestration steps.
How you can add orchestration steps to social and local account starter pack.
A user must reach the last step to acquire a token. Orchestration steps can be conditionally executed based on preconditions. After an step completes, B2C stores the outputted claims in the claims bag. This bag can be used by any further orchestration steps in the user’s journey.
https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview
https://docs.microsoft.com/en-us/azure/active-directory-b2c/custom-policy-overview
JSON Web Key (JWK) represents a set of public keys as a JSON object. This format is used to represent bare keys.
The following is a key example:
{
"jwk": [
{
"alg": "EC",
"crv": "P-256",
"x": "{x_value}",
"y": "{y_value}",
"use": "enc",
"kid": "1"
},
{
"alg": "RSA",
"mod": "{mod_value}",
"exp": "AQAB",
"kid": "2011-04-29"
}
]
}
It’s possible to go from PEM format to JWK and from JWK to PEM.
Azure AD B2C creates and validates user flows with keys. It automatically rotates them, but they’re created as JWK and not PEM.
To validate the JWT we need to:
As the documentation states the client needs to check periodically for new JWK keys, as they rotate them. A good period check is every 24 hours.
https://openid.net/specs/draft-jones-json-web-key-03.html#anchor1
https://stackoverflow.com/questions/50816301/msal-access-token-invalid-signature
https://docs.microsoft.com/es-es/azure/active-directory-b2c/tokens-overview
Azure AD B2C is Identity as a Service. It allows you to login into apps or use Twitter, Google or other authenticators. They can sign up or sign in. OpenID, OAuth, SAML.
Customers get to use their preferred accounts to sign up or create a regular user / pwd. You can customize the login experience.
This is best for the following types:
This doesn’t work together with Azure AD B2C.
Create new resource -> B2C -> Create new tenant -> enter general information
Notice for the initial domain name, the full domain will be *.onmicrosoft.com
Once a tenant is provisioned, click to manage it. A new tab opens, this is because the B2C tenant is separate from your Azure subscription’s tenant. Your Azure subscription has an Azure Active Directory Tenant associated with it and this new B2C one is distinct and separate. It’s its own directory.
Inside we have the following modules or tabs:
Before being able to use the B2C instance, you also have to link the B2C directory back to the main subscription. This makes it a service for you to use.
Create new resource -> Azure Active Directory B2C -> Create -> Link existing Azure AD B2C Tenant to my Azure subscription -> select the one you just created -> put it into a resource group
The flows are reusable. They controls when social accounts can be used to sign in.
The attributes to collect from the user. (you can collect standard or custom ones).
To use MFA or not.
User interface customization.
Information inside the token that’s returned from B2C.
It can be used across B2C apps. They’re entirely reusable.
Azure AD B2C Application - it’s not your web or API. It’s models apps that have authentication added. It makes sure only your users can sign-in.
Redirect URI - where to redirect response after the user’s been authenticated. As a test, put https://jwt.ms to see what’s inside the JWT token.
There’re 3 recommended to have, but you can create custom ones:
Everything that controls the journeys of the users is located under Policies.
Social network provider are called identity providers (IdP). In order to use them, you have to configure them first. You will get a key which you enter into B2C and the authentication will happen seamlessly.
A B2C app models the real world. Every real-world app needs a B2C app.
reply URL: URL where responses will be returned to your webapp.
App ID: unique ID that identifies your B2C app.
They obey standards like OAuth 2.0 or OpenID Connect.
When you want to interact with it, you specify your user flow.
Everything from Sign in to get Resource token happens inside Azure, not your app.
They’re the way that B2C uses to transmit claims about a user calling Apps. They’re all JWT tokens.
ID token: contains claims user to identify user. (e.g. user’s object ID in AD). You must always validate it. Access token: Claims used to identify API permissions. Validate it. Refresh token: It should be a black box to your app. Both others tokens expire.
How server-based apps authentication works with B2C. Underlying authentication protocol is OpenID Connect.
Individual steps into a user’s journey:
They’re XML files
have a Schema definition (which will be used to return the tokens)
Content definition - Things like how to render pages.
Technical profiles - they’re the endpoints and how to communicate with identity providers.
Orchestration - steps that are contained within the custom policies
In order to work with custom policies we’ll need to handle three files:
User flows and custom policies in Azure Active Directory B2C - Azure AD B2C | Microsoft Learn
Files that compose an Azure Function:
Create a resource -> Compute -> Function App.
The function name has to be unique.
Create new resource group.
You can choose the OS.
Storage:
Create a new recommended storage.
It offers to create an application insight instance for us. This stores logs and diagnostic information. This is really recommended.
On Configuration > Application settings you can create sys envs which will appear in your code.
There’s a storage explorer where you may see the contents for your function in real time.
There’re a lot of trigger types
Input / Output Bindings
To work with Azure Functions, you may work with Visual Studio. There’s an option to enable “Azure Development” with which you’ll be able to project and run your functions locally.
Azure Functions are based in serverless programming. They integrate easily with other Azure services. You provide Code to execute and an event that triggers it.
For example to run background tasks every hour.
They’re brilliant for:
Azure Functions is built on top of the web jobs SDK and it’s hosted on the app service platform.
With VM you can install whatever you want: web servers, services etc. This is known as IaaS (infrastructure as a service). You can choose OS and have complete control of the server, but you’re responsible for it: Patching, maintaining, scaling, operational overhead.
This are examples of queries to use for Azure CosmosDB, as this database uses a restricted version of SQL and it doesn’t allow all queries or joins.
To be used with the main, partial query. This query starts with something such as SELECT * FROM c
WHERE c.ts LIKE "%2022/03/10%"
ORDER BY c.ts DESC
WHERE c.type = "Writeable"
AND c.ts LIKE "%2022/03/10, 15:2%"
ORDER BY c.ts DESC
Normal SQL queries to be used as custom queries. Note that CosmosDB doesn’t support a 100% of all SQL statements.
(count number of entries)
SELECT COUNT(1) FROM c
WHERE c.ts LIKE "%2022/03/10%"
ORDER BY c.ts DESC