Software Engineer Encyclopedia
0%
Domain 10 · Python, Machine Learning & Data Engineering · Topic 10.9

هندسة مشروع تعلم آلة تطبيقي

Applied ML Project Engineering

A reproducible path from problem framing and data splitting to evaluation, packaging and release gates.

  • Intermediate
  • ~17 min read
  • 21 sections
  • 6 code examples
  • 1 diagrams
  • 10 questions
  • Priority L2 · Essential
  • Python 3 · scikit-learn (CalibratedClassifierCV, TimeSeriesSplit, GroupKFold) · skl2onnx · ONNX Runtime for .NET · المعمل stdlib (executed)

بعد الدرس ده هتقدر

  • تحوّل طلب بيزنس غامض لقرار وlabel وأفق زمني وmetric مرتبط بالقيمة
  • تكتشف target/temporal/group/preprocessing leakage وتختار temporal أو group validation
  • تعاير الاحتمالات (isotonic/Platt) وتختار threshold من مصفوفة التكلفة
  • تعمل slice analysis وتتعامل مع الشرائح الضعيفة
  • تخدّم موديل scikit-learn من ASP.NET Core بـ ONNX Runtime مع parity tests وfeature contract
  • تكتب model card وتراقب feedback loops وtraining-serving skew

المتطلبات قبل ما تبدأ

مستوى التعمق المطلوب

END-TO-END PRACTICALحوّل تجربة ML إلى منتج قابل لإعادة الإنتاج والقياس والنشر، مع فصل التدريب عن inference.

01

مخرجات التعلم والمتطلبات

Learning outcomes

الدرس ده بيربط ML النظري بدورة حياة مشروع حقيقي. المطلوب معرفة Python و Pandas و scikit-learn ومفاهيم classification/regression. بعده لازم تقدر تكتب experiment plan، تمنع leakage، تختار metric و threshold، وتسلّم artifact له contract واضح.

  • تحويل business question إلى target و prediction unit و decision.
  • اختيار split يحاكي زمن وواقع الاستخدام.
  • بناء preprocessing داخل Pipeline وتسجيل التجارب.
  • تحليل الأخطاء وتحديد release gates قابلة للقياس.
02

صياغة المشكلة قبل اختيار الموديل

Problem framing

ابدأ بتحديد من أو ماذا يتم التنبؤ به، ومتى تتوفر البيانات، ومتى يحدث القرار. في churn مثلًا: prediction unit هو customer في تاريخ snapshot، والـ target هو churn خلال أفق زمني لاحق. لا تستخدم عمودًا لم يكن متاحًا وقت التنبؤ مثل cancellation_date؛ ده leakage حتى لو رفع الأداء.

اكتب baseline بسيطًا قبل النماذج المعقدة: majority class، rule-based، أو logistic regression. حدد تكلفة false positive و false negative، latency، وتواتر إعادة التدريب. النجاح مش أعلى score فقط؛ لازم النموذج يحسن قرارًا حقيقيًا مقارنة بال baseline.

03

تقسيم البيانات ومنع Data Leakage

Split strategy and leakage

Random split مناسب فقط عندما تكون العينات مستقلة والتوزيع ثابتًا تقريبًا. بيانات الزمن تحتاج chronological split. وجود عدة صفوف لنفس العميل أو الجهاز يستدعي group split حتى لا يظهر الشخص نفسه في train و test. اختَر split بناءً على طريقة وصول البيانات في الإنتاج.

أي خطوة تتعلم من البيانات — imputation، scaling، feature selection، vocabulary، target encoding — يجب أن تتعلم من training fold فقط. ضعها داخل Pipeline، ولا تحسب إحصاءات على كامل dataset قبل التقسيم. احتفظ بـ test set مغلقًا حتى نهاية الاختيار.

PythonLeakage-safe tabular pipeline
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.preprocessing import OneHotEncoder, StandardScaler
from sklearn.pipeline import Pipeline
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split

numeric = ["tenure", "monthly_charges"]
categorical = ["contract", "payment_method"]
preprocess = ColumnTransformer([
    ("num", Pipeline([("impute", SimpleImputer(strategy="median")),
                      ("scale", StandardScaler())]), numeric),
    ("cat", Pipeline([("impute", SimpleImputer(strategy="most_frequent")),
                      ("encode", OneHotEncoder(handle_unknown="ignore"))]), categorical)
])
model = Pipeline([("features", preprocess),
                  ("classifier", LogisticRegression(max_iter=1000))])
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y)
model.fit(X_train, y_train)
print(model.score(X_test, y_test))

الكود يوضح مكان التحويلات، لكنه يفترض أن X و y نظيفان وأن random split مناسب للمشكلة. في time/group data استبدل split بالطريقة الصحيحة. لا تعتمد على accuracy وحدها.

04

Validation و Hyperparameter Tuning

Model selection

استخدم validation أو cross-validation لاختيار النموذج والـ hyperparameters. Grid search يجرب مجموعة محددة بالكامل؛ random search يختبر عينات من المساحة وقد يكون أكفأ؛ Bayesian optimization يختار التجارب التالية بناءً على النتائج. لا تكرر النظر إلى test set لتوجيه الاختيار؛ كده يتحول عمليًا إلى validation.

ثبّت random seeds حيث ينطبق، وسجّل dataset version و code commit و parameters و metrics و environment. الـ seed وحده لا يضمن reproducibility كاملة مع GPU أو عمليات غير حتمية أو تغير dependencies.

