Un agente de análisis documental sin claves en Container Apps: lo que falló en el primer despliegue

Este artículo cuenta lo que falló al desplegar un agente de análisis de documentos extensos en Azure Container Apps, y las decisiones de arquitectura que sí resistieron. Es un laboratorio propio y los detalles del circuito están en el proyecto 046.

1. Qué es, y qué no es

Un servicio pequeño que recibe un documento largo (un pliego, un contrato, una norma), recupera las partes relevantes, las contrasta con una base de conocimiento propia y pide al modelo un borrador de análisis. No hay cliente, ni documentos reales, ni una evaluación de la calidad del análisis frente a un revisor humano. Los ejemplos son sintéticos y la salida del modelo es un borrador que exige revisión.

Si te interesa la parte de IA, es la menos interesante. Lo que merece contarse es la parte de plataforma: cómo se maneja un documento más largo que el contexto, qué significa de verdad «sin claves» y qué pasa cuando el despliegue no sale como en el tutorial.

2. Doble RAG: dos índices, dos preguntas

El primer problema de un documento largo es que no cabe, y el segundo es que lo que cabe no tiene por qué ser lo importante. El servicio resuelve las dos cosas con dos recuperaciones distintas:

• Sobre el documento: se trocea en fragmentos de 1.200 palabras con solape de 150, se calculan embeddings y se indexan en Azure AI Search. En lugar de enviar el documento entero, se hace una consulta híbrida (texto y vector) por cada dimensión de análisis (objeto y alcance, requisitos técnicos, criterios de valoración, cumplimiento, presupuesto y plazos) y se conservan los tres mejores fragmentos de cada una. El contexto enviado queda acotado, sea cual sea la longitud del original.
• Sobre la base de conocimiento propia: con el contexto recuperado como consulta, se buscan en un segundo índice las capacidades que respaldan cada requisito. La columna «cobertura» se apoya así en evidencia recuperable, no en lo que el modelo crea recordar. Si ese índice no está disponible, el prompt lo dice en vez de rellenar el hueco.

Un detalle práctico: un PDF escaneado, sin capa de texto, se rechaza con un mensaje claro. Es preferible a producir un análisis vacío con aspecto de análisis. El reconocimiento óptico de caracteres queda como siguiente paso.

3. «Sin claves»: qué significa de verdad

La aplicación usa una identidad gestionada de usuario con los roles mínimos: usuario del servicio de modelos, contribuidor de datos y de servicio en el buscador, usuario de secretos en el almacén y un rol de plano de datos en la base de datos. No hay claves en el código ni en la configuración. Conviene precisar dos cosas que se confunden con facilidad:

• «Sin claves» en la aplicación no es «sin claves» en el servicio. El buscador pasó de clave a roles habilitando la autenticación por roles en modo aadOrApiKey, concediendo a la identidad el rol de gestión de índices, cambiando la aplicación a autenticación por identidad y borrando el secreto del almacén. Pero con aadOrApiKey el servicio sigue aceptando claves. Según la documentación de Microsoft, para usar roles en exclusiva hay que desactivar además la autenticación local en una segunda petición. En el laboratorio ese cierre queda documentado como paso opcional, así que la propiedad que puedo afirmar es la de la aplicación, no la del servicio.
• La zona de datos no es la región. Los modelos se despliegan en Data Zone Standard: el tipo Standard regional no estaba disponible para el modelo elegido en la región del laboratorio. Según la documentación, un despliegue de zona de datos puede procesar las peticiones en cualquier país de la UE, y los datos en reposo permanecen en la geografía del recurso. Es una garantía de zona, no de país.

4. Medir cada análisis con una línea

La observabilidad cabe en una línea: cada análisis imprime en consola un JSON con identificador, fichero, modelo, fragmentos indexados, latencia, tokens de entrada y salida y coste estimado. Log Analytics recoge los registros de consola de Container Apps sin ningún agente, y una consulta sobre ellos da análisis por día, tokens y latencia p50 y p95. Un libro de Azure Monitor desplegado con Bicep la pone en pantalla.

El coste es una estimación: tokens por una tarifa configurable. Sirve para operar y detectar desviaciones al día siguiente, no para cuadrar la factura; para eso están los informes del proveedor, con su propia latencia, como cuento en el artículo 039.

5. Lo que falló en el primer despliegue

