APEX، ایک اوپن RTL LLM انفیرنس ٹائل، بنائیں اور اس کی تصدیق کریں

APEX کیا کرتا ہے

APEX ایک مکمل طور پر اوپن، تصدیق کو اولین ترجیح دینے والا LLM inference tile ہے۔ یہ حقیقی RTL میں ایک transformer decoder layer نافذ کرتا ہے، جس میں attention، KV-cache compression، online softmax، RMSNorm، rotary position embeddings، SwiGLU، residual connections اور matrix operations شامل ہیں۔

اس منصوبے کا ہدف edge inference کی ایک بڑی رکاوٹ کو حل کرنا ہے: جیسے جیسے گفتگو بڑھتی ہے، ہر نئے token کو مسلسل بڑے ہوتے ہوئے key-value cache کو پڑھنا پڑتا ہے۔ APEX، KV codec کو براہِ راست hardware datapath میں شامل کرتا ہے۔ Keys اور values بنائے جاتے وقت compress ہوتے ہیں، compressed صورت میں محفوظ کیے جاتے ہیں، اور attention کے استعمال کے دوران decompress ہوتے ہیں۔

APEX ایک inference tile ہے، مکمل accelerator chip نہیں۔ DRAM controllers، PCIe اور network-on-chip repository کے بیان کردہ دائرۂ کار سے باہر ہیں۔

اس tile کا Qwen2.5-0.5B کے ساتھ FPGA hardware پر مظاہرہ کیا جا چکا ہے۔ Qwen2.5-7B کے tokens software-verified golden pipeline سے گزر چکے ہیں، لیکن README یہ دعویٰ نہیں کرتا کہ 7B model silicon پر چلایا گیا ہے۔

اہم خصوصیات

• مکمل decoder-layer datapath: RTL میں projections، attention، normalization، RoPE، feed-forward computation، residual operations اور KV-cache handling شامل ہیں۔
• Datapath کے اندر KV compression: Keys کے لیے per-channel INT4 quantization، values کے لیے per-token INT4 quantization استعمال ہوتی ہے، جبکہ مشکل channels کے لیے fp16 outlier lane استعمال کی جا سکتی ہے۔
• Adaptive precision: TIP unit token importance کو track کرتا ہے اور ہر region کے لیے KVQ8، KVQ4 یا outliers کے ساتھ KVQ4 منتخب کرتا ہے۔
• Shared matrix engine: INT8 systolic MXE کو decoder layer میں matrix jobs کے درمیان time-multiplex کیا جاتا ہے۔
• Online softmax: Scores ایک عددی طور پر مستحکم softmax implementation سے stream ہوتے ہیں، جس کے لیے context-length کے برابر score buffer درکار نہیں ہوتا۔
• Bit-exact verification: RTL نتائج کا موازنہ executable NumPy reference models سے کیا جاتا ہے، اور کسی mismatch کی اجازت نہیں دی جاتی۔
• Mutation-tested testbenches: Verification کو اسی وقت بامعنی سمجھا جاتا ہے جب جان بوجھ کر پیدا کیے گئے RTL defects tests کو fail کر دیں۔
• Simulation-to-silicon replay: FPGA register-operation programs کو bit-for-bit differential comparison کے لیے Verilator twin میں بھی چلایا جاتا ہے۔
• واضح evidence labels: نتائج کو measured یا projected کے طور پر درجہ بند کیا جاتا ہے، بجائے اس کے کہ انہیں ایک ہی performance claim میں ملا دیا جائے۔

Architecture کو سمجھیں

Decode step ایک activation vector سے شروع ہوتا ہے۔ RMSNorm input کو تیار کرتا ہے، اور MXE query، key اور value projections کا حساب لگاتا ہے۔ KVQ engine storage کے لیے keys اور values کو compress کرنے سے پہلے RoPE، queries اور keys کو transform کرتا ہے۔

Attention کے دوران cached values کو read path میں decompress کیا جاتا ہے۔ MXE query-key products کا حساب لگاتا ہے، ASU online softmax نافذ کرتا ہے، اور MXE کا ایک اور job probabilities کو cached values کے ساتھ ملاتا ہے۔ Output projection، residual addition، normalization کا ایک اور مرحلہ اور SwiGLU feed-forward path layer کو مکمل کرتے ہیں۔