05

Metrics و Calibration و Threshold

Decision-aware evaluation

في classification غير المتوازن، راجع confusion matrix و precision و recall و F1 و PR-AUC. ROC-AUC مفيد لترتيب الحالات عبر thresholds لكنه قد يبدو متفائلًا مع ندرة الفئة الإيجابية. اختَر metric يعكس القرار، واعرض الأداء لكل شريحة مهمة.

احتمال 0.8 لا يعني بالضرورة أن 80% من الحالات المشابهة ستحدث؛ افحص calibration plot و Brier score، واستخدم calibration على بيانات مستقلة مناسبة عند الحاجة. threshold ليس خاصية ثابتة للموديل: اختَره بناءً على تكلفة القرار وقدرة فريق التشغيل، ثم راقب تغيره.

06

Error Analysis و Slice Evaluation

Understand where the model fails

قسّم الأخطاء حسب الوقت، نوع العميل، مصدر البيانات، اللغة، missingness، وقيم feature المهمة. راجع false positives و false negatives يدويًا بعينة محكومة. ابحث عن label noise، تغيّر تعريف target، بيانات مفقودة بصورة غير عشوائية، وشرائح لا تمثلها بيانات التدريب.

لا تستنتج العدالة من metric إجمالي. افحص الفروق بين المجموعات ذات الصلة قانونيًا وأخلاقيًا، واحذر أن بعض السمات proxy لسمات حساسة. قرارات الاستخدام والقيود تحتاج مراجعة بشرية ومجالًا قانونيًا مناسبًا.

Slice analysis: المتوسط بيكدب

Pythonslices.py
import pandas as pd
from sklearn.metrics import average_precision_score, brier_score_loss

def slice_report(df: pd.DataFrame, score="p_cal", label="churn_30d", by=("plan", "tenure_bucket", "region")):
    rows = []
    for col in by:
        for value, g in df.groupby(col):
            if g[label].nunique() < 2 or len(g) < 200:          # tiny slices -> noisy metrics; flag them instead
                rows.append({"slice": f"{col}={value}", "n": len(g), "note": "too small"})
                continue
            rows.append({
                "slice": f"{col}={value}", "n": len(g), "base_rate": round(g[label].mean(), 3),
                "ap": round(average_precision_score(g[label], g[score]), 3),
                "brier": round(brier_score_loss(g[label], g[score]), 4),
            })
    return pd.DataFrame(rows).sort_values("ap", na_position="last")

بعد ما تلاقي slice ضعيف: (1) هل فيه داتا كفاية؟ (2) هل الـ features بتعني حاجة للـ slice ده (العميل الجديد ما عندوش «تاريخ استخدام»)؟ (3) حل منفصل (rule أو موديل للـ slice) أحسن من إجبار موديل واحد. (4) لو الـ slice حساس (منطقة، فئة عملاء)، ده كمان سؤال fairness (الدرس في ML Fundamentals).

07

تسجيل التجارب وإدارة النماذج

Experiment and artifact management

كل تجربة يجب أن ترتبط بـ dataset fingerprint/version، commit، parameters، metrics، artifacts، ووقت التنفيذ. استخدم experiment tracker مثل MLflow أو بديلًا داخليًا. لا تخزن بيانات شخصية خام في سجل التجارب. افصل model registry عن مجرد مجلد ملفات، وعرّف حالات مثل candidate و staging و production و archived مع صلاحيات وتاريخ اعتماد.

Model artifact يتضمن preprocessing المتعلم مع estimator، schema للمدخلات، إصدار dependencies، model version، training window، و known limitations. احتفظ بإمكانية إعادة بناء البيئة، ولا تحمّل pickle/joblib من مصدر غير موثوق؛ فكّ serialization قد ينفذ كودًا.

08

Batch و Online Inference و Contract

Serving architecture

Batch inference مناسب عندما يمكن معالجة آلاف السجلات دوريًا وتخزين النتائج. Online inference مناسب لقرار تفاعلي ويتطلب latency budget و timeouts وتحمّل أعطال. أحيانًا hybrid architecture أفضل: scoring دوري مع إعادة تقييم عند event معين.

عقد API يجب أن يحدد schema، required/optional fields، units، null behavior، validation، model_version، request_id، error format، وحدود الحجم. لا تخلط بين probability و business decision؛ يمكن للـ backend تطبيق threshold و authorization وقواعد العمل. عند تحديث model schema استخدم versioning واختبارات توافق.

09

Release Gates و Rollback

Production readiness
  • Data contract validation واكتشاف schema drift.
  • Offline metrics تتجاوز baseline وحدودًا متفقًا عليها.
  • Latency و memory و throughput ضمن SLO.
  • Security/privacy review و dependency scanning.
  • Canary أو shadow evaluation قبل التعميم.
  • Rollback موثق إلى artifact سابق.

لا تطلق نموذجًا لمجرد نجاح notebook. افصل training pipeline عن serving process، واختبر artifact بعد تحميله في بيئة نظيفة، مع بيانات edge cases وحدود input.

10

مشروع تطبيقي ومعايير الإتقان

Capstone

