| # Análise Matemática — BiGRU_T_version (Refatoração GRU-RING v13.9.2) |
|
|
| ## 1. Visão geral |
|
|
| A refatoração **BiGRU_T_version** preserva a filosofia cooperativa do GRU-RING v13.9.2 |
| (4 camadas BiGRU + Transformer + Hypothesis Network + Trust Network), mas reorganiza |
| o cálculo em torno de **4 lemas formais** que tornam explícitos os mecanismos de |
| desacoplamento, cirurgia de gradiente, cancelamento de ruído de quantização e |
| auto-configuração. |
|
|
| ### 1.1 Comparação estrutural com v13.9.2 |
|
|
| | Aspecto | v13.9.2 (original) | BiGRU_T_version (refatorado) | |
| |---|---|---| |
| | Camadas BiGRU | 4 cooperativas (d_model=128) | 4 por BiGRU4 × 8 paralelas por u8cell_T | |
| | Módulos especialistas | 1 (single stack) | até `max_modules=64` u8cell_T | |
| | Seleção de módulos | implícita (Confidence Gate) | **softmax com temperatura α (Lema 1)** | |
| | Hipótese | 16 hipóteses com mapeamento LoRA | **HypT: delta correção sobre y_hat (Lema 3)** | |
| | Trust | TD-learning + softmax norm | **τ limiar + MetaConfigurator (Lema 4)** | |
| | Quantização | W8A8 QOperator (SmoothQuant) | **W8A8 fake-quant em Linear (Lema 3)** | |
| | Interação gradiente main/hyp | Punishment gate | **gradient surgery ortogonal (Lema 2)** | |
| | Multimodalidade | xavante/multimodal/* | mantida (image/audio/video/text encoders) | |
| | Otimizador | AdamW | AdamW + **HamiltonianWassersteinOptimizer opcional** | |
| | Tokenizer | BBPE 16K | BBPE 16K (reaproveitado) | |
| | Datasets | 9 base + 3 PT-BR finetune | mesmos (reaproveitados) | |
| |
| --- |
| |
| ## 2. Lema 1 — Desacoplamento via atenção hierárquica |
| |
| **Enunciado.** Seja $\mathcal{M} = \{m_1, \ldots, m_K\}$ um conjunto de módulos |
| $u8cell_T$ e sejam $\mathbf{z} \in \mathbb{R}^K$ logits de seleção. Define-se |
|
|
| $$\alpha_k(T) = \frac{e^{z_k / T}}{\sum_{j=1}^K e^{z_j / T}}$$ |
|
|
| A saída agregada é $H = \sum_{k=1}^K \alpha_k(T) \, h_k$, com $h_k = u8cell_T_k(x)$. |
|
|
| **Propriedade (especialização por entropia).** A entropia da distribuição |
| $H(\alpha) = -\sum_k \alpha_k \log \alpha_k$ é maximizada em $\log K$ quando |
| $T \to \infty$ (seleção uniforme) e minimizada em $0$ quando $T \to 0^+$ |
| (seleção argmax). Minimizar $H(\alpha)$ indiretamente via regularização |
| $L_{\text{ent}} = \lambda_{\text{ent}} \cdot H(\alpha)$ força especialização: |
| aproximadamente um subconjunto $\mathcal{S} \subset \mathcal{M}$ com |
| $|\mathcal{S}| \ll K$ retém pesos significativos. |
| |
| **Propriedade (redução da disputa de gradiente).** Seja $g_k = \nabla_{\theta_k} L$ |
| o gradiente da perda em relação aos parâmetros do módulo $k$. Como |
| $\partial L / \partial \theta_k = \alpha_k \cdot \partial L / \partial h_k \cdot \partial h_k / \partial \theta_k$, |
| quando $\alpha_k \to 0$ o gradiente $\|g_k\| \to 0$. Logo, módulos inativos |
| não competem por capacidade de gradiente, reduzindo o produto interno |
| $\langle g_i, g_j \rangle$ para $i \neq j$ ativos. |
| |
| **Implementação.** Em `model/module_selector.py`: |
| - `module_logits: nn.Parameter(torch.zeros(K))` — logits aprendíveis |
| - `alpha = F.softmax(module_logits / T, dim=0)` no forward |
| - `entropy_reg = -lambda_ent * (alpha * log(alpha + eps)).sum()` retornado como aux loss |
|
|
| **Meta-ajuste de T.** T é tratado como hiperparâmetro aprendível pelo |
| `MetaConfigurator` (Lema 4) via `T = exp(log_temperature)`. |
|
|
| --- |
|
|
| ## 3. Lema 2 — Gradiente cirúrgico |
|
|
| **Enunciado.** Sejam $L_{\text{main}}(\theta)$ e $L_{\text{hyp}}(\theta)$ duas perdas |
| compartilhando parâmetros $\theta$. Sejam |
| $g_{\text{main}} = \nabla_\theta L_{\text{main}}$ e |
| $g_{\text{hyp}} = \nabla_\theta L_{\text{hyp}}$. |
|
|
| **Projeção ortogonal.** Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$ |
| (gradientes conflitantes), projeta-se $g_{\text{hyp}}$ no complemento ortogonal |
| de $g_{\text{main}}$: |
|
|
| $$g_{\text{hyp}}^{\perp} = g_{\text{hyp}} - \frac{\langle g_{\text{main}}, g_{\text{hyp}} \rangle}{\|g_{\text{main}}\|^2 + \epsilon} \, g_{\text{main}}$$ |
|
|
| O gradiente combinado é $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}^{\perp}$. |
| |
| **Propriedade (não-interferência).** Por construção, |
| $\langle g_{\text{total}}, g_{\text{main}} \rangle = \|g_{\text{main}}\|^2 + 0 = \|g_{\text{main}}\|^2 \geq 0$, |
| logo $g_{\text{total}}$ sempre reduz $L_{\text{main}}$. Adicionalmente, |
| $\langle g_{\text{total}}, g_{\text{hyp}} \rangle = \langle g_{\text{main}}, g_{\text{hyp}} \rangle + \|g_{\text{hyp}}^{\perp}\|^2$. |
| Como $\|g_{\text{hyp}}^{\perp}\|^2 = \|g_{\text{hyp}}\|^2 - \frac{\langle g_{\text{main}}, g_{\text{hyp}} \rangle^2}{\|g_{\text{main}}\|^2}$ |
| e $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$, segue que |
| $\langle g_{\text{total}}, g_{\text{hyp}} \rangle > \langle g_{\text{main}}, g_{\text{hyp}} \rangle$, |
| ou seja, $g_{\text{total}}$ também não piora $L_{\text{hyp}}$ além do que |
| $g_{\text{main}}$ já pioraria. |
|
|
| **Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle \geq 0$** (gradientes |
| alinhados), não há projeção: $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}$. |
| |
| **Implementação.** Em `training/gradient_surgery.py`: |
| - `orthogonalize_gradient(g_main, g_hyp)`: implementação vetorial da projeção |
| - `apply_gradient_surgery(model, loss_main, loss_hyp)`: calcula gradientes |
| independentes via `torch.autograd.grad` (com `retain_graph=True` para main), |
| aplica projeção e atribui `p.grad = g_total` |
|
|
| --- |
|
|
| ## 4. Lema 3 — Cancelamento de ruído de quantização |
|
|
| **Enunciado.** Seja $f_\theta: \mathcal{X} \to \mathbb{R}^V$ o modelo principal |
| e $Q_8(\cdot)$ a quantização W8A8 (pesos e ativações em 8 bits). A saída |
| quantizada é |
|
|
| $$\hat{y} = f_{Q_8(\theta)}(x) = f_\theta(x) + \eta(x)$$ |
| |
| onde $\eta(x)$ é o erro de quantização (viés + variância). |
| |
| **Hipótese corretiva.** Define-se uma cabeça de hipótese $h_\phi: \mathbb{R}^d \to \mathbb{R}^V$ |
| que produz uma correção $\delta = h_\phi(o)$ onde $o$ é a representação |
| agregada pelo orquestrador. A predição final é |
| |
| $$y_{\text{final}} = \hat{y} + \delta = f_\theta(x) + \eta(x) + h_\phi(o)$$ |
|
|
| **Objetivo.** Treinar $h_\phi$ para que $h_\phi(o) \approx -\eta(x)$, cancelando |
| o ruído de quantização. A perda é |
| $L_{\text{hyp}} = \ell(y_{\text{final}}, y^*)$ onde $y^*$ é o rótulo verdadeiro. |
|
|
| **Isolamento do sinal (stop_grad_hyp).** Para evitar que o gradiente de |
| $L_{\text{hyp}}$ contamine os parâmetros principais via $o$, a entrada $o$ |
| de $h_\phi$ é destacada: $\delta = h_\phi(\text{sg}(o))$ onde $\text{sg}$ é |
| stop-gradient. Isso faz $\nabla_\theta L_{\text{hyp}}$ depender apenas dos |
| parâmetros compartilhados via $f_\theta$ (gerenciados pelo Lema 2). |
|
|
| **Ativação condicional.** A hipótese só é ativada quando $L_{\text{main}} > \tau$, |
| ou seja, quando a perda principal excede um limiar (indicando que a quantização |
| está prejudicando a predição). Caso contrário, $\delta = 0$ e o modelo usa |
| apenas $\hat{y}$. |
| |
| **Implementação.** Em `model/hyp_t.py` e `quantization/quantized_linear.py`: |
| - `QuantizedLinear(nn.Linear)`: fake quant W8A8 no forward (STE backward) |
| - `HypT.forward(o, stop_grad=True)`: aplica `o.detach()` quando stop_grad |
| - No `UnifiedModel.forward`: se `use_hypothesis=True` e `loss_main > tau`, |
| calcula `y_final = y_hat + delta` e retorna ambos |
| |
| --- |
| |
| ## 5. Lema 4 — Auto-configuração e suavização |
| |
| **Enunciado.** Seja $\mathcal{L}_{\text{val}}(T, \tau; \theta)$ a perda de |
| validação como função dos hiperparâmetros temperatura $T$ e limiar $\tau$. |
| O MetaConfigurator mantém $T = \exp(\log T)$ e $\tau = \exp(\log \tau)$ |
| (garantindo positividade) e os otimiza por gradiente descendente em um |
| meta-objetivo: |
|
|
| $$\mathcal{L}_{\text{meta}}(T, \tau) = \mathcal{L}_{\text{val}}(T, \tau; \theta^*) + \lambda_s \cdot S(\theta^*)$$ |
|
|
| onde $\theta^* = \theta - \eta \nabla_\theta \mathcal{L}_{\text{train}}(T, \tau; \theta)$ |
| é o parâmetro após um passo de treino (diferenciação implícita), e |
| $S(\theta) = \|\nabla_\theta \mathcal{L}\|^2$ é uma **proxy de agudeza** |
| (sharpness) — aproximação de baixo custo para o maior autovalor da Hessiana. |
| |
| **Propriedade (mínimos planos).** Minimizar $S(\theta)$ empurra o modelo |
| para regiões de baixa curvatura, onde o ruído de gradiente (devido a |
| mini-batches e quantização W8A8) produz atualizações menores em magnitude, |
| reduzindo variância e melhorando generalização (Keskar et al., 2017; |
| Foret et al., 2021 — SAM). |
| |
| **Controle implícito do número de módulos ativos.** Como $T$ controla a |
| entropia de $\alpha$ (Lema 1), minimizar $\mathcal{L}_{\text{meta}}$ ajusta |
| $T$ para o regime onde apenas os módulos necessários estão ativos. Não há |
| necessidade de regularização explícita de cardinalidade (embora |
| $L_{\text{ent}}$ possa ser adicionada se desejado). |
| |
| **Implementação.** Em `training/meta_configurator.py`: |
| - `log_temperature: nn.Parameter` — aprendível, $T = \exp(\log T)$ |
| - `log_tau: nn.Parameter` — aprendível, $\tau = \exp(\log \tau)$ |
| - `forward_with_meta(x_val, y_val)`: |
| 1. Forward com $T$ atual → $\mathcal{L}_{\text{val}}$ |
| 2. `grads = autograd.grad(L_val, model.parameters(), create_graph=True)` |
| 3. `sharpness = sum((g**2).sum() for g in grads)` |
| 4. `meta_loss = L_val + lambda_s * sharpness` |
| 5. `meta_optim.zero_grad(); meta_loss.backward(); meta_optim.step()` |
| 6. Atualiza `model.tau = exp(log_tau).detach()` |
| |
| --- |
| |
| ## 6. Análise de estabilidade e convergência |
| |
| ### 6.1 Estabilidade do gradiente combinado |
| |
| Sob os Lemas 1–4, o gradiente efetivo em $\theta$ é |
| |
| $$g_{\text{eff}} = \alpha_k(T) \cdot g_{\text{main}} + \mathbb{1}[L_{\text{main}} > \tau] \cdot g_{\text{hyp}}^\perp$$ |
| |
| Sob **assumir** (i) gradientes com norma limitada $\|g\| \leq G$, (ii) |
| $\alpha_k \in [0,1]$ com $\sum \alpha_k = 1$, (iii) projeção ortogonal |
| preserva norma $\|g_{\text{hyp}}^\perp\| \leq \|g_{\text{hyp}}\|$, então |
| $\|g_{\text{eff}}\| \leq G + G = 2G$. Logo, com clipping em $5.0$ (como no |
| script original), o gradiente é estável. |
|
|
| ### 6.2 Convergência do meta-aprendizado |
|
|
| O MetaConfigurator usa Adam com $\eta_{\text{meta}} = 0.01$ em |
| $(\log T, \log \tau)$. Como a meta-perda é diferenciável em $(\log T, \log \tau)$ |
| via `create_graph=True`, Adam converge para um mínimo local sob condições |
| padrão (Kingma & Ba, 2015). A proxy de agudeza $S(\theta)$ é não-negativa e |
| diferenciável, garantindo que o meta-objetivo é coercivo. |
|
|
| ### 6.3 Não-divergência do modelo principal |
|
|
| Mesmo se $h_\phi$ divergir, $y_{\text{final}} = \hat{y} + \delta$ é limitado |
| pelo fato de que $L_{\text{hyp}}$ penaliza $\delta$ quando $y_{\text{final}}$ |
| se afasta de $y^*$. Adicionalmente, o stop-gradient isola $\delta$ do caminho |
| principal, então $\hat{y}$ permanece estável. |
| |
| --- |
| |
| ## 7. Mapeamento de reaproveitamento (source → BiGRU_T_version) |
| |
| | Componente | Source path | Target path | Reuso | |
| |---|---|---|---| |
| | BBPE Tokenizer | `flexnet/bbpe_tokenizer.py` | `src/bigru_t/tokenizer/bbpe_tokenizer.py` | Cópia fiel | |
| | Streaming datasets | `flexnet/streaming_datasets_v13_9.py` + `scripts/streaming_datasets_v13_9.py` | `src/bigru_t/data/streaming_datasets.py` | Merge (9 base + 3 PT-BR + format_template) | |
| | W8A8 QOperator | `flexnet/w8a8_qoperator.py` | `src/bigru_t/quantization/w8a8_qoperator.py` | Cópia + wrapper `QuantizedLinear` do Lema 3 | |
| | Hardware detector | `flexnet/hardware_detector.py` + `xavante/core/hardware_detector.py` | `src/bigru_t/utils/hardware_detector.py` | Cópia do flexnet (mais canônico) | |
| | Xeon runtime | `flexnet/xeon_runtime.py` | `src/bigru_t/utils/xeon_runtime.py` | Cópia fiel | |
| | OOM guard | `flexnet/oom_guard.py` | `src/bigru_t/utils/oom_guard.py` | Cópia fiel | |
| | Memory monitor | `flexnet/memory_monitor.py` | `src/bigru_t/utils/memory_monitor.py` | Cópia fiel | |
| | Tensor ops | `xavante/utils/tensor_ops.py` | `src/bigru_t/utils/tensor_ops.py` | Cópia fiel | |
| | Validators | `xavante/utils/validators.py` | `src/bigru_t/utils/validators.py` | Cópia fiel | |
| | Logging utils | `xavante/utils/logging_utils.py` | `src/bigru_t/utils/logging_utils.py` | Cópia fiel | |
| | Hamiltonian-Wasserstein optimizer | `flexnet/hamiltonian_wasserstein_optimizer.py` | `src/bigru_t/optim/hamiltonian_wasserstein.py` | Cópia (opcional em treino) | |
| | Multimodal: text encoder | `xavante/multimodal/text_encoder.py` | `src/bigru_t/multimodal/text_encoder.py` | Cópia fiel | |
| | Multimodal: image encoder | `xavante/multimodal/image_encoder.py` | `src/bigru_t/multimodal/image_encoder.py` | Cópia fiel | |
| | Multimodal: audio encoder | `xavante/multimodal/audio_encoder.py` | `src/bigru_t/multimodal/audio_encoder.py` | Cópia fiel | |
| | Multimodal: video encoder | `xavante/multimodal/video_encoder.py` | `src/bigru_t/multimodal/video_encoder.py` | Cópia fiel | |
| | Multimodal: modal router | `xavante/multimodal/modal_router.py` | `src/bigru_t/multimodal/modal_router.py` | Cópia fiel | |
| |
| **Descartados (superseded)**: |
| - `flexnet/train_v13_9_minimal.py` — superseded by `flexnet/train_v13_9.py` |
| - `xavante/enhanced/enhanced_xavante_v1.py`, `v2.py` — superseded by `v3.py` |
| - `xavante/training/medusa_trainer.py` — superseded by `medusa_trainer_bpe.py` |
| - `flexnet/hf_dataset_streamer.py` — superseded by `streaming_datasets_v13_9.py` |
| |
| --- |
| |
| ## 8. Diferenças do treino (bug-detection run) |
| |
| | Parâmetro | v13.9.2 original | BiGRU_T_version (bug-detection) | |
| |---|---|---| |
| | Epochs | 1 (effective, via max_steps) | **2** (fixo por especificação) | |
| | Datasets | 9 base + 3 PT-BR | mesmos | |
| | Max samples por dataset | 200-500 | 50 (bug-detection, reduzido) | |
| | Max optimizer steps | 40-200 | 30 (2 épocas × ~15 steps/época) | |
| | Grad accum | 16 | 8 | |
| | LR | 1e-5 a 2e-5 | 1e-3 (treino from-scratch, não fine-tune) | |
| | Monitor | loss, ppl, conf | loss, ppl, **RAM, disk, módulos ativos** | |
| | Kill-switch | punishment gate | **loss não diminui em N steps OU RAM > 90%** | |
| |
| --- |
| |
| ## 9. Conclusão |
| |
| A refatoração BiGRU_T_version formaliza os mecanismos heurísticos do v13.9.2 |
| em 4 lemas matemáticos verificáveis, mantendo a multimodalidade e o stack de |
| otimização original. O treino de bug-detection (2 épocas) valida o pipeline |
| end-to-end sem pretender produzir um modelo competitivo — o objetivo é |
| detectar erros de implementação nos 4 lemas e nos módulos reaproveitados. |
| |
