LucilleAI

چرا LucilleAI ساخته شد

LucilleAI به یک سؤال ساده جواب می‌دهد: آیا می‌شود یک LLM واقعی را از صفر — بدون PyTorch و بدون پایتون — روی لپ‌تاپی با فقط ۴ گیگ VRAM آموزش داد؟

جواب این پروژه است. این ریپازیتوری یک استک کامل یادگیری عمیق «دست‌ساز» به زبان راست است که یک NVIDIA GTX 1650 Ti (Turing, SM75) را با پل CUDA اختصاصی خودش به کار می‌گیرد. پیش‌آموزش روی کورپوس ۱۴ گیگابایتی فارسی و فاین‌تیون نظارت‌شده (SFT) روی ۵۵ هزار نمونه آموزشی انجام می‌شود و کل خط لوله — توکنایزر، خواننده دیتاست، تریـِینر، دقت ترکیبی و استنتاج — داخل همین کدبیس است.

چه چیزی آن را خاص می‌کند

• بدون رپر. نه پایتون، نه PyTorch و نه وابستگی به فریم‌ورک CUDA: cuBLAS مستقیم با FFI صدا زده می‌شود و گراف محاسباتی کاملاً دست‌ساز است.
• روی سخت‌افزاری اجرا می‌شود که «همه» می‌گویند نشدنی است. آموزش ترنسفورمر روی ۴ گیگ VRAM یعنی حل مسئله‌های واقعی حافظه: تخصیص arena، استریم دیتاست بدون کپی و مدیریت دقیق اکتیویشن.
• داستان کامل زبان فارسی. توکنایزر یونی‌گرام فارسی، Sequence Packing و خط لوله SFT برای داده‌های دستوری — همه در همین‌جا پیاده شده‌اند، نه ایمپورت.

معماری (بر اساس سورس)

کریت lucille_ai چند باینری مجزا دارد و کتابخانه‌اش به ماژول‌های متمرکز تقسیم شده است:

