Arquitectura Modular con IA Generativa: Tratando la Inteligencia como Capacidad, No como Dependencia
Este artículo no es sobre cómo usar LLMs. Es sobre cómo arquitectar sistemas que los incorporan con la misma disciplina exigida de cualquier otro componente crítico
Existe un momento específico en la vida de un sistema que incorpora IA Generativa en el que la deuda arquitectural se vuelve insoportable. No es cuando aparece el primer bug. Es cuando alguien pregunta: "¿Qué prompt estaba en producción cuando eso ocurrió?" y nadie sabe responder.
El Problema que Nadie Nombra
Llamo AI Spaghetti al estado en que la lógica de IA está distribuida caóticamente por la base de código: llamadas al modelo dentro de controllers, montaje de prompts concatenando strings en helpers, lógica de retrieval mezclada con reglas de negocio, y cero separación entre el qué quiere hacer el sistema y el cómo lo ejecuta la IA.
Ese estado no nace de negligencia. Nace de la velocidad y de una ilusión específica que crea la IA Generativa: la de que integrar es trivial. Y lo es, al principio. Una llamada a la API, una respuesta, valor entregado. El problema es que los sistemas no son prototipos, y la mayoría de los equipos se da cuenta demasiado tarde.
El costo real del AI Spaghetti no aparece en los tests. Aparece en producción, meses después, cuando necesitas cambiar de provider y descubres que eso requiere cirugía en decenas de archivos. Cuando necesitas investigar un incidente y no puedes reconstruir el contexto de la llamada. Cuando intentas medir el costo real de operación y no tienes ninguna granularidad. Cuando escalas el equipo y te das cuenta de que nadie entiende el flujo completo.
La ironía es que la solución no requiere ninguna tecnología nueva. Requiere la aplicación de principios arquitecturales ya bien establecidos aplicados a un dominio que la industria todavía está aprendiendo a tratar con seriedad.
El Principio Fundamental: IA como Capacidad
La premisa central de una buena arquitectura de IA es engañosamente simple:
"La IA Generativa es una capacidad, no una implementación.
Así como "persistencia" es una capacidad que puede ser satisfecha por Postgres, DynamoDB o Redis y la abstraes detrás de un repositorio la inteligencia generativa es una capacidad que puede ser satisfecha por OpenAI, Anthropic, modelos locales, o un ensemble corriendo en paralelo.
Cuando tratas la IA como implementación, tu lógica de negocio sabe demasiado. Sabe qué SDK usar, qué modelo llamar, cómo formatear la petición, cómo interpretar la respuesta. Esa promiscuidad crea acoplamiento que cobra su precio con intereses.
Cuando tratas la IA como capacidad, la lógica de negocio declara lo que necesita "quiero que alguien evalúe si este texto es relevante para esta pregunta" y el sistema de IA cumple ese contrato sin exponer los detalles de cómo.
Este principio tiene nombre en la literatura de diseño: es la Inversión de Dependencia aplicada al dominio de IA. Y su expresión arquitectural más natural son los Ports & Adapters la Arquitectura Hexagonal.
La Anatomía de una Capa de IA Bien Diseñada
Una capa de IA bien diseñada tiene fronteras claras entre cuatro responsabilidades distintas. Confundirlas es la raíz de la mayoría de los problemas.
Los contratos definen qué necesita entregar el sistema de IA, sin revelar cómo. Un contrato de inferencia declara que dado un prompt, se espera una respuesta con uso de tokens y metadatos de trazabilidad. Un contrato de embedding declara que dado un texto, se espera un vector. Un contrato de retrieval declara que dado un vector, se esperan documentos rankeados por relevancia. Esos contratos pertenecen al dominio de la aplicación, no a la infraestructura.
Los adaptadores son implementaciones concretas de esos contratos. El adapter de Anthropic sabe cómo llamar a la API de Claude. El de OpenAI sabe cómo llamar a GPT. El de Ollama sabe cómo llamar a modelos locales. Para la aplicación, todos son intercambiables y cumplen el mismo contrato.
El servicio de orquestación coordina los contratos para ejecutar flujos complejos. Un pipeline de RAG, por ejemplo, orquesta embedding → retrieval → montaje de contexto → inferencia → validación de respuesta. Ese servicio conoce los contratos, no los adaptadores.
La infraestructura de IA provee capacidades transversales: gestión de prompts, circuit breakers, telemetría, caché semántico, gestión de costos. No ejecuta lógica de negocio y garantiza que la capa de IA opere con fiabilidad.
El resultado de esa separación es un sistema donde cambiar de GPT-4o a Claude Opus es un cambio de configuración, no una refactorización. Donde agregar un nuevo provider lleva horas, no días. Donde la testeabilidad es natural porque sustituyes contratos, no SDKs.
Gestión de Prompts: La Disciplina Ignorada
Si hay un único aspecto donde la mayoría de los sistemas de IA en producción falla sistemáticamente, es la gestión de prompts.
Los prompts son artefactos de primera clase. Determinan el comportamiento del sistema tanto como cualquier línea de código. Pero mientras el código tiene versionamiento, revisión, historial y trazabilidad, los prompts frecuentemente viven como strings literales enterrados en archivos, copiados entre entornos sin control, modificados directamente en producción por conveniencia.
El problema se hace evidente cuando algo sale mal. Un incidente en producción exige respuesta a las siguientes preguntas: ¿qué versión del prompt estaba activa? ¿Cuándo fue el último cambio? ¿Quién lo aprobó? ¿Cuál era el comportamiento anterior? Los sistemas sin control de prompt no pueden responder ninguna de ellas.
La solución es tratar los prompts con la misma gobernanza aplicada al código y a la configuración. Eso significa versionamiento con semántica clara: los prompts tienen versiones que evolucionan con significado explícito. Significa historial de cambios y trazabilidad de autoría. Significa promoción entre entornos con los mismos controles aplicados a los deploys.
Hay además una dimensión frecuentemente descuidada: los prompts necesitan tests. No solo validación manual de "parece bien", sino suites de evaluación que verifican si la versión actual sigue satisfaciendo los comportamientos esperados: casos borde, escenarios de fallo, instrucciones de frontera. Todo eso necesita estar codificado como expectativas verificables.
El corolario inevitable es que los cambios de prompt necesitan pasar por un proceso de revisión. Así como ningún ingeniero sube código a producción sin review, ningún prompt debería ser promovido sin una evaluación sistemática del impacto en la calidad de las respuestas.
RAG Como Arquitectura, No Como Feature
Retrieval-Augmented Generation se convirtió en buzzword antes de convertirse en disciplina. La mayoría de las implementaciones trata RAG como una feature: un conjunto de llamadas encadenadas que "busca documentos y los manda al modelo". Eso funciona en demos. En producción, se fragmenta.
RAG bien arquitectado es un pipeline con etapas independientes, cada una con responsabilidades claras y puntos de intervención explícitos.
La fase de ingestión — procesamiento, chunking e indexación de documentos — necesita estar completamente separada de la fase de serving. Esa separación es estratégica: la estrategia de chunking tiene impacto directo en la calidad del retrieval, y necesitas iterar sobre ella sin afectar el sistema en producción. Jerarquía de chunks, solapamiento, enriquecimiento con metadatos: esas decisiones merecen experimentación controlada.
La fase de retrieval tiene más matices de lo que aparenta. La búsqueda vectorial pura frecuentemente no es suficiente. Los sistemas robustos combinan búsqueda semántica con búsqueda por palabras clave (hybrid search), aplican reranking para refinar los resultados iniciales, y filtran por metadatos para restringir el espacio de búsqueda. Cada una de esas etapas es un punto de optimización independiente.
El montaje del contexto es donde la mayoría de los sistemas desperdicia dinero y calidad simultáneamente. Enviar todos los documentos recuperados indiscriminadamente al modelo es un antipatrón. Las ventanas de contexto tienen costo: cada token enviado es un token pagado, y los documentos marginalmente relevantes frecuentemente perjudican más de lo que ayudan, diluyendo la atención del modelo sobre lo que realmente importa. Un assembler bien diseñado orquesta selección dentro de un presupuesto de tokens, formateo que favorece la comprensión del modelo, y compresión del historial de conversación cuando es necesario.
La validación de la respuesta cierra el ciclo. ¿La respuesta está fundamentada en el contexto proporcionado? ¿El modelo alucinó información? ¿El contenido satisface criterios de seguridad? Esas verificaciones no son opcionales en sistemas que llegan a usuarios reales.
Resiliencia: Lo que Nadie Planifica Hasta el Primer Incidente
Las APIs de LLM tienen características que hacen que la resiliencia no sea solo deseable, sino obligatoria. Latencia altamente variable, donde el P99 puede ser diez veces el P50. Rate limits que llegan sin aviso en períodos de carga. Fallos parciales donde el modelo responde pero con calidad degradada. Interrupciones de provider que, sin fallback, se convierten en interrupciones de tu servicio.
El Circuit Breaker es el primer instrumento de resiliencia a implementar. Monitorea fallos consecutivos y, al detectar degradación, deja de enviar peticiones que probablemente fallarán: protege el sistema de cascada de errores y le da tiempo al provider para recuperarse.
Pero el Circuit Breaker en aislamiento no es suficiente. Los sistemas críticos necesitan fallback entre providers. Un router de modelos que intenta el provider primario, detecta el fallo, y automáticamente dirige al provider secundario convierte una indisponibilidad de vendor en una degradación imperceptible para el usuario. La simetría de contratos en los adapters es lo que hace esto posible sin lógica adicional.
Timeouts agresivos son tan importantes como los fallbacks, y frecuentemente más descuidados. Una llamada a un LLM sin timeout puede esperar indefinidamente, consumiendo recursos y degradando la experiencia sin nunca fallar explícitamente. Todo sistema de IA necesita timeouts por defecto.
Retry con backoff exponencial resuelve fallos transitorios. Pero retry sin circuit breaker puede empeorar una situación ya degradada. Los dos trabajan juntos: retry para fallos aislados, circuit breaker para fallos sistémicos.
Observabilidad: Las Tres Dimensiones que Importan
La observabilidad en sistemas tradicionales vive alrededor de los cuatro golden signals: latencia, tráfico, errores y saturación. Los sistemas de IA necesitan esas dimensiones y tres capas adicionales específicas.
Las métricas operacionales son lo que el SRE monitorea. Latencia por provider y por modelo, porque el P95 de inferencia es un SLO que necesitas honrar. Tasa de errores segmentada por tipo: rate limit, timeout, content filter, error de red tienen causas y soluciones diferentes. Volumen de tokens consumidos por feature, porque el costo en sistemas de IA es proporcional al consumo, y sin granularidad vuelas a ciegas en el presupuesto.
Las métricas de calidad son lo que el producto monitorea. Tasa de respuestas fundamentadas en evidencias, especialmente en RAG, donde la alucinación es el principal riesgo. Score medio de relevancia de los documentos recuperados: si está cayendo, tu base de conocimiento puede estar desactualizada o tu índice puede estar degradándose. Feedback explícito del usuario, ruidoso pero insustituible. Distribución del tamaño de las respuestas: respuestas sistemáticamente muy cortas o muy largas son síntomas de problemas en el prompt.
Las métricas de gobernanza son lo que compliance monitorea. Distribución de versiones de prompt en producción: necesitas saber si una versión antigua todavía está sirviendo tráfico. Tasa de activación de content filters: los picos indican intentos de abuso. Trazabilidad de llamadas: la capacidad de reconstruir completamente el contexto de cualquier interacción a partir de un correlation ID.
La distinción entre esas capas importa porque tienen audiencias y cadencias diferentes. Las métricas operacionales se monitorean en tiempo real mediante alertas. Las métricas de calidad se analizan en dashboards semanales. Las métricas de gobernanza se auditan periódicamente y bajo demanda en investigaciones.
Testeabilidad: La Consecuencia Natural de Buenos Contratos
Una arquitectura bien diseñada es, casi por definición, testeable. Cuando la lógica de negocio depende de contratos y no de implementaciones, probarla no requiere llamadas reales a APIs de LLM: requiere solo sustitutos determinísticos de los contratos.
Esto resuelve un problema que paraliza a muchos equipos: ¿cómo testear flujos de IA sin pagar por tokens, sin depender de la disponibilidad de la API, sin flakiness por variabilidad de respuesta? La respuesta es que no testeas la IA, testeas la lógica alrededor de la IA.
La pirámide de tests para sistemas de IA tiene tres niveles con propósitos distintos.
Tests unitarios cubren componentes de lógica pura: el assembler de contexto que respeta presupuestos de tokens, el renderizador de prompt que interpola variables correctamente, el estimador de costo. Ninguno de esos tests necesita LLM.
Tests de integración cubren la orquestación del pipeline completo, con sustitutos determinísticos en los contratos. El flujo de RAG puede ser testeado con embeddings fijos, documentos predefinidos y respuesta de LLM sustituida. Validas que la orquestación es correcta, que los datos fluyen entre las etapas como se espera, que los errores se propagan adecuadamente.
Tests de evaluación cubren calidad semántica, y aquí los LLMs son inevitables. La técnica de LLM-as-Judge automatiza la evaluación de respuestas contra criterios definidos: ¿la respuesta está fundamentada en el contexto? ¿Es relevante para la pregunta? Un modelo evaluador, operando con temperatura cero para el determinismo, produce scores que pueden ser incorporados al pipeline de CI/CD. Si la media de fundamentación cae por debajo de un umbral tras un cambio de prompt, el deployment es bloqueado.
Los tests unitarios y de integración corren en cada commit, en segundos, sin costo. Los tests de evaluación corren en pull requests significativos, en minutos, con costo controlado. Esa separación es lo que hace el enfoque práctico a escala.
Multi-Agente: Cuando un Modelo No Es Suficiente
Los sistemas de múltiples agentes están emergiendo como patrón para tareas que exceden la capacidad de un único LLM en una única llamada. La arquitectura es poderosa y por eso mismo merece atención especial a sus trampas.
El patrón central es la separación entre orquestador y ejecutores. El orquestrador recibe la tarea de alto nivel y decide la secuencia de acciones necesarias. Los ejecutores son especializados: un agente que investiga, uno que escribe, uno que valida, uno que interactúa con APIs externas. Cada ejecutor tiene un alcance limitado y bien definido.
Esa especialización tiene una ventaja frecuentemente subestimada: modelos más pequeños y baratos pueden ejecutar tareas especializadas con calidad comparable a modelos más grandes ejecutando tareas genéricas. El orquestrador puede ser el único componente que exige el modelo más capaz.
Las trampas de los sistemas multi-agente son específicas. La propagación de errores es la más insidiosa: un agente que produce output incorrecto en una etapa inicial contamina todas las etapas posteriores, y el sistema frecuentemente continúa ejecutando con convicción creciente en la dirección equivocada. Los checkpoints de validación entre etapas son el mecanismo de contención.
Los loops infinitos emergen cuando el orquestrador no tiene un límite explícito de iteraciones. Todo sistema de agentes necesita un budget de iteraciones hard-coded. La trazabilidad en sistemas multi-agente es órdenes de magnitud más compleja que en agente único: un correlation ID necesita traversar todos los agentes, y cada decisión del orquestrador necesita ser logueada con su razonamiento.
Deployment: Los Prompts Son Código
Un cambio de prompt en producción tiene el mismo potencial de impacto que un cambio de código. Puede silenciosamente degradar la calidad de las respuestas, introducir sesgos, o alterar comportamientos de los que los usuarios dependen. Pero en la mayoría de los sistemas, los prompts se tratan con mucho menos rigor.
La estrategia de canary release, familiar en deploys de código, se aplica directamente a prompts. Una nueva versión comienza sirviendo una fracción pequeña del tráfico. Las métricas de calidad se comparan entre la versión actual y la candidata en tiempo real. Si la candidata demuestra mejora o paridad, el rollout continúa. Si demuestra degradación, el rollback es automático.
Lo que hace esto técnicamente viable es el prompt registry. Cuando cada request lleva el identificador de la versión del prompt que lo procesó, comparar versiones se vuelve trivial: segmentas métricas por versión y la comparación emerge de los datos.
La misma disciplina se aplica a cambios de modelo. Migrar de una versión a otra, o de un provider a otro, es un cambio de comportamiento del sistema, no solo de infraestructura. Requiere el mismo proceso de evaluación, el mismo canary cauteloso, y la misma capacidad de rollback rápido.
Gobernanza e IA Responsable
Los sistemas de IA en producción tienen responsabilidades que los sistemas tradicionales no tienen, o tienen en menor escala.
La alucinación es un fallo específico de la IA generativa sin análogo preciso en el software determinístico. Un sistema que presenta información falsa con la misma confianza que presenta información verdadera crea riesgos que van desde el reputacional hasta el legal. Los guardrails de salida: verificaciones que validan la respuesta antes de enviarla al usuario, son la línea de defensa aquí. No eliminan la alucinación, pero contienen sus efectos.
La fuga de información es un riesgo en cualquier sistema RAG que indexa documentos sensibles. Sin control de acceso a nivel del retrieval, un usuario puede obtener información a la que no debería tener acceso, no porque la IA haya cometido un error moral, sino porque el sistema no implementó los controles adecuados. El namespace isolation en el vector store, los filtros por permiso de usuario, y la validación de autorización antes del retrieval son controles no negociables en sistemas corporativos.
La inyección de prompt: ataques donde contenido malicioso en los documentos recuperados intenta manipular el comportamiento del modelo, es una superficie de ataque específica de sistemas RAG. La separación clara entre instrucción y datos en el template del prompt, y el monitoreo de comportamientos anómalos, son las defensas disponibles.
La documentación de modelos y pipelines no es burocracia. Es el mecanismo que permite al equipo, auditores y stakeholders entender el comportamiento esperado del sistema, sus limitaciones conocidas y los sesgos identificados.
Lo que Separa la Arquitectura de Juguete de la Arquitectura de Producción
Después de construir y revisar muchos sistemas de IA, identifico cinco dimensiones que distinguen consistentemente los sistemas robustos de los frágiles.
Los contratos explícitos separan lo que el sistema quiere de la IA de cómo la IA lo entrega. Los sistemas robustos tienen interfaces bien definidas. Los sistemas frágiles tienen dependencias directas de SDK esparcidas por el código.
La trazabilidad end-to-end permite reconstruir el contexto completo de cualquier interacción. Los sistemas robustos tienen correlation IDs, versionamiento de prompts, y logging estructurado de decisiones. Los sistemas frágiles no pueden responder "¿qué ocurrió en esta llamada específica?"
La calidad como métrica continua, no como verificación puntual. Los sistemas robustos miden fundamentación, relevancia y seguridad en producción, continuamente. Los sistemas frágiles dependen del feedback reactivo de los usuarios.
La resiliencia por diseño, no como afterthought. Los sistemas robustos funcionan de forma degradada cuando los providers fallan. Los sistemas frágiles propagan los fallos del vendor directamente al usuario.
La gobernanza de prompts con el mismo rigor aplicado al código. Los sistemas robustos tienen historial de cambios, proceso de aprobación, y capacidad de rollback. Los sistemas frágiles tienen strings literales modificados directamente en producción.
Por Dónde Empezar
La refactorización perfecta no existe. Lo que existe es una secuencia de cambios que reduce el riesgo progresivamente sin paralizar al equipo.
El punto de partida de mayor impacto es extraer un contrato de inferencia. Crear una interfaz que encapsule las llamadas al LLM, sin cambiar nada más de inmediato, hace el código inmediatamente testeable y prepara el terreno para todo lo que viene después. Sin ningún cambio de comportamiento en producción.
El segundo paso es implementar el prompt registry, aunque inicialmente sea solo un repositorio de archivos con versionamiento en Git. Ganas trazabilidad de qué prompt está en producción e historial de cambios sin complejidad operacional.
El tercer paso es agregar telemetría básica: tokens consumidos por feature, latencia de inferencia, tasa de errores por provider. Esos datos iluminan el sistema de una forma que cambia permanentemente cómo el equipo toma decisiones.
El resto: circuit breaker, tests de evaluación, gestión de contexto, guardrails, puede ser agregado iterativamente, priorizando por el dolor más inmediato.
El sistema de IA ideal no es el más sofisticado. Es el que permite a tu equipo iterar con confianza: cambiar prompts sin miedo, cambiar de provider sin reescribir, escalar sin sorpresas. Ese es el norte.