اہم RTL Blocks

• MXE: Layer کی matrix operations کے لیے استعمال ہونے والا INT8 systolic GEMM engine۔
• KVQ: KV-cache compression اور decompression engine۔
• ASU: Online softmax، RMSNorm، SiLU اور SwiGLU۔
• RoPE: Queries اور keys کے لیے rotary position embedding۔
• TIP: Token-importance tracking اور precision-tier decisions۔
• SEQ: Control and status register file، job decoder اور layer walker۔
• SEAM: Activation framing، boundary quantization اور scale transport۔
• XBR: غیر ضروری host round trips کے بغیر engines کے درمیان routing۔
• TOP: apex_top composition layer اور integration logic۔

تفصیلی design، decision register اور module provenance کے لیے ARCHITECTURE.md پڑھیں۔

Host Mode اور Walked Mode

APEX execution کے دو طریقوں کو support کرتا ہے۔ Host mode میں host ہر hardware job کو الگ الگ تیار کر کے submit کرتا ہے۔ یہ mode FPGA silicon پر ثابت شدہ ہے، لیکن ہر job کے لیے host round trip درکار ہوتا ہے۔

Walked mode میں host ایک مرتبہ layer شروع کرتا ہے۔ On-tile layer walker descriptors fetch کرتا ہے، engines کو sequence کرتا ہے، intermediate tensors کو XBR fabric کے ذریعے route کرتا ہے اور quantization scales کو آگے منتقل کرتا ہے۔ Walked layer simulation میں bit-exact ہے۔ README کے مطابق FPGA پر walked attention کی bring-up ابھی فعال طور پر جاری ہے۔

Host mode اور walked mode کو یکساں performance configurations نہ سمجھیں۔ Host mode correctness اور bring-up کے لیے مفید ہے، جبکہ walker کا مقصد ہر job کے لیے درکار نمایاں host overhead کو ختم کرنا ہے۔

Installation اور Local Setup

Prerequisites

دستاویزی local verification flow کے لیے درج ذیل انسٹال کریں:

• Python 3.11
• NumPy
• Verilator 5.x
• GNU Make
• Icarus Verilog، cross-checking کے لیے اختیاری

Commands کو checked-out APEX repository کے root سے چلائیں۔ شروع کرنے سے پہلے بنیادی tools کی تصدیق کریں:

python3 --version
verilator --version
make --version
python3 -c "import numpy; print(numpy.__version__)"

README package-install command یا pinned Python environment command فراہم نہیں کرتا۔ Evaluation یا FPGA workflows کے لیے اضافی dependencies حل کرتے وقت repository کی اپنی files اور subdirectory documentation استعمال کریں۔

Evidence پہلے دیکھیں

طویل workflow چلانے سے پہلے project کے evidence اور limitations کا جائزہ لیں:

• STATUS.md میں مشین سے تیار کردہ تصدیقی شمار اور ناپے گئے نتائج شامل ہیں۔
• TRACEABILITY.md معلوم خلا کو ریکارڈ کرتا ہے اور دعووں کو معاون شواہد سے جوڑتا ہے۔
• ماسٹر ٹیبل نفاذ اور bring-up کی صورتحال کو ٹریک کرتا ہے۔
• نتائج کا اشاریہ جمع کیے گئے شواہد کو مہم کے لحاظ سے منظم کرتا ہے۔

گولڈن ماڈل ٹیسٹ چلائیں

قابلِ اجرا NumPy حوالہ ماڈلز اور منجمد ویکٹرز سے آغاز کریں:

make -C golden test

یہ کمانڈ گولڈن ماڈلز کو چلاتی ہے اور کمپریشن اکاؤنٹنگ گیٹ بھی شامل کرتی ہے۔ کمپریشن اکاؤنٹنگ اہم ہے کیونکہ APEX میں صرف نامیاتی INT4 پے لوڈ کی رپورٹنگ کے بجائے ٹیگز، اسکیلز، پیڈنگ اور آؤٹ لائر اسٹوریج بھی شامل ہیں۔