بخش	ماژول‌های سورس	محتوا
تنسور هسته	core/tensor, core/shape, core/memory	ویوهای تنسور ۴بعدی، حافظه بدون کپی، shape4 کانونیکال
بک‌اند ریاضی	compute/simd, compute	کرنل‌های AVX2+FMA؛ توزیع SIMD
استک GPU	gpu/*	cuda_bridge (FFI)، cublas، matmul، arena، pinned_memory، sampler و سورس کرنل‌ها
مدل	ml/model, llm	بلوک/استک ترنسفورمر، اتنشن، FFN، LayerNorm
آموزش	training/*	تریـِینر، AdamW، گرید کلیپ، GradScaler (AMP)، بازرس آمادگی
توکنایزر	tokenizer	یونی‌گرام + کاراکتری برای فارسی
زمان اجرا	runtime/*	توزیع دستگاه/حالت اجرا (cpu/cuda/fusion)، اتوکست AMP، سخت‌سازی و tracing
استنتاج و مغز	inference, core/brain, core/tools	دیکودینگ، حلقه «مغز» عامل‌محور با ابزارها (web_search, reader، …)، policy/router/session
دستیارها	code_assistant, workspace	خودترمیمی، ارکستراتور دیباگر، پیشنهادها، بررسی امنیت
ارزیابی و متریک	evaluation, metrics, observability	سوئیت‌های ارزیابی، مقایسه، گزارش
خروجی	export, pdf	موتور چیدمان، خروجی PDF، تست‌های قرارداد

باینری‌های کلیدی (src/bin/): train (پیش‌آموزش)، train_sft (فاین‌تیون دستوری)، chat (چت عامل‌محور)، eval، scientific_eval، tensor_bench، phase1_smoke_bench و workspace_server.

یک همراه lucille-ui/ (Next.js) و پوشه patent/ با مدارک نهایی ثبت اختراع (ادعاها و شرح به فارسی) هم وجود دارد.

اعداد واقعی اندازه‌گیری‌شده روی همین سخت‌افزار

• پیش‌آموزش (کورپوس ۱۴ گیگ، ۵.۳ میلیون خط): چند کانفیگ اعتبارسنجی شده؛ مثلاً اجرای «متوازن» با ۳.۲ میلیون پارامتر در ۲۰۰ استپ به loss 9.5 → 5.9 رسید و اجرای «کارایی» با ۵.۵ میلیون پارامتر بدون OOM با 127 مگابایت VRAM اجرا شد.
• SFT (۵۵ هزار دستور فارسی): مدل ۱.۹ میلیون پارامتری با seq 512 + packing حدود ۷۰٪ پدینگ را حذف کرد؛ ۱۱,۶۴۷ استپ در هر epoch؛ ۱۱.۶ استپ بر ثانیه با ۸۷ میلی‌ثانیه هر استپ روی GTX 1650 Ti؛ best_loss 2.36.
• شتاب‌ها: AVX2+FMA حدود ۳.۲ برابر نسبت به scalar؛ Tensor-Core AMP با FP16 حدود ۳.۸ برابر نسبت به FP32 خالص.
• تست‌ها: بیش از ۳۴۷ تست در ماژول‌های مختلف (cargo test --features cuda,amp بدون هیچ warning).

نقشه وابستگی‌ها (از Cargo.toml)

• Async/زمان اجرا: tokio، tokio-tungstenite، futures-util، axum، tower
• سریالایز: serde، serde_json
• موازی و SIMD: rayon، wide، crossbeam، num_cpus
• حافظه و I/O: memmap2، memchr، tempfile
• اعداد تصادفی: rand، fastrand
• متن/یونیکد: unicode-normalization، unicode-segmentation، regex، urlencoding
• CLI/خطا/لاگ: clap، anyhow، thiserror، tracing، tracing-subscriber
• عددی: ndarray، ndarray-stats، nalgebra، half (اختیاری، برای FP16)
• کلاینت HTTP: reqwest (rustls)
• مستند/PDF: printpdf، image، sha2
• سایر: chrono، ahash، dashmap، once_cell، lazy_static
• CUDA (فیچر cuda/amp): FFI مستقیم به libcuda/cublas؛ ساخت کرنل با cc در build.rs
• فیچر اختیاری amp: اتوکست FP16 + GradScaler

شروع کار

# ساخت CPU-only
cargo build --release

# GPU با cuBLAS (بدون AMP)
cargo build --release --features cuda

# GPU + Tensor Cores (پیشنهادی روی Turing)
cargo build --release --features cuda,amp

# گیت‌های کیفیت
cargo fmt --check && cargo clippy -- -D warnings && cargo test

اجرای پیش‌آموزش سبک (کانفیگ Eco):

./target/release/train \
  --corpus <path>/pretrain.txt --device cuda --amp --attn-backend flash \
  --batch-size 4 --seq-len 32 \
  --embed-dim 128 --hidden-dim 256 --layers 2 --num-heads 4 \
  --learning-rate 0.001 --lr-scheduler none --epochs 1 --dataset-mode stream \
  --tokenizer-vocab 2000 --train-tokenizer --threads 8 \
  --save-every 100 --output-dir artifacts/pretrain_eco

سپس فاین‌تیون SFT و چت:

./target/release/train_sft --dataset <path>/persian_sft_data.jsonl \
  --init-from artifacts/pretrain_balanced/latest.ckpt \
  --device cuda --amp --attn-backend flash \
  --batch-size 16 --seq-len 512 --packing \
  --dataset-mode stream --epochs 3 \
  --learning-rate 0.0003 --lr-scheduler cosine --warmup-steps 100 --min-lr 0.00003 \
  --output-dir artifacts/sft_balanced

./target/release/chat   # چک‌پوینت را از config.toml می‌خواند

چرا در این رزومه مهم است

۱۱.۶ استپ بر ثانیه روی یک 1650 Ti درباره سخت‌افزار نیست — نتیجه مهندسی دورِ آن است: توزیع هوشمند GPU، انباشت FP16، Sequence Packing و استخر حافظه. LucilleAI نشان می‌دهد که یادگیری عمیق را جعبه سیاه نمی‌دانم: می‌توانم جعبه را بسازم، بازش کنم و در ۴ گیگ جا بدهم.