• Updated:
  • Featured post

How LLMs get their probabilities for the next token

(este post es una explicación de la teoría. dejo aquí otro post con el detalle práctico de como usar la temperature, top_k y top_p a efectos prácticos)

Explicación más en detalle de cómo obtienen los LLMs las probabilidades para generar el siguiente token

Sampling

En cada posición el modelo tiene una bolsa con miles de tokens posibles. Sampling es el proceso de no coger siempre el token más probable, si no de orientarlo a coger respuestas con determinadas características.

Si el modelo escogiera siempre el token con más probabilidades, obtendríamos respuestas aburridas y repetitivas.

Logits

Para generar el siguiente token, una red neuronal calcula primero los vectores de logits, donde cada logit corresponde a un valor posible. El tamaño de estos vectores de logits es tan grande como el vocabulario completo del modelo.

(representación de vectores de logits)

flowchart LR
	N1["What's your favorite color?"]:::note --> Z
	Z --> A1 --> A
	Z --> B1 --> B
	Z --> C1 --> C
	Z --> D1 --> D
	
	Z["Neural network"]
    A["a"]
    A1["(-0.5)"]
    B["green"]
    B1["(0.7)"]
    C["red"]
    C1["(0.5)"]
    D["the"]
    D1["(-1.2)"]
    
    classDef note fill:none,stroke:none,color:#777;    

Los logits NO representan probabilidades ya que no suman 1 y pueden incluso ser negativos (la probabilidades no pueden). Para convertir logits a probabilidades se usa una Softmax layer

Temperature

La temperatura es una constante que se aplica a los logits antes de la transformación de la Softmax layer. Se usa para ajustar la creatividad del modelo y redistribuir la probabilidad de los valores. Una temperatura más alta hace que el modelo sea más creativo ya que aumenta las posibilidades de elegir tokens menos probables.

xychart-beta
  title "Temperatura vs Probabilidad"
  x-axis "Temperatura (T)" [0.1, 0.2, 0.5, 1, 2, 5]
  y-axis "Probabilidad" 0 --> 1
  line "P(token1)" [0.9999546, 0.9933071, 0.8807971, 0.7310586, 0.6224593, 0.5498340]
  line "P(token2)" [0.0000454, 0.0066929, 0.1192029, 0.2689414, 0.3775407, 0.4501660]

Ejemplos de temperaturas:

  • Low (0.2-0.3): El modelo es cauto y elige las palabras más probables. Output factual y predecible.
  • Medium (0.5-0.7): Un mix de confiabilidad y engagement
  • High (0.9-1.0): Toma riesgos y es impredecible

Read More

Reference Key Vault secrets (App Configuration)

Understand Key Vault references

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

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

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

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

Create Key Vault references

Podemos crear referencias desde el Azure Portal o con Azure CLI

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

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

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

Configure python provider for Key Vault resolution

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

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

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

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

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

Set up authentication for both services

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

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

IMPORTANTE

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

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

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

/IMPORTANTE

Understand refresh behavior for Key Vault references

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

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

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

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

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

Match response channel to the operation

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

direct HTTP streaming

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

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

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

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

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

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

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

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

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

Azure Key Vault tiene 3 core capabilities:

  • Secrets management
  • Key management
  • certificate management

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

Opera en 2 tiers:

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

Choose the right object type for your credentials

Secrets

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

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

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

Keys

Alacena keys criptográficas para encriptar y firmar.

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

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

Certificates

Alacenan certificados junto a sus claves privadas.

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

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

Organize vaults and objects for AI solutions

IMPORTANTE

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

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

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

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

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

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

IMPORTANTE

Control access with RBAC

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

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

Key Vault ofrece distintos data plane roles para secret management:

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

IMPORTANTE

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

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

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

/IMPORTANTE

Protect against accidental deletion with soft delete and purge protection

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

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

Handle secret versioning and rotation (Key Vault)

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

Understand how Key Vault versions secrets

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

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

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

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

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

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

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

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

Los IDs son utiles para auditorias.

List and inspect secret versions

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

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

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

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

Choose rotation strategy

Manual rotation

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

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

