🎙️ MillieSpeech (v1.0.0-release)

Motor Conversacional Full-Duplex en Español de Ultra-Baja Latencia

Arquitectura PersonaPlex 7B / Moshi — Optimizado para NVIDIA Blackwell (RTX 5070 Ti 12GB VRAM)

---

📌 Resumen Ejecutivo y Estado de Producción

MillieSpeech es una solución enterprise de voz conversacional Full-Duplex en español de segunda generación, adaptada sobre el modelo de fundación NVIDIA PersonaPlex 7B y el códec neuronal Kyutai Mimi.

El sistema procesa y genera flujos bidireccionales de texto y audio a 24kHz en tiempo real, ofreciendo respuestas habladas con voz personalizada en español nativo con un Tiempo al Primer Token (TTFT) de solo 45.25 ms, operando 100% de forma local en Windows 11 / Linux dentro de un estricto presupuesto de VRAM < 6.5 GB (consumo real auditado de 1.68 GB).

---

🏛️ Arquitectura del Sistema

El flujo conversacional Full-Duplex se ejecuta desacoplado mediante una tubería de intercalado dual (Dual-Stream Interleaving):

graph TD
    subgraph ClientLayer ["Capa de Cliente & Transporte (Real-Time)"]
        Mic["Micrófono (PCM 24kHz)"] --> WebRTC["Servidor Streaming WebRTC (Puerto 8998)"]
        WebRTC --> Speaker["Altavoz / Audio Salida (< 200ms)"]
    end

    subgraph CodecLayer ["Capa de Códec Neuronal de Audio"]
        WebRTC --> MimiEnc["Encoder Mimi (8 Codebooks @ 12.5Hz)"]
        MimiDec["Decoder Mimi PCM (24kHz)"] --> WebRTC
    end

    subgraph CoreModelLayer ["Capa de Backbone & Adaptación QLoRA"]
        MimiEnc --> DualInterleaver["Dual-Stream Interleaver"]
        SPM["SentencePiece Tokenizer (32k Vocab)"] --> DualInterleaver
        DualInterleaver --> Model7B["Backbone PersonaPlex 7B (Cuantización 4-bit NF4)"]
        QLoRA["Adaptador QLoRA Español (r=64, α=128)"] --> Model7B
        VoicePrompt["Prompt de Voz (user_custom_voice.pt [187, 1, 1, 4096])"] --> Depformer["Proyección Depformer (Timbre Vocal)"]
        Depformer --> Model7B
        Model7B --> MimiDec
    end

    subgraph OrchestrationLayer ["Capa de Orquestación & Resiliencia"]
        MasterPipe["Master Pipeline Orchestrator (master_pipeline.py)"]
        FaultMgr["Fault Tolerance Manager (checkpoints/phase*_completed.pt)"]
        HealthCheck["Health Checker (GPU / VRAM Diagnostics)"]
    end

    MasterPipe --> HealthCheck
    MasterPipe --> FaultMgr
    MasterPipe --> Model7B

---

⚡ Métricas Empíricas de Inferencia Auditadas

Todas las métricas fueron registradas en una estación de trabajo con GPU NVIDIA GeForce RTX 5070 Ti Laptop (12 GB VRAM, Blackwell sm_120) ejecutando Windows 11 Home 64-bit y PyTorch 2.11.0+cu128:

---

🧪 Auditoría Conversacional en 14 Escenarios

---

🛠️ Tecnologías e Innovaciones Técnicas

1. Cuantización 4-bit NF4 con PyTorch SDPA:
   • Integración nativa de bitsandbytes (PagedAdamW8bit) y PyTorch Scaled Dot-Product Attention (SDPA).
   • Elimina la dependencia rígida de Triton en Windows 11 utilizando kernels CUDA compilados para la arquitectura Blackwell.
2. Fine-Tuning QLoRA con Estabilización Anti-PAD:
   • Adaptación de las capas de atención (q_proj, k_proj, v_proj, o_proj, out_proj) con rango $r=64$ y $\alpha=128$.
   • Incorporación de text_padding_weight = 0.0 para evitar el colapso del modelo a silencio constante y regularización $L_2$ (lora_b_l2_reg = 1e-4).
3. Refinamiento de Voz Multi-Pasada (Multi-Pass SNR-Averaged):
   • Selección automática de las 5 mejores ventanas de audio por relación señal-ruido.
   • Generación del tensor de timbre user_custom_voice.pt de dimensión [187, 1, 1, 4096] en bfloat16, inyectado en la proyección depformer.

---

📂 Organización y Estructura del Repositorio

