PowerMachine commited on
Commit
04e5e76
·
verified ·
1 Parent(s): 3b4c35a

Upload docs/analysis.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. docs/analysis.md +259 -0
docs/analysis.md ADDED
@@ -0,0 +1,259 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Análise Matemática — BiGRU_T_version (Refatoração GRU-RING v13.9.2)
2
+
3
+ ## 1. Visão geral
4
+
5
+ A refatoração **BiGRU_T_version** preserva a filosofia cooperativa do GRU-RING v13.9.2
6
+ (4 camadas BiGRU + Transformer + Hypothesis Network + Trust Network), mas reorganiza
7
+ o cálculo em torno de **4 lemas formais** que tornam explícitos os mecanismos de
8
+ desacoplamento, cirurgia de gradiente, cancelamento de ruído de quantização e
9
+ auto-configuração.
10
+
11
+ ### 1.1 Comparação estrutural com v13.9.2
12
+
13
+ | Aspecto | v13.9.2 (original) | BiGRU_T_version (refatorado) |
14
+ |---|---|---|
15
+ | Camadas BiGRU | 4 cooperativas (d_model=128) | 4 por BiGRU4 × 8 paralelas por u8cell_T |
16
+ | Módulos especialistas | 1 (single stack) | até `max_modules=64` u8cell_T |
17
+ | Seleção de módulos | implícita (Confidence Gate) | **softmax com temperatura α (Lema 1)** |
18
+ | Hipótese | 16 hipóteses com mapeamento LoRA | **HypT: delta correção sobre y_hat (Lema 3)** |
19
+ | Trust | TD-learning + softmax norm | **τ limiar + MetaConfigurator (Lema 4)** |
20
+ | Quantização | W8A8 QOperator (SmoothQuant) | **W8A8 fake-quant em Linear (Lema 3)** |
21
+ | Interação gradiente main/hyp | Punishment gate | **gradient surgery ortogonal (Lema 2)** |
22
+ | Multimodalidade | xavante/multimodal/* | mantida (image/audio/video/text encoders) |
23
+ | Otimizador | AdamW | AdamW + **HamiltonianWassersteinOptimizer opcional** |
24
+ | Tokenizer | BBPE 16K | BBPE 16K (reaproveitado) |
25
+ | Datasets | 9 base + 3 PT-BR finetune | mesmos (reaproveitados) |
26
+
27
+ ---
28
+
29
+ ## 2. Lema 1 — Desacoplamento via atenção hierárquica
30
+
31
+ **Enunciado.** Seja $\mathcal{M} = \{m_1, \ldots, m_K\}$ um conjunto de módulos
32
+ $u8cell_T$ e sejam $\mathbf{z} \in \mathbb{R}^K$ logits de seleção. Define-se
33
+
34
+ $$\alpha_k(T) = \frac{e^{z_k / T}}{\sum_{j=1}^K e^{z_j / T}}$$
35
+
36
+ A saída agregada é $H = \sum_{k=1}^K \alpha_k(T) \, h_k$, com $h_k = u8cell_T_k(x)$.
37
+
38
+ **Propriedade (especialização por entropia).** A entropia da distribuição
39
+ $H(\alpha) = -\sum_k \alpha_k \log \alpha_k$ é maximizada em $\log K$ quando
40
+ $T \to \infty$ (seleção uniforme) e minimizada em $0$ quando $T \to 0^+$
41
+ (seleção argmax). Minimizar $H(\alpha)$ indiretamente via regularização
42
+ $L_{\text{ent}} = \lambda_{\text{ent}} \cdot H(\alpha)$ força especialização:
43
+ aproximadamente um subconjunto $\mathcal{S} \subset \mathcal{M}$ com
44
+ $|\mathcal{S}| \ll K$ retém pesos significativos.
45
+
46
+ **Propriedade (redução da disputa de gradiente).** Seja $g_k = \nabla_{\theta_k} L$
47
+ o gradiente da perda em relação aos parâmetros do módulo $k$. Como
48
+ $\partial L / \partial \theta_k = \alpha_k \cdot \partial L / \partial h_k \cdot \partial h_k / \partial \theta_k$,
49
+ quando $\alpha_k \to 0$ o gradiente $\|g_k\| \to 0$. Logo, módulos inativos
50
+ não competem por capacidade de gradiente, reduzindo o produto interno
51
+ $\langle g_i, g_j \rangle$ para $i \neq j$ ativos.
52
+
53
+ **Implementação.** Em `model/module_selector.py`:
54
+ - `module_logits: nn.Parameter(torch.zeros(K))` — logits aprendíveis
55
+ - `alpha = F.softmax(module_logits / T, dim=0)` no forward
56
+ - `entropy_reg = -lambda_ent * (alpha * log(alpha + eps)).sum()` retornado como aux loss
57
+
58
+ **Meta-ajuste de T.** T é tratado como hiperparâmetro aprendível pelo
59
+ `MetaConfigurator` (Lema 4) via `T = exp(log_temperature)`.
60
+
61
+ ---
62
+
63
+ ## 3. Lema 2 — Gradiente cirúrgico
64
+
65
+ **Enunciado.** Sejam $L_{\text{main}}(\theta)$ e $L_{\text{hyp}}(\theta)$ duas perdas
66
+ compartilhando parâmetros $\theta$. Sejam
67
+ $g_{\text{main}} = \nabla_\theta L_{\text{main}}$ e
68
+ $g_{\text{hyp}} = \nabla_\theta L_{\text{hyp}}$.
69
+
70
+ **Projeção ortogonal.** Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$
71
+ (gradientes conflitantes), projeta-se $g_{\text{hyp}}$ no complemento ortogonal
72
+ de $g_{\text{main}}$:
73
+
74
+ $$g_{\text{hyp}}^{\perp} = g_{\text{hyp}} - \frac{\langle g_{\text{main}}, g_{\text{hyp}} \rangle}{\|g_{\text{main}}\|^2 + \epsilon} \, g_{\text{main}}$$
75
+
76
+ O gradiente combinado é $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}^{\perp}$.
77
+
78
+ **Propriedade (não-interferência).** Por construção,
79
+ $\langle g_{\text{total}}, g_{\text{main}} \rangle = \|g_{\text{main}}\|^2 + 0 = \|g_{\text{main}}\|^2 \geq 0$,
80
+ logo $g_{\text{total}}$ sempre reduz $L_{\text{main}}$. Adicionalmente,
81
+ $\langle g_{\text{total}}, g_{\text{hyp}} \rangle = \langle g_{\text{main}}, g_{\text{hyp}} \rangle + \|g_{\text{hyp}}^{\perp}\|^2$.
82
+ Como $\|g_{\text{hyp}}^{\perp}\|^2 = \|g_{\text{hyp}}\|^2 - \frac{\langle g_{\text{main}}, g_{\text{hyp}} \rangle^2}{\|g_{\text{main}}\|^2}$
83
+ e $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$, segue que
84
+ $\langle g_{\text{total}}, g_{\text{hyp}} \rangle > \langle g_{\text{main}}, g_{\text{hyp}} \rangle$,
85
+ ou seja, $g_{\text{total}}$ também não piora $L_{\text{hyp}}$ além do que
86
+ $g_{\text{main}}$ já pioraria.
87
+
88
+ **Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle \geq 0$** (gradientes
89
+ alinhados), não há projeção: $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}$.
90
+
91
+ **Implementação.** Em `training/gradient_surgery.py`:
92
+ - `orthogonalize_gradient(g_main, g_hyp)`: implementação vetorial da projeção
93
+ - `apply_gradient_surgery(model, loss_main, loss_hyp)`: calcula gradientes
94
+ independentes via `torch.autograd.grad` (com `retain_graph=True` para main),
95
+ aplica projeção e atribui `p.grad = g_total`
96
+
97
+ ---
98
+
99
+ ## 4. Lema 3 — Cancelamento de ruído de quantização
100
+
101
+ **Enunciado.** Seja $f_\theta: \mathcal{X} \to \mathbb{R}^V$ o modelo principal
102
+ e $Q_8(\cdot)$ a quantização W8A8 (pesos e ativações em 8 bits). A saída
103
+ quantizada é
104
+
105
+ $$\hat{y} = f_{Q_8(\theta)}(x) = f_\theta(x) + \eta(x)$$
106
+
107
+ onde $\eta(x)$ é o erro de quantização (viés + variância).
108
+
109
+ **Hipótese corretiva.** Define-se uma cabeça de hipótese $h_\phi: \mathbb{R}^d \to \mathbb{R}^V$
110
+ que produz uma correção $\delta = h_\phi(o)$ onde $o$ é a representação
111
+ agregada pelo orquestrador. A predição final é
112
+
113
+ $$y_{\text{final}} = \hat{y} + \delta = f_\theta(x) + \eta(x) + h_\phi(o)$$
114
+
115
+ **Objetivo.** Treinar $h_\phi$ para que $h_\phi(o) \approx -\eta(x)$, cancelando
116
+ o ruído de quantização. A perda é
117
+ $L_{\text{hyp}} = \ell(y_{\text{final}}, y^*)$ onde $y^*$ é o rótulo verdadeiro.
118
+
119
+ **Isolamento do sinal (stop_grad_hyp).** Para evitar que o gradiente de
120
+ $L_{\text{hyp}}$ contamine os parâmetros principais via $o$, a entrada $o$
121
+ de $h_\phi$ é destacada: $\delta = h_\phi(\text{sg}(o))$ onde $\text{sg}$ é
122
+ stop-gradient. Isso faz $\nabla_\theta L_{\text{hyp}}$ depender apenas dos
123
+ parâmetros compartilhados via $f_\theta$ (gerenciados pelo Lema 2).
124
+
125
+ **Ativação condicional.** A hipótese só é ativada quando $L_{\text{main}} > \tau$,
126
+ ou seja, quando a perda principal excede um limiar (indicando que a quantização
127
+ está prejudicando a predição). Caso contrário, $\delta = 0$ e o modelo usa
128
+ apenas $\hat{y}$.
129
+
130
+ **Implementação.** Em `model/hyp_t.py` e `quantization/quantized_linear.py`:
131
+ - `QuantizedLinear(nn.Linear)`: fake quant W8A8 no forward (STE backward)
132
+ - `HypT.forward(o, stop_grad=True)`: aplica `o.detach()` quando stop_grad
133
+ - No `UnifiedModel.forward`: se `use_hypothesis=True` e `loss_main > tau`,
134
+ calcula `y_final = y_hat + delta` e retorna ambos
135
+
136
+ ---
137
+
138
+ ## 5. Lema 4 — Auto-configuração e suavização
139
+
140
+ **Enunciado.** Seja $\mathcal{L}_{\text{val}}(T, \tau; \theta)$ a perda de
141
+ validação como função dos hiperparâmetros temperatura $T$ e limiar $\tau$.
142
+ O MetaConfigurator mantém $T = \exp(\log T)$ e $\tau = \exp(\log \tau)$
143
+ (garantindo positividade) e os otimiza por gradiente descendente em um
144
+ meta-objetivo:
145
+
146
+ $$\mathcal{L}_{\text{meta}}(T, \tau) = \mathcal{L}_{\text{val}}(T, \tau; \theta^*) + \lambda_s \cdot S(\theta^*)$$
147
+
148
+ onde $\theta^* = \theta - \eta \nabla_\theta \mathcal{L}_{\text{train}}(T, \tau; \theta)$
149
+ é o parâmetro após um passo de treino (diferenciação implícita), e
150
+ $S(\theta) = \|\nabla_\theta \mathcal{L}\|^2$ é uma **proxy de agudeza**
151
+ (sharpness) — aproximação de baixo custo para o maior autovalor da Hessiana.
152
+
153
+ **Propriedade (mínimos planos).** Minimizar $S(\theta)$ empurra o modelo
154
+ para regiões de baixa curvatura, onde o ruído de gradiente (devido a
155
+ mini-batches e quantização W8A8) produz atualizações menores em magnitude,
156
+ reduzindo variância e melhorando generalização (Keskar et al., 2017;
157
+ Foret et al., 2021 — SAM).
158
+
159
+ **Controle implícito do número de módulos ativos.** Como $T$ controla a
160
+ entropia de $\alpha$ (Lema 1), minimizar $\mathcal{L}_{\text{meta}}$ ajusta
161
+ $T$ para o regime onde apenas os módulos necessários estão ativos. Não há
162
+ necessidade de regularização explícita de cardinalidade (embora
163
+ $L_{\text{ent}}$ possa ser adicionada se desejado).
164
+
165
+ **Implementação.** Em `training/meta_configurator.py`:
166
+ - `log_temperature: nn.Parameter` — aprendível, $T = \exp(\log T)$
167
+ - `log_tau: nn.Parameter` — aprendível, $\tau = \exp(\log \tau)$
168
+ - `forward_with_meta(x_val, y_val)`:
169
+ 1. Forward com $T$ atual → $\mathcal{L}_{\text{val}}$
170
+ 2. `grads = autograd.grad(L_val, model.parameters(), create_graph=True)`
171
+ 3. `sharpness = sum((g**2).sum() for g in grads)`
172
+ 4. `meta_loss = L_val + lambda_s * sharpness`
173
+ 5. `meta_optim.zero_grad(); meta_loss.backward(); meta_optim.step()`
174
+ 6. Atualiza `model.tau = exp(log_tau).detach()`
175
+
176
+ ---
177
+
178
+ ## 6. Análise de estabilidade e convergência
179
+
180
+ ### 6.1 Estabilidade do gradiente combinado
181
+
182
+ Sob os Lemas 1–4, o gradiente efetivo em $\theta$ é
183
+
184
+ $$g_{\text{eff}} = \alpha_k(T) \cdot g_{\text{main}} + \mathbb{1}[L_{\text{main}} > \tau] \cdot g_{\text{hyp}}^\perp$$
185
+
186
+ Sob **assumir** (i) gradientes com norma limitada $\|g\| \leq G$, (ii)
187
+ $\alpha_k \in [0,1]$ com $\sum \alpha_k = 1$, (iii) projeção ortogonal
188
+ preserva norma $\|g_{\text{hyp}}^\perp\| \leq \|g_{\text{hyp}}\|$, então
189
+ $\|g_{\text{eff}}\| \leq G + G = 2G$. Logo, com clipping em $5.0$ (como no
190
+ script original), o gradiente é estável.
191
+
192
+ ### 6.2 Convergência do meta-aprendizado
193
+
194
+ O MetaConfigurator usa Adam com $\eta_{\text{meta}} = 0.01$ em
195
+ $(\log T, \log \tau)$. Como a meta-perda é diferenciável em $(\log T, \log \tau)$
196
+ via `create_graph=True`, Adam converge para um mínimo local sob condições
197
+ padrão (Kingma & Ba, 2015). A proxy de agudeza $S(\theta)$ é não-negativa e
198
+ diferenciável, garantindo que o meta-objetivo é coercivo.
199
+
200
+ ### 6.3 Não-divergência do modelo principal
201
+
202
+ Mesmo se $h_\phi$ divergir, $y_{\text{final}} = \hat{y} + \delta$ é limitado
203
+ pelo fato de que $L_{\text{hyp}}$ penaliza $\delta$ quando $y_{\text{final}}$
204
+ se afasta de $y^*$. Adicionalmente, o stop-gradient isola $\delta$ do caminho
205
+ principal, então $\hat{y}$ permanece estável.
206
+
207
+ ---
208
+
209
+ ## 7. Mapeamento de reaproveitamento (source → BiGRU_T_version)
210
+
211
+ | Componente | Source path | Target path | Reuso |
212
+ |---|---|---|---|
213
+ | BBPE Tokenizer | `flexnet/bbpe_tokenizer.py` | `src/bigru_t/tokenizer/bbpe_tokenizer.py` | Cópia fiel |
214
+ | 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) |
215
+ | W8A8 QOperator | `flexnet/w8a8_qoperator.py` | `src/bigru_t/quantization/w8a8_qoperator.py` | Cópia + wrapper `QuantizedLinear` do Lema 3 |
216
+ | 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) |
217
+ | Xeon runtime | `flexnet/xeon_runtime.py` | `src/bigru_t/utils/xeon_runtime.py` | Cópia fiel |
218
+ | OOM guard | `flexnet/oom_guard.py` | `src/bigru_t/utils/oom_guard.py` | Cópia fiel |
219
+ | Memory monitor | `flexnet/memory_monitor.py` | `src/bigru_t/utils/memory_monitor.py` | Cópia fiel |
220
+ | Tensor ops | `xavante/utils/tensor_ops.py` | `src/bigru_t/utils/tensor_ops.py` | Cópia fiel |
221
+ | Validators | `xavante/utils/validators.py` | `src/bigru_t/utils/validators.py` | Cópia fiel |
222
+ | Logging utils | `xavante/utils/logging_utils.py` | `src/bigru_t/utils/logging_utils.py` | Cópia fiel |
223
+ | Hamiltonian-Wasserstein optimizer | `flexnet/hamiltonian_wasserstein_optimizer.py` | `src/bigru_t/optim/hamiltonian_wasserstein.py` | Cópia (opcional em treino) |
224
+ | Multimodal: text encoder | `xavante/multimodal/text_encoder.py` | `src/bigru_t/multimodal/text_encoder.py` | Cópia fiel |
225
+ | Multimodal: image encoder | `xavante/multimodal/image_encoder.py` | `src/bigru_t/multimodal/image_encoder.py` | Cópia fiel |
226
+ | Multimodal: audio encoder | `xavante/multimodal/audio_encoder.py` | `src/bigru_t/multimodal/audio_encoder.py` | Cópia fiel |
227
+ | Multimodal: video encoder | `xavante/multimodal/video_encoder.py` | `src/bigru_t/multimodal/video_encoder.py` | Cópia fiel |
228
+ | Multimodal: modal router | `xavante/multimodal/modal_router.py` | `src/bigru_t/multimodal/modal_router.py` | Cópia fiel |
229
+
230
+ **Descartados (superseded)**:
231
+ - `flexnet/train_v13_9_minimal.py` — superseded by `flexnet/train_v13_9.py`
232
+ - `xavante/enhanced/enhanced_xavante_v1.py`, `v2.py` — superseded by `v3.py`
233
+ - `xavante/training/medusa_trainer.py` — superseded by `medusa_trainer_bpe.py`
234
+ - `flexnet/hf_dataset_streamer.py` — superseded by `streaming_datasets_v13_9.py`
235
+
236
+ ---
237
+
238
+ ## 8. Diferenças do treino (bug-detection run)
239
+
240
+ | Parâmetro | v13.9.2 original | BiGRU_T_version (bug-detection) |
241
+ |---|---|---|
242
+ | Epochs | 1 (effective, via max_steps) | **2** (fixo por especificação) |
243
+ | Datasets | 9 base + 3 PT-BR | mesmos |
244
+ | Max samples por dataset | 200-500 | 50 (bug-detection, reduzido) |
245
+ | Max optimizer steps | 40-200 | 30 (2 épocas × ~15 steps/época) |
246
+ | Grad accum | 16 | 8 |
247
+ | LR | 1e-5 a 2e-5 | 1e-3 (treino from-scratch, não fine-tune) |
248
+ | Monitor | loss, ppl, conf | loss, ppl, **RAM, disk, módulos ativos** |
249
+ | Kill-switch | punishment gate | **loss não diminui em N steps OU RAM > 90%** |
250
+
251
+ ---
252
+
253
+ ## 9. Conclusão
254
+
255
+ A refatoração BiGRU_T_version formaliza os mecanismos heurísticos do v13.9.2
256
+ em 4 lemas matemáticos verificáveis, mantendo a multimodalidade e o stack de
257
+ otimização original. O treino de bug-detection (2 épocas) valida o pipeline
258
+ end-to-end sem pretender produzir um modelo competitivo — o objetivo é
259
+ detectar erros de implementação nos 4 lemas e nos módulos reaproveitados.