Resumen Técnico: SQL Query Engine – Un Pipeline de LLM Auto-Reparador para la Traducción de Lenguaje Natural a PostgreSQL

1. El Problema

La traducción de lenguaje natural a consultas SQL (text-to-SQL) ha avanzado significativamente con la llegada de los Modelos de Lenguaje Grandes (LLM), logrando altas tasas de precisión en benchmarks sintéticos como Spider. Sin embargo, existe una brecha considerable entre el rendimiento en laboratorio y la implementación en entornos de producción reales. Los principales desafíos identificados son:

• Falta de recuperación ante errores: Los enfoques de un solo paso fallan catastróficamente cuando el LLM genera una consulta incorrecta (por errores de sintaxis, nombres de columnas inexistentes o tipos de datos incorrectos), devolviendo el error crudo al usuario o fallando silenciosamente.
• Esquemas dinámicos y complejos: Las bases de datos reales tienen esquemas grandes, evolutivos y a menudo mal documentados, lo que dificulta la introspección estática.
• Seguridad y observabilidad: Los entornos empresariales requieren garantías estrictas de que el sistema no modificará datos y necesitan visibilidad en el proceso de reparación de consultas.

2. Metodología: SQL Query Engine

El sistema propuesto es un servicio de código abierto y auto-alojado que implementa un pipeline de dos etapas impulsado por LLMs, diseñado para ser agnóstico al modelo y compatible con cualquier endpoint compatible con OpenAI.

Arquitectura del Pipeline

El sistema se compone de dos etapas principales orquestadas por un servicio FastAPI:

1. Etapa 1: Introspección de Esquema y Generación de SQL

   • Introspección Dinámica: El sistema consulta information_schema de PostgreSQL para obtener la estructura de la base de datos y muestra filas de ejemplo.
   • Descripción del Esquema: Un LLM genera una descripción legible en Markdown del esquema (tablas, relaciones, tipos de datos), que se almacena en caché en Redis por sesión (chatID) para evitar introspecciones redundantes en turnos posteriores.
   • Generación y Parsing: El LLM genera una consulta SQL inicial. Un parser de respuesta multi-estrategia extrae el SQL de cualquier formato de salida (JSON, bloques de código, texto plano) sin depender de APIs de salida estructurada.

2. Etapa 2: Evaluación y Bucle de Auto-Reparación (Self-Healing)

   • Ejecución y Diagnóstico: La consulta generada se ejecuta contra una instancia de PostgreSQL (conectada en modo solo lectura a nivel de driver).
   • Bucle Iterativo: Si la consulta falla o devuelve resultados vacíos, el sistema captura el error completo de PostgreSQL, incluyendo el código SQLSTATE, mensajes de diagnóstico, sugerencias (hints) y el traceback de Python.
   • Corrección: Esta información de error se alimenta de vuelta al LLM en un prompt de evaluación para que diagnostique el problema y genere una corrección.
   • Mecanismos de Seguridad:
     • Early-Accept (Aceptación Temprana): Si una consulta se ejecuta sin errores y devuelve al menos una fila, se acepta inmediatamente sin re-evaluación del LLM, evitando que un modelo "arregle" una consulta correcta convirtiéndola en incorrecta.
     • Seguimiento del Mejor Resultado: El sistema rastrea el mejor resultado parcial obtenido durante las iteraciones. Si se agotan los reintentos, devuelve el mejor resultado encontrado en lugar de fallar.
     • Ignorancia de la Autoevaluación: El sistema no confía en la afirmación del LLM de que una consulta es válida (isValid); solo la ejecución exitosa cuenta como éxito.

Características Adicionales

• Streaming en Tiempo Real: Utiliza Redis Pub/Sub y Server-Sent Events (SSE) para transmitir el progreso de la reparación (pensamiento del LLM, intentos de corrección) al cliente en tiempo real.
• Doble Interfaz API: Ofrece una API REST nativa y una interfaz compatible con OpenAI (/v1/chat/completions), permitiendo su uso con herramientas existentes como Open WebUI o el SDK de Python de OpenAI sin modificaciones.

