Rizzo Flow کے ساتھ تیز، ٹائپ شدہ مقامی LLM فیصلے بنائیں

Rizzo Flow کیا ہے؟

Rizzo Flow ایک اوپن سورس، لوکل فرسٹ نظام ہے جو غیر ساختہ متن یا JSON حالت کو احتمالات کے ساتھ ٹائپ شدہ فیصلوں میں تبدیل کرتا ہے۔ زبان کے ماڈل سے نثر یا JSON کو ٹوکن بہ ٹوکن تیار کروانے کے بجائے، یہ فارورڈ پاس کے بعد محدود جوابی حروف کے مجموعے کے لیے ماڈل کے احتمال کو پڑھتا ہے۔

یہ ڈیزائن ایسے فیصلوں کی معاونت کرتا ہے:

• true کے احتمال کے ساتھ بولین جواب۔
• نامزد اختیارات میں سے انتخاب، ہر اختیار کے لیے ایک احتمال کے ساتھ۔
• ترتیب دی گئی روبریک سطحوں پر اسکور۔
• نمائندہ اینکرز کی بنیاد پر عددی تخمینہ۔

Rizzo Flow آپ کے اپنے ہارڈویئر پر llama.cpp کے ذریعے چلتا ہے۔ یہ Apple Metal، NVIDIA CUDA، Vulkan، AMD ROCm، Intel SYCL یا CPU execution استعمال کر سکتا ہے۔ یہ Jev-compatible HTTP انٹرفیس بھی فراہم کرتا ہے، جس سے مطابقت رکھنے والی ایپلی کیشنز hosted service کے بجائے مقامی URL کو ہدف بنا سکتی ہیں۔

Rizzo Flow ایک آزاد پروجیکٹ ہے۔ یہ Jev کے پیچھے موجود انٹرفیس پیٹرن کو دوبارہ بناتا ہے، نہ کہ Jev کے ملکیتی آرکیٹیکچر یا تربیت کو۔ جب تک آپ انہیں اپنے نمائندہ ڈیٹا پر کیلیبریٹ نہ کریں، اس کے احتمالات غیر کیلیبریٹڈ رہتے ہیں۔

صفر ٹوکن والے فیصلے کیسے کام کرتے ہیں

ہر درخواست کے لیے Rizzo Flow حالت کو پرامپٹ کے آغاز میں رکھتا ہے اور اسے ایک مرتبہ پراسیس کرتا ہے۔ اس کے بعد سوالات مشترکہ حالت کے کیش سے شاخیں بناتے ہیں۔ ہر ممکن جواب کو ایک بڑے حرف سے منسلک کیا جاتا ہے، اور نظام صرف مجاز حروف کے logits پڑھتا ہے۔

1. حالت کو متن میں تبدیل کرکے ماڈل کے KV cache میں پہلے سے بھر دیا جاتا ہے۔
2. ہر سوال کو محدود متعدد انتخابی مسئلے کے طور پر پیش کیا جاتا ہے۔
3. ایک ہی حالت کا اشتراک کرنے والے سوالات کو micro-batches میں جانچا جاتا ہے۔
4. مجاز جواب کے logits کو softmax کے ذریعے احتمالات میں تبدیل کیا جاتا ہے۔
5. Python code schema-validated بولین، انتخاب، اسکور یا عددی ڈیٹا واپس کرتا ہے۔

اس میں کوئی decoding loop، sampled text، output parsing یا JSON repair نہیں ہوتا۔ تاہم، صفر تیار کردہ ٹوکن کا مطلب صفر computation نہیں ہے: حالت اور سوال کے پرامپٹس کے لیے اب بھی ماڈل inference درکار ہوتی ہے۔

اہم خصوصیات

