🌍 English | Türkçe | العربية | 日本語 | 中文

Soup

Soup

اضبط نماذج اللغة الكبيرة (LLMs) ضبطًا دقيقًا وأجرِ لها تدريبًا لاحقًا بأمر واحد. بلا SSH، وبلا جحيم الإعدادات.

الموقع · البدء السريع · واجهة الويب · الإعدادات · التوثيق · الأوامر · النماذج · Discord · Telegram · Product Hunt

PyPI التنزيلات Python 3.11-3.13 ترخيص Apache-2.0 الاختبارات CI الموقع Discord Telegram DOI: 10.5281/zenodo.21771064

Soup CLI - ضبط نموذج لغوي كبير بحجم 8B على وحدة معالجة رسومية لحاسوب محمول بسعة 4 GB | Product Hunt MakazhanAlpamys/Soup | Trendshift

--- يحوّل Soup عناء الضبط الدقيق لنماذج اللغة الكبيرة إلى سير عمل بسيط. ملف إعدادات واحد، وأمر واحد، وانتهى الأمر. ```bash pip install "soup-cli[train]" # أضف [train] للضبط الدقيق؛ أما soup-cli وحدها فهي واجهة سطر الأوامر الخفيفة soup init --template chat soup train ``` **اضبط نموذجًا بحجم 8B ضبطًا دقيقًا على وحدة معالجة رسومية لحاسوب محمول بسعة 4 GB.** يُبقي بثّ الطبقات النموذجَ الأساسي المجمَّد خارج VRAM ويغذّي به وحدة المعالجة الرسومية طبقةَ فك ترميز واحدة في كل مرة. قِيس الأداء على RTX 3050 Laptop بسعة 4 GB: Llama-3.1-8B-Instruct + NF4 عند **119.6 tok/s بتردد 952 MHz وبذروة 3.32 GB** (قبل الإصلاح) — مطابق بتًّا ببتّ لتشغيل عادي مقيم بالكامل في الذاكرة، وأُعيد إنتاجه بصورة مستقلة على H100 عند 113.00 tok/s وفي 3.32 GB نفسها. (قِيس الرقمان على الإصدار v0.72.2، قبل إصلاح صحة النتائج في v0.73.0 الذي كلّف انخفاضًا قدره 4.8% في الأداء عند 32B. أما التشغيل بعد الإصلاح، على حاسوب محمول آخر ببطاقة RTX 3050 Laptop بسعة 4 GB (@umran666، #1103)، فيسجّل **208.6 tok/s بتردد 1935–1957 MHz وبذروة 2.40 GB**. وهذا يعادل 59% من سقف GEMM في الجلسة نفسها مقابل 68% قبل الإصلاح: أي أبطأ بنحو 14% لكل وحدة من تردد الساعة، فالكسب الخام البالغ 1.74x مردّه تردد الساعة لا تسريع فعلي. وقد غيّر بثّ الطبقات الكبيرة أيضًا نمط استخدام الذاكرة بين الصفّين، فحتى هذه النسبة ليست مقارنة متكافئة — [السجل](benchmarks/gate-v0.72.2-nf4.md).) وهو لا يُفعَّل إلا بطلب صريح (`stream_layers: true`) ولا يزال BETA — [كيف يعمل](docs/performance-and-quantization.md#layer-streaming-beta-v0720-nf4-v0722-disk--wider-archs-v0723-preference-losses-v0724) · [جميع القياسات](benchmarks/) · [الورقة البحثية](https://doi.org/10.5281/zenodo.21771064) · **[تحقّق بنفسك على Colab T4 مجاني](notebooks/proof-4gb.ipynb)** (يحدّ العملية بسعة 4 GB، ثم يتحقق من أن النموذج المبثوث مطابق بتًّا ببتّ لنموذج عادي)

الفحص المسبق لأمر soup train لنموذج Llama-3.1-8B على بطاقة 4 GB: مخزن أساسي بحجم 3.60 GB مثبَّت في RAM عبر 32 طبقة ومخزنان مؤقتان في VRAM حجم كلٍّ منهما 113 MB، ثم ذروة مقيسة قدرها 3.32 GB عند 119.6 tok/s، متوقفةً دون خط الـ 4 GB (صفّ ما قبل الإصلاح، قِيس على v0.72.2 بتردد 952 MHz؛ وصفّ ما بعد #331 في الشرح أدناه)
Llama-3.1-8B-Instruct + NF4 وLoRA وحجم دفعة 1 وطول تسلسل 512 على RTX 3050 Laptop بسعة 4 GB — ذروة 3.32 GB، و119.6 tok/s بتردد 952 MHz (قبل الإصلاح، v0.72.2؛ وبعد #331: 208.6 tok/s بتردد 1935 MHz في 2.40 GB، ولا تصح مقارنتهما مباشرة، @umran666، #1103). الفيديو كاملًا (90 ثانية)

## لماذا Soup؟ لا يزال تدريب نماذج اللغة الكبيرة مؤلمًا. حتى الفرق ذات الخبرة تقضي ما بين 30 و50% من وقتها في مصارعة البنية التحتية بدلًا من تحسين النماذج. ويأتي Soup ليعالج ذلك. - **بلا SSH.** لن تحتاج بعد اليوم إلى الدخول عبر SSH إلى خادم GPU معطَّل. - **ملف إعدادات واحد.** كل ما تحتاجه ملف YAML بسيط. - **كل شيء تلقائي.** حجم الدفعة، واكتشاف وحدة GPU، والتكميم — كلها تُدار عنك. - **يعمل محليًا.** درّب على وحدة GPU الخاصة بك باستخدام QLoRA. لا حاجة إلى السحابة. ## ما الجديد **v0.77.2 — قطع من `main` بعد v0.77.1: 159 طلب سحب (pull request)، منها 153 من 30 شخصًا من خارج المشرف.** معظمه إصلاحات. ويضيف أيضًا ميزات وقاعدتين قد ترفضان ما كان v0.77.1 يقبله، لذا اقرأ [ملاحظات إصدار v0.77.2](https://github.com/MakazhanAlpamys/Soup/releases/tag/v0.77.2) قبل ترقية خادم أو إعداد `task: sft`. إن كنت قادمًا من 0.76.x فشغّل `soup doctor --config soup.yaml` أولًا واقرأ [ملاحظات إصدار v0.77.0](https://github.com/MakazhanAlpamys/Soup/releases/tag/v0.77.0). - **`soup profile --model ` يجيب عن سؤال «هل يتّسع؟» دون ملف `soup.yaml`.** يسعّر التشغيل انطلاقًا من `config.json` الخاص بالنموذج، ويحدّده `--seq` و`--batch` و`--method` و`--lora-r` و`--optimizer` و`--gradient-checkpointing`؛ وعلى Apple Silicon يقارنه بمجموعة العمل في Metal. ويقبل `soup plan` و`soup apply` الخيار `--minillm-on-policy`. - **مزيد من التدريب على Apple Silicon.** يشغّل `task: preference` مع `preference_loss: dpo` أو `orpo` أو `simpo` مدرّب MLX الأصلي، ويتدرّب GRPO على MLX على قواعد `mlx-community` بدقة 4 بت، ويتبع Adafactor على MLX معدّل التعلّم والجدول المضبوطين. - **وصفتان جديدتان لـ DPO:** `qwen3.5-0.8b-dpo` و`qwen3.5-27b-dpo`. - **تقديرات VRAM أقرب.** خطوة المُحسِّن مرحلة قائمة بذاتها، وتُحمَّل خطوة PRM لوغاريتمات موضع واحد، ويُسعَّر تشغيل FSDP أو ZeRO المجزَّأ لكل بطاقة، وتُحمَّل خطوة `stream_loss_chunk` إعادة حساب طبقتها الأخيرة، وتُحتسب أهداف LoRA في Unsloth كما يختارها محمِّله. - **كتابة فوق الملفات بصمت ونتائج فارغة أقل.** ترفض أوامر أكثر قيمةَ `--output` تسمّي أحد المدخلات (`soup data ingest` و`persona-mix` و`generate` وغيرها)؛ ويرفض `soup ship --adapter` محوّلًا لا يغيّر شيئًا؛ وتفشل `soup distill-prompt` و`soup data evolve` و`gen-magpie` و`filter --perplexity` بدل أن تكتب ملفًا فارغًا أو غير مُصفّى. - **إصلاحات التفضيل والتعلّم المعزَّز.** عاد `data.max_length` يُطبَّق على SimPO وKTO، ويطبّق PPO الـ gradient checkpointing على سياسته عند طلبه (ولم ينهَر بعد الآن مع 4 بت و8 بت)، ويحمّل `soup merge` الإيداع الأساسي الذي دُرِّب عليه المحوّل. - **النص يُعرض كما كُتب.** عشرات الأوامر تطبع المسارات والأسماء والرسائل مع الإبقاء على الأقواس ونص `:name:` وإزالة محارف التحكم في الطرفية. **تغييرات في السلوك يجب أن تعرفها.** يجب أن يكون `soup serve --tool-auth-token` من 16 إلى 128 محرفًا من `A-Z` و`a-z` و`0-9` و`_` و`-` (وإلا يكون رمز الخروج 2). ويرفض `task: sft` الإعدادات `reasoning_effort` و`train_on_eot` و`use_flash_attn` و`use_liger` على مسارات الرؤية والصوت وMLX وUnsloth وRAFT والبيانات المرمَّزة مسبقًا التي لم تكن تطبّقها. ويلزم إعادة توليد نصوص `soup completions`. وقد يعطي `soup data from-traces --signal thumbs_up` وAdafactor على MLX و`soup merge` والفحص المسبق لـ VRAM نتيجة مختلفة عن v0.77.1. تجد أبرز ما في الإصدارات الأقدم في صفحة [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases). ## البدء السريع ### 1. التثبيت Soup تطبيق سطر أوامر، ولذلك فإن أنظف تثبيت هو أن تمنحه بيئته الخاصة وأن يضع `soup` على `PATH` لديك: ```bash # النواة الخفيفة: CLI + الإعدادات + أدوات البيانات، بلا PyTorch pipx install soup-cli uv tool install soup-cli # الفكرة نفسها، إن كنت تستخدم uv أصلًا # أضف حزمة التدريب (torch وtransformers وpeft وtrl وdatasets وغيرها …) pipx install "soup-cli[train]" # كل شيء (train + serve + ui + data) دفعة واحدة pipx install "soup-cli[all]" # أو من GitHub (أحدث نسخة تطوير) pipx install "git+https://github.com/MakazhanAlpamys/Soup.git" ``` هل أنت داخل بيئة virtualenv أو دفتر Colab أو صورة Docker أصلًا؟ استخدم `pip` مباشرةً بالأسماء والحزم الإضافية نفسها: ```bash pip install soup-cli pip install "soup-cli[train]" pip install "soup-cli[all]" pip install git+https://github.com/MakazhanAlpamys/Soup.git ``` استخدم `pip` بدلًا من `pipx` إن كنت تريد أيضًا تنفيذ `import soup_cli` من شيفرتك الخاصة، لأن pipx يعزل التطبيق عمدًا عن كل ما عداه. يوجد جدول الحزم الإضافية الكامل (`fast` و`mlx` و`serve` و`eval` و`ui` و`vision` و`audio` و…) في [`docs/models.md`](docs/models.md#optional-extras). > **`error: externally-managed-environment`؟** هذه هي > [PEP 668](https://peps.python.org/pep-0668/)، وليست مشكلة في Soup. فمنذ Debian 12 وUbuntu 23.04 وما > بعدهما يمنع النظام `pip` من الكتابة في Python الخاصة بالنظام، لأن `apt` يدير هذه الملفات أيضًا. ويتجاوز > `pipx` و`uv tool` ذلك بمنح Soup بيئته الخاصة، وهذا سبب ذكرهما أولًا أعلاه. كما يفي بالغرض تنفيذ > `python3 -m venv .venv && source .venv/bin/activate` ثم استخدام `pip` العادي. > **علامتا اقتباس مزدوجتان لا مفردتان.** الصيغة `"soup-cli[train]"` هي الوحيدة التي تعمل في كل الأصداف — > `cmd.exe` وPowerShell وbash وzsh. وإن كنت قد نسخت `'soup-cli[train]'` من برنامج تعليمي أقدم ورفضه pip، > فهذا هو السبب: > [السبب ونص الخطأ كاملًا](docs/models.md#quoting-the-extra). تعمل الأوامر `soup init` و`soup data …` وسائر أوامر البيانات والفحص على التثبيت الخفيف. أما الضبط الدقيق (`soup train`) فيحتاج إلى الحزمة الإضافية `[train]`. ### 2. أنشئ ملف الإعدادات ```bash soup init # معالج تفاعلي soup init --template chat # أو ابدأ من قالب ``` القوالب: `chat` و`code` و`tool-calling` و`medical` و`reasoning` و`vision` و`kto` و`orpo` و`simpo` و`ipo` و`bco` و`rlhf` و`pretrain` و`moe` و`longcontext` و`embedding` و`audio`. ### 3. درّب، واختبر، وانشر ```bash soup train --config soup.yaml # LoRA والتكميم وتقسيم الدفعات — كل ذلك يُدار عنك soup chat --model ./output # تحدَّث إلى نموذجك soup push --model ./output --repo you/my-model soup merge --adapter ./output # ادمج LoRA في النموذج الأساسي soup export --model ./output --format gguf --quant q4_k_m # GGUF لـ Ollama / llama.cpp ``` وتوجد أهداف تصدير أخرى (ONNX وTensorRT وBitNet) وخيارات النشر في [`docs/serving-and-export.md`](docs/serving-and-export.md). ## واجهة الويب تفضّل المتصفح؟ يقدّم `soup ui` لوحة محلية للتجارب وإعداد التدريب والمقاييس الحية واستكشاف مجموعات البيانات والدردشة مع النموذج. ```bash pip install "soup-cli[ui]" soup ui # يفتح http://127.0.0.1:7860/?token= ``` ![واجهة ويب Soup — تدريب جديد](docs/assets/web-ui-new-training.png) [توثيق واجهة الويب](docs/serving-and-export.md#web-ui) ## الإعدادات ملف `soup.yaml` كامل: ```yaml base: meta-llama/Llama-3.1-8B-Instruct task: sft # backend: unsloth # أسرع بمقدار 2-5 أضعاف، pip install "soup-cli[fast]" data: train: ./data/train.jsonl format: alpaca val_split: 0.1 training: epochs: 3 lr: 2e-5 batch_size: auto lora: r: 64 alpha: 16 quantization: 4bit output: ./output ``` `config/schema.py` هو المصدر الوحيد للحقيقة لكل حقل. أما خيارات البيانات والتدريب وPEFT المتقدمة فموثَّقة تحت [التوثيق](#التوثيق). > **مفاتيح الإعداد غير المعروفة تُرفَض منذ v0.75.** المفتاح الذي لا يعرّفه أي نموذج في المخطط (Pydantic) — كخطأ إملائي مثل > `quantizaton`، أو حقل لا يوجد إلا في إصدار أحدث من Soup — كان يجتاز التحقق نظيفًا ثم يُهمَل، فيستمر > التشغيل دون تطبيق الإعداد ببساطة. وكان v0.74 يبلّغ عنه عند التحميل مع الحقل الذي ربما قصدته؛ أما بدءًا > من **v0.75** فيفشل تحميل الإعداد نفسه، فصحِّح المفتاح أو احذفه بدلًا من الاعتماد على إهماله. راجع > [مفاتيح الإعداد غير المعروفة](docs/backends-and-ops.md#unknown-config-keys). ## التوثيق المرجع الكامل للميزات موجود في [`docs/`](docs/). ابدأ من هنا:
| الدليل | ما يغطيه | |---|---| | [مهام التدريب وأساليبه](docs/training.md) | SFT وDPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO، واستدعاء الأدوات، وPRM، والتدريب المسبق، والتقطير، والتصنيف، والرؤية/الصوت/TTS، وإلغاء التعلّم، وRAFT/RA-DIT، وكواشف تحصين الحلقات التكرارية (loops) ضد الأعطال | | [PEFT والسياق الطويل والكفاءة](docs/peft-and-efficiency.md) | DoRA وLoRA+ وrsLoRA وVeRA وOLoRA وNEFTune وPiSSA وReLoRA، ومجموعة المُحسِّنات وطرائق PEFT، وLLaMA Pro وGaLore وYaRN/LongLoRA، والتعبئة (packing)، والمنهج التدريجي (curriculum)، والضبط التلقائي | | [الأداء والتكميم](docs/performance-and-quantization.md) | QAT وFP8 وقائمة التكميم (I + II) وذاكرة KV المؤقتة وNVFP4 وصيغ الحفظ وCut Cross-Entropy ونقاط فحص التدرّج (gradient checkpointing) والنوى (kernels) ونقل التنشيطات (activation offloading) وبثّ الطبقات وتعدد GPU / DeepSpeed / FSDP | | [هندسة البيانات](docs/data.md) | الصيغ، وخط أنابيب مكافئ لـ Axolotl/LF، وأدوات البيانات، والتوليد الاصطناعي وforge، وبطاقات تقييم الجودة، وأدوات التتبّع (trace)، ومجموعات البيانات البعيدة، والمزج، ورسوم الوصفات الموجَّهة (DAG) | | [التقييم والمجسّات](docs/evaluation.md) | تصميم التقييم/بوابته، والتدريب المشروط ببوابة التقييم، والمقاييس المعيارية، ومقاييس NLG، والمعايرة، وساحة Elo، والتشخيص، ومجسّات X-ray بعد التدريب، وA/B، والانحراف (drift)، وقابلية الضبط، و`soup advise` | | [الخدمة والتصدير](docs/serving-and-export.md) | خادم متوافق مع OpenAI، والاستدلال الدُفعي، وقياس الأداء، والدمج/التصدير، ونقطة نهاية Anthropic Messages، وفك الترميز التخميني (درّب مسودتك وقِسها)، والطيار الآلي للنشر، وواجهة الويب، وAgent Forge | | [المهايئات (Adapters) والسجل والحوكمة](docs/adapters-and-governance.md) | دورة حياة المهايئات وإدارتها، وسجل النماذج، وSoup Cans، ودولاب البيانات (`soup loop`)، وتحرير المعرفة، والتوجيه (steering)، وضوابط سلسلة التوريد (scan/sign/BOM/attest/audit/airgap) | | [البدء السريع للامتثال والحوكمة](docs/compliance.md) | قوالب `init` لـ HIPAA/SOC2/EU-AI-Act/SR-11-7، والمنشأ (BOM/attest/repro-receipt)، وسجل التدقيق، والعزل الشبكي (air-gap)، والتوليد التلقائي لبطاقة النموذج (`soup card`)، وبوابة CI (`soup ci init`) | | [الواجهات الخلفية والمنصة والعمليات](docs/backends-and-ops.md) | واجهتا MLX/Unsloth الخلفيتان، والمراكز البديلة (hubs)، وتكامل HF Hub، والطيار الآلي، وتتبّع التجارب، وplan/apply، وملفات قفل البيئة، وملاءمة العتاد، وإكمالات الأوامر، والإضافات، وأوامر الأدوات المساعدة | | [مرجع الأوامر](docs/commands.md) | قائمة أوامر `soup` الكاملة | | [النماذج المدعومة والحزم الإضافية](docs/models.md) | عائلات النماذج الموصى بها، ودليل أحجام VRAM، ومصفوفة الحزم الإضافية في pip |
## صيغ البيانات Alpaca وShareGPT وChatML وأزواج التفضيلات (DPO / ORPO / SimPO / IPO / KTO) والرؤية والصوت وASR والنص العادي والتضمين (embedding) وRAFT وغيرها — كلها تُكتشف تلقائيًا من JSONL أو JSON أو CSV أو Parquet أو TXT، ولذلك تكتفي في معظم الحالات بتوجيه `data.train` إلى ملف دون أن يتغير شيء آخر. وتوجد المخططات مع مثال عملي لكل صيغة، إضافةً إلى خط أنابيب البيانات (معرّفات URI البعيدة، والبثّ، والتقسيم إلى شظايا (sharding)، والدمج المتناوب (interleaving)، وتوسيع المفردات، واستيعاب المستندات)، في [`docs/data.md`](docs/data.md#data-formats)، مع توثيق [تدريب الصوت الأصلي لـ Sesame CSM](docs/training.md#native-sesame-csm) بشكل منفصل. ## الأوامر الشائعة ```bash soup train --config soup.yaml # درّب (SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...) soup infer --model ./output --input prompts.jsonl --output results.jsonl # استدلال دُفعي soup chat --model ./output # دردشة تفاعلية soup serve --model ./output # خادم API متوافق مع OpenAI soup ui # لوحة متصفح محلية soup merge --adapter ./output # ادمج LoRA في النموذج الأساسي soup export --model ./output --format gguf # صدِّر للنشر soup eval benchmark --model ./output # قيِّم soup data inspect ./data/train.jsonl # إحصاءات مجموعة البيانات soup recipes list # أكثر من 100 وصفة نموذج جاهزة soup autopilot --model --data d.jsonl --goal chat # بلا إعدادات soup doctor # افحص GPU / الاعتماديات / البيئة ``` قائمة الأوامر الكاملة موجودة في [`docs/commands.md`](docs/commands.md). ## النماذج المدعومة يعمل Soup مع **أي** نموذج لتوليد النصوص على [HuggingFace Hub](https://huggingface.co/models?pipeline_tag=text-generation) — فإن كان يُحمَّل عبر `AutoModelForCausalLM` فهو يعمل دون أي تغيير في الإعدادات. وتأتي Llama 3.x/4 وQwen 2.5/3 وGemma 3 وMistral وMixtral وDeepSeek R1/V3 وPhi-4 وأكثر من 100 نموذج آخر كوصفات جاهزة (`soup recipes list`).
| VRAM | أكبر نموذج (QLoRA بدقة 4-bit) | مثال | |---|---|---| | 8 GB | ~7B | Llama-3.1-8B, Mistral-7B | | 16 GB | ~14B | Phi-4-14B, Qwen2.5-14B | | 24 GB | ~34B | CodeLlama-34B, Yi-1.5-34B | | 48 GB | ~70B | Llama-3.3-70B | | 80 GB+ | 70B+ (كامل) أو MoE | Mixtral-8x22B, DeepSeek-V3 |
جداول النماذج الكاملة ونماذج الرؤية ومصفوفة الحزم الإضافية موجودة في [`docs/models.md`](docs/models.md). ## Docker شغّل Soup دون تثبيت CUDA أو PyTorch محليًا (تُنشر الصورة على GHCR مع كل إصدار): ```bash docker pull ghcr.io/makazhanalpamys/soup:latest docker run --gpus all -v $(pwd):/workspace ghcr.io/makazhanalpamys/soup train --config soup.yaml --yes docker compose up # أو ابنِ الصورة محليًا ``` ## المتطلبات - Python 3.11 أو 3.12 أو 3.13 (هذه هي الإصدارات التي يختبرها CI؛ أما 3.14 وما بعده فغير مدعوم بعد لأن حزمة PyTorch لم يُتحقَّق منها هناك) - GPU يدعم CUDA (موصى به) أو Apple Silicon (MPS) أو CPU (تجريبي — بطيء جدًا) - 8 GB فأكثر من VRAM للنماذج بحجم 7B مع QLoRA تعمل جميع مهام التدريب على CPU لأغراض الاختبار (ويُعطَّل التكميم تلقائيًا). والحزم الإضافية الاختيارية (`train` و`all` و`fast` و`vision` و`qat` و`serve` و`serve-fast` و`ui` و`eval` و`deepspeed` و`liger` و`mlx` و`onnx` و`tensorrt` و…) مذكورة في [`docs/models.md`](docs/models.md#optional-extras). ## استكشاف الأخطاء وإصلاحها ```bash soup doctor # GPU وموارد النظام والاعتماديات والإصدار في مكان واحد ``` حزم CUDA الجاهزة (wheels) وعدم تطابق الإصدارات: [`docs/backends-and-ops.md`](docs/backends-and-ops.md#troubleshooting). ## التطوير ```bash git clone https://github.com/MakazhanAlpamys/Soup.git cd Soup pip install -e ".[dev]" ruff check src/soup_cli/ tests/ # فحص الشيفرة (lint) pytest tests/ -v # اختبارات الوحدة (سريعة، بلا GPU) pytest tests/ -m smoke -v # اختبارات الدخان (تنزّل نموذجًا صغيرًا وتدرّبه) pytest tests/ -m gpu --no-cov -v # اختبارات GPU (تحتاج بطاقة CUDA؛ بلّغ عن النتائج، راجع CONTRIBUTING.md) pre-commit install # اختياري: ruff lint+format عند كل commit ``` راجع [CONTRIBUTING.md](CONTRIBUTING.md) لمعرفة سير العمل الكامل، و[SECURITY.md](SECURITY.md) للإبلاغ عن ثغرة أمنية. والقياس عن بُعد (Telemetry) لا يعمل إلا بموافقتك الصريحة (`SOUP_TELEMETRY=1`، وهو معطَّل افتراضيًا؛ راجع [سياسة الخصوصية](docs/backends-and-ops.md#privacy-policy)). ## ادعم Soup Soup مرخَّص بـ Apache-2.0 ومجاني — وسيبقى كذلك. يُبنى ويُصان علنًا على حاسوب محمول واحد بسعة 4 GB، ولهذا فإن كل رقم أداء في هذا التوثيق مقيس لا مدَّعى. إن وفّر عليك Soup جولة تدريب، فإن [وضع نجمة على المستودع](https://github.com/MakazhanAlpamys/Soup) هو أكثر ما يفيد، ولا يكلّفك شيئًا. وإن أردت تمويل العمل مباشرةً: **[❤️ تبرَّع](https://buy.stripe.com/4gMcN441k3pha3T19ye7m04)** — مرة واحدة وبأي مبلغ (استخدم خيار *Change amount* / *تغيير المبلغ* في صفحة الدفع). تُعالَج المدفوعات عبر Stripe باسم النشاط التجاري المسجَّل للمشرف، **MePlay, Inc.** — وهذا الاسم، لا «Soup»، هو الذي يظهر في صفحة الدفع وفي كشف حساب بطاقتك. تشتري التبرعات وقت GPU للأعمال المقيَّدة بالعتاد — تعدد وحدات GPU، والتحقق على نماذج 8B فما فوق، وApple Silicon — التي لا يستطيع حاسوب محمول واحد بسعة 4 GB بلوغها. والطريقة الأخرى لتحريك هذه البنود نفسها هي **العتاد ذاته**. فهي تُطرح خلف بوابات صادقة من نوع «يتطلب \<العتاد\>» بدلًا من ادعاءات غير مُتحقَّق منها؛ ولذلك إن كان لديك وصول إلى جهاز أكبر — أو رصيد GPU غير مستخدم — فإن تشغيل إحدى مسائل [`help wanted`](https://github.com/MakazhanAlpamys/Soup/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ونشر الأرقام يفيد بقدر ما يفيد تمويل وقت GPU. وتذكر تلك المسائل بالضبط ما هو معطَّل بسبب العتاد اليوم. ## المساهمون بناه المجتمع ❤️ — شكرًا لكل من ساهم. راجع [CONTRIBUTORS.md](CONTRIBUTORS.md). [![المساهمون](https://contrib.rocks/image?repo=MakazhanAlpamys/Soup)](https://github.com/MakazhanAlpamys/Soup/graphs/contributors) ## التواصل مكان الأخطاء وطلبات الميزات هو [متتبّع المسائل](https://github.com/MakazhanAlpamys/Soup/issues)، ومكان الأسئلة هو [Discussions](https://github.com/MakazhanAlpamys/Soup/discussions) — وكلاهما يُجاب عنه أسرع ويساعد الشخص التالي الذي يواجه المشكلة نفسها. للدردشة المباشرة والمساعدة في الإعداد وكل ما يُفضَّل أن يكون حوارًا مباشرًا، انضم إلى [Discord](https://discord.gg/dgd2pJcjwP) أو إلى [مجتمع Telegram](https://t.me/souptasters). أما كل ما ينبغي أن يظل قابلًا للعثور عليه بعد ستة أشهر فمكانه Issues أو Discussions — فالإجابة في Discord تفيد شخصًا واحدًا، بينما يفيد البلاغ (Issue) كل من يصادف الأمر نفسه. وتنطبق [مدونة قواعد السلوك](CODE_OF_CONDUCT.md) هناك أيضًا. أما لكل ما لا يصلح للعلن — بلاغات الأمان (راجع [SECURITY.md](SECURITY.md)) أو مسائل مدونة قواعد السلوك أو الصحافة — فراسل **team@trysoup.dev**. فهذا هو عنوان المشروع والعنوان الصحيح لكل ما يتعلق بـ Soup. أما **makazanalpamys@gmail.com** فهو العنوان الشخصي للمشرف؛ وهو يصل إلى الشخص نفسه، ويصلح بديلًا احتياطيًا عند الحاجة. ## الاستشهاد بـ Soup يوصَف بثّ الطبقات — أي تدريب نموذج بحجم 8B على وحدة معالجة رسومية لحاسوب محمول بسعة 4 GB عبر بثّ النموذج الأساسي المجمَّد من ذاكرة RAM المضيفة طبقةَ فك ترميز واحدة في كل مرة — في ورقة ما قبل النشر (preprint)، مع بروتوكول صحة النتائج الذي يتحقق من تشغيلٍ مبثوث مقارنةً بتشغيل مقيم بالكامل في الذاكرة (ويُذكر التمرير الأمامي والخلفي كلٌّ على حدة، لأنهما ادعاءان اثنان لا ادعاء واحد). > Makazhan, A. (2026). *Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop > GPU* (v3). Zenodo. https://doi.org/10.5281/zenodo.21918325 **الإصدار 3 (13 أغسطس 2026) هو الحالي.** لم يتغير العنوان ولا الادعاء — 8B على 4 GB — ولم يتغير أي رقم مقيس منذ v1. وما يفعله v3 هو **سحب تفسير كنا قد نشرناه**، وهذا أيضًا أقصر وصف لغاية الورقة: - **سُحب في v3: «بثّ الطبقات مقيَّد بالنقل من المضيف إلى الجهاز، لا بوحدة GPU».** كان ذلك *استنتاجًا* من إعادة الإنتاج على H100 المذكورة أدناه، ولم يُقَس قط. وقد قسناه في 11 أغسطس فتبيّن أنه خاطئ عند الإعداد المنشور: فحذف كل بايت منقول من المضيف إلى الجهاز لا يوفّر سوى **1.4%**، ويظل مسار الحساب (compute stream) ينتظر انتهاء عملية نسخ خلال **0.20%** من زمن الخطوة، وتعمل الخطوة عند **71.3%** من سقف GEMM لتلك البطاقة في الجلسة نفسها. وأكبر تكلفة خاصة بالبثّ هي إزالة تكميم NF4 لكل طبقة، بنسبة 9.8% ([السجل](benchmarks/probe-v0.73.0-what-bounds-streaming.md)). وتبقى كل القياسات قائمة؛ أما إعادة الإنتاج فتصمد بصورة أضعف — فالقيد مشترك بين الجهازين وليس قدرة GPU الحسابية. - **إعادة إنتاج على عتاد لا يشبه الأصلي في شيء** (أُضيفت في v2): 119.6 tok/s على RTX 3050 (بتردد 952 MHz) مقابل وسيط 113.00 على H100، عند الذروة نفسها 3.32 GB. وكلاهما سابق لإصلاح #331، وهما الرقمان اللذان توردهما الورقة. أما صفّ ما بعد #331 (@umran666، #1103) فهو 208.6 tok/s بتردد 1935–1957 MHz وبذروة 2.40 GB، أي 59% مقابل 68% من سقف GEMM في الجلسة نفسها: فالكسب الخام البالغ 1.74x مردّه تردد الساعة لا تسريع فعلي، وقد تغيّر نمط استخدام الذاكرة بين الصفّين، فحتى هذه النسبة ليست مقارنة متكافئة ([السجل](benchmarks/gate-v0.72.2-nf4.md)). - **عيب صامت يُنتج تدرّجات خاطئة، اكتُشف وأُصلح.** على NF4 فوق نحو 165 MiB لكل طبقة بقي التمرير الأمامي مطابقًا بتًّا ببتّ وبدا منحنى الخسارة سليمًا بينما كانت التدرّجات خاطئة. وقد حُدِّد السبب في المكتبة المصدرية (upstream) وأُبلغ عنه هناك؛ والإصلاح مشروط بضوابط على نماذج حقيقية بحجم 32B و72B. - **مطابقة بتًّا ببتّ عند أحجام نماذج حقيقية** بدلًا من نماذج تجريبية مبسّطة من ثلاث طبقات: التمرير الأمامي من 0.5B إلى 72B، والخلفي عند 8B و14B. - **جودة النموذج المدرَّب، مقيسةً للمرة الأولى**، ولا يمكن تمييزها عن تشغيل مقيم بالكامل في الذاكرة. - **مقارنة مع DeepSpeed** — بما في ذلك النتيجة التي لا تصبّ في صالحنا: ثماني بطاقات بـ ZeRO-3 أبطأ من بطاقة واحدة تدرّب تشغيلًا مقيمًا. - **أُعيدت كتابة قسم القيود**: من بنود v1 العشرة أُغلق بند واحد وضاق نطاق أربعة أخرى، وأُضيفت سبعة بنود جديدة. استشهد بالإصدار الذي استخدمته. إن `10.5281/zenodo.21771064` هو معرّف DOI الشامل (Concept DOI) ويحيل دائمًا إلى أحدث إصدار (v3 اليوم)؛ ويبقى v1 وv2 قابلين للاستشهاد بمعرّفَي DOI الخاصَّين بكل منهما ولا يُعدَّلان — فالسحب المذكور أعلاه إصدار جديد بالتحديد كي يبقى سجل ما ادّعيناه ومتى ادّعيناه سليمًا. وسجلات القياس التي تقف خلف كل رقم فيها موجودة في [`benchmarks/`](benchmarks/)، منشورةً كما كُتبت — بما في ذلك الإخفاقات والافتراضات التي تبيّن خطؤها والأرقام التي قِيست ثم استُبعدت. ```bibtex @misc{makazhan2026exact, title = {Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU}, author = {Makazhan, Alpamys}, year = {2026}, publisher = {Zenodo}, version = {v3}, doi = {10.5281/zenodo.21918325}, url = {https://doi.org/10.5281/zenodo.21918325} } ``` ## الترخيص [Apache-2.0](LICENSE). Copyright 2026 Makazhan Alpamys and the Soup contributors. إذا أعدتَ توزيع Soup أو نسخة معدَّلة منه، فإن البندين 4 و6 من الترخيص ينطبقان عليك: احتفظ بالملفين `LICENSE` و`NOTICE` مع كل نسخة، وضع علامة على الملفات التي غيّرتها، ولا تستخدم اسم Soup إلا لبيان مصدر العمل.