Upload distill/README.md with huggingface_hub

distill/README.md

@@ -0,0 +1,103 @@
+# Kimi-K3-Linear-48B-A3B — chaîne de distillation
+
+Le modèle n'existe pas : il s'agit de le **construire**, en distillant
+Kimi-K3 dans le socle `Kimi-Linear-48B-A3B-Instruct`. C'est la recette déjà
+validée dans `Kimi-K3-L4-GenAI-TurboQuant` (Qwen3.5-9B + LoRA dérivée de K3,
+32,3 tok/s et 91 % d'acceptation MTP sur L4), appliquée cette fois à un socle
+qui partage l'architecture `KimiLinearForCausalLM` de K3.
+
+```
+generate.py   collecte les reponses de K3 via l'endpoint officiel, budget plafonne
+train_lora.py QLoRA NF4 sur le socle bf16, reprise apres interruption
+              service : vllm serve <socle> --enable-lora --lora-modules k3linear=<out>
+```
+
+## Ce que la chaîne peut et ne peut pas faire
+
+**Distillation au niveau séquence uniquement.** L'API de K3 ne rend pas les
+logits : le socle apprend à imiter les *sorties*, pas les distributions. C'est
+moins efficace en tokens qu'une KD sur logits, mais c'est la seule voie sans
+poids K3 locaux — et K3 complet fait 1 499 Gio au minimum, soit une vingtaine
+de cartes.
+
+**Le mur matériel, chiffré :**
+
+```
+socle bf16 pour du QLoRA        91,5 Gio     (l'AWQ 4 bits est inference seule)
+disque d'un pod standard        100 Go       -> ne tient pas avec l'environnement
+poids NF4 en VRAM               ~26 Go       -> tient sur une A40 de 46 Go
+debit d'entrainement, 1x A40    quelques centaines de tokens/s
+LoRA qui change le comportement quelques millions de tokens
+```
+
+Autrement dit : **une distillation utile ne rentre pas dans 8 $ sur une seule
+A40.** La chaîne est écrite pour reprendre après interruption précisément parce
+que l'entraînement s'étalera sur plusieurs sessions, avec un disque plus grand.
+
+## Les données
+
+Les prompts ciblent les écarts *mesurés* entre le socle et K3, pas des tâches
+génériques :
+
+- **français technique** — le socle traduit « gate » par « gâteau » ; K3 non
+- **usage d'outils** — traces agentiques, l'essentiel pour Claude Code
+- **édition de code** — le régime réel d'un agent
+- **raisonnement quantitatif** — où la trace de K3 porte sa méthode
+
+`generate.py` conserve `reasoning_content` séparément : l'entraîner ou non est
+une décision à prendre en aval (`--keep-reasoning`), pas figée à la collecte.
+
+## Incertitudes à lever avant de lancer le calcul
+
+1. **vLLM sert-il un LoRA sur `KimiLinearForCausalLM` ?** Non vérifié. Si non,
+   il faudra fusionner le LoRA dans le socle puis requantifier.
+2. **Les noms de modules cibles** sont déduits de la géométrie MLA (`q_a_proj`,
+   `kv_b_proj`…) ; le script les filtre sur ceux réellement présents et échoue
+   avec la liste des modules disponibles plutôt que de deviner.
+3. **Le tokenizer corrigé** (`patdev/kimi-linear-tokenizer-fix`) est requis :
+   l'original casse sur transformers ≥ 5.5.3.
+
+## Économie réelle, mesurée
+
+La chaîne a été exécutée de bout en bout sur l'endpoint officiel :
+
+```
+2 exemples collectes            0,085 $
+extrapolation                  42 a 51 $ pour 1000 exemples
+```
+
+K3 est un modèle à raisonnement : il dépense **1200 à 2000 tokens de réflexion**
+avant chaque réponse, tous facturés à 15 $/1M. C'est ce qui domine le coût, pas
+la réponse elle-même.
+
+```
+budget disponible        8 $      ->  ~150 exemples
+LoRA changeant le comportement    ->  plusieurs milliers d'exemples
+collecte d'un jeu utile           ->  250 a 1000 $, avant tout entrainement
+```
+
+**Conclusion honnête : la collecte est le mur, pas le calcul.** Puisqu'on paie
+le raisonnement, autant l'entraîner (`--keep-reasoning`) plutôt que de le jeter.
+
+## Trois pièges de l'API, tous rencontrés
+
+1. **`runsync` rend un identifiant de tâche** quand la génération dépasse son
+   attente interne. Ne pas le suivre donne une réponse sans `output` : vide,
+   sans coût, et sans erreur visible — un symptôme qui ressemble à tort à un
+   problème de modèle.
+2. **`temperature` doit valoir 1.** Toute autre valeur échoue avec
+   `invalid temperature: only 1 is allowed for this model`, et l'erreur reste
+   invisible tant que la tâche n'est pas suivie.
+3. **Cloudflare rejette la signature d'urllib** avec un 403 `error code: 1010`.
+   Un `User-Agent` explicite suffit.
+
+## Ce que la collecte vise, démontré
+
+```
+K3           "Le mecanisme d'aiguillage (ou routeur) est un petit reseau auxiliaire..."
+Kimi-Linear  "...combines via un 'gateau' (un reseau de selection)"
+```
+
+Les outils sont passés dans le champ `tools` de la requête, pas décrits en
+prose : sollicité en prose, K3 répond à juste titre qu'aucun outil ne lui est
+fourni, et l'exemple est inutilisable.