Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.
finetune: make training seed explicit (#108)
Semyon Pokladcd2eae34b96e
diff --git a/doc/finetuning.md b/doc/finetuning.mdindex 1a67b5a..1085cef 100644--- a/doc/finetuning.md+++ b/doc/finetuning.md@@ -44,7 +44,7 @@ adapter; `needle build` rejects a conflicting bit-width override. UseTo share a tuned model, set `NEEDLE_HF_REPO=<you>/<model>` and pass `--upload` to `needle build`; on any other machine `needle download <you>/<model>/tuned.cact` pulls it back down (or pass just `<you>/<model>` when the repo holds a single archive).-Defaults: batch size 16, learning rate 0.0001 with warmup and cosine decay, gradient clipping at norm 1, rank 16, alpha 32, max length 1024, validation split 0.1. The base checkpoint downloads from Hugging Face on first run.+Defaults: batch size 16, learning rate 0.0001 with warmup and cosine decay, gradient clipping at norm 1, rank 16, alpha 32, max length 1024, validation split 0.1, random seed 0. Use `--seed` to reproduce or intentionally vary LoRA initialization, validation selection, and epoch shuffling. The base checkpoint downloads from Hugging Face on first run.To grow a small hand written set, seed the generator with it (needs `OPENROUTER_API_KEY`; set `OPENROUTER_URL` to use another OpenAI compatible gateway):diff --git a/needle/cli.py b/needle/cli.pyindex 192c383..15dd39b 100644--- a/needle/cli.py+++ b/needle/cli.py@@ -140,6 +140,8 @@ def main():p.add_argument("--max-len", type=int, default=1024, help="Max training sequence length")p.add_argument("--val-split", type=float, default=0.1,help="Fraction of examples held out for validation (0 disables)")+ p.add_argument("--seed", type=int, default=0,+ help="Random seed for LoRA init, validation split, and epoch shuffling")p.add_argument("--generate", type=int, default=0,help="Generate N extra examples via OpenRouter before training (0 = off)")p.add_argument("--model", type=str, default="deepseek/deepseek-v4-flash",diff --git a/needle/model/finetune.py b/needle/model/finetune.pyindex 08e63f6..2f7ec37 100644--- a/needle/model/finetune.py+++ b/needle/model/finetune.py@@ -21,6 +21,12 @@ from .tokenizer import ()LORA_TARGETS = ("q_proj", "k_proj", "v_proj", "gate_proj", "out_proj")+++def _training_rng(seed):+ return np.random.default_rng(int(seed))++DEFAULT_BASE = "checkpoints/needle2.pkl"OPENROUTER_URL = os.environ.get(@@ -354,12 +360,14 @@ def finetune_local(args, progress=None):emit(f" {'numerics':<9} full precision")paths = lora_target_paths(params)scale = args.lora_alpha / args.lora_rank- lora = init_lora(params, paths, args.lora_rank, jax.random.PRNGKey(0))+ seed = int(getattr(args, "seed", 0))+ rng = _training_rng(seed)+ lora = init_lora(params, paths, args.lora_rank, jax.random.PRNGKey(seed))emit(f" {'lora':<9} rank {args.lora_rank} alpha {args.lora_alpha:g} {len(paths)} weight groups")n_val = min(int(len(seqs) * getattr(args, "val_split", 0.1)), len(seqs) - 1)if n_val > 0:- order = np.random.default_rng(0).permutation(len(seqs))+ order = rng.permutation(len(seqs))seqs, masks = seqs[order], masks[order]val_seqs, val_masks = seqs[:n_val], masks[:n_val]seqs, masks = seqs[n_val:], masks[n_val:]@@ -399,7 +407,7 @@ def finetune_local(args, progress=None):every = max(1, total_steps // 50)step_i = 0for epoch in range(args.epochs):- order = np.random.permutation(count)+ order = rng.permutation(count)last = 0.0for start in range(0, count, batch):idx = order[start:start + batch]@@ -428,6 +436,7 @@ def finetune_local(args, progress=None):"rank": args.lora_rank,"qat_bits": qat_bits,"qat_bits_map": qat_bits_map,+ "seed": seed,}, handle)print(f" {'adapter':<9} {out}")print(f" {'next':<9} needle build {base_path} --lora {out}")diff --git a/tests/test_finetune.py b/tests/test_finetune.pyindex 9d7a95b..3392b8f 100644--- a/tests/test_finetune.py+++ b/tests/test_finetune.py@@ -114,3 +114,42 @@ def test_auto_qat_preserves_checkpoint_mixed_bit_map(tiny_checkpoint, tmp_path):lora=str(adapter_path),out=str(tmp_path / "wrong.cact"),upload=False, bits="4"))+++def test_finetune_rng_is_controlled_by_seed():+ from needle.model.finetune import _training_rng++ a = _training_rng(17)+ b = _training_rng(17)+ c = _training_rng(18)+ a_orders = [a.permutation(12).tolist() for _ in range(3)]+ b_orders = [b.permutation(12).tolist() for _ in range(3)]+ c_orders = [c.permutation(12).tolist() for _ in range(3)]+ assert a_orders == b_orders+ assert a_orders != c_orders+++def test_finetune_adapter_records_realized_seed(tiny_checkpoint, tmp_path):+ from needle.model.finetune import finetune_local++ data = tmp_path / "data.jsonl"+ rows = []+ for i in range(4):+ rows.append({+ "tools": TOOLS,+ "query": f"email user{i}@example.com about item {i}",+ "answers": [{"name": "send_email", "arguments": {"to": f"user{i}@example.com", "subject": f"item {i}"}}],+ })+ with data.open("w") as handle:+ for row in rows:+ handle.write(json.dumps(row) + "\n")++ out = tmp_path / "seeded-adapter.pkl"+ args = _finetune_args(data, tiny_checkpoint, out, tmp_path / "ck", qat_bits="none")+ args.seed = 17+ args.val_split = 0.0+ finetune_local(args)++ with out.open("rb") as handle:+ adapter = pickle.load(handle)+ assert adapter["seed"] == 17