ابنِ churn prediction pipeline: dataset snapshot مؤرخ، split زمني أو group-aware، baseline، preprocessing pipeline، cross-validation، calibration، error analysis، تسجيل التجربة، ثم inference API. سلّم model card و API contract و README لإعادة التشغيل ونتائج مقارنة بال baseline.

  1. اكتب تعريف target وتاريخ snapshot وأي feature غير متاح وقت القرار.
  2. قارن baseline مع نموذجين على split ثابت.
  3. اعرض precision/recall و PR-AUC و calibration حسب الشرائح.
  4. اختبر missing fields و unknown categories و out-of-range values.
  5. نفّذ shadow release تجريبيًا مع عدم اتخاذ قرار حقيقي.
لماذا لا نستخدم test set في كل تجربة؟
لأن تكرار الاختيار بناءً على test يسرّب معلوماته إلى عملية التطوير ويجعل تقدير الأداء متفائلًا.
هل threshold يساوي 0.5 دائمًا؟
لا؛ يتحدد حسب calibration وتكلفة الأخطاء وسعة التشغيل والقرار المطلوب.
هل حفظ model.pkl وحده كافٍ؟
لا؛ نحتاج preprocessing و schema ونسخ البيانات والكود والاعتماديات والـ metrics وسجل إصدار.
11

من Notebook لـ Artifact: Packaging و Contract Tests و Release Gate

A model bundle with its metadata, input contract, golden predictions and a promotion gate — executed
Practical

موديل دقته عالية في notebook مش منتج. المنتج هو artifact تقدر تجاوب عنه: اتدرّب على إيه؟ بأنهي كود ومكتبات؟ بيقبل إيه كـ input؟ هل النسخة دي بتدّي نفس التوقعات اللي اتوافق عليها؟ وهل هي أحسن من اللي في الإنتاج؟ الكود ده بيبني الـ bundle ده وبيشغّل الاختبارات اللي بتحميه.

Pythonpackage_model.py — train, bundle with metadata, validate inputs, golden-prediction test, promotion gateExecuted ✓
import hashlib, io, json, platform
import joblib, numpy as np, pandas as pd, sklearn
from sklearn.compose import ColumnTransformer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import average_precision_score
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

rng = np.random.default_rng(42)
n = 3000
df = pd.DataFrame({"tenure_months": rng.integers(1, 72, n), "monthly_charge": rng.normal(60, 20, n).round(2).clip(5),
                   "plan": rng.choice(["basic", "plus", "pro"], n)})
logit = -1.2 - 0.04 * df.tenure_months + 0.02 * df.monthly_charge + np.where(df.plan == "basic", 0.7, 0)
df["churned"] = (rng.random(n) < 1 / (1 + np.exp(-logit))).astype(int)

X, y = df.drop(columns="churned"), df.churned
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.25, stratify=y, random_state=0)

def train(C):
    prep = ColumnTransformer([("num", StandardScaler(), ["tenure_months", "monthly_charge"]),
                              ("cat", OneHotEncoder(handle_unknown="ignore"), ["plan"])])
    return Pipeline([("prep", prep), ("clf", LogisticRegression(C=C, max_iter=1000))]).fit(X_tr, y_tr)

# ---------- 1) the input contract travels WITH the model ----------
SCHEMA = {"tenure_months": {"type": "int", "min": 0, "max": 600},
          "monthly_charge": {"type": "float", "min": 0, "max": 10_000},
          "plan": {"type": "str", "allowed": ["basic", "plus", "pro"]}}

def validate(row, schema):
    errors = [f"missing field '{k}'" for k in schema if k not in row] + [f"unexpected field '{k}'" for k in row if k not in schema]
    for k, rule in schema.items():
        if k not in row: continue
        v = row[k]
        if rule["type"] in ("int", "float"):
            if isinstance(v, bool) or not isinstance(v, (int, float)): errors.append(f"'{k}' must be a number")
            elif not rule["min"] <= v <= rule["max"]: errors.append(f"'{k}'={v} outside [{rule['min']}, {rule['max']}]")
        elif v not in rule["allowed"]: errors.append(f"'{k}'={v!r} not in {rule['allowed']}")
    return errors

# ---------- 2) bundle = model bytes + everything needed to reproduce and to check it ----------
def bundle(model, version):
    buf = io.BytesIO(); joblib.dump(model, buf); blob = buf.getvalue()
    golden_inputs = [{"tenure_months": 2, "monthly_charge": 95.0, "plan": "basic"},
                     {"tenure_months": 60, "monthly_charge": 30.0, "plan": "pro"},
                     {"tenure_months": 24, "monthly_charge": 60.0, "plan": "plus"}]
    golden = [round(float(p), 6) for p in model.predict_proba(pd.DataFrame(golden_inputs))[:, 1]]
    meta = {"name": "churn", "version": version, "sha256": hashlib.sha256(blob).hexdigest()[:16],
            "python": platform.python_version(), "sklearn": sklearn.__version__, "numpy": np.__version__,
            "training_rows": len(X_tr), "training_data_sha256": hashlib.sha256(pd.util.hash_pandas_object(X_tr).values.tobytes()).hexdigest()[:16],
            "metrics": {"pr_auc_test": round(float(average_precision_score(y_te, model.predict_proba(X_te)[:, 1])), 4)},
            "schema": SCHEMA, "golden": {"inputs": golden_inputs, "expected": golden}}
    return blob, meta

