| --- |
| license: mit |
| library_name: peft |
| base_model: |
| - Qwen/Qwen3.5-0.8B |
| - Qwen/Qwen3.5-2B |
| - Qwen/Qwen3.5-9B |
| tags: |
| - networking |
| - linux |
| - world-model |
| - lora |
| --- |
| |
| # NetOracle: LoRA adapters |
|
|
| LoRA adapters for **NetOracle**, a world model for the Linux kernel network |
| stack, from the HotNets '26 paper *Toward a World Model for the Linux Kernel |
| Network Stack* (Luyao Bai and Xiaoguang Wang, University of Illinois Chicago). |
|
|
| Given one measurement of the configuration a host is running and a change to |
| one knob (congestion control, queueing discipline, or socket buffer preset), |
| the model predicts whether a performance metric goes up, goes down, or stays |
| the same, and by roughly how much. It does this without running the new |
| configuration. |
|
|
| Code, testbed, corpora, and the StackBench benchmark: |
| https://github.com/sysec-uic/NetOracle |
|
|
| ## Files |
|
|
| | Folder | Base model | Seeds | Size each | |
| |---|---|---|---| |
| | `netoracle-0.8b/seed{41,42,43}` | `Qwen/Qwen3.5-0.8B` | 3 | 68 MB | |
| | `netoracle-2b/seed{41,42,43}` | `Qwen/Qwen3.5-2B` | 3 | 103 MB | |
| | `netoracle-9b/seed41` | `Qwen/Qwen3.5-9B` | 1 | 242 MB | |
|
|
| The 0.8B adapters are the model the paper calls NetOracle. The 2B and 9B |
| adapters are the scale study in Table 1 of the paper. Each folder holds a |
| PEFT adapter (`adapter_config.json`, `adapter_model.safetensors`) and the |
| tokenizer files used in training. |
|
|
| ## Training |
|
|
| - LoRA rank 32, alpha 64, on all attention and MLP projections |
| (12.8M trainable parameters for the 0.8B model). |
| - Data: `dataset/ft-all` in the GitHub repository, 726 leakage-filtered |
| measured cells from the testbed, about 3,800 examples of two kinds: |
| quantitative (predict one metric of one cell) and counterfactual (two |
| cells that differ in exactly one knob, one given as the measured anchor). |
| - Targets are strict JSON: `{"direction": "increase|decrease|same", "ratio": <float>}` |
| for counterfactual questions. A change within plus or minus 10% counts as |
| `same`. |
| - About 20 minutes per 0.8B run on one consumer GPU |
| (`scripts/train_lora.py --data dataset/ft-all`). |
|
|
| ## Results |
|
|
| On the 218 StackBench tasks whose targets are absent from training, averaged |
| over seeds (Table 1 of the paper): |
|
|
| | Model | Direction, all | Direction, off-grid | Median APE | Within 2x, off-grid | |
| |---|---|---|---|---| |
| | NetOracle 0.8B | 0.78 | 0.84 | 0.10 | 0.88 | |
| | NetOracle 2B | 0.81 | 0.79 | 0.03 | 0.91 | |
| | NetOracle 9B | 0.82 | 0.68 | 0.03 | 0.86 | |
| | kNN / GBT / random forest, same data | 0.70 / 0.72 / 0.78 | 0.32 / 0.63 / 0.47 | | | |
|
|
| Off-grid means conditions far outside the training grid (160 ms RTT or |
| 400 Mbit/s). Scores are computed with `scripts/eval_stats.py` in the GitHub |
| repository. |
|
|
| ## Usage |
|
|
| ```python |
| import torch |
| from transformers import AutoModelForCausalLM, AutoTokenizer |
| from peft import PeftModel |
| from huggingface_hub import snapshot_download |
| |
| repo = snapshot_download("Haku247/NetOracle", allow_patterns=["netoracle-0.8b/seed41/*"]) |
| adapter = f"{repo}/netoracle-0.8b/seed41" |
| |
| tok = AutoTokenizer.from_pretrained(adapter) |
| base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.5-0.8B", torch_dtype=torch.bfloat16, device_map="auto") |
| model = PeftModel.from_pretrained(base, adapter).eval() |
| |
| prompt = "..." # a StackBench-style prompt: testbed description, the measured anchor, the knob change |
| msgs = [{"role": "user", "content": prompt}] |
| ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(model.device) |
| out = model.generate(ids, max_new_tokens=96, do_sample=False) |
| print(tok.decode(out[0, ids.shape[1]:], skip_special_tokens=True)) |
| ``` |
|
|
| The prompts the paper evaluates on are produced by `scripts/ft_eval_io.py export` |
| in the GitHub repository, and `scripts/batch_generate.py` runs them in batch: |
|
|
| ```bash |
| python3 scripts/batch_generate.py --model Qwen/Qwen3.5-0.8B \ |
| --adapter <path>/netoracle-0.8b/seed41 \ |
| --prompts dataset/ft/eval_prompts.jsonl --out gen.jsonl |
| ``` |
|
|
| The gated policy in the paper samples 5 answers at temperature 0.8 and changes |
| a knob only if at least 4 agree on a gain of at least 15%. |
|
|
| ## Limitations |
|
|
| - Trained only on an emulated testbed (network namespaces, HTB bottleneck, |
| netem delay and loss) on one kernel version. |
| - On real paths whose bottleneck the host cannot observe (the Pantheon |
| archive), the emulation-only model barely beats always predicting no change. |
| Training on measurements from other real paths raises direction accuracy to |
| 0.68; those replay models are not part of this release. |
| - One short measurement cannot predict tail latency dominated by |
| retransmission timeouts. |
|
|
| ## License |
|
|
| The adapters are released under the MIT license. Use of the base models is |
| governed by their own licenses. |
|
|
| ## Citation |
|
|
| ```bibtex |
| @inproceedings{netoracle2026, |
| author = {Luyao Bai and Xiaoguang Wang}, |
| title = {Toward a World Model for the Linux Kernel Network Stack}, |
| booktitle = {Proceedings of the 25th ACM Workshop on Hot Topics in Networks (HotNets '26)}, |
| year = {2026}, |
| address = {Salt Lake City, UT, USA}, |
| publisher = {ACM}, |
| doi = {10.1145/3847290.3859973} |
| } |
| ``` |
|
|