MillieSpeech/
├── milliespeech/                    # Motor central y subsistemas desacoplados
│   ├── core/                        # Configuración, salud, cuantización 4-bit y resiliencia
│   │   ├── config.py                # Configuración global (VRAM, audio 24kHz, QLoRA)
│   │   ├── model.py                 # Cargador cuantizado 4-bit NF4 + SDPA
│   │   ├── health_check.py          # Diagnóstico preventivo de hardware y CUDA
│   │   ├── fault_tolerance.py       # Gestor de resiliencia y recuperación automática
│   │   └── mimi_codec.py            # Wrapper del códec neuronal Mimi (8 codebooks)
│   ├── voice/                       # Subsistema de audio y procesamiento dual
│   │   ├── dataset_prep.py          # Estandarización de audio a 24kHz estéreo/mono
│   │   ├── interleaver.py           # DualStreamInterleaver (Texto + Audio Mimi)
│   │   └── voice_trainer_pytorch.py # Extractor multi-pasada de prompts de voz .pt
│   ├── training/                    # Módulos de Fine-Tuning QLoRA y Destilación
│   │   ├── finetune_qlora.py        # Entrenador QLoRA (PagedAdamW8bit, r=64)
│   │   └── distill.py               # Destilador de conocimiento (7B -> 3B)
│   └── server/                      # Servidores conversacionales y streaming
│       ├── app.py                   # CLI del servidor
│       └── webrtc_server.py         # Servidor WebRTC streaming en tiempo real (puerto 8998)
├── scripts/                         # Orquestadores y scripts de ejecución
│   ├── master_pipeline.py           # Orquestador Maestro (Fases 1 a 6 reproducibles)
│   ├── push_to_hf_hub.py            # Sincronizador con Hugging Face Hub
│   ├── benchmark_text_inference.py  # Suite de benchmarking en 14 escenarios
│   ├── build_phase3_interleaved_dataset.py
│   ├── run_phase4_qlora_training.py
│   └── run_phase5_voice_mounting.py
├── data/                            # Datasets estandarizados
│   ├── raw/clips/                   # 105 clips de audio a 24kHz (82 min)
│   ├── raw/transcripts/             # Transcripciones limpias (dataset.json)
│   └── processed/                   # Diálogos sintéticos JSONL (2,000 diálogos) y tensores
├── voices/                          # Prompts de timbre de voz (.pt)
│   └── user_custom_voice.pt         # Tensor refinado SNR [187, 1, 1, 4096]
├── checkpoints/                     # Adaptadores QLoRA y checkpoints de resiliencia
├── tests/                           # Batería de 18 pruebas unitarias (100% PASS)
├── ARCHITECTURE_DOCUMENTATION.md    # Manual de arquitectura y reproducción
├── ARCHITECTURE_DIAGRAM.mmd         # Diagrama Mermaid del sistema
├── CHANGELOG.md                     # Registro histórico de versiones
├── START_PIPELINE.bat               # Ejecutable directo para Windows 11
├── LICENSE                          # Licencia MIT
└── README.md                        # Documentación principal de producción

---

🚀 Guía de Instalación y Reconstrucción 100% Reproducible

1. Requisitos Previos de Hardware y Software

• GPU: NVIDIA GeForce RTX (Serie 3000, 4000 o 5000 / Blackwell con VRAM ≥ 6 GB).
• SO: Windows 11 Home/Pro 64-bit o Linux Ubuntu 22.04 LTS.
• Driver NVIDIA & CUDA: Driver 550+ / CUDA 12.x.
• Python: 3.10, 3.11 o 3.12 (Recomendado 3.12.10).

2. Clonar el Repositorio

git clone https://github.com/WriteColor/MillieSpeech.git
cd MillieSpeech

3. Configurar Variables de Entorno

$env:HF_TOKEN="hf_tu_token_aqui"

4. Instalar Dependencias

pip install -r requirements.txt

5. Ejecución del Pipeline Maestro (Orquestador)

Para ejecutar la reconstrucción automática y reproducible de las Fases 1 a 6:

• Opción A (Un Clic en Windows 11): Doble clic en START_PIPELINE.bat

• Opción B (Consola de Comandos):

  python scripts/master_pipeline.py --phase all
  

---

🔄 Estrategia de Ramas en Git

El proyecto sigue una estrategia rigurosa de control de versiones con 2 ramas principales:

• main: Rama de producción estable (v1.0.0-release). Todo commit en main debe superar el 100% de las pruebas unitarias y de rendimiento.
• develop: Rama de desarrollo activo donde se integran y prueban nuevas funcionalidades.

# Publicación de cambios en GitHub
git checkout main
git push -u origin main --tags

git checkout develop
git push -u origin develop

---

🤗 Respaldo en Hugging Face Hub

Sincroniza los adaptadores QLoRA, prompts de voz y reportes de benchmarking en tu cuenta de Hugging Face Hub:

python scripts/push_to_hf_hub.py --repo-id "WriteColor/MillieSpeech-7B-Spanish-QLoRA"

• 🔗 Repositorio en Hugging Face Hub: https://huggingface.co/WriteColor/MillieSpeech-7B-Spanish-QLoRA

---

📜 Licencia y Derechos de Autor

Este proyecto se distribuye bajo la Licencia MIT. El modelo base se encuentra sujeto a la licencia oficial de NVIDIA PersonaPlex 7B License y Kyutai Moshi License.