• مکمل طور پر مقامی عمل: ماڈل inference آپ کی مشین پر ہوتی ہے۔
• ٹائپ شدہ نتائج: ایپلی کیشنز کو تیار کردہ نثر کے بجائے ساختہ اقدار موصول ہوتی ہیں۔
• احتمالی تقسیمیں: انتخاب اور اسکور کے نتائج صرف argmax جواب کے بجائے احتمالات ظاہر کرتے ہیں۔
• چار مقامی primitives: بولین، انتخاب، اسکور اور عددی۔
• اختیاری عدم جواب: مقامی API ناکافی شواہد، غیر یقینی یا حد سے باہر عددی نتیجے کی اطلاع دے سکتی ہے۔
• مشترکہ حالت کی batching: ایک درخواست میں کئی سوالات حالت کے KV cache کو دوبارہ استعمال کرتے ہیں۔
• Jev-compatible endpoints: موجودہ کلائنٹس /v1/systemone اور /v1/models استعمال کر سکتے ہیں۔
• طویل context والا ماڈل: Spark-X2.5 زیادہ سے زیادہ 1,048,576 tokens کے native context کو سپورٹ کرتا ہے، اگرچہ Rizzo Flow ہر سوال کے لیے بطور ڈیفالٹ 8,192 tokens استعمال کرتا ہے۔
• مقامی ٹولز: سرور میں playground، interactive OpenAPI documentation اور Snake demonstration شامل ہیں۔

ضروریات

Rizzo Flow انسٹال کرنے سے پہلے یقینی بنائیں کہ آپ کے پاس یہ موجود ہیں:

• Python 3.11 یا اس کے بعد کا ورژن۔
• Git۔
• انحصارات اور ماحول کے انتظام کے لیے uv۔
• منتخب کردہ ماڈل اور runtime کے لیے کافی ڈسک اسپیس۔

ڈیفالٹ Spark-X2.5-4B Q8_0 ماڈل ڈاؤن لوڈ تقریباً 4.4 GB کا ہے۔ runtime ڈاؤن لوڈ پلیٹ فارم کے لحاظ سے مختلف ہوتا ہے، Mac پر تقریباً 11 MB سے لے کر CUDA package کے لیے تقریباً 570 MB تک۔

سرور انسٹال اور شروع کریں

repository کو clone کریں، اس کی pinned dependencies کو synchronize کریں، ڈیفالٹ runtime اور ماڈل ڈاؤن لوڈ کریں، پھر سروس شروع کریں:

git clone https://github.com/Rizzo-AI-Academy/rizzo-flow
cd rizzo-flow
uv sync --locked
uv run rizzo download
uv run rizzo serve

download command موجودہ مشین کے لیے سرکاری طور پر پہلے سے تیار کردہ llama.cpp package منتخب کرتا ہے، اس کے SHA-256 checksum کی تصدیق کرتا ہے اور Spark-X2.5-4B Q8_0 ڈاؤن لوڈ کرتا ہے۔ رکا ہوا ڈاؤن لوڈ وہیں سے دوبارہ شروع ہو سکتا ہے جہاں رک گیا تھا۔

پروجیکٹ کی documentation کے مطابق ماڈل لوڈ ہونے میں تقریباً دس سیکنڈ لگتے ہیں۔ سروس تیار ہونے کے بعد یہ کھولیں:

• visual playground کے لیے http://127.0.0.1:8017/playground۔
• interactive OpenAPI documentation کے لیے http://127.0.0.1:8017/docs۔
• Snake demonstration کے لیے http://127.0.0.1:8017/snake۔

playground میں تیار شدہ مثالیں، question builder، دونوں APIs کے لیے raw JSON editors، probability bars، timing details اور مساوی cURL commands شامل ہیں۔ یہ بیرونی calls نہیں کرتا اور اسے English اور Italian کے درمیان تبدیل کیا جا سکتا ہے۔

چھوٹا ماڈل استعمال کریں

پہلا ڈاؤن لوڈ تیز کرنے کے لیے 1.7B ماڈل انسٹال کریں:

uv run rizzo download --size 1.7b
uv run rizzo serve --size 1.7b

