Splash کے ساتھ Apple Silicon پر تیز رفتار مقامی AI ماڈلز چلائیں

Splash کیا ہے؟

Splash ایک مقامی inference engine ہے جو خصوصی طور پر Apple silicon کے لیے تیار کیا گیا ہے۔ یہ ایسے optimized language models فراہم کرتا ہے جو coding agents اور OpenAI یا Anthropic APIs کو سپورٹ کرنے والی applications کے لیے ہیں۔ سرور مقامی طور پر ایک Mac پر چلتا ہے اور اپنی API کو 127.0.0.1:8000 پر دستیاب کرتا ہے۔

عام مقصد کے inference engine کے برعکس، Splash ہر معاون model کے لیے اپنے kernels، speculative-decoding draft model، weight layout، اور memory plan کو خصوصی طور پر بہتر بناتا ہے۔ Model packages پہلے سے چلانے کے لیے تیار ہوتے ہیں، اس لیے آپ کو Xcode، compiler toolchain، یا model-specific tuning کی ضرورت نہیں ہوتی۔

اہم خصوصیات

• مقامی Apple silicon inference: Splash معاون Mac پر models براہِ راست چلاتا ہے۔
• OpenAI compatibility: یہ /v1/chat/completions پر Chat Completions اور /v1/responses پر Responses فراہم کرتا ہے۔
• Anthropic compatibility: Anthropic Messages requests /v1/messages پر دستیاب ہیں۔
• جدید request support: APIs streaming، tool calls، JSON Schema output، images، اور inline PDFs کو سپورٹ کرتی ہیں۔
• Coding-agent integration: Splash میں OpenCode، Claude، Codex، اور Hermes کے لیے commands شامل ہیں۔
• Model-specific acceleration: ہر model package میں speculative decoding کے لیے DFlash 2 draft اور model کے عین dimensions کے مطابق tuned، precompiled Metal kernels شامل ہوتے ہیں۔
• خودکار memory planning: Splash startup کے وقت Metal کے لیے دستیاب memory کی بنیاد پر context، KV-cache capacity، اور batch limits کا حساب لگاتا ہے۔
• Prompt inspection: /tokenize اور /apply-template endpoints inference چلائے بغیر token IDs یا rendered prompts واپس کرتے ہیں۔

سسٹم کی ضروریات

Splash انسٹال کرنے سے پہلے تصدیق کریں کہ آپ کا سسٹم ان تمام ضروریات کو پورا کرتا ہے:

• Apple M3 یا اس سے نیا processor
• macOS 26.4 یا بعد کا ورژن
• Homebrew
• کم از کم 36 GB unified memory
• 48 GB یا اس سے زیادہ unified memory تجویز کی جاتی ہے

قابلِ استعمال context capacity دستیاب memory پر منحصر ہے۔ اگرچہ معاون models کی native context window زیادہ سے زیادہ 256K ہے، لیکن مکمل window ہر Mac پر فٹ نہیں ہو سکتی۔

Splash انسٹال کریں

Packaged release کو Inco Homebrew tap کے ذریعے انسٹال کریں:

brew install incoai/tap/splash

کوئی configuration file بنانے کی ضرورت نہیں۔ Splash اختیاری settings کے لیے command-line flags اور environment variables استعمال کرتا ہے۔

Model server شروع کریں

Optimized Qwen3.8-27B package کو اس command کے ذریعے serve کریں:

splash serve --model incoai/Qwen3.8-27B-Splash

پہلی بار چلنے پر Splash model package download اور verify کرتا ہے، دستیاب memory چیک کرتا ہے، memory plan بناتا ہے، اور 127.0.0.1:8000 پر server شروع کرتا ہے۔ Qwen3.8-27B package کا download 17.4 GB ہے اور اس میں 4-bit target model کے ساتھ DFlash 2 draft شامل ہے۔

ٹرمینل میں Ready ظاہر ہونے تک انتظار کریں۔ Model استعمال کرتے وقت یہ terminal کھلا رہنے دیں۔ اس کے بعد chat page تک رسائی کے لیے browser میں http://127.0.0.1:8000 کھول سکتے ہیں۔

Splash روکنے کے لیے server terminal میں Ctrl+C دبائیں۔

متبادل model استعمال کریں

Splash ایک 20.9 GB package بھی شائع کرتا ہے جس میں 4-bit Qwen3.6-35B-A3B model اور اس کا DFlash 2 draft شامل ہے:

splash serve --model incoai/Qwen3.6-35B-A3B-Splash

