Arquitectura Modular con IA Generativa: Tratando la Inteligencia como una Capacidad, No como una Dependencia
Este artículo no trata sobre cómo usar LLMs. Trata sobre cómo diseñar sistemas que los incorporen con la misma disciplina que se exige a 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 arquitectónica se vuelve insoportable. No es cuando aparece el primer bug. Es cuando alguien pregunta: "¿Qué prompt estaba en producción cuando esto ocurrió?" y nadie sabe responder.
El Problema Que Nadie Nombra
Llamo AI Spaghetti al estado en el que la lógica de IA está distribuida caóticamente por la base de código: llamadas de modelo dentro de controllers, construcción de prompts concatenando strings en helpers, lógica de retrieval mezclada con reglas de negocio, y cero separación entre lo que el sistema quiere hacer y cómo la IA ejecuta eso.
Este estado no nace de negligencia. Nace de la velocidad y de una ilusión específica que la IA Generativa crea: la de que integrar es trivial. Y lo es, al inicio. Una llamada de API, una respuesta, valor entregado. El problema es que los sistemas no son prototipos, y la mayoría de los equipos se da cuenta de eso 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 exige cirugía en decenas de archivos. Cuando necesitas investigar un incidente y no logras 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 arquitectónicos 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:
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 ejecutándose 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 solicitud, cómo interpretar la respuesta. Esa promiscuidad crea un 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 Dependencias aplicada al dominio de IA. Y su expresión arquitectónica 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 lo que el sistema de IA necesita entregar, 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. Estos contratos pertenecen al dominio de la aplicación no a la infraestructura.
Los adaptadores son implementaciones concretas de estos contratos. El adapter de Anthropic sabe cómo llamar a la API de Claude. El de OpenAI sabe cómo llamar a GPT. Ollama sabe cómo llamar a modelos locales. Para la aplicación, todos son intercambiables 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 → construcción de contexto → inferencia → validación de respuesta. Este 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 garantiza que la capa de IA opere con confiabilidad.
El resultado de esta 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 toma horas, no días. Donde la testabilidad 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 enterradas en archivos, copiadas entre ambientes sin control, modificadas directamente en producción por conveniencia.
El problema se vuelve evidente cuando algo sale mal. Un incidente en producción exige respuestas 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 antes? Sistemas sin control de prompt no pueden responder ninguna de ellas.
La solución es tratar los prompts con la misma gobernanza aplicada a código y configuración. Esto significa versionamiento con semántica clara prompts tienen versiones que evolucionan con significado explícito. Significa historial de cambios y trazabilidad de autoría. Significa promoción entre ambientes con los mismos controles aplicados a deploys.
Hay además una dimensión frecuentemente ignorada: los prompts necesitan pruebas. No solo validación manual de "parece bien", sino suites de evaluación que verifiquen si la versión actual sigue satisfaciendo los comportamientos esperados casos de borde, escenarios de falla, instrucciones de frontera. Todo esto necesita estar codificado como expectativas verificables.
El corolario inevitable es que los cambios de prompt deben 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 evaluación sistemática del impacto en la calidad de las respuestas.
RAG como Arquitectura, no como Feature
Retrieval-Augmented Generation se volvió 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 envía al modelo". Esto 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. Esta 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, superposición, enriquecimiento con metadatos estas 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. Sistemas robustos combinan búsqueda semántica con búsqueda por palabras clave (búsqueda híbrida), aplican reranking para refinar los resultados iniciales, y filtran por metadatos para restringir el espacio de búsqueda. Cada uno de estos estadios es un punto de optimización independiente.
La construcción 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 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? Estas verificaciones no son opcionales en sistemas que llegan a usuarios reales.
Resiliencia: Lo Que Nadie Planea Hasta el Primer Incidente
Las APIs de LLM tienen características que hacen que la resiliencia no solo sea 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. Fallas 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 fallas consecutivas y, al detectar degradación, deja de enviar solicitudes que probablemente fallarán protegiendo el sistema de cascadas de error y dando tiempo al provider para recuperarse.
Pero Circuit Breaker por sí solo no es suficiente. Sistemas críticos necesitan fallback entre providers. Un router de modelos que intenta el provider primario, detecta la falla, y automáticamente redirige a un provider secundario transforma una indisponibilidad de vendor en 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 ignorados. Una llamada a LLM sin timeout puede esperar indefinidamente, consumiendo recursos y degradando la experiencia sin fallar explícitamente. Todo sistema de IA necesita timeouts por defecto.
Retry con backoff exponencial resuelve fallas transitorias. Pero retry sin circuit breaker puede empeorar una situación ya degradada. Ambos trabajan juntos: retry para fallas aisladas, circuit breaker para fallas sistémicas.
Observabilidad: Las Tres Dimensiones Que Importan
La observabilidad en sistemas tradicionales gira en torno a los cuatro golden signals: latencia, tráfico, errores y saturación. Los sistemas de IA necesitan estas dimensiones y tres capas específicas adicionales.
Las métricas operacionales son lo que monitorea el SRE. Latencia por provider y por modelo porque el P95 de inferencia es un SLO que necesitas cumplir. Tasa de errores segmentada por tipo rate limit, timeout, content filter, error de red tienen causas y soluciones distintas. 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 monitorea producto. Tasa de respuestas fundamentadas en evidencia especialmente en RAG, donde la alucinación es el principal riesgo. Score promedio 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 monitorea compliance. Distribución de versiones de prompt en producción necesitas saber si una versión antigua aún está sirviendo tráfico. Tasa de activación de content filters 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 estas capas importa porque tienen audiencias y cadencias distintas. Las métricas operacionales se monitorean en tiempo real con 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.
Testabilidad: La Consecuencia Natural de Buenos Contratos
Una arquitectura bien diseñada es, casi por definición, testable. 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 probar flujos de IA sin pagar por tokens, sin depender de la disponibilidad de la API, sin flakiness por variabilidad de respuestas? La respuesta es que no pruebas la IA pruebas 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 estos 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 probado con embeddings fijos, documentos predefinidos y respuesta de LLM sustituida. Validas que la orquestación es correcta, que los datos fluyen entre etapas como se espera, que los errores se propagan adecuadamente.
Tests de evaluación cubren calidad semántica y aquí los LLM 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 determinismo, produce scores que pueden ser incorporados al pipeline de CI/CD. Si el promedio de fundamentación cae por debajo de un threshold después de un cambio de prompt, el deployment es bloqueado.
Tests unitarios y de integración se ejecutan en cada commit, en segundos, sin costo. Tests de evaluación se ejecutan en pull requests significativos, en minutos, con costo controlado. Esta separación es lo que hace que el enfoque sea práctico a escala.
Multi-Agente: Cuando un Modelo No Es Suficiente
Los sistemas de agentes múltiples están emergiendo como patrón para tareas que exceden la capacidad de un único LLM en una sola 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 orquestador 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.
Esta especialización tiene una ventaja frecuentemente subestimada: modelos más pequeños y más baratos pueden ejecutar tareas especializadas con calidad comparable a modelos más grandes ejecutando tareas genéricas. El orquestador puede ser el único componente que requiere el modelo más capaz.
Las trampas de sistemas multi-agente son específicas. La propagación de errores es la más insidiosa un agente que produce un output incorrecto en una etapa inicial contamina todas las etapas subsecuentes, y el sistema frecuentemente continúa ejecutándose con convicción creciente en la dirección equivocada. Checkpoints de validación entre etapas son el mecanismo de contención.
Loops infinitos emergen cuando el orquestador no tiene un límite explícito de iteraciones. Todo sistema de agentes necesita un presupuesto 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 atravesar todos los agentes, y cada decisión del orquestador necesita ser registrada 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 degradar silenciosamente 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 despliegues 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 una falla específica de la IA generativa sin un análogo preciso en software determinístico. Un sistema que presenta información falsa con la misma confianza que presenta información verdadera crea riesgos que van desde lo reputacional hasta lo legal. 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 de 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. Aislamiento por namespace en el vector store, filtros por permisos de usuario y 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. Separación clara entre instrucción y datos en el template del prompt y 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 Arquitectura de Juguete de Arquitectura de Producción
Después de construir y revisar muchos sistemas de IA, identifico cinco dimensiones que distinguen consistentemente sistemas robustos de sistemas frágiles.
Contratos explícitos separan lo que el sistema quiere de la IA de cómo la IA entrega. Sistemas robustos tienen interfaces bien definidas. Sistemas frágiles tienen dependencias directas de SDK distribuidas por el código.
Trazabilidad end-to-end permite reconstruir el contexto completo de cualquier interacción. Sistemas robustos tienen correlation IDs, versionamiento de prompts y logging estructurado de decisiones. Sistemas frágiles no pueden responder "¿qué ocurrió en esta llamada específica?"
Calidad como métrica continua, no como verificación puntual. Sistemas robustos miden fundamentación, relevancia y seguridad en producción, continuamente. Sistemas frágiles dependen de feedback reactivo de usuarios.
Resiliencia por diseño, no como afterthought. Sistemas robustos funcionan de forma degradada cuando los providers fallan. Sistemas frágiles propagan fallas del vendor directamente al usuario.
Gobernanza de prompts con el mismo rigor aplicado al código. Sistemas robustos tienen historial de cambios, proceso de aprobación y capacidad de rollback. Sistemas frágiles tienen strings literales modificadas 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 llamadas a LLM sin cambiar nada más inmediatamente vuelve el código 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. Obtienes trazabilidad de qué prompt está en producción y el historial de cambios sin complejidad operativa.
El tercer paso es agregar telemetría básica: tokens consumidos por feature, latencia de inferencia, tasa de errores por provider. Estos 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 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 providers sin reescribir, escalar sin sorpresas. Ese es el norte.