1.7B Q8_0 فائل تقریباً 1.8 GB ہے اور تقریباً دو گنا تیزی سے چلتی ہے، لیکن README میں خبردار کیا گیا ہے کہ یہ بہت کم درست ہے۔ جب abstention فعال ہو تو یہ ناکافی شواہد والے آپشن کو بھی منتخب کرنے کی طرف مائل ہوتی ہے، اس لیے اپنے کام کے بوجھ پر اسے احتیاط سے آزمائیں۔

اپنا پہلا فیصلہ کریں

تیز ترین API ٹیسٹ Jev-compatible POST /v1/systemone اینڈ پوائنٹ استعمال کرتا ہے۔ درج ذیل درخواست پوچھتی ہے کہ آیا سپورٹ پیغام عجلت کا اظہار کرتا ہے:

curl http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "Help! My payouts have been failing for 3 days.",
    "model": "rizzo-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      }
    }
  }'

noul نتیجہ ہاں کہنے کا امکان ہے، جسے صفر سے ایک تک کی عددی قدر کے طور پر ظاہر کیا جاتا ہے۔ درخواست میں rizzo-latest یا کوئی سہولت والا عرف استعمال ہونے کے باوجود، جواب اصل مقامی ماڈل شناخت کنندہ کی اطلاع دیتا ہے۔

ایک درخواست میں متعدد سوالات پوچھیں

Rizzo Flow کو اسی state کے خلاف متعدد سوالات کا جائزہ لینے کے لیے بنایا گیا ہے۔ انہیں ایک درخواست میں یکجا کرنے سے سوالات state کے KV cache کو مشترکہ طور پر استعمال کر سکتے ہیں:

curl http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "Help! My payouts have been failing for 3 days.",
    "model": "rizzo-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments, invoicing, refunds",
          "technical": "Bugs and outages",
          "sales": null
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": ["Calm", "Frustrated", "Very angry"]
      }
    }
  }'

جواب میں noul کے لیے ہاں کا امکان، تمام choice آپشنز کے امکانات، اور اس کی legend کے ساتھ امکان سے وزن دیا گیا اسکور شامل ہوتا ہے۔ usage.output_tokens کی قدر ہمیشہ صفر ہوتی ہے۔

مقامی decisions API استعمال کریں

مقامی POST /v1/decisions اینڈ پوائنٹ Rizzo Flow کی مکمل خصوصیات فراہم کرتا ہے، جن میں عددی سوالات اور abstention بھی شامل ہیں۔ اس کے سوالات کی چار اقسام یہ ہیں:

• boolean: typed value اور true ہونے کا امکان واپس کرتا ہے۔
• choice: منتخب آپشن اور تمام آپشنز کی مکمل تقسیم واپس کرتا ہے۔
• score: ترتیب دی گئی سطحوں پر امکان سے وزن دیے گئے اور normalized اسکور واپس کرتا ہے۔
• numeric: تخمینہ، median، پھیلاؤ، اور حد سے کم یا زیادہ ہونے کا امکان واپس کرتا ہے۔

anchors سے عددی قدر کا تخمینہ لگائیں

عددی سوال بڑھتی ہوئی نمائندہ anchors متعین کرتا ہے۔ یہ مثال ماڈل سے رپورٹ شدہ fill percentage پڑھنے کو کہتی ہے:

curl http://127.0.0.1:8017/v1/decisions \
  -H 'Content-Type: application/json' \
  -d '{
    "state": {"measurement": 75, "unit": "percent"},
    "questions": {
      "fill": {
        "type": "numeric",
        "instructions": "Read the reported fill percentage.",
        "unit": "percent",
        "anchors": [
          {"value": 0, "description": "Empty"},
          {"value": 50, "description": "Half full"},
          {"value": 75, "description": "Three quarters full"},
          {"value": 100, "description": "Completely full"}
        ]
      }
    }
  }'

Anchors نمائندہ قدریں ہیں، شماریاتی وقفے نہیں۔ رپورٹ شدہ mean بدستور سب سے کم اور سب سے زیادہ anchor کے درمیان رہتا ہے، جبکہ quantiles ان anchors پر موجود متفرق probability distribution کو بیان کرتے ہیں۔