RTL پائپ لائن کی تصدیق کریں

مکمل Attention-Tile Smoke Test چلائیں

make -C verif/top/smoke smoke

یہ attention tile کے لیے دستاویزی end-to-end smoke ہدف ہے۔ گولڈن ماڈل سوٹ کامیاب ہونے کے بعد اسے ابتدائی انٹیگریشن چیک کے طور پر استعمال کریں۔

Layer-3 تصدیق چلائیں

make -C verif/top l3

Layer-3 ہدف فراہم کردہ کیسز میں حقیقی مرکب tile کا گولڈن ماڈل سے موازنہ کرتا ہے۔ APEX میں تقریباً عددی برداشت کے بجائے bit-identical نتائج درکار ہیں۔

Layer Walker کی تصدیق کریں

make -C verif/seq_walker

یہ walker سوٹ اور اس کے mutation gates چلاتا ہے۔ Mutation testing جان بوجھ کر رویے کو خراب کرتی ہے اور جانچتی ہے کہ آیا verification environment نقص کو پکڑتا ہے۔ جو mutant بچ جائے، وہ کامیاب ڈیزائن کے نتیجے کے بجائے verification کی کمزوری کی نشاندہی کرتا ہے۔

کارکردگی کا ماڈل چیک کریں

تجزیاتی ماڈل کی calibration checks اس کمانڈ سے چلائیں:

python3 perf/apex_perf_model.py --check

کارکردگی کا ماڈل واضح طور پر متوقع کارکردگی ہے، ناپی گئی silicon کارکردگی نہیں۔ اس کے مفروضے اور calibration anchors PERF_MODEL.md میں درج ہیں۔

متوقع 7B-class reading-speed اور energy اعداد ان سسٹم اجزا پر منحصر ہیں جو ابھی بنائے نہیں گئے یا نامکمل ہیں، جن میں native W4 weight path، hardware layer walking، اور wide LPDDR integration شامل ہیں۔ انہیں حاصل شدہ hardware نتائج کے طور پر پیش نہیں کیا جانا چاہیے۔

ماڈلز پر KV Compression کا جائزہ لیں

repository میں verified KV codec کے لیے model-accuracy matrices شامل ہیں۔ 0.5B اور 1.5B matrix اس کمانڈ سے چلائیں:

bash eval/kv_eval/run_matrix.sh

7B matrix اس کمانڈ سے چلائیں:

bash eval/kv_eval/run_matrix_7b.sh

ان کمانڈز کو چلانے سے پہلے committed result files کے ساتھ موجود evaluation READMEs دیکھیں۔ شائع شدہ evaluation میں مکمل 10,042-document HellaSwag validation set استعمال کیا گیا ہے۔ README چھوٹے ماڈلز کے لیے near-lossless رویہ، 7B پر KVQ8 کے لیے مکمل set میں کوئی قابلِ شناخت اثر نہ ہونے، اور 7B پر KVQ4 کی معمولی ناپی گئی لاگت کی رپورٹ دیتا ہے۔

متعلقہ شواہد head-to-head نتائج اور 7B evaluation نتائج میں دستیاب ہیں۔

گولڈن پائپ لائن کے ذریعے ماڈل چلائیں

پروجیکٹ run_tinynpu.py --prompt کے ذریعے prompt execution کی دستاویز فراہم کرتا ہے۔ یہ fixed-point golden pipeline کے ذریعے greedy Qwen tokens کو stream کرتا ہے اور replay کے لیے hardware-shaped jobs تیار کر سکتا ہے۔

run_tinynpu.py --prompt

README اپنی اعلیٰ سطحی ہدایات میں مکمل model setup یا ہر command-line argument فراہم نہیں کرتا، اس لیے درست scope، artifacts اور reproduction details کے لیے 7B token artifact documentation دیکھیں۔ یاد رکھیں کہ یہ 7B flow software-verified ہے؛ یہ FPGA tile پر 7B execution کا دعویٰ نہیں ہے۔