--model option کسی دوسرے owner/repo repository کی طرف اشارہ کر سکتا ہے جس میں درست Splash package موجود ہو۔ Plain MLX اور Transformers checkpoints compatible نہیں ہیں۔ Private Hugging Face repository کے لیے مناسب HF_TOKEN فراہم کریں۔

Coding agent سے منسلک ہوں

Server کے ready ہونے کی اطلاع دینے کے بعد دوسرا terminal کھولیں اور معاون installed coding agents میں سے ایک launch کریں:

splash opencode
splash claude
splash codex
splash hermes

صرف اس agent کی command چلائیں جسے آپ استعمال کرنا چاہتے ہیں۔ Agent کے requests بھیجتے وقت اصل server process فعال رہنا چاہیے۔

OpenAI Chat Completions API کو call کریں

Applications Splash کو OpenAI-compatible local server کے طور پر call کر سکتی ہیں۔ درج ذیل request served model سے ایک جملے میں وضاحت طلب کرتی ہے:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "incoai/Qwen3.8-27B-Splash",
    "messages": [
      {
        "role": "user",
        "content": "Explain speculative decoding in one sentence."
      }
    ]
  }'

model property اختیاری ہے۔ اگر آپ اسے شامل کریں تو اس کی value فی الحال serve کیے جانے والے package سے match ہونی چاہیے۔

مناسب API endpoint منتخب کریں

• OpenAI Chat Completions clients کے لیے /v1/chat/completions استعمال کریں۔
• OpenAI Responses clients کے لیے /v1/responses استعمال کریں۔
• Anthropic Messages clients کے لیے /v1/messages استعمال کریں۔
• Model چلائے بغیر token IDs حاصل کرنے کے لیے /tokenize استعمال کریں۔
• Inference چلائے بغیر rendered prompt کا جائزہ لینے کے لیے /apply-template استعمال کریں۔

Reasoning کو کنٹرول کریں

Reasoning بطورِ پیش فرض فعال ہے۔ اسے غیر فعال کرنے کے لیے request body میں "reasoning_effort": "none" شامل کریں۔ Qwen3.8-27B low، medium، اور xhigh بھی قبول کرتا ہے۔

{
  "model": "incoai/Qwen3.8-27B-Splash",
  "reasoning_effort": "none",
  "messages": [
    {
      "role": "user",
      "content": "Summarize speculative decoding."
    }
  ]
}

جب کسی کام کے لیے طویل استدلالی عمل درکار نہ ہو تو reasoning کو غیر فعال کرنا مفید ہو سکتا ہے۔ Qwen3.8-27B کے ان کاموں کے لیے جن میں reasoning سے فائدہ ہوتا ہے، workload کے مطابق معاون effort level منتخب کریں۔

میموری اور context کی حدود ترتیب دیں

Splash موزوں default settings کا خودکار تعین کرتا ہے، لیکن splash serve زیادہ باریک کنٹرول کے لیے اختیاری flags فراہم کرتا ہے:

• --max-memory 28G، Metal allocations کی زیادہ سے زیادہ حد مقرر کرتا ہے۔
• --max-context 100K، context window کو محدود کرتا ہے، جو model کی مقامی 256K حد تک ہو سکتی ہے۔
• --max-image-pixels، ہر image کے لیے resize کیے جانے والے pixels کی زیادہ سے زیادہ تعداد متعین کرتا ہے۔ اس کی default قدر 4,194,304 ہے۔
• --allowed-host، ایک اضافی HTTP Host نام کی اجازت دیتا ہے، مثلاً proxy کے ذریعے استعمال ہونے والا نام۔ یہ option بار بار استعمال کیا جا سکتا ہے۔
• --no-webui، browser chat page کو غیر فعال کرتا ہے۔

مثال کے طور پر، درج ذیل command Metal allocations کو 28 GB اور context کو 100K تک محدود کرتی ہے:

splash serve \
  --model incoai/Qwen3.8-27B-Splash \
  --max-memory 28G \
  --max-context 100K

اگر کوئی model دستیاب memory میں فٹ نہ ہو سکے تو Splash memory budget کی تفصیل دکھا کر رک جاتا ہے، بجائے اس کے کہ ناقابلِ استعمال server شروع کرے۔ Context یا memory کی ضروریات کم کرنے سے مدد مل سکتی ہے، لیکن model weights اور مطلوبہ runtime state کے لیے پھر بھی کافی جگہ ہونی چاہیے۔

مقامی API کو محفوظ بنائیں

Authentication بطور default غیر فعال ہے۔ Server شروع کرنے والے shell میں SPLASH_API_KEY set کر کے آپ key لازمی قرار دے سکتے ہیں:

