El desarrollo de soluciones empresariales basadas en Inteligencia Artificial Generativa requiere superar el paradigma de las respuestas aisladas y migrar hacia arquitecturas robustas, escalables y mantenibles. Cuando se abordan problemas complejos del mundo real —como la consulta de políticas internas, transacciones financieras o gestión de workflows de negocio— el LLM no puede actuar de forma puramente probabilística, ya que corre el riesgo de alucinar o devolver datos desactualizados.
Para mitigar este problema, surge el enfoque de Arquitectura Híbrida: un esquema que combina el dinamismo de la interacción agéntica (capaz de razonar, descomponer tareas y tomar decisiones autónomas) con procesos deterministas (reglas de negocio estrictas, transacciones SQL y búsquedas vectoriales estructuradas). Aplicando el patrón ReAct (Reasoning and Acting) sobre un orquestador como LangChain, el modelo alternadamente "piensa" la estrategia a seguir y "actúa" invocando herramientas especializadas para consultar bases de datos relacionales (PostgreSQL) o repositorios de conocimiento (FAISS VectorStore).
Te gustaría revisar Arquitectura tecnologica para el despliegue en GCP de de una solución Híbrido bajo el patrón ReAct (Reasoning and Acting).
A nivel de ingeniería de software, la separación de responsabilidades exige desacoplar totalmente la interfaz de usuario (Streamlit) de la lógica del agente y de integración de datos (FastAPI + LangChain + OpenAI GPT-4o), estructurando un proyecto modular mediante repositorios o directorios diferenciados de Frontend y Backend.
En este articuloo revisaremos detallaremos la estructura de un proyecto modular bajo una arquitectura híbrida donde combina el dinamismo de la interacción agéntica (razonamiento y uso flexible de herramientas con el patrón ReAct) con la consistencia de procesos deterministas (consultas a base de datos relacional, validaciones de negocio y RAG estructurado).
Te haz preguntado, cómo Desacoplar el Frontend y Backend en Proyectos de IA Generativa Híbrida.
A continuación se detalla la estructura recomendada para un proyecto modular donde separar el proyecto en Backend (API/Orquestador) y Frontend (UI en Streamlit).
Estructura General del Proyecto
genai-hybrid-agent/
├── backend/
│ ├── app/
│ │ ├── api/
│ │ │ ├── v1/
│ │ │ │ ├── endpoints/
│ │ │ │ │ ├── agent.py
│ │ │ │ │ └── health.py
│ │ │ │ └── router.py
│ │ │ └── dependencies.py
│ │ ├── agents/
│ │ │ ├── prompts/
│ │ │ │ └── react_prompt.py
│ │ │ ├── tools/
│ │ │ │ ├── db_tool.py
│ │ │ │ └── rag_tool.py
│ │ │ └── orchestrator.py
│ │ ├── core/
│ │ │ ├── config.py
│ │ │ ├── database.py
│ │ │ ├── llm.py
│ │ │ └── vectorstore.py
│ │ ├── services/
│ │ │ ├── db_service.py
│ │ │ └── rag_service.py
│ │ └── schemas/
│ │ ├── agent_schema.py
│ │ └── chat_schema.py
│ ├── data/
│ │ └── faiss_index/
│ ├── .env
│ ├── Dockerfile
│ ├── main.py
│ └── requirements.txt
└── frontend/
├── src/
│ ├── components/
│ │ ├── chat_interface.py
│ │ └── sidebar.py
│ ├── services/
│ │ └── api_client.py
│ └── utils/
│ └── state_manager.py
├── .env
├── app.py
├── Dockerfile
└── requirements.txt
Detalle del Backend (backend/)
El Backend encapsula toda la lógica agéntica, herramientas deterministas, conexión a PostgreSQL y FAISS. Expone endpoints (vía FastAPI) que consume Streamlit.
1. core/ (Configuración e Infraestructura)
config.py: Configuración centralizada utilizandopydantic-settings(claves de OpenAI, credenciales de PostgreSQL, rutas de FAISS, temperatura del modelo).llm.py: Inicializador del modelo LLMChatOpenAI(model="gpt-4o", temperature=0).database.py: Manejo de la conexión determinista a PostgreSQL con SQLAlchemy o Psycopg3 (pool de conexiones y sesiones).vectorstore.py: Carga y gestión del índice FAISS local o persistido, junto con la configuración deOpenAIEmbeddings.
2. services/ (Capa Determinista)
db_service.py: Funciones puras e imperativas para consultar o actualizar PostgreSQL (por ejemplo, validar un estado financiero, obtener transacciones o datos de clientes).rag_service.py: Lógica de búsqueda vectorial en FAISS (retrieval, filtrado por metadatos, re-ranking si aplica).
3. agents/ (Capa Agéntica & ReAct)
tools/db_tool.py: Define las herramientas (@tool) que el agente invoca cuando requiere datos relacionales precisos (e.g.,consultar_saldo_usuario,obtener_historial).tools/rag_tool.py: Define la herramienta RAG (@tool) encargada de buscar contexto no estructurado en FAISS (manuales, políticas, documentos).prompts/react_prompt.py: Contiene la plantilla del sistema (System Prompt) que instruye al agente a razonar en formato Thought → Action → Action Input → Observation.orchestrator.py: Inicializa el agente ReAct con LangChain (create_react_agentoLangGraphAgent loop) vinculando el LLM GPT-4o con el conjunto de tools deterministas.
4. schemas/ y api/ (Capa de Exposición REST)
schemas/chat_schema.py: Modelos Pydantic para validar entradas/salidas (ChatRequest,ChatResponse,ThoughtStep).api/v1/endpoints/agent.py: Endpoint/api/v1/agent/chatque recibe el mensaje del usuario, invoca al orquestador LangChain y devuelve la respuesta final junto con las trazas de razonamiento si se requiere.
Detalle del Frontend (frontend/)
El Frontend en Streamlit actúa como la capa de presentación desacoplada, enfocada en la experiencia de usuario y manejo de estado de sesión.
1. src/components/
chat_interface.py: Renderizado del historial de mensajería (st.chat_message), caja de texto de entrada y visualización de pasos intermedios (Intermediate Steps/Thought Process) del patrón ReAct en elementos expandibles (st.expander).sidebar.py: Panel lateral para selección de parámetros (ID de usuario, temperatura, reset de conversación, carga de documentos si aplica).
2. src/services/
api_client.py: Cliente HTTP (httpxorequests) para enviar consultas al backend (http://backend:8000/api/v1/agent/chat) con timeout y manejo de errores.
3. src/utils/
state_manager.py: Inicialización y sincronización dest.session_state(almacenamiento demessages,session_id, token de autenticación).
4. Archivo Raíz (app.py)
- Punto de entrada de la aplicación Streamlit. Configura la página (
st.set_page_config), carga el sidebar y renderiza el componente principal de chat.
Flujo de Ejecución (Híbrido Determinista-Agéntico)
El siguiente gráfico ilustra cómo interactúa el Frontend desacoplado con la arquitectura agéntica/determinista del Backend:
Usuario envía consulta: Streamlit reenvía el mensaje al Backend vía REST.
Razonamiento ReAct: GPT-4o analiza la intención del usuario y decide si necesita:
- Ruta Determinista: Consultar datos estructurados en PostgreSQL usando
db_tool. - Ruta RAG: Buscar conocimiento no estructurado en FAISS usando
rag_tool. - Respuesta Directa: Responder basándose en la conversación previa.
- Ruta Determinista: Consultar datos estructurados en PostgreSQL usando
Ejecución de Tools: LangChain ejecuta la herramienta correspondiente y devuelve la observación al LLM.
Respuesta Final: El agente consolida los hallazgos y devuelve la respuesta estructurada a la UI de Streamlit.
Estructura del Proyecto con comentarios para cada elemento:
genai-hybrid-agent/ # Raíz del proyecto
├── backend/ # Servicio de API, lógica agéntica y conexión a datos
│ ├── app/ # Código fuente principal de la aplicación Backend
│ │ ├── api/ # Capa de exposición de endpoints HTTP
│ │ │ ├── v1/ # Versión 1 de la API REST
│ │ │ │ ├── endpoints/ # Endpoints específicos agrupados por dominio
│ │ │ │ │ ├── agent.py # Endpoint POST para procesar mensajes del agente
│ │ │ │ │ └── health.py # Endpoint GET para verifiación de estado (Health Check)
│ │ │ │ └── router.py # Agregador y ruteador de endpoints v1
│ │ │ └── dependencies.py # Inyección de dependencias (sesiones DB, auth, etc.)
│ │ ├── agents/ # Componentes del Agente ReAct y orquestación
│ │ │ ├── prompts/ # Plantillas de prompts para el modelo
│ │ │ │ └── react_prompt.py # System Prompt adaptado al patrón ReAct
│ │ │ ├── tools/ # Herramientas expuestas al agente
│ │ │ │ ├── db_tool.py # Tool de LangChain para consultas relacionales a PostgreSQL
│ │ │ │ └── rag_tool.py # Tool de LangChain para búsqueda contextual en FAISS
│ │ │ └── orchestrator.py # Inicialización del agente orquestador (LangChain + GPT-4o)
│ │ ├── core/ # Configuraciones centrales e infraestructura
│ │ │ ├── config.py # Gestión de variables de entorno y parámetros globales
│ │ │ ├── database.py # Configuración del cliente y sesión SQLAlchemy/PostgreSQL
│ │ │ ├── llm.py # Instanciación y configuración del modelo GPT-4o
│ │ │ └── vectorstore.py # Carga y gestión del índice FAISS y embeddings
│ │ ├── services/ # Capa de negocio y operaciones deterministas
│ │ │ ├── db_service.py # Consultas e inserciones directas/deterministas en PostgreSQL
│ │ │ └── rag_service.py # Algoritmo de recuperación (retrieval) en FAISS
│ │ └── schemas/ # Esquemas Pydantic para validación de datos
│ │ ├── agent_schema.py # DTOs para estado interno y trazabilidad del agente
│ │ └── chat_schema.py # DTOs para Request y Response de la interfaz de chat
│ ├── data/ # Almacenamiento de archivos locales y persistencia
│ │ └── faiss_index/ # Archivos persistidos del índice vectorial FAISS
│ ├── .env # Variables de entorno secretas del Backend (API Keys, DB Uri)
│ ├── Dockerfile # Dockerfile para la contenerización del Backend
│ ├── main.py # Punto de entrada FastAPI para iniciar el servidor HTTP
│ └── requirements.txt # Dependencias Python del Backend (LangChain, FastAPI, etc.)
└── frontend/ # Interfaz de usuario construida en Streamlit
├── src/ # Código fuente principal de la UI
│ ├── components/ # Componentes reutilizables de la interfaz
│ │ ├── chat_interface.py # Renderizado del historial, mensajes y pasos del ReAct
│ │ └── sidebar.py # Panel lateral de navegación, parámetros y configuración
│ ├── services/ # Capa de comunicación externa
│ │ └── api_client.py # Cliente HTTP (httpx/requests) para consumir la API FastAPI
│ └── utils/ # Funciones de soporte e utilidades
│ └── state_manager.py # Gestión y persistencia del estado de sesión (st.session_state)
├── .env # Variables de entorno del Frontend (URLs de Backend, etc.)
├── app.py # Punto de entrada principal de la app Streamlit
├── Dockerfile # Dockerfile para la contenerización del Frontend
└── requirements.txt # Dependencias Python del Frontend (Streamlit, httpx, etc.)
Resumen
A continuación, se resume la arquitectura, tecnologías y organización física del proyecto:
- Arquitectura de Software: Híbrida (Agéntica + Determinista) mediante el patrón ReAct, desacoplada en dos servicios independientes (Backend API y Frontend UI).
- Stack Tecnológico:
- LLM & Orquestación: OpenAI (GPT-4o) + LangChain Agent Orchestrator.
- Backend Framework: FastAPI (Python) expuesto mediante API RESTful.
- Base de Datos Relacional (Determinista): PostgreSQL con SQLAlchemy.
- Base de Datos Vectorial (RAG): FAISS con
OpenAIEmbeddings. - Frontend UI: Streamlit (interfaz conversacional con gestión de sesión y trazabilidad).
Referencias Técnicas y Arquitecturales
- Yao, S., et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv preprint arXiv:2210.03629. (Paper seminal que introduce la intercalación de trazas de razonamiento y acciones específicas con herramientas en LLMs).
- LangChain Documentation (Agent Architectures): LangChain Agents & Custom Tools Framework. Documentación oficial sobre la orquestación de agentes, creación de custom tools (
@tool) y ciclos de ejecución agéntica. - OpenAI API Documentation: GPT-4o & Function Calling Capabilities. Especificación sobre la selección y ejecución estructurada de funciones por parte de los modelos de la familia GPT-4.
- FastAPI & Clean Architecture Guidelines: FastAPI Official Documentation - Bigger Applications & Routers. Buenas prácticas de desacoplamiento de capas (Router, Services, Schemas/DTOs, Core) para APIs en Python.
- Johnson, J., Douze, M., Jégou, H. (2019). Billion-scale similarity search with GPUs (FAISS). IEEE Transactions on Big Data / Meta AI Research. (Referencia para la Búsqueda Vectorial por Aproximación de Vecinos Más Cercanos en RAG).
0 Comentarios