Esta es la parte útil, porque cada uno de estos fallos aparece en cualquier despliegue real:

5.1 La orden única no cambió la imagen

La aplicación se había creado con una imagen de ejemplo. Al lanzar az containerapp up --source, la aplicación siguió respondiendo con la imagen de ejemplo. La documentación de Microsoft indica que, para redesplegar con una imagen actualizada, hay que pasar el grupo de recursos y el entorno; no consta con qué opciones lo lancé, así que no puedo asegurar que fuera un defecto del comando y no de cómo lo usé. Cambié a una secuencia explícita: construir con az acr build y una etiqueta por marca de tiempo, conceder el rol AcrPull a la identidad, registrar el registro por identidad con containerapp registry set --identity y cambiar la imagen con update --image --container-name, dejando para una actualización aparte las variables de entorno. Cuatro pasos en lugar de uno, pero cada uno se puede leer, repetir y auditar.

5.2 Un contenedor duplicado en el mismo pod

El resto de la primera creación había dejado un segundo contenedor en el pod, y los dos intentaban escuchar en el mismo puerto. El síntoma era un bucle de reinicios con el error de dirección en uso y, lo más engañoso, respuestas intermitentes entre una versión y otra: a veces contestaba la aplicación buena y a veces la otra. La solución fue un PATCH de ARM con una plantilla mínima, sin los campos de solo lectura que la API rechaza (almacenamiento efímero, periodo de enfriamiento, intervalo de sondeo). Después hubo que reafirmar las variables de entorno, que el PATCH había dejado vacías.

5.3 La reparación cambió el escalado

Lo que no esperaba: el script que deja un solo contenedor fija el mínimo y el máximo de réplicas en uno. La aplicación dejó de escalar a cero. Para un servicio que se está depurando tiene sentido, pero contradice la premisa de coste casi nulo en reposo del laboratorio. Una reparación de emergencia es también una decisión de coste, y hay que acordarse de revertirla.

5.4 Dos fallos silenciosos

• Los roles tardan en propagarse. El script espera 60 segundos tras asignar el rol, el README habla de dos o tres minutos y la documentación de Microsoft menciona que las asignaciones pueden tardar entre cinco y diez. Un error de autorización justo después del cambio no prueba que la configuración esté mal.
• El histórico es de mejor esfuerzo. Si la escritura en la base de datos falla, el servicio lo registra como aviso y sigue. Es cómodo en una demostración y peligroso en producción: un permiso mal concedido produce un histórico vacío sin romper nada.

6. Alcance de laboratorio

Es un entorno de laboratorio y no un patrón de producción. Un solo servicio de IA y de búsqueda, sin redundancia; el nivel gratuito del buscador, que solo admite uno por suscripción; red pública en los servicios de datos y de seguridad; sin evaluación de calidad ni pruebas de carga; y los documentos escaneados se rechazan. Las cifras de coste del laboratorio son estimaciones del propio diseño, no una factura analizada. El entorno ya está destruido, así que no hay URL que enlazar, y no publico identificadores de suscripción ni de identidad.

7. Qué hacer el lunes

1. Recupera por dimensiones en lugar de volcar el documento, y separa la evidencia del documento de la evidencia propia.
2. Distingue «sin claves en la aplicación» de «sin claves en el servicio» y cierra el ciclo desactivando la autenticación local cuando hayas verificado el acceso por roles.
3. Despliega con una secuencia explícita (construir, permiso de descarga, cambiar imagen, cambiar variables) y etiqueta cada imagen para que cada despliegue genere una revisión.
4. Cuenta los contenedores del pod después de cada reparación y comprueba qué ha cambiado en el escalado.
5. Emite una línea estructurada por inferencia y haz que alguien mire la consulta cada semana.

Fuentes

Páginas consultadas el 4 de noviembre de 2026. Las capacidades, los tipos de despliegue y el comportamiento de la CLI cambian con frecuencia: conviene revalidarlos antes de usarlos.

• Microsoft Learn. Deployment types for Azure AI Foundry Models
• Microsoft Learn. Enable or disable role-based access control in Azure AI Search
• Microsoft Learn. Manage your Azure AI Search service using REST APIs
• Microsoft Learn. Deploy Azure Container Apps with the az containerapp up command
• Microsoft Learn. Manage revisions in Azure Container Apps