AWS F2 Demonstration چلائیں

تقاضے اور لاگت

FPGA demonstration کے لیے AWS CLI credentials درکار ہیں جنہیں us-west-2 میں موجود f2.6xlarge instance تک رسائی حاصل ہو۔ README کے مطابق مکمل run میں تقریباً 30 منٹ اور تقریباً دو امریکی ڈالر لاگت آتی ہے۔

دستاویزی reference FPGA image agfi-030a812cd224b409d ہے۔ یہ A2 recipe کو 15.625 MHz tile clock کے ساتھ استعمال کرتی ہے۔

Verification Battery چلائیں

bash scripts/fpga/f2/run_walked_demo.sh agfi-030a812cd224b409d

اسکرپٹ FPGA instance کو boot کرتی ہے، image لوڈ کرتی ہے، دستاویزی verification battery اور walked chains چلاتی ہے، verdict پرنٹ کرتی ہے، اور instance ختم کر دیتی ہے۔

Interactive Prompt Demo شروع کریں

bash scripts/fpga/f2/run_chat_demo.sh

Interactive demo walked pipeline استعمال کرتا ہے۔ README The capital of France is کو ایک مثالی prompt کے طور پر دیتی ہے اور graded response Paris. رپورٹ کرتی ہے۔

DDR images mlx-community/Qwen2.5-0.5B-Instruct-4bit سے اخذ کی گئی ہیں۔ Team staging artifacts اسکرپٹس میں configured ہیں۔ بیرونی صارفین کو یہ کمانڈ استعمال کرتے ہوئے weight image تیار کرنی چاہیے:

python3 scripts/fpga/f2/make_weight_image.py

حاصل ہونے والی image کو اپنے زیرِ انتظام bucket کے لیے configure کریں، ٹیم کے staging bucket تک رسائی فرض نہ کریں۔

Hardware نتائج کی درست تشریح

repository 62.5 MHz پر A0 image میں 0.56 tokens per second اور 15.625 MHz والی A2 reference image میں 0.25 tokens per second کی ناپی گئی throughput رپورٹ کرتا ہے۔ یہ host-driven baseline سے 0.004-token-per-second کی ناپی گئی پیش رفت بھی رپورٹ کرتا ہے۔

یہ اعداد مخصوص FPGA images، clocks اور execution paths کو بیان کرتے ہیں۔ انہیں نقل کرنے سے پہلے FIRST_WALKED_TOKENS.md دیکھیں اور متعلقہ configuration اور measured label برقرار رکھیں۔

اعلیٰ درجے کی تجاویز

Golden Model کو Arbiter کے طور پر استعمال کریں

RTL بلاک تبدیل کرتے وقت پہلے قابلِ اجرا specification کو اپ ڈیٹ یا validate کریں، repository کے تقاضے کے مطابق vectors دوبارہ تیار کریں یا ان کی تصدیق کریں، اور RTL کے output کا bit-by-bit موازنہ کریں۔ tolerance پر مبنی checks متعارف نہ کریں، جب تک project کا documented arithmetic contract واضح طور پر ان کا تقاضا نہ کرتا ہو۔

Mutation Coverage برقرار رکھیں

APEX methodology کے تحت regression کا کامیاب ہونا کافی نہیں ہے۔ testbench، scoreboard، sequencer یا arithmetic block تبدیل کرنے کے بعد متعلقہ mutation gates چلائیں۔ اگر جان بوجھ کر خراب کی گئی implementation کامیاب ہو جائے تو اصل green result پر اعتماد کرنے سے پہلے verification مضبوط کریں۔

ایک ہی Job کو مختلف Environments میں دوبارہ چلائیں

APEX operations self-describing job descriptors استعمال کرتی ہیں جن میں shapes، routing اور quantization contracts شامل ہوتے ہیں۔ mismatch کی تشخیص کرتے وقت descriptors، scales اور register operations برقرار رکھیں۔ Verilator F2 twin اور hardware پر ایک ہی flight کو دوبارہ چلانا RTL defects کو synthesis یا toolchain defects سے الگ کرنے کا ترجیحی طریقہ ہے۔

