Cortex BitNet Engine

Schnelle 1.58-bit (ternäre) LLM-Inference auf Consumer-GPUs — mit eigenen CUDA-Kerneln, ohne Microsoft-Code.

Unterstützt aktuell zwei QAT-native Ternary-Modelle auf einer RTX 3070 (8 GB):

Modell	TPS (Decode)	VRAM	Charakter
BitNet b1.58 2B4T (perrow)	~206–217	~2.6 GB	Speed-Demo, englisch stark
Falcon3-10B-Instruct-1.58bit	~68	~6–7 GB	der Alltags-Chat (DE/EN, Code)

Zum Vergleich: Microsofts bitnet.cpp erreicht auf derselben Karte ~132 TPS (2B) — diese Engine ist ~60 % schneller bei 3× weniger VRAM.

Hinweis: TPS schwankt mit Systemzustand (andere GPU-Prozesse, Clocks). Werte oben aus bench_our_v4.py / bench_falcon.py, RTX 3070, sm_86.

Features

• Eigene CUDA-Kernel: fused FFN, fused RMSNorm, fused RoPE+KV-Cache, int8-GEMV (lm_head)
• CUDA-Graphs (per-position) für Decode — kein Python-Overhead pro Token
• Modell-generisch: Architektur per Checkpoint-Sidecar (<ckpt>.json), Tokenizer austauschbar (Llama-3 tiktoken / HF-fast)
• OpenAI-kompatible API + Web-UI (server.py) und Terminal-Chat (chat.py)
• VRAM-Diät: Originalgewichte nach Kernel-Repack freigegeben (3.2 GB bei 10B)
• Windows-first (WDDM-getestet), Python 3.11, torch + xformers

Schnellstart (Deutsch)

Voraussetzung: NVIDIA-GPU (≥ 8 GB), Python 3.11, CUDA-fähiges torch.

git clone <dieses-repo> && cd bitnet-final
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt

Modelle in checkpoints/ legen (siehe unten), dann:

• start_falcon.bat — Server mit Falcon-10B (Web-UI + API auf localhost:8000)
• start_chat_falcon.bat — Terminal-Chat mit Falcon (deutsch)
• start_2b.bat — Server mit dem 2B-Modell (maximale TPS)

Manuell (Modellwahl per Env-Var):

set BITNET_CKPT=model_state_int2_falcon10b.pt
python server.py --port 8000

API: POST /v1/chat/completions und /v1/completions (OpenAI-kompatibel), GET /health, GET /v1/models. Web-UI auf /.

Modelle

Die Checkpoints sind nicht Teil des Repos (zu groß, siehe .gitignore).

BitNet b1.58 2B4T (Default)

checkpoints/model_state_int2_perrow.pt — Repack von microsoft/BitNet-b1.58-2B-4T (MIT). Das perrow-Format (Row-Scales + MS-Interleave) ist wertidentisch zum Original.

Falcon3-10B-Instruct-1.58bit

Reproduzierbar mit dem mitgelieferten Konverter:

python -c "from huggingface_hub import snapshot_download; snapshot_download('tiiuae/Falcon3-10B-Instruct-1.58bit', local_dir='hf_model')"
python tools/convert_falcon.py

Erzeugt checkpoints/model_state_int2_falcon10b.pt (+ Sidecar-JSON). Lizenz: TII Falcon License (nicht MIT!) — siehe NOTICE.md.

Repo-Layout

engine.py / model.py     Engine + Modell (fused Pfade, CUDA-Graphs)
chat.py / server.py      Interfaces (Terminal / OpenAI-API + Web-UI)
tokenizer.py             Llama-3 tiktoken (2B-Modell)
tokenizer_hf.py          HF-fast-Tokenizer-Wrapper (Falcon)
tokenizer.model          Llama-3 BPE
tokenizer_falcon.json    Falcon3 BPE
bitnet_kernels/          eigene CUDA-Kernel (.cu + .dll + Loader)
tools/                   convert_falcon.py, eval_falcon.py, pack_weight.py
checkpoints/             Modelle (.pt + .json Sidecars) — nicht im Git
bench_our_v4.py          TPS-Bench (Default-Checkpoint)
bench_falcon.py          TPS-Bench (Falcon)
start_*.bat              Doppelklick-Starter (Windows)

Bekannte Grenzen (ehrlich)

• Arithmetik/Toolcalls sind ternär-typisch unzuverlässig — auch beim 10B (mal richtig, mal falsch). Für Text, Erklärungen und Code-Skizzen stark, für exaktes Rechnen nicht gebaut.
• Das 2B-Modell degeneriert bei Minimal-Prompts („Hi!", „Hallo" → HTML/C++-Spam). Mit etwas Kontext („Hi, how are you?") antwortet es kohärent. Für ernsthaften Chat: Falcon nehmen.
• prompt_length Default 96; bei Falcon liefert 128 Echo/Garbage (Root Cause offen).
• Der Graph-Capture-Peak liegt über 8 GB (WDDM-Shared-Memory) — bei belegter GPU (Browser, andere ML-Prozesse) kann der Server ins Paging fallen (2–8 TPS). Dann: GPU freimachen (nvidia-smi), Server neu starten.
• Windows + NVIDIA only (CUDA sm_86 getestet; andere sm_ sollten gehen, Kernel sind generisch).

Unterstützen

Dieses Projekt ist für private Nutzung kostenlos (PolyForm Noncommercial). Wenn es dir gefällt, kannst du die Weiterentwicklung mit einer kleinen Spende unterstützen — danke! ☕

• PayPal: https://paypal.me/marvinwitte0

(Kommerzielle Nutzung: siehe LICENSE — separate Lizenzvereinbarung.)

Lizenz

Code: PolyForm Noncommercial 1.0.0 (LICENSE) — komplett eigene Implementierung, kein Microsoft-Code. Privat, Hobby, Forschung, Bildung und gemeinnützige/öffentliche Einrichtungen: kostenlos. Kommerzielle Nutzung: nur mit separater kostenpflichtiger Lizenz des Autors. Hinweis: Das ist bewusst kein OSI-„Open Source" — kommerzielle Nutzung ist ausgeschlossen ohne Vereinbarung. Modelle/Tokenizer: eigene Lizenzen, siehe NOTICE.md (BitNet: MIT; Falcon3: TII Falcon License; Llama-3-Tokenizer: Meta Community License).