Dani0604/proyecto3-text2sql-qlora

Adapter QLoRA Text-to-SQL — Grupo 1

Adapter ganador del Proyecto 3 de Deep Learning y Sistemas Inteligentes, sección 30, Universidad del Valle de Guatemala.

Modelo y configuración

• Base: Qwen/Qwen2.5-Coder-1.5B-Instruct.
• Método: QLoRA, rango 32, alpha 32 y dropout 0.05.
• Entrenamiento: NF4 de 4 bits, cómputo FP16 y semilla 2026.
• Parámetros entrenables: 36,929,536.
• Tiempo: 133.4 minutos en una RTX 4050 Laptop de 6 GB.

El modelo base no está incluido. Transformers lo descarga por separado y PEFT aplica este adapter.

Datos y resultados

Se entrenó con 2,592 pares auditables sobre 12 esquemas propios, ejecutados en MySQL 8.4.10. La validación usa 40 preguntas sobre dos esquemas inéditos.

Variante	EX ponderada	SQL ejecutable	Latencia p95
Modelo base	3.8%	62.5%	6.66 s
QLoRA r=16	97.4%	97.5%	15.72 s
QLoRA r=32	97.4%	97.5%	13.20 s

R16 y R32 empataron en EX y ejecutabilidad. Se eligió R32 por menor latencia p95. La reparación guiada no cambió la EX y añadió latencia.

Integridad y revisión publicada

• Archivo: adapter_model.safetensors.
• SHA-256: d3126183a092521cb1feffb9424b188552d27bb8fc4b51a8d13a1348d89016f1.
• Revisión de Hugging Face: 24658a4efce8303165906832f0eede2b5c56de84.
• Repositorio público: Dani0604/proyecto3-text2sql-qlora.

Uso

Desde la raíz del proyecto, config.json debe contener "usar_adapter": true:

from solucion import generar_sql

sql = generar_sql(esquema, pregunta)

La generación es determinista, local y restringida a una única consulta SELECT o WITH ... SELECT.

El adapter se puede recuperar anónimamente desde Hugging Face, sin token:

.\.venv\Scripts\hf.exe download Dani0604/proyecto3-text2sql-qlora `
  --revision 24658a4efce8303165906832f0eede2b5c56de84 `
  --local-dir adapter

Compatibilidad y limitaciones

La prueba limpia en Google Colab con Tesla T4 aprobó instalación, carga, determinismo, callback, baseline y restauración del adapter. El adapter cargó en 42.728 s y usó 1.438 GB de VRAM asignada; la evidencia completa está en notebooks/04_prueba_integral_colab_t4.ipynb.

• La validación propia solo contiene dos esquemas inéditos y no equivale a la evaluación oculta.
• Identificadores abreviados, mezcla de idiomas y dominios muy distintos pueden reducir la EX.
• Un caso de validación falló por una entidad inexistente.

Autores y asistencia

Wilson Alejandro Calderón Argueta y Pablo Daniel Barillas Moreno. OpenAI Codex se utilizó como asistencia para implementación, documentación y verificación; no participa como API externa durante la generación SQL evaluada.