الأول: هل محتاج fine-tuning أصلًا؟
أشهر غلطة: «الموديل مش عارف سياسات الشركة، يبقى نعمل fine-tune». الـ fine-tuning بيغيّر السلوك والشكل بكفاءة، لكنه طريقة ضعيفة ومكلفة لإضافة معرفة بتتغير — وصعب تحدّثها أو تمسحها أو تعمل لها citations. القاعدة:
| المشكلة | الحل الأول | إمتى fine-tuning يكسب |
|---|---|---|
| الموديل مش عارف معلومات خاصة/متغيرة | RAG | نادرًا؛ المعرفة في الأوزان ما ليهاش citations ولا بتتحدث بسهولة |
| شكل الـ output مش ثابت (JSON، أسلوب) | prompting + structured outputs | لو الـ prompt طويل جدًا ومكلف، أو الثبات مش كفاية على الحجم |
| مهمة ضيقة متكررة (تصنيف تذاكر، استخراج حقول) | few-shot prompting | غالبًا: موديل صغير متعدّل ممكن يوصل لجودة الكبير بتكلفة و latency أقل بكتير |
| أسلوب/مصطلحات domain (قانوني، طبي، لهجة) | prompting + أمثلة | لو الأمثلة كتير والسلوك صعب يتوصف |
| الموديل الكبير مكلف/بطيء | routing لموديل أصغر | distillation: درّب الصغير على مخرجات الكبير (درس RL & distillation) |
LoRA من جوه
الفكرة: بدل ما نعدّل مصفوفة الأوزان W (d×k) كلها، بنجمّدها ونتعلم تعديل ΔW = B·A حيث A (r×k) و B (d×r) و r صغير جدًا (4، 8، 16). المخرج بيبقى Wx + B(Ax). عدد الـ parameters اللي بتتدرب r(d+k) بدل d·k — لـ d=k=4096 و r=8: حوالي 65 ألف بدل 16.7 مليون للمصفوفة الواحدة.
- ليه بيشتغل؟ الفرضية (ومدعومة تجريبيًا) إن التعديل اللازم لتكييف موديل مدرّب على مهمة جديدة له «rank منخفض»: اتجاهات قليلة في فضاء الأوزان بتكفي.
- B بيبدأ أصفار: فـ ΔW = 0 في البداية، والموديل بيبدأ بالظبط زي الأصلي، والتدريب بيبعد عنه تدريجيًا.
- alpha/r: scaling factor بيتحكم في حجم التعديل؛ بيتضبط مع الـ learning rate.
- QLoRA: الموديل الأساسي متخزن 4-bit (مجمّد)، والـ adapters بتتدرب بدقة أعلى ← fine-tune لموديلات كبيرة على GPU واحد.
- بعد التدريب: تقدر تدمج ΔW في W (inference بنفس السرعة) أو تخليه منفصل وتبدّل adapters لكل مهمة/عميل على نفس الـ base.
معمل: LoRA بإيدك — قبل وبعد، ومقارنة بالـ full fine-tune
موديل خطي «مدرّب مسبقًا» على مهمة أساسية، ومهمة جديدة قاعدتها متغيرة بتغيير low-rank (زي ما بيحصل في التكييف الحقيقي غالبًا). عندنا 300 مثال بس للمهمة الجديدة. بنقارن: الموديل قبل أي تعديل، full fine-tune، و LoRA بـ r=1 و r=2 — وبنقيس كمان الأداء على المهمة الأصلية.
import random, math
random.seed(4)
D, C = 24, 4 # input features, classes
def rand_mat(r, c, s): return [[random.gauss(0, s) for _ in range(c)] for _ in range(r)]
def matvec(M, x): return [sum(m * xi for m, xi in zip(row, x)) for row in M]
def softmax(z):
m = max(z); e = [math.exp(v - m) for v in z]; s = sum(e); return [v / s for v in e]
# Two tasks share the input space but the "new domain" uses a shifted decision rule.
TRUE_BASE = rand_mat(C, D, 1.0)
SHIFT = [[0.0] * D for _ in range(C)]
u, v = [random.gauss(0, 1) for _ in range(C)], [random.gauss(0, 1) for _ in range(D)]
for i in range(C):
for j in range(D): SHIFT[i][j] = 1.6 * u[i] * v[j] # the domain shift is (approximately) LOW-RANK
TRUE_NEW = [[a + b for a, b in zip(r1, r2)] for r1, r2 in zip(TRUE_BASE, SHIFT)]
def make(W, n):
data = []
for _ in range(n):
x = [random.gauss(0, 1) for _ in range(D)]
z = matvec(W, x); data.append((x, z.index(max(z))))
return data
base_train, base_test = make(TRUE_BASE, 3000), make(TRUE_BASE, 800)
new_train, new_test = make(TRUE_NEW, 300), make(TRUE_NEW, 800) # small labelled set for the new domain
def accuracy(W, data): return sum(1 for x, y in data if (lambda z: z.index(max(z)))(matvec(W, x)) == y) / len(data)
def train_full(W, data, epochs, lr=0.05):
W = [row[:] for row in W]
for _ in range(epochs):
random.shuffle(data)
for x, y in data:
p = softmax(matvec(W, x))
for i in range(C):
g = p[i] - (1 if i == y else 0)
for j in range(D): W[i][j] -= lr * g * x[j]
return W
def train_lora(W0, data, r, epochs, lr=0.05):
A = rand_mat(r, D, 0.1) # down-projection, random init
B = [[0.0] * r for _ in range(C)] # up-projection, ZERO init -> the adapter starts as a no-op
for _ in range(epochs):
random.shuffle(data)
for x, y in data:
ax = matvec(A, x)
z = [w + d for w, d in zip(matvec(W0, x), matvec(B, ax))]
p = softmax(z)
g = [p[i] - (1 if i == y else 0) for i in range(C)]
gA = [sum(g[i] * B[i][k] for i in range(C)) for k in range(r)] # backprop through B before updating it
for i in range(C):
for k in range(r): B[i][k] -= lr * g[i] * ax[k]
for k in range(r):
for j in range(D): A[k][j] -= lr * gA[k] * x[j]
delta = [[sum(B[i][k] * A[k][j] for k in range(r)) for j in range(D)] for i in range(C)]
return [[w + d for w, d in zip(r1, r2)] for r1, r2 in zip(W0, delta)], r * (D + C)
W_pre = train_full(rand_mat(C, D, 0.01), base_train, epochs=4) # the "pretrained" model
print(f"pretrained model: base task acc={accuracy(W_pre, base_test):.3f} | NEW domain acc={accuracy(W_pre, new_test):.3f} (before fine-tuning)")
print(f"\n{'method':26s}{'trainable params':>18s}{'new-domain acc':>16s}{'base-task acc':>15s}")
W_full = train_full(W_pre, list(new_train), epochs=8)
print(f"{'full fine-tune':26s}{C * D:>18d}{accuracy(W_full, new_test):>16.3f}{accuracy(W_full, base_test):>15.3f}")
for r in (1, 2):
random.seed(10 + r)
W_l, n = train_lora(W_pre, list(new_train), r=r, epochs=8)
print(f"{'LoRA r=' + str(r):26s}{n:>18d}{accuracy(W_l, new_test):>16.3f}{accuracy(W_l, base_test):>15.3f}")
print("\n(the base weights stay frozen in LoRA: you can keep one base model and swap small adapters per task/tenant)")pretrained model: base task acc=0.951 | NEW domain acc=0.659 (before fine-tuning)
method trainable params new-domain acc base-task acc
full fine-tune 96 0.906 0.657
LoRA r=1 28 0.953 0.637
LoRA r=2 56 0.854 0.564
(the base weights stay frozen in LoRA: you can keep one base model and swap small adapters per task/tenant)- قبل: الموديل ممتاز على مهمته الأصلية وضعيف على الـ domain الجديد. ده الـ baseline اللي لازم تقيسه الأول.
- LoRA r=1 بعدد parameters أقل بكتير وصل لأداء أعلى من الـ full fine-tune هنا، لأن التغيير الحقيقي low-rank والـ constraint عمل regularization مع 300 مثال بس. وr=2 كان أسوأ: rank أعلى مش أحسن تلقائيًا مع داتا قليلة. الـ rank hyperparameter بيتضبط بالـ eval.
- Forgetting: كل الطرق بعد الدمج نزلت على المهمة الأصلية. مع LoRA الحل بسيط: ما تدمجش؛ استخدم الـ adapter للـ domain الجديد بس واستخدم الـ base من غيره للباقي. ده سبب إن eval «قبل وبعد» لازم يشمل القدرات اللي كانت شغالة، مش المهمة الجديدة بس.
تجهيز الداتا: الجزء اللي بيحدد النتيجة
- الصيغة: محادثات (system/user/assistant) بنفس الـ chat template اللي هتستخدمه في الإنتاج. أي اختلاف = سلوك غريب.
- الجودة أهم من الكمية: مئات لآلاف أمثلة نظيفة ومتسقة غالبًا أحسن من عشرات الآلاف عشوائية. مثال واحد غلط بيتعلّم زي الصح.
- التغطية: نفس شرائح الـ golden set (أنواع الطلبات، اللغات، الحالات الحدية، أمثلة «أرفض»).
- Dedup وتقسيم: ما يبقاش فيه أمثلة متشابهة جدًا في train و eval. والـ golden set بتاع الـ eval ما يدخلش التدريب أبدًا.
- PII والحقوق: البيانات اللي تدخل التدريب بتتحفظ في الأوزان بشكل ما يتمسحش بسهولة (ممكن تطلع بالـ extraction attacks). امسح/استبدل الـ PII، واتأكد إن عندك حق قانوني تدرّب على البيانات دي (عقود العملاء!).
{
"messages": [
{"role": "system", "content": "صنّف تذكرة الدعم. أرجع JSON فقط: {\"category\": ..., \"priority\": ..., \"needs_human\": bool}"},
{"role": "user", "content": "الفاتورة نزلت مرتين على الكارت ومحدش بيرد من امبارح"},
{"role": "assistant", "content": "{\"category\": \"billing\", \"priority\": \"high\", \"needs_human\": true}"}
]
}Training run بـ PEFT و TRL
from datasets import load_dataset
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer
BASE = "<org>/<small-instruct-model>" # choose by licence, language quality (Arabic!) and size; pin the revision
data = load_dataset("json", data_files={"train": "train.jsonl", "eval": "eval.jsonl"})
peft_cfg = LoraConfig(
r=8, lora_alpha=16, lora_dropout=0.05,
target_modules="all-linear", # or the attention projections only; measure both
task_type="CAUSAL_LM",
)
args = SFTConfig(
output_dir="out/ticket-classifier-lora",
num_train_epochs=3,
per_device_train_batch_size=8,
gradient_accumulation_steps=2,
learning_rate=2e-4, # LoRA usually tolerates higher LR than full fine-tuning
lr_scheduler_type="cosine", warmup_ratio=0.05,
eval_strategy="steps", eval_steps=50, save_steps=50,
load_best_model_at_end=True, # keeps the checkpoint with the best eval loss
bf16=True, logging_steps=10, report_to="none",
)
trainer = SFTTrainer(model=BASE, args=args, train_dataset=data["train"], eval_dataset=data["eval"], peft_config=peft_cfg)
trainer.train()
trainer.save_model() # saves only the adapter (small), not the base modelHyperparameters اللي بتفرق: learning rate (أهمهم)، عدد الـ epochs (زيادة = overfitting وحفظ)، r و alpha، والـ target modules. راقب eval loss، لكن القرار النهائي من الـ task eval (accuracy/F1 على الـ golden) مش من الـ loss. والـ API/الأسماء في المكتبات دي بتتغير بين النسخ — ثبّت النسخ في requirements.lock.
Managed fine-tuning: بعض الـ providers (مثلًا OpenAI و Azure OpenAI) بيوفروا fine-tuning لموديلات معينة كخدمة. أسهل في التشغيل، لكن راجع: أنهي موديلات مدعومة حاليًا، التكلفة (تدريب + hosting/inference)، مكان البيانات، وإمكانية تصدير الموديل (غالبًا مش ممكن).
بروتوكول التقييم قبل وبعد
- Baselines قوية: قارن الـ fine-tuned مش بالـ base «عريان»، لكن بأحسن prompt + few-shot على نفس الـ base، وبالموديل الكبير اللي بتحاول تستبدله. لو الـ prompt الكويس بيوصل لنفس الجودة، وفّر الـ fine-tune.
- Held-out golden set ما شافوش التدريب، بالشرائح.
- Regression suite: قدرات تانية الموديل لازم يحتفظ بيها (الأمان، الرفض، لغات تانية، مهام عامة بيستخدمها المنتج). الـ fine-tune ممكن يبوظ safety behaviour بشكل غير متوقع.
- Format compliance: نسبة JSON valid، الالتزام بالـ schema.
- التكلفة والـ latency: جزء من القرار (غالبًا ده سبب الـ fine-tune من الأساس).
- Paired comparison بفواصل ثقة (زي Evaluation Engineering).
| Variant | Macro-F1 | JSON valid | Safety suite | p95 latency | cost/1k |
|---|---|---|---|---|---|
| Large API + few-shot (baseline) | … | … | … | … | … |
| Small base + best prompt | … | … | … | … | … |
| Small + LoRA r=8 | … | … | … | … | … |
| Small + LoRA r=16 | … | … | … | … | … |
(القالب ده يتملي بأرقامك؛ قرار «نطلق الـ fine-tuned» = بيعدّي الـ gates ومش أسوأ في الـ regression suite وأرخص/أسرع بشكل ملموس.)
تخديم الـ adapters
بعض محركات الـ serving (مثلًا vLLM) بتدعم تحميل adapters LoRA متعددة على نفس الـ base وتختار الـ adapter لكل طلب. ده بيسمح بـ «adapter لكل مهمة» أو حتى لكل tenant كبير من غير ما تستضيف موديل كامل لكل واحد.
vllm serve <org>/<small-instruct-model> \
--enable-lora \
--lora-modules ticket-classifier=/adapters/ticket-classifier-lora contract-extractor=/adapters/contract-lora \
--max-lora-rank 16
# Then request "model": "ticket-classifier" on the OpenAI-compatible endpoint.Release discipline: الـ adapter = artifact بـ version و hash و model card (البيانات، التاريخ، النتايج)، ويمشي في نفس الـ release manifest والـ canary زي أي تغيير prompt/model (LLMOps).
Failure modes
- Overfitting/memorization: eval loss بيطلع و training loss بينزل؛ الموديل بيكرر جمل من التدريب حرفيًا.
- Catastrophic forgetting: (المعمل) القدرات العامة أو الـ safety behaviour بتضعف.
- Format drift: اتدرّب على JSON بمفاتيح معينة، والكود اتغير بعدها ← لازم versioning للـ schema مع الـ adapter.
- Data leakage لبيانات العملاء: بيانات tenant اتعلّمت في adapter مشترك ← ممكن تطلع لـ tenant تاني. adapters مشتركة تتدرب على بيانات مسموح مشاركتها بس.
- حق المسح (GDPR): لو عميل طلب مسح بياناته وكانت في التدريب، المسح من الأوزان مش عملي — غالبًا لازم إعادة تدريب من غير البيانات. صمّم من الأول (درس Governance).
- Base model update: الـ provider/المجتمع طلّع نسخة أحسن من الـ base ← الـ adapter القديم مش متوافق؛ لازم إعادة تدريب وتقييم.
حسبة الذاكرة: ليه QLoRA بيخلي 8B يتدرّب على GPU واحد
قبل ما تأجّر GPU، احسب. معظم فشل الـ fine-tuning الأول بيكون «CUDA out of memory» في أول دقيقة.
| المكوّن | Full fine-tune (bf16 + Adam) | LoRA (bf16 base) | QLoRA (4-bit base) |
|---|---|---|---|
| أوزان الموديل 8B | 8B × 2 bytes ≈ 16 GB | ≈ 16 GB (frozen) | 8B × ~0.5 byte ≈ 4–5 GB |
| Gradients | ≈ 16 GB | للـ adapters بس (عشرات MB) | للـ adapters بس |
| Adam states (2 × fp32) | 8B × 8 bytes ≈ 64 GB | للـ adapters بس | للـ adapters بس |
| Activations | بتعتمد على sequence length × batch؛ gradient checkpointing بيقللها على حساب السرعة | ||
| إجمالي تقريبي | > 100 GB (عدة GPUs) | ~20–30 GB | ~10–16 GB (GPU واحد 24 GB كفاية غالبًا) |
عدد بارامترات LoRA: لكل weight matrix بأبعاد d×k، الـ adapter بيضيف r×(d+k). موديل hidden=4096 و r=16 على q,k,v,o في 32 layer: تقريبًا 4 × 32 × 16 × (4096+4096) ≈ 16.8M بارامتر (أقل من 0.25% من 8B) — الأرقام الحقيقية بتختلف مع GQA لأن k/v أصغر. الملف الناتج عشرات الـ MB، وده اللي بيخلي multi-LoRA serving ممكن.
Recipe كامل: QLoRA SFT بـ PEFT و TRL
import torch
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer
BASE = "your-org/base-instruct-8b" # an instruct model whose license allows fine-tuning
tok = AutoTokenizer.from_pretrained(BASE)
bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4",
bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
model = AutoModelForCausalLM.from_pretrained(BASE, quantization_config=bnb, device_map="auto")
# data: JSONL with {"messages": [{"role":"system",...},{"role":"user",...},{"role":"assistant",...}]}
train = load_dataset("json", data_files="data/train.jsonl", split="train")
val = load_dataset("json", data_files="data/val.jsonl", split="train")
peft_cfg = LoraConfig(r=16, lora_alpha=32, lora_dropout=0.05, task_type="CAUSAL_LM",
target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"])
cfg = SFTConfig(
output_dir="out/ticket-lora", num_train_epochs=2, learning_rate=2e-4, lr_scheduler_type="cosine", warmup_ratio=0.03,
per_device_train_batch_size=4, gradient_accumulation_steps=4, # effective batch 16
gradient_checkpointing=True, bf16=True, logging_steps=10,
eval_strategy="steps", eval_steps=100, save_steps=100, save_total_limit=3,
max_length=2048, # truncate long examples (check how many)
assistant_only_loss=True, # learn the answers, not the prompts
seed=42, report_to="none",
)
trainer = SFTTrainer(model=model, args=cfg, train_dataset=train, eval_dataset=val,
processing_class=tok, peft_config=peft_cfg)
trainer.train()
trainer.save_model("out/ticket-lora/final") # saves only the adapter weights| Hyperparameter | نقطة البداية | علامة إنها غلط |
|---|---|---|
| learning_rate | 1e-4 – 2e-4 لـ LoRA | loss بيتذبذب/ينفجر (عالي)، أو ما بيتحركش (واطي) |
| r / alpha | 8–16 / 2×r | r عالي جدًا مع داتا قليلة = overfitting |
| epochs | 1–3 | val loss بيطلع و train بينزل = overfitting؛ اختار checkpoint بالـ eval مش الأخير |
| max_length | حسب توزيع أطوال الداتا | نسبة كبيرة من الأمثلة بتتقطع ← الموديل بيتعلم إجابات ناقصة |
Chat template: لازم الأمثلة تتنسق بنفس الـ template اللي الموديل اتدرب عليه، ونفس الـ template عند الـ inference. اختلاف بسيط (system role، special tokens) = جودة أسوأ من الـ base. ده أشهر bug صامت.
من adapter لـ API: merge أو multi-LoRA
| الطريقة | إمتى | الـ trade-off |
|---|---|---|
Merge في الأوزان (merge_and_unload) | adapter واحد، أقصى سرعة inference | نسخة كاملة من الموديل لكل adapter؛ الدمج يكون على base بدقة كاملة مش 4-bit |
| Multi-LoRA serving (مثلًا vLLM مع LoRA support) | adapter لكل tenant/مهمة على base واحد | overhead بسيط لكل طلب، توفير ضخم في الـ GPUs |
| Managed fine-tuning من provider | ما عندكش MLOps للـ GPUs | أقل تحكم، تكلفة hosting للموديل المخصص، والبيانات بتتبعت للـ provider |
من .NET، الـ serving engine بيتعرض غالبًا كـ OpenAI-compatible endpoint، فالـ IChatClient في التطبيق بيتعامل معاه زي أي موديل، والـ adapter بيتحدد باسم الموديل في الطلب. التفاصيل في Inference & Serving.
Knowledge check
بعد fine-tune، الموديل ممتاز على الـ val set لكن بيرد بشكل غريب في الإنتاج. أول حاجة تتأكد منها؟
ليه QLoRA بيوفر ذاكرة أكتر من LoRA؟
اختبر فهمك
الموديل لازم يجاوب على أسئلة عن سياسات الشركة اللي بتتحدث كل شهر، مع citations. الأنسب؟
ليه B في LoRA بيبدأ بأصفار؟
LoRA fine-tune رفع دقة المهمة الجديدة 20 نقطة. إيه الناقص قبل الإطلاق؟
تمارين محلولة
1: احسب عدد parameters الـ LoRA لـ 32 layer، كل layer فيها 4 projections بـ 4096×4096، r=16
الحل: لكل مصفوفة r(d+k) = 16 × 8192 = 131,072. × 4 × 32 = 16.8 مليون تقريبًا — مقابل 4096² × 4 × 32 ≈ 2.1 مليار للمصفوفات دي في الـ full fine-tune. حجم الـ adapter بـ bf16 ≈ 34 MB.
2: عدّل المعمل: خلّي الـ SHIFT بـ rank 3 (مجموع 3 حواصل ضرب). إيه المتوقع لـ r=1 مقابل r=2/3؟
الحل: r=1 مش هيقدر يمثّل التغيير كله فأداؤه هيقف تحت المستوى الممكن؛ r أعلى هيبقى ليه ميزة لو الداتا كفاية. الدرس: الـ rank المناسب مرتبط بتعقيد التغيير المطلوب وحجم الداتا، ويتحدد تجريبيًا.
3: عميل enterprise عايز «موديل متدرّب على بياناته». إيه التصميم الآمن؟
الحل: أولًا هل RAG كفاية؟ لو لأ: adapter منفصل للـ tenant ده بس، مدرّب في بيئة معزولة، بيانات بعد PII review وبموافقة تعاقدية، يتخزن ويتخدّم بـ ACL على مستوى الـ tenant، model card، وخطة مسح (حذف الـ adapter = حذف أثر البيانات). وما يستخدمش في أي adapter مشترك.
Mini project: Ticket classifier — prompt vs LoRA
Dataset تذاكر دعم (عربي/إنجليزي) بـ 1,500 مثال للتدريب و300 للـ eval. (1) baseline: موديل كبير API + few-shot. (2) موديل صغير مفتوح + أحسن prompt. (3) نفس الصغير + LoRA. املا جدول الـ eval فوق (F1 لكل category، JSON validity، safety suite صغيرة، latency، تكلفة). المخرج: ADR بالقرار والأرقام — حتى لو القرار «ما نعملش fine-tune».
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) إيه الفرق بين RAG و fine-tuning؟
(Senior) اشرح LoRA وليه بيوفر.
(Senior) إزاي تقيّم fine-tune بشكل عادل؟
(Staff) org عايزة «platform للـ fine-tuning» لكل الفرق. إيه اللي تحطه وإيه اللي تمنعه؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.