مخرجات التعلم والمتطلبات
الدرس ده بيربط 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 قابلة للقياس.
صياغة المشكلة قبل اختيار الموديل
ابدأ بتحديد من أو ماذا يتم التنبؤ به، ومتى تتوفر البيانات، ومتى يحدث القرار. في churn مثلًا: prediction unit هو customer في تاريخ snapshot، والـ target هو churn خلال أفق زمني لاحق. لا تستخدم عمودًا لم يكن متاحًا وقت التنبؤ مثل cancellation_date؛ ده leakage حتى لو رفع الأداء.
اكتب baseline بسيطًا قبل النماذج المعقدة: majority class، rule-based، أو logistic regression. حدد تكلفة false positive و false negative، latency، وتواتر إعادة التدريب. النجاح مش أعلى score فقط؛ لازم النموذج يحسن قرارًا حقيقيًا مقارنة بال baseline.
تقسيم البيانات ومنع Data Leakage
Random split مناسب فقط عندما تكون العينات مستقلة والتوزيع ثابتًا تقريبًا. بيانات الزمن تحتاج chronological split. وجود عدة صفوف لنفس العميل أو الجهاز يستدعي group split حتى لا يظهر الشخص نفسه في train و test. اختَر split بناءً على طريقة وصول البيانات في الإنتاج.
أي خطوة تتعلم من البيانات — imputation، scaling، feature selection، vocabulary، target encoding — يجب أن تتعلم من training fold فقط. ضعها داخل Pipeline، ولا تحسب إحصاءات على كامل dataset قبل التقسيم. احتفظ بـ test set مغلقًا حتى نهاية الاختيار.
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 وحدها.
Validation و Hyperparameter Tuning
استخدم 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.
Metrics و Calibration و Threshold
في classification غير المتوازن، راجع confusion matrix و precision و recall و F1 و PR-AUC. ROC-AUC مفيد لترتيب الحالات عبر thresholds لكنه قد يبدو متفائلًا مع ندرة الفئة الإيجابية. اختَر metric يعكس القرار، واعرض الأداء لكل شريحة مهمة.
احتمال 0.8 لا يعني بالضرورة أن 80% من الحالات المشابهة ستحدث؛ افحص calibration plot و Brier score، واستخدم calibration على بيانات مستقلة مناسبة عند الحاجة. threshold ليس خاصية ثابتة للموديل: اختَره بناءً على تكلفة القرار وقدرة فريق التشغيل، ثم راقب تغيره.
Error Analysis و Slice Evaluation
قسّم الأخطاء حسب الوقت، نوع العميل، مصدر البيانات، اللغة، missingness، وقيم feature المهمة. راجع false positives و false negatives يدويًا بعينة محكومة. ابحث عن label noise، تغيّر تعريف target، بيانات مفقودة بصورة غير عشوائية، وشرائح لا تمثلها بيانات التدريب.
لا تستنتج العدالة من metric إجمالي. افحص الفروق بين المجموعات ذات الصلة قانونيًا وأخلاقيًا، واحذر أن بعض السمات proxy لسمات حساسة. قرارات الاستخدام والقيود تحتاج مراجعة بشرية ومجالًا قانونيًا مناسبًا.
Slice analysis: المتوسط بيكدب
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).
تسجيل التجارب وإدارة النماذج
كل تجربة يجب أن ترتبط بـ 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 قد ينفذ كودًا.
Batch و Online Inference و Contract
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 واختبارات توافق.
Release Gates و Rollback
- 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.
مشروع تطبيقي ومعايير الإتقان
ابنِ churn prediction pipeline: dataset snapshot مؤرخ، split زمني أو group-aware، baseline، preprocessing pipeline، cross-validation، calibration، error analysis، تسجيل التجربة، ثم inference API. سلّم model card و API contract و README لإعادة التشغيل ونتائج مقارنة بال baseline.
- اكتب تعريف target وتاريخ snapshot وأي feature غير متاح وقت القرار.
- قارن baseline مع نموذجين على split ثابت.
- اعرض precision/recall و PR-AUC و calibration حسب الشرائح.
- اختبر missing fields و unknown categories و out-of-range values.
- نفّذ shadow release تجريبيًا مع عدم اتخاذ قرار حقيقي.
لماذا لا نستخدم test set في كل تجربة؟
هل threshold يساوي 0.5 دائمًا؟
هل حفظ model.pkl وحده كافٍ؟
من Notebook لـ Artifact: Packaging و Contract Tests و Release Gate
موديل دقته عالية في notebook مش منتج. المنتج هو artifact تقدر تجاوب عنه: اتدرّب على إيه؟ بأنهي كود ومكتبات؟ بيقبل إيه كـ input؟ هل النسخة دي بتدّي نفس التوقعات اللي اتوافق عليها؟ وهل هي أحسن من اللي في الإنتاج؟ الكود ده بيبني الـ bundle ده وبيشغّل الاختبارات اللي بتحميه.
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")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 (الموديل نفسه ما اتغيرش). أرجح سبب؟
خريطة تغطية الأهداف
الأهداف العشرة المدرجة في خريطة المنهج تم تناولها عبر الأقسام والتمارين أعلاه. التغطية تعني وجود شرح أو نشاط تعليمي، ولا تعني الإتقان أو الاعتماد أو الجاهزية الإنتاجية دون تنفيذ المشروع والاختبارات.
حالة كاملة: Churn prediction من السؤال للـ endpoint
هنمشي حالة واحدة واقعية من أولها لآخرها، لأن معظم مشاريع الـ ML بتفشل في الربط بين المراحل مش في اختيار الموديل. الشركة: SaaS اشتراكات. الطلب من الإدارة: «عايزين نعرف العملاء اللي هيلغوا».
- القرار مش التنبؤ: السؤال الحقيقي «لمين نبعت عرض خصم؟». ده بيحدد كل حاجة بعد كده: الـ metric (قيمة مالية مش accuracy)، الأفق الزمني (العرض محتاج وقت يأثر = نتنبأ 30 يوم قدام)، والـ threshold.
- تعريف الـ label بدقة: «churn» = الاشتراك اتلغى أو ما اتجددش خلال 30 يوم بعد تاريخ القطع (cutoff). العملاء اللي اشتراكهم بيخلص بعد 90 يوم؟ مش في نفس المشكلة. التعريف الغامض هنا بيبوّظ كل الأرقام بعدين.
- Features بالـ point-in-time: كل feature محسوبة من بيانات قبل الـ cutoff بس (عدد الـ logins آخر 14 يوم قبل الـ cutoff، مش «آخر 14 يوم» النهارده). الـ join الغلط هنا هو أشهر مصدر leakage (الـ lesson السابق في Data Engineering شرح الـ point-in-time joins).
- Validation زمني: تدريب على يناير–يونيو، اختبار على يوليو–أغسطس. الـ random split بيخلي الموديل يشوف «المستقبل».
- Calibration + threshold من التكلفة (المعمل تحت).
- Slice analysis: الأداء على العملاء الجدد (أقل من 60 يوم تاريخ) غالبًا أسوأ بكتير — يمكن محتاجين قاعدة منفصلة.
- Serving + monitoring: batch يومي بيكتب scores في الـ DB، والـ CRM بيعرضها. والـ monitoring الحقيقي مش AUC بس: هل العروض قللت الـ churn؟ (ده محتاج holdout group — uplift).
Leakage: أربع حالات حقيقية وإزاي تكتشفها
| النوع | مثال | العَرَض | الكشف |
|---|---|---|---|
| Target leakage | feature «عدد تذاكر الإلغاء» — بتتكتب بعد ما العميل قرر يلغي | AUC 0.99 في التجربة، 0.6 في الإنتاج | feature importance: feature واحدة مسيطرة؟ اسأل «القيمة دي كانت معروفة وقت التنبؤ؟» |
| Temporal leakage | random split على بيانات زمنية؛ أو feature محسوبة بـ «النهارده» | أداء ممتاز offline، وتدهور فوري | temporal split؛ مراجعة كل feature بتاريخ الـ cutoff |
| Group leakage | نفس العميل له صفوف في train و test (كل شهر صف) | الموديل «بيعرف» العميل | GroupKFold بالـ customer_id |
| Preprocessing leakage | scaling/imputation/target encoding على الداتا كلها قبل التقسيم | تحسن صغير وهمي | كل التحويلات جوه Pipeline بيتعمل fit على train بس |
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.
معمل: Calibration و threshold من التكلفة (مش 0.5)
ليه calibration؟ كتير من الموديلات بترتّب صح (AUC كويس) لكن الأرقام نفسها مش احتمالات: «0.3» ممكن تكون في الحقيقة 90%. لو هتستخدم الـ score في قرار مالي (توقع خسارة، أولوية، تسعير)، محتاج احتمالات حقيقية. الـ calibration بيتعلم mapping من الـ score للاحتمال الفعلي على held-out set منفصل عن التدريب.
ليه مش threshold 0.5؟ الـ threshold الصح بييجي من التكاليف: نبعت عرض لو p × قيمة_الإنقاذ > تكلفة_العرض. المعمل بيحاكي موديل scores بتاعته مش calibrated، بيصلّحه بـ isotonic (Pool-Adjacent-Violators)، وبيختار الـ threshold بالقيمة المتوقعة.
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}")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) أبسط وأثبت مع داتا قليلة.
Serving من .NET: ONNX Runtime في ASP.NET Core
ليه 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 على نفس الصفوف.
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"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 في الاتنين.
Model card لموديل الـ churn
# 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.Failure modes في الإنتاج: feedback loops و training-serving skew
- 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 شهريًا.
Knowledge check
الموديل جاب ROC-AUC 0.97 بـ random split و0.71 بـ temporal split. إيه التفسير الأرجح؟
عرض الاحتفاظ يكلف 10، وإنقاذ العميل يوفر 60 في المتوسط. نبعت العرض لما الاحتمال المعاير أكبر من؟
تمارين محلولة
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 لوحدها.
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) إيه هو data leakage واديني مثال.
(Senior) إزاي تختار الـ threshold لموديل تصنيف؟
(Senior) الموديل شغال في الإنتاج 6 شهور والـ AUC ثابت، لكن البيزنس بيقول مفيش فايدة. ليه ممكن؟
(Staff) فريق الـ ML وفريق الـ .NET بيتخانقوا على مكان الموديل (Python service vs ONNX in-process). إزاي تحسم؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.