Tensor Data کے ساتھ Scales کو Track کریں

Quantization scales hardware contract کا حصہ ہیں، محض incidental metadata نہیں۔ jobs بناتے یا inspect کرتے وقت وہ scale information محفوظ رکھیں جو seams کے ذریعے منتقل ہوتی ہے۔ متعلقہ scale کے بغیر tensor مطلوبہ fixed-point operation کو دوبارہ پیدا نہیں کر سکتا۔

Codec Payload اور Total Storage میں فرق رکھیں

compression کا حساب صرف INT4 payloads سے نہ کریں۔ scale banks، tags، padding، precision metadata اور outlier lanes بھی شامل کریں۔ شائع شدہ ratios کے لیے repository کے golden accounting gate اور STATUS.md کو مستند بنیاد کے طور پر استعمال کریں۔

Model Sizes اور Execution Claims الگ رکھیں

• Qwen2.5-0.5B: project میں بیان کردہ FPGA-backed pipeline کے ذریعے demonstrate کیا گیا۔
• Qwen2.5-7B: software-verified golden pipeline کے ذریعے exercise کیا گیا۔
• 7B-class architecture projections: tile کے گرد ایک بڑے system کے لیے analytic projections ہیں، موجودہ FPGA implementation کی measured performance نہیں۔

Walker کو وسعت دینے سے پہلے Weight Streaming کا مطالعہ کریں

Model weights مکمل طور پر tile پر فٹ نہیں ہوتے۔ IB-FUEL design ہر job کے weight records کو DDR سے on-tile FIFO میں stream کرتا ہے، جبکہ W4 path four-bit groups منتقل کر کے انہیں INT8 matrix engine کے لیے unpack کرتا ہے۔ scheduling یا feeder behavior میں ترمیم سے پہلے IB_FUEL.md اور W4_DATAPATH.md کا جائزہ لیں۔

Repository Layout کو مؤثر طریقے سے استعمال کریں

• rtl/ میں hardware implementation موجود ہے۔
• golden/ میں bit-exact NumPy reference models موجود ہیں۔
• verif/ میں testbenches، assertions، scoreboards، mutation gates اور F2 simulation twin موجود ہیں۔
• eval/ میں codec کے model-accuracy evaluation tools موجود ہیں۔
• perf/ میں projected analytic performance model موجود ہے۔
• scripts/fpga/ میں build، image، DDR-loading، flight اور token-loop scripts موجود ہیں۔
• docs/results/ میں committed campaign evidence موجود ہے۔

موجودہ حدود اور Roadmap

فعال roadmap FPGA پر walked attention validation، تیز تر timing closure، sustained weight streaming، end-to-end W4 support، اضافی measured token-rate work اور Sky130 signoff کی تیاری کو ترجیح دیتا ہے۔ live status master table میں برقرار رکھا جاتا ہے۔

یہ فرض نہ کریں کہ roadmap کے items مکمل ہو چکے ہیں۔ خاص طور پر، README full walked-attention hardware bring-up اور bandwidth سے متعلق کئی dependencies کو جاری کام قرار دیتا ہے۔

نتیجہ

APEX transformer decoder tile کی RTL implementation بھی ہے اور evidence-driven hardware verification کا case study بھی۔ اس کی سب سے نمایاں خصوصیت integrated KV-cache codec ہے، جو keys اور values کو compressed form میں محفوظ رکھتے ہوئے verified attention datapath کا حصہ رہتا ہے۔

golden tests سے آغاز کریں، پھر tile اور walker verification چلائیں، measured evidence کا جائزہ لیں، اور صرف اسی وقت model یا FPGA workflows کی طرف بڑھیں جب ان کے اضافی artifacts دستیاب ہوں۔ measured FPGA results کو analytic projections سے الگ رکھیں، اور کسی claim کو پیش کرتے وقت project کی traceability documents استعمال کریں۔

APEX Apache License 2.0 کے تحت جاری کیا گیا ہے۔ قابلِ اطلاق شرائط اور notices کے لیے LICENSE دیکھیں۔