abstention کو سمجھیں

مقامی سوالات میں بطور ڈیفالٹ abstention کی اجازت ہوتی ہے۔ Rizzo Flow اندرونی insufficient-evidence آپشن شامل کرتا ہے، جبکہ numeric سوالات میں حد سے کم اور حد سے زیادہ کے امکانات بھی شامل ہوتے ہیں۔ منتخب آپشن اور policy کے مطابق primary value null ہو سکتی ہے اور status insufficient_evidence، out_of_range، یا uncertain کی اطلاع دے سکتا ہے۔

Jev-compatible فارمیٹ abstention استعمال نہیں کرتا۔ اس کا yes/no نتیجہ عین دو آپشنز پر حساب کیا جاتا ہے۔ اگر آپ native API کے ذریعے چھوٹا 1.7B ماڈل استعمال کرتے ہیں تو project کی سفارش کے مطابق allow_abstain کو false کرنے پر غور کریں، اور اپنے ڈیٹا پر اس کے اثر کی توثیق کریں۔

سرور کے بغیر فیصلے چلائیں

اسکرپٹس، ٹیسٹس، یا یک وقتی جائزوں کے لیے request file براہِ راست CLI کو دیں:

uv run rizzo decide examples/ticket.json

آپ virtual environment فعال کر کے uv run prefix بھی چھوڑ سکتے ہیں:

source .venv/bin/activate
rizzo decide examples/ticket.json

PowerShell میں اسے اس طرح فعال کریں:

.venv\Scripts\activate

ماڈل، quantization، اور device منتخب کریں

ڈیفالٹ configuration Spark-X2.5-4B Q8_0 استعمال کرتی ہے۔ دیگر دستاویزی quantizations Q4_K_M اور BF16 ہیں:

• 4B Q8_0: تقریباً 4.4 GB اور ڈیفالٹ configuration۔
• 4B Q4_K_M: تقریباً 2.6 GB۔
• 4B BF16: تقریباً 8.2 GB۔
• 1.7B Q8_0: تقریباً 1.8 GB۔
• 1.7B Q4_K_M: تقریباً 1.1 GB۔
• 1.7B BF16: تقریباً 3.4 GB۔

سرور شروع کرنے سے پہلے runtime کو نظر آنے والے devices کا معائنہ کریں:

uv run rizzo devices

اس کے بعد آپ device family واضح طور پر منتخب کر سکتے ہیں:

uv run rizzo serve --device cuda
uv run rizzo serve --device vulkan
uv run rizzo serve --device metal
uv run rizzo serve --device cpu

نامزد ڈیوائس فیملیز محض اشارے نہیں بلکہ تقاضے ہیں، اس لیے Rizzo Flow واضح GPU فیملی کو خاموشی سے CPU پر منتقل نہیں کرتا۔ اضافی رَن ٹائم پیکیجز الگ سے ڈاؤن لوڈ کیے جا سکتے ہیں:

uv run rizzo download --only runtime --runtime rocm
uv run rizzo download --only runtime --runtime sycl
uv run rizzo download --only runtime --runtime cpu

اعلیٰ درجے کی تشکیل اور عملی نکات

بیچ سے متعلق سوالات

ایک ہی حالت سے متعلق تمام سوالات ایک درخواست میں رکھیں۔ یہ Rizzo Flow کے ڈیزائن کا بنیادی حصہ ہے: حالت ایک بار پہلے سے پُر کی جاتی ہے، اور سوالوں کے لاحقوں کا جائزہ مائیکرو بیچز میں لیا جاتا ہے۔ سوالوں کے لیے طے شدہ مائیکرو بیچ سائز چار ہے، جسے --batch-size سے بدلا جا سکتا ہے۔

uv run rizzo serve --batch-size 8

بڑے بیچ خود بخود بہتر نہیں ہوتے۔ ہدف مشین پر تاخیر اور میموری کے استعمال کا موازنہ کریں۔