export SPLASH_API_KEY='replace-with-your-key'
splash serve --model incoai/Qwen3.8-27B-Splash

Splash کے زیرِ انتظام coding agent شروع کرنے کے لیے استعمال ہونے والے shell میں بھی یہی environment variable set کریں:

export SPLASH_API_KEY='replace-with-your-key'
splash opencode

API clients یہ key bearer token کے طور پر یا x-api-key header کے ذریعے بھیج سکتے ہیں۔ آپ server کے --api-key option کے ذریعے بھی براہِ راست key فراہم کر سکتے ہیں۔ Health اور readiness probes عوامی رہتی ہیں۔

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

Model cache کے مطابق منصوبہ بنائیں

Download کیے گئے packages، Hugging Face cache میں محفوظ ہوتے ہیں۔ brew upgrade splash چلانے سے یہ packages، model links اور agent sessions برقرار رہتے ہیں، اس لیے engine upgrade کرنے کے لیے انہیں حذف کرنا ضروری نہیں ہوتا۔

Proxy کے ساتھ host allowlisting استعمال کریں

Server مقامی طور پر 127.0.0.1:8000 پر bind ہوتا ہے۔ اگر کوئی local proxy مختلف HTTP Host value بھیجتا ہے تو اس hostname کو --allowed-host کے ساتھ شامل کریں۔ متعدد hostnames قبول کرنے ہوں تو flag کو بار بار استعمال کریں۔

صرف API استعمال کے لیے Web interface غیر فعال کریں

اگر Splash صرف applications یا agents کو service فراہم کرے گا تو اسے --no-webui کے ساتھ شروع کریں۔ اس سے chat page بند ہو جاتا ہے، جبکہ معاون API endpoints دستیاب رہتے ہیں۔

Inference سے پہلے prompts کا جائزہ لیں

Token IDs درکار ہوں تو /tokenize استعمال کریں، یا final rendered prompt کا جائزہ لینے کے لیے /apply-template استعمال کریں۔ چونکہ یہ endpoints model نہیں چلاتے، اس لیے context size اور prompt formatting کی debugging میں مفید ہیں۔

SSD cache offloading آزمائیں

pull request 3 میں موجود experimental implementation، KV-cache اور GDN states کو SSD پر منتقل کر سکتی ہے۔ اس branch کو build کریں اور اسے فعال کرنے کے لیے server کو --max-cache-disk 8G کے ساتھ شروع کریں۔ RAM محدود ہونے پر یہ reusable prefixes برقرار رکھنے اور بار بار ہونے والے prefill کام کو کم کرنے میں مدد دے سکتا ہے۔

SSD offloading feature تجرباتی ہے اور quick start میں بیان کردہ standard packaged workflow کا حصہ نہیں ہے۔

Splash کی کارکردگی کو سمجھیں

Splash ہر model کے لیے inference stack کے بیشتر حصوں کو مخصوص بنا کر رفتار حاصل کرتا ہے۔ Speculative decoding، optional mode کے بجائے standard decode path ہے۔ Model-specific DFlash 2 draft token blocks تجویز کرتا ہے، جن کی target model متوازی طور پر تصدیق کرتا ہے۔

اس کے fused Metal kernels model کی exact shapes کے لیے compile کیے جاتے ہیں اور disk سے mapped خصوصی طور پر packed weights کو اضافی copy کے بغیر پڑھتے ہیں۔ Startup کے وقت Splash موجودہ machine کے لیے context، cache اور batch limits بھی calculate کرتا ہے۔

Project کی measurements کے مطابق، 16-core GPU اور 48 GB memory والے M5 Pro پر Qwen3.8-27B نے short-prompt decoding کے لیے 74 tokens per second حاصل کیے اور cached 32K context کو replay کرتے وقت اپنا پہلا token 282 ms میں واپس کیا۔ نتائج model، prompt، concurrency، hardware اور memory conditions پر منحصر ہوتے ہیں۔ Splash launch post benchmark کے طریقۂ کار اور موازنوں کی تفصیل فراہم کرتی ہے۔

نتیجہ

Splash حالیہ Apple silicon پر منتخب، انتہائی optimized models چلانے کا ایک streamlined طریقہ فراہم کرتا ہے۔ اسے Homebrew کے ذریعے install کریں، compatible Splash model package شروع کریں، پھر browser، معاون coding agent، یا OpenAI- یا Anthropic-compatible API کے ذریعے connect کریں۔ Automatic defaults ابتدائی setup کو آسان بناتے ہیں، جبکہ memory، context، security، host اور interface options زیادہ قابو میں deployments کی معاونت کرتے ہیں۔