node-ia-modeler
v0.15.0
Published
Toolkit d'IA frugale en JavaScript/TypeScript : définir, entraîner, compresser, adapter, exporter, servir.
Maintainers
Readme
node-ia-modeler
Le toolkit d'IA frugale en JavaScript / TypeScript : définir, entraîner, compresser, adapter, exporter et servir de petits modèles efficaces — sans Python, sans binaire à compiler, sans dépendance.
import { Adam, Tensor, mse, tensor, tidy } from 'node-ia-modeler';| | |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Calcul | Tenseurs + autograd (f32/f64), couches modernes (RoPE, GQA, RMSNorm, SwiGLU, KV-cache) |
| Frugalité | Quantization int8 / int4 (≈ 4× / 7× plus petit), LoRA / QLoRA, distillation |
| Vitesse | Noyaux WebAssembly SIMD (matmul, convolution, int8/int4), worker threads — 40 à 80 GFLOPS (CPU) |
| GPU | Backend WebGPU optionnel (npm i webgpu), mémoire unifiée/dédiée, repli CPU automatique |
| Interop | safetensors, GGUF (lecture K-quants, écriture F32/F16/Q8_0/Q4_0, adaptateurs LoRA), tokenizer BPE, Llama/Qwen2/Qwen3, ONNX |
| Vision | Convolutions, détecteur dense, U-Net + DDIM, YOLOv8 ONNX validé contre ONNX Runtime |
| Agent | Petit modèle + outils à décodage contraint (llama.cpp), lecture seule par défaut |
| Sûreté | Aucun pickle, parseurs défensifs fuzzés, réseau uniquement à l'appel (hub), zéro dépendance runtime |
| API typée | ESM + .d.ts : s'utilise pareil en JavaScript et en TypeScript |
Installation
npm install node-ia-modeler # Node.js ≥ 22
npm install webgpu # facultatif : active le backend GPU (voir plus bas)Aucun Python n'est nécessaire, ni pour l'installation ni pour l'utilisation.
Votre premier modèle en 5 minutes
Un perceptron multicouche qui apprend le XOR (xor.mjs) :
import { Adam, Tensor, manualSeed, mse, tensor, tidy } from 'node-ia-modeler';
manualSeed(3);
const x = tensor([
[0, 0],
[0, 1],
[1, 0],
[1, 1],
]);
const y = tensor([[0], [1], [1], [0]]);
// Paramètres : des tenseurs qui « requièrent un gradient ».
const w1 = Tensor.randn([2, 8], { requiresGrad: true });
const b1 = Tensor.zeros([8], { requiresGrad: true });
const w2 = Tensor.randn([8, 1], { requiresGrad: true });
const b2 = Tensor.zeros([1], { requiresGrad: true });
const opt = new Adam([w1, b1, w2, b2], { lr: 0.05 });
const forward = () => x.matmul(w1).add(b1).tanh().matmul(w2).add(b2).sigmoid();
for (let step = 1; step <= 500; step++) {
const loss = tidy(() => mse(forward(), y)); // `tidy` libère les intermédiaires
loss.backward(); // rétropropagation
opt.step();
opt.zeroGrad();
if (step % 100 === 0) console.log(`pas ${step} loss ${loss.item().toFixed(5)}`);
loss.dispose();
}
console.log(
tidy(() =>
forward()
.toArray()
.map((v) => v.toFixed(2)),
).join(' '),
); // 0.01 0.99 0.99 0.01node xor.mjsEn TypeScript, le code est identique : les types viennent du paquet (voir examples/xor.ts).
Mémoire. Les tenseurs se libèrent avec
dispose()ou en les créant dans untidy(() => …)(tout ce qui est créé dedans est libéré, sauf la valeur retournée). Voir le guide.
Un mini-transformer qui écrit du texte
import { LMDataset, generate, model, tokenizer, train } from 'node-ia-modeler';
const corpus = 'abracadabra '.repeat(200);
const tok = tokenizer.charLevel(corpus);
const m = model.gpt({ vocab: tok.vocabSize, dim: 64, heads: 4, depth: 2, maxSeq: 128 });
const data = new LMDataset(tok.encode(corpus), { blockSize: 32 });
// Entraînement dans un worker thread : la boucle d'événements reste libre.
const run = train(m, data, {
epochs: 5,
batchSize: 16,
stepsPerEpoch: 30,
optimizer: { type: 'adamw', lr: 3e-3, weightDecay: 0.1 },
schedule: { type: 'cosine', warmup: 10 },
clipGradNorm: 1,
keepBest: true, // rend le modèle de meilleure validation (earlyStopping, evalEvery : docs/training.md)
});
run.on('epoch', ({ epoch, trainLoss, valLoss }) => console.log(epoch, trainLoss, valLoss));
await run.done;
const ids = generate(m, [...tok.encode('abra')], { maxNewTokens: 40, temperature: 0.8, topK: 5 });
console.log(tok.decode(ids));Sans tokenizer : H-Net (découpage dynamique)
model.hnet lit des octets bruts et apprend lui-même où couper ses « tokens » (H-Net, Hwang, Wang et Gu, 2025) : un petit encodeur, un routeur qui place une frontière quand deux octets voisins deviennent
dissemblables, un grand réseau sur les blocs, puis un petit décodeur. Aucun vocabulaire à entraîner, toute
langue et tout octet acceptés.
const bytes = tokenizer.bytes();
const m = model.hnet({
dim: 64,
innerDim: 96,
heads: 4,
mainDepth: 3,
maxSeq: 128,
targetRatio: 4,
});
await train(m, new LMDataset(bytes.encode(corpus), { blockSize: 128 }), options).done;
console.log(m.lastChunking.ratio); // octets par bloc apprisLimites : une seule étape de hiérarchie, encodeur/décodeur en transformeurs (l'article utilise Mamba-2), backends CPU seulement, génération sans cache KV (contexte recalculé à chaque pas). Mesure et décision : ADR-24.
Composer de nouveaux modèles à partir d'autres
import { agent, compose, io, tools } from 'node-ia-modeler';
const merged = await compose.merge([codeModel, chatModel], { method: 'ties', base, density: 0.5 });
const deeper = await compose.layers(merged, [0, 1, 2, 3, 2, 3, 4, 5]); // blocs dupliqués
compose.freeze(deeper, /^0\./); // embeddings gelés pour le réentraînement
const a = agent.create({
model: agent.local({ model: deeper, tokenizer }),
tools: [tools.calculator()],
});
await io.exportGGUF(deeper, 'nouveau.gguf', { type: 'Q8_0', tokenizer }); // llama, qwen2, qwen3Fusion linear / slerp / task / ties / dare, en mémoire ou en flux sur les fichiers pour les
gros modèles (compose.mergeFiles, dépôts Hugging Face en plusieurs morceaux : 612 Mio de pic au lieu de
2,9 Go mesurés sur 110 M de paramètres). Assemblage de couches, vocabulaire, gel et édition des
paramètres ; agent piloté par votre propre modèle, sans serveur ; CLI merge, layers, export.
Guide : docs/compose.md.
Compresser, adapter, exporter
import { io, lora, model, modelBytes, quantize } from 'node-ia-modeler';
// 1. Quantifier : int8 par canal (≈ 4× plus petit) ou int4 par groupes de 32 (≈ 6–7×).
const light = quantize(m, { bits: 4, groupSize: 32 });
console.log(modelBytes(m), '->', modelBytes(light));
// 2. Adapter sans réentraîner : LoRA (≤ 2 % des paramètres), éventuellement sur une base quantifiée.
const summary = lora.apply(m, { rank: 4, alpha: 8, targets: ['wq', 'wv'] });
console.log(`${(summary.ratio * 100).toFixed(2)} % entraînables`);
// … entraînement … puis : lora.merge(m) (ou lora.adapterState(m) pour ne sauver que A et B)
// 3. Sauvegarder / recharger (safetensors, architecture incluse) et exporter en ONNX.
await io.save(light, 'model.safetensors');
const back = await io.load('model.safetensors');
await io.exportOnnx(m, 'model.onnx', { batch: 1, seqLen: 16 });Charger un modèle ouvert (Llama, SmolLM, TinyLlama…)
import { generate, io } from 'node-ia-modeler';
// Dossier Hugging Face (config.json + model.safetensors + tokenizer.json) ou fichier .gguf
const { model, tokenizer } = await io.loadLlama({ dir: './SmolLM2-135M' });
const ids = generate(model, [...tokenizer.encode('The capital of France is')], {
maxNewTokens: 24,
temperature: 0,
});
console.log(tokenizer.decode(ids));Hugging Face Hub : rechercher, vérifier, charger
import { hub, OPEN_LICENSES } from 'node-ia-modeler';
const [best] = await hub.search({
query: 'smollm',
task: 'text-generation',
license: 'apache-2.0',
});
const head = await hub.inspect(best.id, 'model.safetensors'); // en-tête seul (Range), sans télécharger
const { model, tokenizer, snapshot } = await hub.loadLlama(best.id, { licenses: OPEN_LICENSES });Dépôts publics uniquement, licence visible et imposable, fichiers vérifiés (SHA-256), cache par commit sans réseau, reprise sur coupure : docs/hub.md.
En ligne de commande
npx node-ia-modeler inspect model.safetensors
npx node-ia-modeler convert ./SmolLM2-135M model.safetensors
npx node-ia-modeler quantize model.safetensors model-int8.safetensors --bits 8
npx node-ia-modeler generate model-int8.safetensors --tokenizer ./SmolLM2-135M/tokenizer.json --prompt "Hello"
npx node-ia-modeler hub download HuggingFaceTB/SmolLM2-135M --include "*.json,*.safetensors" --license openRAG : interroger vos documents
import { io, rag } from 'node-ia-modeler';
const { model } = await io.loadLlama({ dir: 'Qwen3-Embedding-0.6B' });
const tokenizer = await io.loadTokenizer('Qwen3-Embedding-0.6B/tokenizer.json');
const embedder = rag.embedder({ model, tokenizer, suffix: '<|endoftext|>' });
const base = rag.retriever({ embedder });
await base.add([
{ id: 'guide', text: guide },
{ id: 'faq', text: faq },
]);
const hits = await base.search('Comment reprendre un entraînement ?'); // BM25 + vecteurs
const { answer, sources } = await rag.answer({ retriever: base, model: chat, question: '…' });Embeddings identiques à ceux publiés pour Qwen3-Embedding, base sauvegardable, outil d'agent
search_docs : docs/rag.md.
Détecteurs d'objets et génération d'images
Les mêmes tenseurs, le même autograd et les mêmes noyaux WebAssembly servent aux convolutions : un
détecteur et un générateur d'images s'entraînent et s'exécutent sans dépendance. Les images se lisent
depuis vos dossiers (PNG), et un modèle d'images se « gonfle » en modèle vidéo (attention
temporelle, diffusion.inflate, clips enregistrés en APNG) : docs/images.md.
import { Rng, diffusion, fit, vision } from 'node-ia-modeler';
// Détecteur dense sans ancres (18 K paramètres, ≈ 3 s d'entraînement sur des scènes synthétiques).
const net = vision.createDetector({ classes: 3, widths: [8, 16, 32] });
fit(net, { steps: 150, batch, loss: (m, b) => vision.detectionLoss(m.forward(b.x), targets(b)) });
const fast = vision.fuseConvBatchNorm(net.eval()); // BatchNorm absorbée pour l'inférence
const detections = vision.decodeDetections(fast.forward(images), { scoreThreshold: 0.4 });
// Diffusion : U-Net conditionné par classe, DDIM en 20 pas, guidage sans classifieur.
const schedule = diffusion.noiseSchedule({ steps: 200, kind: 'cosine' });
const unet = new diffusion.UNet({
inChannels: 1,
baseChannels: 16,
channelMults: [1, 2],
numClasses: 2,
});
// … fit(unet, { loss: (m, b) => diffusion.diffusionLoss(m, b.x, { schedule, rng, labels }) }) …
const pics = diffusion.sample(unet, {
shape: [4, 1, 8, 8],
schedule,
steps: 20,
labels: [0, 0, 1, 1],
guidanceScale: 2,
});Détecteurs publics : await io.loadOnnx('yolov8n.onnx') exécute un réseau ONNX (inférence, ≈ 50
opérateurs de vision, aucune dépendance) avec vision.letterbox / decodeYolo. Validé sur le vrai
YOLOv8n contre ONNX Runtime (écart ≈ 10⁻³ px, mêmes détections ; ≈ 0,4 – 1,1 s par image 640×640 sur CPU ici) —
voir la recette dans docs/recipes.md et ADR-20. Sur GPU
(setBackend('gpu')), le même YOLOv8n passe de ≈ 1,1 s à ≈ 0,15 – 0,2 s par image sur un iGPU Intel.
Exemples exécutables : node examples/detector.mjs, node examples/diffusion.mjs. net.quantize({ bits: 8 })
quantifie aussi les convolutions. Limites (pas de modèles publics importés, pas de VAE) : voir
ADR-14 et docs/rapport-phase-8.md.
Performances (indicatif)
Mesures sur un laptop Intel i7-1065G7 (4 cœurs / 8 threads), Node 24, matmul f32 1024² :
| Backend | GFLOPS |
| ------------------------------------ | ----------- |
| JS de référence (setBackend('js')) | ≈ 1 |
| JS optimisé, parallèle | 6 – 14 |
| WebAssembly SIMD, parallèle | 43 – 84 |
| numpy / OpenBLAS (AVX-512) | ≈ 340 |
Convolutions (bench/conv.mjs, inférence, mêmes réglages) : 3×3 32→32 sur 64×64 en ≈ 2 ms
(30 – 45 GFLOPS) contre ≈ 105 ms avec le backend JS ; depthwise 3×3 en 1,4 ms (30 ms avant noyau dédié) ;
mémoire de travail ÷ 7 (les patches ne sont jamais matérialisés).
LLM (bench/llm-decode.mjs, 52 M paramètres, cache KV) : décodage f32 ≈ 38 – 58 ms/token, int8 ≈ 18 – 26 ms/token
(×1,6 à ×3, poids ÷ 4), int4 ≈ 38 – 46 ms/token (poids ÷ 7 : il économise la RAM, pas le calcul). Le produit quantifié
utilise une activation int16 (erreur ≈ 10⁻⁴ relatif, voir ADR-13).
SmolLM2-135M (Llama, 163 M paramètres) : chargement en 3 s. Le backend se règle par
setBackend('auto' | 'js' | 'workers', { threads, wasm }).
GPU (optionnel)
import { getBackend, io, prepareBackend, setBackend } from 'node-ia-modeler';
setBackend('gpu'); // repli CPU automatique si aucun GPU / paquet `webgpu` absent
await prepareBackend();
const net = await io.loadOnnx('yolov8n.onnx');
const out = net.run({ images });
const data = await out.output0.toTypedArrayAsync(); // un résultat GPU se lit en asynchrone
await getBackend().synchronize?.(); // pour mesurer : attend la fin des calculsNoyaux WGSL (matmul par tuiles, convolution, depthwise, softmax, normalisations, réductions, pooling…), mémoire unifiée (iGPU, Apple Silicon) ou dédiée détectée, budget par appareil et repli CPU par tenseur. Le GPU est opt-in : sans lui, rien ne change. Limites : pas de NPU/TPU, un seul appareil, calcul f32 — détails dans docs/gpu.md et ADR-19.
Entraîner et pré-entraîner sur GPU
setBackend('gpu', { overBudget: 'throw' });
await prepareBackend();
const m = model.gpt({
vocab: 32000,
dim: 768,
heads: 12,
depth: 12,
maxSeq: 512,
checkpoint: true,
});
await runTraining(m, new ShardedDataset(['shard-0.bin', 'val.bin'], { blockSize: 512 }), {
epochs: 1,
batchSize: 4,
gradAccumSteps: 8,
optimizer: { type: 'adamw8bit', lr: 3e-4 },
clipGradNorm: 1,
checkpointPath: 'run.safetensors', // reprise exacte avec { resume: true }
});Rétropropagation, optimiseurs (AdamW, Adam 8 bits, Lion), écrêtage et saut de pas sur débordement
se font sur le GPU ; attention, entropie croisée, RoPE et SwiGLU sont fusionnés ; checkpoint et
gradAccumSteps bornent la mémoire d'activations ; stepInBackward: true met à jour chaque paramètre
dès que son gradient est complet et libère ce gradient (−4 o/paramètre, combiné à checkpoint) ;
halfWeights: true stocke les poids des couches linéaires en f16 (−2 o/paramètre, calcul en f32, arrondi
stochastique, qualité mesurée équivalente) ; poids initialisés directement sur le GPU ; corpus en flux (ShardedDataset) ; QLoRA, QAT et
élagage. Mesuré sur une RTX 4060 Laptop (8 Go) : 5 M de paramètres 304 → 56 000 tokens/s, 134 M à
≈ 5 000 tokens/s, 554 M de paramètres entraînés dans 8 Go. Guide, budgets et limites :
docs/training.md et ADR-21. Le modèle entraîné s'exporte en
GGUF (io.exportGGUF) pour llama.cpp, Ollama ou LM Studio ; un adaptateur LoRA entraîné sur un GGUF
Llama ou Qwen existant s'exporte seul (io.exportLoraGGUF) pour llama-server --lora. Qwen3.5 (GGUF
qwen35, hybride Gated DeltaNet + attention) se charge et s'affine sur ses poids GGUF d'origine, sans
requantification ni Python ; l'adaptateur exporté est reproduit à l'identique par llama.cpp
(docs/training.md).
Sécurité
Aucun format exécutable n'est chargé (pas de pickle .pt/.bin), les parseurs safetensors et GGUF
sont bornés et fuzzés, la bibliothèque n'effectue aucun accès réseau de son propre chef (seulement la boucle locale vers un
llama-server que vous démarrez, et le module hub que vous appelez : HTTPS, fichiers vérifiés) et n'a aucune dépendance runtime
(le paquet webgpu du backend GPU est facultatif, installé par vous). Détails dans docs/security.md.
Documentation
- Guide — concepts : tenseurs, autograd, mémoire, backends, modèles, entraînement
- Recettes — LoRA, quantization, modèles ouverts, ONNX, modules personnalisés
- Gros modèles : llama.cpp, GPU, mémoire dédiée/partagée
- Backend GPU WebGPU : activation, règles, diagnostic, mesures
- Entraîner et pré-entraîner sur GPU : mémoire, optimiseurs 8 bits, reprise, QLoRA
- Agent : petit modèle + outils, général et code
- Composer des modèles : fusion, couches, paramètres, agent local, GGUF
- RAG : recherche hybride, embeddings, réponses sourcées
- Modèles d'images et de vidéos : diffusion, clips, PNG / APNG
- Hugging Face Hub : recherche, licences, téléchargement vérifié, cache
- Référence de l'API
- Versions et publication
- Sécurité · Décisions d'architecture · Changelog
Ce que ce n'est pas
Pas de pré-entraînement de LLM généralistes de plusieurs milliards de paramètres, pas d'entraînement
distribué multi-GPU, pas de chargement de fichiers pickle. Le GPU est optionnel (voir plus haut) ;
pour les gros modèles, le module engines pilote llama.cpp (docs/engines.md).
Développement
npm install
npm run check # build + typecheck + lint + format + tests (deux backends)
npm run bench:backendsLicence MIT.