سیاق و سباق احتیاط سے بڑھائیں

اگرچہ Spark-X2.5 میں مقامی طور پر 1,000,000 ٹوکن کا سیاق و سباق موجود ہے، سرور فی سوال ڈیفالٹ طور پر 8,192 ٹوکنز استعمال کرتا ہے۔ حد --ctx سے بڑھائیں:

uv run rizzo serve --ctx 32768

KV کیش آغاز کے وقت مختص کیا جاتا ہے۔ 4B ماڈل کے لیے README کا تخمینہ تقریباً 144 KiB فی ٹوکن، یعنی ڈیفالٹ حد پر تقریباً 1.4 GiB اور 32,000 ٹوکنز پر 4.8 GiB ہے۔ مقررہ حد سے زیادہ ہونے والے اِن پٹس کو مختصر کرنے کے بجائے مسترد کر دیا جاتا ہے۔ تقریباً 60,000 ٹوکنز سے آگے schema.py میں موجود ریپوزٹری کی 256 KB اسٹیٹ حد بھی بڑھانا ضروری ہے۔

مطابقت رکھنے والے اینڈ پوائنٹس کو محفوظ بنائیں

Bearer توثیق درکار بنانے کے لیے سرور شروع کرنے سے پہلے RIZZO_API_KEY مقرر کریں:

export RIZZO_API_KEY="replace-with-a-secret"
uv run rizzo serve

Windows PowerShell میں:

$env:RIZZO_API_KEY = "replace-with-a-secret"
uv run rizzo serve

توثیق کی ناکامیاں HTTP 401 واپس کرتی ہیں۔ درخواست کا غلط ڈیٹا HTTP 422 واپس کر سکتا ہے۔

مطابقت رکھنے والے کلائنٹ کو ری ڈائریکٹ کریں

Hosted TypeSafe API کے لیے تیار کردہ کلائنٹ اپنے base URL کو تبدیل کر کے مقامی سروس کو ہدف بنا سکتا ہے:

export TYPESAFE_BASE_URL=http://127.0.0.1:8017

پروجیکٹ کے مطابق یہ ماحولاتی متغیر کی ترتیب سرکاری SDKs کے لیے تیار کی گئی ہے، تاہم ابھی ان کے ساتھ آزمائی نہیں گئی۔ انٹرفیس مطابقت رکھتا ہے، لیکن بنیادی مقامی ماڈل Jev نہیں ہے۔

اعتماد اور احتمالات کو درست طور پر سمجھیں

مطابقت رکھنے والی API کی confidence قدر اختیارات کی تقسیم کی ساخت بیان کرتی ہے۔ یہ اس بات کا تصدیق شدہ احتمال نہیں کہ جواب درست ہے۔ اسی طرح خام ماڈل احتمالات حد سے زیادہ پُراعتماد یا کسی اور طرح غلط طور پر calibrated ہو سکتے ہیں۔

فیصلوں کو نمائندہ لیبل شدہ ڈیٹاسیٹ پر validate کریں اور ضرورت پڑنے پر اصل تعیناتی کے ماحول کے لیے calibrate کریں۔ سرور --calibration کے ذریعے calibration فائل قبول کرتا ہے:

uv run rizzo serve --calibration fit.json

Calibration اس ماڈل فائل، رَن ٹائم، quantization اور hardware backend سے وابستہ ہوتی ہے جس پر اسے fit کیا گیا تھا۔ CUDA، Vulkan اور Metal مختلف طریقے سے rounding کر سکتے ہیں، اور quantization واپس کیے جانے والے احتمالات کو بدل سکتی ہے۔

جواب کے خانوں کی حد کا خیال رکھیں