Automated Rotation with Event Grid

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

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

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

Esto lo automatiza enteramente el lifecycle. Resumen:

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

Dual-credential rotation

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

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

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

Implement zero-downtime rotation in app code

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

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

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

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

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

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

Set expiration dates on secrets

IMPORTANTE

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

/IMPORTANTE

Retrieve secrets using Azure SDK client libraries (Key Vault)

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

Install the SDK

El Key Vault secrets SDK requiere de dos packages

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

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

la url se puede obtener desde la web o asi

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

Authenticate with DefaultAzureCredential

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

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

Orden que sigue:

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

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

Retrieve a secret by name

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

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

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

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

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

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

List secret properties

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

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

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

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

Handle errors and exceptions

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

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

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

Use the async client for high-throughput apps

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

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

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

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

    await credential.close()
    return secret.value

Implement caching strategies (Key Vault)

Understand Key Vault throttling limits

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

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

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

Implement a time-based in-memory cache

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

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

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

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

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

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

El param cache_ttl_seconds controla el tiempo en segundos.

Invalidar la cache con Azure Event Grid

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

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

Entonces invalidamos la cache local y obtenemos el nuevo.

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

Choose the right cache scope

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

Per-process cache

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

Shared distributed cache

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

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

Application startup preloading

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

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

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

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

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

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

Balance cache lifetime with security requirements

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

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

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

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

Handle throttling gracefully

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

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

logger = logging.getLogger("keyvault")

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

Design reliable workflow steps (Durable Functions)

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

Classify failures before retrying

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

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

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

Apply bounded activity retries

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

en python usamos la RetryOptions API

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

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

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

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

Enforce durable timeouts

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

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

Timeout scopes:

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

Make activity side effects idempotent

IMPORTANTE

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

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

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

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

/IMPORTANTE

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

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


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

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

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

Compoensate completed side effects

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

La compensación debe ser idempotente.

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

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

Expose terminal status and diagnostics

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

Incluir IDs para poder trackear requests.

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

Azure App Configuration

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

Understand the App Configuration data model

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

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

Install the python provider library

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

Tambien necesitamos la libreria azure-identity para auth

pip install azure-appconfiguration-provider azure-identity

Connect and retrieve settings

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

como conectar a App Configuration y hacer get de un valor

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

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

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

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

Authenticate with DefaultAzureCredential

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

Select and filter keys with SettingSelector

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

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

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

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

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

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

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

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

Trim key prefixes

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

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

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

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

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

Enable dynamic configuration refresh

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

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

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

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

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

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

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

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

Organize settings with labels and feature flags (App Configuration)

Use labels for environment differentiation

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

Una key como Pipeline:BatchSize puede tener:

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

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

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

Stack key-value pairs with composition

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

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

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

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

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

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

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

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

Design key naming conventions

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

Ejemplos:

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

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

Understand Feature Flags in App Configuration

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

IMPORTANTE

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

/IMPORTANTE

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

Evaluate feature flags with FeatureManager

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

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

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

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

feature_manager = FeatureManager(config)

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

IMPORTANTE

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

/IMPORTANTE

Refresh feature flags dynamically

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

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

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

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

feature_manager = FeatureManager(config)

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

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

Apply feature flags

Estas se pueden usar de muchas maneras

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

Create triggers and bindings (Azure Functions)

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

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

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

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

Create HTTP triggers (inference endpoint)

Soportan GET, POST y otros HTTP methods.

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

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

app = func.FunctionApp()

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

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

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

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

Authorization levels

Los Auth levels controlan quien puede invocar la función

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

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

Create Service Bus Triggers (Batch Processing)

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

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

Service Bus ofrece features complejas como:

  • message sessions
  • duplication detection
  • scheduled delivery

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

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

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

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

HTTP Function + Service Bus Function (decoupling pattern)

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

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

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

Use output bindings to store results

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

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

Common output binding targets son

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

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

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

    result = extract_and_classify(job["document_url"])

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

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

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

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

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

Connect to Azure AI services from a function

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

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

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

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

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

credential = DefaultAzureCredential()

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

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

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