# ---------- 3) what the serving side does at startup and per request ----------
def load_and_verify(blob, meta):
    if hashlib.sha256(blob).hexdigest()[:16] != meta["sha256"]:
        raise RuntimeError("artifact bytes do not match the recorded hash")
    if sklearn.__version__ != meta["sklearn"]:
        raise RuntimeError(f"trained with scikit-learn {meta['sklearn']}, running {sklearn.__version__}")
    model = joblib.load(io.BytesIO(blob))
    got = model.predict_proba(pd.DataFrame(meta["golden"]["inputs"]))[:, 1]
    if not np.allclose(got, meta["golden"]["expected"], atol=1e-6):
        raise RuntimeError("golden predictions changed: environment or preprocessing drifted")
    return model

def predict(model, meta, row):
    errors = validate(row, meta["schema"])
    if errors:
        return {"status": 422, "errors": errors}
    return {"status": 200, "churn_probability": round(float(model.predict_proba(pd.DataFrame([row]))[0, 1]), 4), "model_version": meta["version"]}

prod_blob, prod_meta = bundle(train(C=0.01), version=13)        # what is live today
cand_blob, cand_meta = bundle(train(C=1.0), version=14)         # the candidate
print("bundle metadata:", json.dumps({k: cand_meta[k] for k in ("name", "version", "sha256", "sklearn", "training_rows", "metrics")}))

model = load_and_verify(cand_blob, cand_meta)
print("startup checks passed: hash, library version, golden predictions")
for row in [{"tenure_months": 3, "monthly_charge": 80.0, "plan": "basic"},
            {"tenure_months": 3, "monthly_charge": 80.0, "plan": "enterprise"},
            {"tenure_months": -5, "monthly_charge": "80", "plan": "basic", "ssn": "x"}]:
    print("  predict ->", predict(model, cand_meta, row))