ہر امیدوار ایک بڑے حرف سے مطابقت رکھتا ہے، جس کے نتیجے میں فی سوال زیادہ سے زیادہ 26 جواب کے خانے بنتے ہیں۔ اندرونی abstention اور range اختیارات بھی خانے استعمال کرتے ہیں۔ چنانچہ abstention کے بغیر ایک choice زیادہ سے زیادہ 26 عام اختیارات، اور abstention کے ساتھ 25 اختیارات کی معاونت کرتی ہے۔ عددی سوالات میں دستیاب anchors کم ہوتے ہیں، کیونکہ range سے کم، range سے زیادہ، اور اختیاری insufficient-evidence اختیارات بھی خانے گھیرتے ہیں۔

حسب ضرورت ماڈل فائل یا llama.cpp build استعمال کریں

مخصوص GGUF فائل کے ساتھ سرور شروع کرنے کے لیے --model استعمال کریں:

uv run rizzo serve --model /path/to/model.gguf

حسب ضرورت llama.cpp installation استعمال کرنے کے لیے RIZZO_LLAMA_DIR کو اس ڈائریکٹری کی طرف متوجہ کریں جس میں libllama موجود ہو۔ README میں llama.cpp commit 161755f درکار ہے، کیونکہ bindings اسی ورژن کے header سے وابستہ ہیں۔

Snake demonstration دیکھیں

مقامی Snake صفحہ دکھاتا ہے کہ ٹائپ شدہ فیصلے کسی interactive application کو کیسے کنٹرول کر سکتے ہیں۔ ہر حرکت ایک POST /v1/decisions درخواست بھیجتی ہے، جس میں board کی وضاحت اور قانونی حرکات کی فہرست دینے والا choice سوال شامل ہوتا ہے۔ صفحہ answer probabilities، logits، timings اور decision log دکھاتا ہے، مگر متن generate نہیں کرتا۔

یہ demonstration ایک اہم modeling سبق بھی دکھاتا ہے: input representation اہمیت رکھتی ہے۔ README کے مطابق 4B ماڈل صرف ASCII grid کے مقابلے میں ہر حرکت کے لیے حساب کیے گئے sensors کے ساتھ کہیں بہتر کارکردگی دکھاتا ہے۔ یہ مشاہدات غیر رسمی کھیلوں کی ایک محدود تعداد سے حاصل ہوئے ہیں اور انہیں benchmark نہیں سمجھنا چاہیے۔

آپریشنل جانچ

ماڈل کے ماخذ اور فائل hashes دیکھنے کے لیے GET /health استعمال کریں۔ درخواست اور جواب کے schemas بھی request.schema.json اور response.schema.json میں دستیاب ہیں۔ قابل تکرار deployments کے لیے model، quantization، runtime، backend، context configuration اور calibration کو یکساں رکھیں۔

README کے مطابق RTX 5060 Ti پر Spark-X2.5-4B Q8_0 کے ساتھ مختصر فیصلے میں تقریباً 50 milliseconds لگتے ہیں، لیکن یہ hardware اور workload کے لحاظ سے مخصوص ہے۔ اسی documentation میں بتایا گیا ہے کہ Apple Silicon، AMD، Intel، Linux NVIDIA اور CPU configurations سب کو یکساں طور پر test نہیں کیا گیا، اس لیے latency کی توقعات مقرر کرنے سے پہلے اپنی مشین کا benchmark کریں۔

نتیجہ

Rizzo Flow غیر منظم حالت کو متن تیار کیے بغیر ٹائپ شدہ، احتمالی فیصلوں میں تبدیل کرنے کے لیے ایک عملی مقامی انٹرفیس فراہم کرتا ہے۔ پلے گراؤنڈ سے آغاز کریں، متعلقہ سوالات کو ایک درخواست میں یکجا کریں، اور جب عددی اندازے یا فیصلے سے گریز درکار ہو تو مقامی API استعمال کریں۔ پروڈکشن میں استعمال سے پہلے، ایسے ڈیٹا پر درستگی، تاخیر، کیلیبریشن، کوانٹائزیشن اور بیک اینڈ کے رویے کی جانچ کریں جو آپ کی حقیقی ایپلیکیشن کی عکاسی کرتا ہو۔