3. Contribuciones Clave

1. Pipeline de Auto-Reparación Basado en Ejecución: Un bucle iterativo que utiliza diagnósticos completos de PostgreSQL (SQLSTATE y mensajes detallados) para corregir errores, logrando mejoras significativas en la precisión de ejecución.
2. Mecanismos de Prevención de Regresión: La combinación de "Early-Accept" y "Best-Result Tracking" garantiza que el sistema nunca degrade una consulta que ya funcionaba correctamente.
3. Parser de Respuesta Universal: Una estrategia de extracción de 5 pasos que permite trabajar con cualquier LLM, independientemente de si su salida es JSON, texto plano o bloques de código, eliminando la dependencia de APIs de salida estructurada.
4. Arquitectura Agnóstica y Segura: Compatible con cualquier backend de LLM (OpenAI, Ollama, vLLM, etc.) y con conexiones de base de datos forzadas a modo solo lectura a nivel de driver.

4. Resultados Empíricos

El sistema se evaluó en dos frentes: un benchmark sintético controlado y el benchmark BIRD (datos del mundo real). Se probaron 5 modelos LLM diferentes (GPT-OSS, Llama 3.3, Llama 4 Scout, Qwen3).

Benchmark Sintético (75 preguntas, 3 bases de datos)

• Mejora de Precisión: El bucle de auto-reparación aumentó la precisión de ejecución en hasta +9.3 puntos porcentuales (de 48.0% a 57.3%) con el modelo Llama 4 Scout 17B.
• Cero Regresiones: En los modelos que mejoraron significativamente (Llama 4 Scout y GPT-OSS-20B), no se registraron regresiones gracias al mecanismo de "Early-Accept".
• Impacto por Dificultad: La mejora fue más notable en consultas difíciles, donde la precisión pasó del 5.6% al 44.4% para el modelo Llama 4 Scout.

Benchmark BIRD (437 preguntas, 11 bases de datos reales migradas de SQLite a PostgreSQL)

• Mejora en Escenario Real: El modelo GPT-OSS-120B logró la mayor precisión final (49.0%), representando una mejora de +4.6 puntos porcentuales gracias al bucle de reparación.
• Superación de Líneas Base: El resultado de 49.0% supera a las líneas base publicadas de ChatGPT (39.3%) y Claude 2 (42.7%) en el conjunto de desarrollo de BIRD.
• Desafíos: Se observaron tasas de regresión más altas en BIRD (17-24 por modelo) comparado con el benchmark sintético, debido a que muchas consultas correctas en datos reales devuelven resultados vacíos, lo que activa innecesariamente el bucle de reparación.

Costo de Latencia

El bucle de auto-reparación introduce una sobrecarga de latencia (aproximadamente 2x a 2.5x en datos sintéticos), pero el sistema mantiene un uso de memoria estable y permite el streaming de progreso para mejorar la experiencia del usuario.

5. Significado e Impacto

El SQL Query Engine demuestra que la reparación basada en la ejecución (execution-grounded repair) es una técnica práctica y efectiva para cerrar la brecha entre el rendimiento de los LLMs en benchmarks sintéticos y su aplicabilidad en producción.

• Viabilidad en Producción: Al integrar mecanismos de seguridad estrictos (solo lectura) y observabilidad en tiempo real, el sistema aborda las preocupaciones de seguridad y usabilidad que a menudo impiden la adopción de soluciones text-to-SQL.
• Independencia del Modelo: La capacidad de funcionar con modelos de código abierto locales (como Llama o Qwen) y modelos propietarios, sin requerir fine-tuning específico, democratiza el acceso a interfaces de bases de datos naturales.
• Nueva Dirección de Investigación: El trabajo sugiere que la arquitectura de un solo agente con bucles de reparación iterativa puede ser tan efectiva como enfoques multi-agente más complejos, pero con una infraestructura significativamente más simple.

En conclusión, este sistema ofrece una solución robusta y escalable para la interacción natural con bases de datos PostgreSQL, transformando los errores de ejecución en oportunidades de aprendizaje para el modelo y mejorando la fiabilidad general del sistema.