tampered = bytearray(cand_blob); tampered[len(tampered) // 2] ^= 0xFF
try:
    load_and_verify(bytes(tampered), cand_meta)
except RuntimeError as e:
    print("corrupted artifact rejected:", e)

# ---------- 4) promotion gate: explicit, automated, recorded ----------
old, new = prod_meta["metrics"]["pr_auc_test"], cand_meta["metrics"]["pr_auc_test"]
checks = {"metric not worse than production (tolerance 0.005)": new >= old - 0.005,
          "schema unchanged (no breaking change for callers)": cand_meta["schema"] == prod_meta["schema"],
          "trained on the same data snapshot": cand_meta["training_data_sha256"] == prod_meta["training_data_sha256"]}
print(f"\npromotion gate: v{prod_meta['version']} PR-AUC={old} -> v{cand_meta['version']} PR-AUC={new}")
for name, ok in checks.items():
    print(f"  [{'pass' if ok else 'FAIL'}] {name}")
print("decision:", "PROMOTE to canary" if all(checks.values()) else "BLOCK")
ConsoleOutput — captured from a real run
bundle metadata: {"name": "churn", "version": 14, "sha256": "dfbd710cfb4da3b1", "sklearn": "1.9.1", "training_rows": 2250, "metrics": {"pr_auc_test": 0.5245}}
startup checks passed: hash, library version, golden predictions
  predict -> {'status': 200, 'churn_probability': 0.7504, 'model_version': 14}
  predict -> {'status': 422, 'errors': ["'plan'='enterprise' not in ['basic', 'plus', 'pro']"]}
  predict -> {'status': 422, 'errors': ["unexpected field 'ssn'", "'tenure_months'=-5 outside [0, 600]", "'monthly_charge' must be a number"]}
corrupted artifact rejected: artifact bytes do not match the recorded hash

promotion gate: v13 PR-AUC=0.5275 -> v14 PR-AUC=0.5245
  [pass] metric not worse than production (tolerance 0.005)
  [pass] schema unchanged (no breaking change for callers)
  [pass] trained on the same data snapshot
decision: PROMOTE to canary

الـ schema جوه الـ bundle مش في كود الخدمة: الموديل اتدرّب على 3 خطط؛ "enterprise" قيمة عمره ما شافها. الـ OneHotEncoder(handle_unknown="ignore") كان هيعدّيها في صمت ويرجّع احتمال شكله طبيعي. الـ validation بيرفضها بـ 422 برسالة واضحة — وده أحسن من توقع غلط بثقة.

الـ golden predictions: 3 مدخلات ثابتة وناتجها المتوقع متسجلين وقت التدريب. عند الـ startup الخدمة بتعيد حسابهم؛ لو اختلفوا يبقى فيه حاجة اتغيرت بين التدريب والـ serving (نسخة مكتبة، ترتيب أعمدة، preprocessing). ده بيمسك أشهر عطل في نشر الموديلات — training/serving skew — قبل ما أول request يوصل.

فحص نسخة المكتبة: ملفات joblib/pickle مش مضمونة بين نسخ scikit-learn. والأهم: joblib.load بينفّذ كود — ما تحمّلش artifact من مصدر مش موثوق. الـ hash بيثبت إن الملف هو اللي اتبنى في الـ pipeline بتاعك.

الـ gate: لاحظ إن النسخة 14 مش أحسن من 13 (0.5245 مقابل 0.5275) — عدّت لأن القاعدة «مش أسوأ بأكتر من 0.005»، وفرق بالحجم ده جوه الضوضاء. الـ gate بيمنع التراجع؛ هل تستاهل تنزّل نسخة مش أحسن ده قرار تاني (ممكن آه لو اتدرّبت على بيانات أحدث). قواعد صريحة بتتشغّل في الـ CI ونتيجتها بتتسجل. لو الـ schema اتغير، ده breaking change للـ callers ومحتاج تنسيق مش مجرد deploy. والخطوة اللي بعد الـ gate مش «production» — هي canary أو shadow (شوف درس الـ MLOps).

الخدمة شغالة ومفيش errors، لكن التوقعات كلها بقت قريبة من 0.5 بعد deploy جديد لخدمة الـ serving (الموديل نفسه ما اتغيرش). أرجح سبب؟

12

خريطة تغطية الأهداف

Learning objective coverage

الأهداف العشرة المدرجة في خريطة المنهج تم تناولها عبر الأقسام والتمارين أعلاه. التغطية تعني وجود شرح أو نشاط تعليمي، ولا تعني الإتقان أو الاعتماد أو الجاهزية الإنتاجية دون تنفيذ المشروع والاختبارات.

13

حالة كاملة: Churn prediction من السؤال للـ endpoint

An end-to-end worked case
Deep dive

هنمشي حالة واحدة واقعية من أولها لآخرها، لأن معظم مشاريع الـ ML بتفشل في الربط بين المراحل مش في اختيار الموديل. الشركة: SaaS اشتراكات. الطلب من الإدارة: «عايزين نعرف العملاء اللي هيلغوا».

Decisionwho gets an offer?Label + cutoffchurn in next 30dPoint-in-timefeatures ≤ cutoffTemporal CVtrain past → test futureCalibrate + costthreshold from €Slice analysisplan · region · agePackageONNX + model cardServe + monitor.NET · drift · uplift
Applied ML project flow: every arrow is a contract you can test
  1. القرار مش التنبؤ: السؤال الحقيقي «لمين نبعت عرض خصم؟». ده بيحدد كل حاجة بعد كده: الـ metric (قيمة مالية مش accuracy)، الأفق الزمني (العرض محتاج وقت يأثر = نتنبأ 30 يوم قدام)، والـ threshold.
  2. تعريف الـ label بدقة: «churn» = الاشتراك اتلغى أو ما اتجددش خلال 30 يوم بعد تاريخ القطع (cutoff). العملاء اللي اشتراكهم بيخلص بعد 90 يوم؟ مش في نفس المشكلة. التعريف الغامض هنا بيبوّظ كل الأرقام بعدين.
  3. Features بالـ point-in-time: كل feature محسوبة من بيانات قبل الـ cutoff بس (عدد الـ logins آخر 14 يوم قبل الـ cutoff، مش «آخر 14 يوم» النهارده). الـ join الغلط هنا هو أشهر مصدر leakage (الـ lesson السابق في Data Engineering شرح الـ point-in-time joins).
  4. Validation زمني: تدريب على يناير–يونيو، اختبار على يوليو–أغسطس. الـ random split بيخلي الموديل يشوف «المستقبل».
  5. Calibration + threshold من التكلفة (المعمل تحت).
  6. Slice analysis: الأداء على العملاء الجدد (أقل من 60 يوم تاريخ) غالبًا أسوأ بكتير — يمكن محتاجين قاعدة منفصلة.
  7. Serving + monitoring: batch يومي بيكتب scores في الـ DB، والـ CRM بيعرضها. والـ monitoring الحقيقي مش AUC بس: هل العروض قللت الـ churn؟ (ده محتاج holdout group — uplift).
14

Leakage: أربع حالات حقيقية وإزاي تكتشفها

Target, temporal, group and preprocessing leakage
Deep dive
النوعمثالالعَرَضالكشف
Target leakagefeature «عدد تذاكر الإلغاء» — بتتكتب بعد ما العميل قرر يلغيAUC 0.99 في التجربة، 0.6 في الإنتاجfeature importance: feature واحدة مسيطرة؟ اسأل «القيمة دي كانت معروفة وقت التنبؤ؟»
Temporal leakagerandom split على بيانات زمنية؛ أو feature محسوبة بـ «النهارده»أداء ممتاز offline، وتدهور فوريtemporal split؛ مراجعة كل feature بتاريخ الـ cutoff
Group leakageنفس العميل له صفوف في train و test (كل شهر صف)الموديل «بيعرف» العميلGroupKFold بالـ customer_id
Preprocessing leakagescaling/imputation/target encoding على الداتا كلها قبل التقسيمتحسن صغير وهميكل التحويلات جوه Pipeline بيتعمل fit على train بس
Pythonvalidation.py
from sklearn.model_selection import GroupKFold, TimeSeriesSplit, cross_validate
from sklearn.pipeline import Pipeline
from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import OneHotEncoder, StandardScaler
from sklearn.ensemble import HistGradientBoostingClassifier

pre = ColumnTransformer([
    ("num", StandardScaler(), NUMERIC),
    ("cat", OneHotEncoder(handle_unknown="ignore", min_frequency=20), CATEGORICAL),
])
model = Pipeline([("pre", pre), ("clf", HistGradientBoostingClassifier(max_iter=300, learning_rate=0.05))])

# Rows are (customer, month) snapshots sorted by cutoff_date.
df = df.sort_values("cutoff_date")
X, y, groups = df[NUMERIC + CATEGORICAL], df["churn_30d"], df["customer_id"]

# 1) Temporal: always train on the past, evaluate on the future.
temporal = cross_validate(model, X, y, cv=TimeSeriesSplit(n_splits=5), scoring=["roc_auc", "average_precision"])
# 2) Group: a customer never appears on both sides (use when time is less important than identity).
grouped = cross_validate(model, X, y, cv=GroupKFold(n_splits=5), groups=groups, scoring=["roc_auc", "average_precision"])
print("temporal AP", temporal["test_average_precision"].round(3), "grouped AP", grouped["test_average_precision"].round(3))

ليه average precision (PR-AUC) مش ROC-AUC بس؟ مع 8% positives، الـ ROC-AUC ممكن يبان عالي والموديل عمليًا مش مفيد في أعلى الـ list (اللي هتبعتلهم عروض). الـ PR-AUC بيركّز على الـ positives. ولو قيمة الـ ROC-AUC اتغيرت جامد بين temporal و random split، ده تحذير leakage.

15

معمل: Calibration و threshold من التكلفة (مش 0.5)

Executed lab: reliability, isotonic calibration and expected-value thresholding
Practical

ليه calibration؟ كتير من الموديلات بترتّب صح (AUC كويس) لكن الأرقام نفسها مش احتمالات: «0.3» ممكن تكون في الحقيقة 90%. لو هتستخدم الـ score في قرار مالي (توقع خسارة، أولوية، تسعير)، محتاج احتمالات حقيقية. الـ calibration بيتعلم mapping من الـ score للاحتمال الفعلي على held-out set منفصل عن التدريب.

ليه مش threshold 0.5؟ الـ threshold الصح بييجي من التكاليف: نبعت عرض لو p × قيمة_الإنقاذ > تكلفة_العرض. المعمل بيحاكي موديل scores بتاعته مش calibrated، بيصلّحه بـ isotonic (Pool-Adjacent-Violators)، وبيختار الـ threshold بالقيمة المتوقعة.

Pythonappliedml_lab.pyExecuted ✓
import random, math
random.seed(5)

# Churn-like problem: 8% positives. A model outputs MISCALIBRATED scores (ranking is good, probabilities are wrong).
def make(n):
    rows = []
    for _ in range(n):
        y = 1 if random.random() < 0.08 else 0
        true_p = 0.04 + 0.5 * y * random.random() + 0.1 * random.random()      # latent risk
        logit = math.log(true_p / (1 - true_p)) * 1.8 + random.gauss(0, 0.6)   # distorted scale
        rows.append((1 / (1 + math.exp(-logit)), y))
    return rows
train_cal, test = make(4000), make(6000)

def reliability(rows, bins=5):
    out = []
    for b in range(bins):
        lo, hi = b / bins, (b + 1) / bins
        sel = [(p, y) for p, y in rows if lo <= p < hi or (b == bins - 1 and p == 1)]
        if sel:
            out.append(f"[{lo:.1f},{hi:.1f}) n={len(sel):4d} mean_pred={sum(p for p,_ in sel)/len(sel):.2f} observed={sum(y for _,y in sel)/len(sel):.2f}")
    return out

def brier(rows): return sum((p - y) ** 2 for p, y in rows) / len(rows)

# Isotonic-style calibration via Pool-Adjacent-Violators on a held-out calibration set.
def fit_pav(rows):
    pts = sorted(rows)
    blocks = [[p, y, 1] for p, y in pts]          # [max_score, sum_y, count]
    merged = []
    for b in blocks:
        merged.append(b)
        while len(merged) > 1 and merged[-2][1] / merged[-2][2] > merged[-1][1] / merged[-1][2]:
            hi = merged.pop(); lo = merged.pop()
            merged.append([hi[0], lo[1] + hi[1], lo[2] + hi[2]])
    return [(m[0], m[1] / m[2]) for m in merged]
def apply_pav(model, p):
    for thr, val in model:
        if p <= thr: return val
    return model[-1][1]

cal = fit_pav(train_cal)
test_cal = [(apply_pav(cal, p), y) for p, y in test]
print("BEFORE calibration  Brier=%.4f" % brier(test)); [print("  ", r) for r in reliability(test)]
print("AFTER  calibration  Brier=%.4f" % brier(test_cal)); [print("  ", r) for r in reliability(test_cal)]

# Threshold from business costs: a retention offer costs 10; losing a churner costs 200; the offer saves 30% of churners.
COST_OFFER, LOSS, SAVE_RATE = 10, 200, 0.30
def expected_value(rows, thr):
    v = 0
    for p, y in rows:
        if p >= thr:
            v -= COST_OFFER
            if y == 1: v += LOSS * SAVE_RATE
    return v
print("\nthreshold  offers  value(calibrated scores)")
best = max((expected_value(test_cal, t / 100), t / 100) for t in range(2, 80, 2))
for t in (0.05, 0.10, 0.15, 0.20, 0.30, 0.50):
    print(f"  {t:.2f}    {sum(1 for p,_ in test_cal if p >= t):5d}   {expected_value(test_cal, t):9.0f}")
print(f"best threshold ~ {best[1]:.2f} (value {best[0]:.0f}); theory: act when p*{LOSS}*{SAVE_RATE} > {COST_OFFER} -> p > {COST_OFFER/(LOSS*SAVE_RATE):.3f}")
ConsoleOutput — captured from a real run
BEFORE calibration  Brier=0.0458
   [0.0,0.2) n=5745 mean_pred=0.02 observed=0.04
   [0.2,0.4) n= 111 mean_pred=0.29 observed=0.99
   [0.4,0.6) n=  94 mean_pred=0.50 observed=1.00
   [0.6,0.8) n=  47 mean_pred=0.68 observed=1.00
   [0.8,1.0) n=   3 mean_pred=0.85 observed=1.00
AFTER  calibration  Brier=0.0258
   [0.0,0.2) n=5465 mean_pred=0.02 observed=0.02
   [0.2,0.4) n= 183 mean_pred=0.23 observed=0.20
   [0.4,0.6) n=   7 mean_pred=0.57 observed=0.29
   [0.6,0.8) n=  46 mean_pred=0.64 observed=0.70
   [0.8,1.0) n= 299 mean_pred=0.99 observed=0.97

threshold  offers  value(calibrated scores)
  0.05      978       14460
  0.10      535       16310
  0.15      535       16310
  0.20      535       16310
  0.30      352       15980
  0.50      352       15980
best threshold ~ 0.22 (value 16380); theory: act when p*200*0.3 > 10 -> p > 0.167
  • قبل الـ calibration: الـ bin اللي متوسط تنبؤه ~0.29 كان فعليًا تقريبًا كله churn. يعني لو حد قرأ «29%» وقرر إن العميل «مش خطر»، غلط كبير. بعد الـ calibration الأرقام قربت من الواقع والـ Brier score نزل بشكل واضح.
  • أفضل threshold طلع قريب من الحد النظري تكلفة/(خسارة × نسبة الإنقاذ) وبعيد جدًا عن 0.5. الـ threshold ده بيتغير لما الأسعار أو نسبة نجاح العرض تتغير — خليه config مش hard-coded.
  • في scikit-learn: CalibratedClassifierCV(method="isotonic"|"sigmoid"). isotonic محتاج داتا أكتر (ممكن يعمل overfit على عينة صغيرة)؛ sigmoid (Platt) أبسط وأثبت مع داتا قليلة.
16

Serving من ‎.NET: ONNX Runtime في ASP.NET Core

Serving a scikit-learn model from C# via ONNX
Practical

ليه ONNX؟ الـ backend بتاعك ASP.NET Core، والموديل اتدرّب في Python. اختيارات: (1) Python service منفصل (FastAPI) — مرن لكن service زيادة للتشغيل. (2) تصدير الموديل لـ ONNX وتشغيله in-process في ‎.NET بـ ONNX Runtime — latency أقل ومن غير hop شبكة، بس مش كل الـ transformers والموديلات بتتحول بسهولة (skl2onnx بيدعم معظم الـ pipelines الشائعة؛ اختبر التحويل). القرار حسب الموديل والفريق — ومهم: اختبار تطابق بين Python و ONNX على نفس الصفوف.

Pythonexport_onnx.py
from skl2onnx import to_onnx
import numpy as np, onnxruntime as ort

onx = to_onnx(model, X_train[:1].astype(np.float32), target_opset=17)   # numeric pipeline example
open("churn-v7.onnx", "wb").write(onx.SerializeToString())

# Parity test: ONNX must reproduce sklearn probabilities on held-out rows.
sess = ort.InferenceSession("churn-v7.onnx")
onnx_p = sess.run(None, {sess.get_inputs()[0].name: X_test[:500].astype(np.float32)})[1]
skl_p = model.predict_proba(X_test[:500])
assert np.allclose([r[1] for r in onnx_p], skl_p[:, 1], atol=1e-4), "ONNX parity failed"
C#ChurnScorer.cs
public sealed class ChurnScorer : IDisposable
{
    private readonly InferenceSession _session;
    private readonly string _input;
    private readonly ICalibrator _calibrator;           // the isotonic table exported as JSON, versioned with the model

    public ChurnScorer(string modelPath, ICalibrator calibrator)
    {
        _session = new InferenceSession(modelPath);    // thread-safe for concurrent Run calls; register as singleton
        _input = _session.InputMetadata.Keys.Single();
        _calibrator = calibrator;
    }

    public float Score(ReadOnlySpan<float> features)
    {
        var tensor = new DenseTensor<float>(features.ToArray(), [1, features.Length]);
        using var results = _session.Run([NamedOnnxValue.CreateFromTensor(_input, tensor)]);
        // skl2onnx classifiers return [label, probabilities]; the second output is a sequence of maps.
        var probs = results.ElementAt(1).AsEnumerable<NamedOnnxValue>().First().AsDictionary<long, float>();
        return _calibrator.Apply(probs[1]);
    }

    public void Dispose() => _session.Dispose();
}

Feature contract: أخطر bug في الـ serving هو إن ترتيب أو معنى الـ features في ‎.NET يختلف عن التدريب. خلي فيه ملف features.json (الأسماء، الترتيب، الأنواع، القيم الافتراضية) بيتولد مع الموديل، والـ C#‎ بيبني الـ vector منه، و contract test بيتأكد إن نفس الصف بيدي نفس الـ score في الاتنين.

17

Model card لموديل الـ churn

Documenting what the model is, and is not, for
Basics
Markdownmodels/churn-v7/MODEL_CARD.md
# churn-v7
- **Decision supported:** who receives a retention offer (human CSM reviews top 200/day).
- **Label:** subscription cancelled or not renewed within 30 days after cutoff.
- **Training data:** snapshots 2025-01..2026-06, tenants on paid plans; excludes trials (< 14 days).
- **Validation:** TimeSeriesSplit (5 folds) + holdout 2026-07..08. AP 0.41 (holdout), Brier 0.026 after isotonic.
- **Known weak slices:** tenure < 60 days (AP 0.18) -> rule-based fallback; region=MEA small sample.
- **Threshold:** expected-value rule, p > cost/(loss*save_rate); config `Churn:Threshold`.
- **Not for:** credit decisions, pricing individual customers, any automated account action.
- **Monitoring:** PSI on top-10 features weekly; calibration drift monthly; offer uplift vs 10% holdout.
- **Owner / rollback:** team-growth-ml; previous version churn-v6 kept warm for 30 days.
18

Failure modes في الإنتاج: feedback loops و training-serving skew

Production failure modes and detection
Pitfalls
  • Feedback loop: العروض نجحت ← العملاء ما لغوش ← الموديل الجاي يتعلم إن «الناس دي ما بتلغيش» ← يبطّل يرشحهم. الحل: holdout group ما بيوصلهاش عروض، والتدريب على الـ holdout أو بتصحيح.
  • Training-serving skew: feature محسوبة بطريقة مختلفة في الـ batch job عن التدريب (timezone، تعريف «نشط»). الكشف: سجّل الـ features وقت التنبؤ وقارن توزيعها بالتدريب.
  • Silent upstream change: فريق تاني غيّر event name ← feature بقت صفر للكل. الكشف: data quality checks (نسبة nulls/zeros) قبل التنبؤ، وتوقف الـ batch لو اتكسرت.
  • Calibration drift: الـ base rate اتغير (موسم، تغيير أسعار) ← الاحتمالات بقت غلط مع إن الترتيب سليم. راقب predicted vs observed شهريًا.
19

Knowledge check

Check your understanding
Basics

الموديل جاب ROC-AUC 0.97 بـ random split و0.71 بـ temporal split. إيه التفسير الأرجح؟

عرض الاحتفاظ يكلف 10، وإنقاذ العميل يوفر 60 في المتوسط. نبعت العرض لما الاحتمال المعاير أكبر من؟

20

تمارين محلولة

Solved exercises
Practical
1: عدّل المعمل: تكلفة العرض بقت 25. الـ threshold يروح فين؟

الحل: الحد النظري = 25/(200×0.3) ≈ 0.417. هتلاقي أفضل threshold اتنقل لفوق وعدد العروض قل، والقيمة الإجمالية قلت. لاحظ إن الـ threshold اتغير من غير ما الموديل يتغير — عشان كده الـ threshold config بيملكه البيزنس مع الـ ML.

2: الـ PM عايز accuracy 95%. ردك؟

الحل: مع 8% churn، موديل بيقول «مش هيلغي» للكل بياخد 92% accuracy ومفيدش. اقترح metric مرتبط بالقرار: القيمة المتوقعة من العروض، أو precision في أعلى 200 عميل يوميًا (لأن الـ CSM بيراجع 200 بس)، و uplift مقابل holdout.

3: الـ ONNX parity test فشل بفرق 0.03 في بعض الصفوف. تحقق إزاي؟

الحل: (1) أنواع البيانات (float64 في sklearn vs float32 في ONNX) — الفروق الصغيرة طبيعية، 0.03 مش طبيعي. (2) categorical encoding: ترتيب الفئات أو handle_unknown مختلف. (3) خطوة preprocessing مش مدعومة اتحولت بشكل تقريبي. اعزل: قارن output كل خطوة في الـ pipeline لوحدها.

21

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) إيه هو data leakage واديني مثال.
معلومة متاحة وقت التدريب ومش متاحة وقت التنبؤ. مثال: scaling على الداتا كلها قبل التقسيم، أو feature بتتسجل بعد حصول الحدث.
(Senior) إزاي تختار الـ threshold لموديل تصنيف؟
من القرار والتكاليف: احتمالات calibrated، مصفوفة تكلفة/قيمة لكل نتيجة، واختيار الحد اللي بيعظّم القيمة المتوقعة، مع قيود تشغيلية (سعة المراجعة اليومية). والـ threshold config بيتراجع لما الأسعار تتغير.
(Senior) الموديل شغال في الإنتاج 6 شهور والـ AUC ثابت، لكن البيزنس بيقول مفيش فايدة. ليه ممكن؟
AUC بيقيس الترتيب مش الأثر. ممكن العروض مش بتغيّر السلوك (uplift صفر)، أو الـ feedback loop، أو الـ threshold قديم. محتاج holdout وقياس الأثر السببي مش دقة التنبؤ بس.
(Staff) فريق الـ ML وفريق الـ ‎.NET بيتخانقوا على مكان الموديل (Python service vs ONNX in-process). إزاي تحسم؟
ADR بمعايير: latency budget، عدد الموديلات ودورة تحديثها، دعم الـ ONNX للموديل، مهارات الفريق، الـ observability. غالبًا: موديلات tabular بسيطة ← ONNX in-process مع parity tests؛ موديلات معقدة/GPU/تحديث سريع ← Python service بـ contract واضح. والأهم contract tests و feature schema مشترك بغض النظر عن الاختيار.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionProblem framing and baseline selection§12
New sectionTrain validation test strategy and temporal/group splits§12
New sectionData leakage and preprocessing pipelines§12
New sectionCross-validation and hyperparameter search§12
New sectionCalibration and threshold selection§12
New sectionError analysis and slice evaluation§12
New sectionExperiment tracking and reproducibility§12
New sectionModel packaging and inference contracts§12
New sectionBatch vs online inference§12
New sectionModel cards and release gates§12

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس