المشروع في صفحة واحدة
بنك بيعمل حملات تليفونية لبيع ودائع لأجل. كل مكالمة بتكلف وقت موظف، وأغلب العملاء بيقولوا لأ (~11% بس بيوافقوا). السؤال: مين نتصل بيه الأول؟ ده مشروع مثالي للـ portfolio لأنه حقيقي (بيانات حملات فعلية من بنك برتغالي، منشورة علميًا)، فيه class imbalance، فيه leakage مشهور لازم تكتشفه، وفيه قرار بيزنس واضح بالتكلفة.
الخطوة 1: صياغة المشكلة والتكلفة
| السؤال | الإجابة في المشروع |
|---|---|
| القرار اللي الموديل بيساعد فيه؟ | ترتيب قائمة الاتصال اليومية (call center عنده سعة N مكالمة) |
| الـ target؟ | y = هل العميل اشترك في الوديعة (yes/no) |
| إمتى بنتنبأ؟ | قبل المكالمة — يعني أي معلومة بتتعرف أثناء/بعد المكالمة ممنوعة كـ feature |
| تكلفة الأخطاء | مكالمة لعميل مش مهتم = ~5 دقايق موظف؛ تفويت عميل مهتم = ربح ضايع أكبر بكتير (افتراض للتمرين: FP=1، FN=10 وحدات) |
| مقياس النجاح | نسبة الموافقات في أول N مكالمة (precision@N / lift) مقارنة بالاتصال العشوائي |
إزاي تتأكد: اكتب الجدول ده في الـ README قبل أي كود. لو مش قادر تكمل خانة «إمتى بنتنبأ»، هتقع في leakage. الغلط الشائع: البدء بـ «هعمل classifier accuracy عالية» — accuracy 89% ممكنة بقول «لأ» للكل.
الخطوة 2: البيانات والـ EDA (ومصيدة duration)
from ucimlrepo import fetch_ucirepo # pip install ucimlrepo
import pandas as pd, hashlib, pathlib
def load_bank_marketing(cache="data/raw/bank.parquet") -> pd.DataFrame:
p = pathlib.Path(cache)
if not p.exists():
ds = fetch_ucirepo(id=222) # UCI Bank Marketing
df = pd.concat([ds.data.features, ds.data.targets], axis=1)
p.parent.mkdir(parents=True, exist_ok=True)
df.to_parquet(p)
df = pd.read_parquet(p)
print("rows", len(df), "sha256", hashlib.sha256(p.read_bytes()).hexdigest()[:12]) # record in the report
return dfdf = load_bank_marketing()
print(df["y"].value_counts(normalize=True)) # ~0.88 no / ~0.12 yes -> imbalance
print(df.isna().mean().sort_values(ascending=False).head()) # missing / "unknown" categories
print(df.groupby("month")["y"].apply(lambda s: (s == "yes").mean())) # strong month effect -> time structure
print(df.groupby(pd.cut(df["duration"], [0, 60, 180, 600, 5000]))["y"].apply(lambda s: (s == "yes").mean()))
# duration (call length) is hugely predictive... and only known AFTER the call ends -> LEAKAGE. Drop it.عمود duration (مدة المكالمة) بيرفع الـ AUC بشكل خرافي، لأن العميل اللي بيوافق بيطول في المكالمة. لكنه مش معروف قبل المكالمة — اللحظة اللي بنتنبأ فيها. مؤلفين الـ dataset نفسهم بيقولوا يتشال لموديل واقعي. لو الـ portfolio بتاعك فيه AUC 0.93 بـ duration، أي interviewer فاهم هيعرف فورًا.
كمان من الـ EDA: قيم «unknown» كفئة (مش NaN)، pdays = −1 أو 999 (حسب النسخة) معناها «ما اتصلناش قبل كده» (flag منفصل بدل رقم)، والترتيب الزمني للحملات (البيانات مرتبة زمنيًا من مايو 2008 لنوفمبر 2010). إزاي تتأكد: notebook الـ EDA بيطلع جدول «قرارات البيانات» (عمود ← قرار ← سبب) بيدخل الـ README.
الخطوة 3: split أمين
البيانات مرتبة زمنيًا، والسلوك اتغير عبر الوقت (أزمة 2008). split عشوائي هيخلط حملات المستقبل بالماضي. الأأمن: آخر 20% من الصفوف (زمنيًا) test، وقبلها validation، والباقي train.
def temporal_split(df, val_frac=0.15, test_frac=0.20):
n = len(df) # rows are in chronological order in this dataset
t1, t2 = int(n * (1 - val_frac - test_frac)), int(n * (1 - test_frac))
return df.iloc[:t1], df.iloc[t1:t2], df.iloc[t2:]
train, val, test = temporal_split(df.drop(columns=["duration"]))
for name, part in [("train", train), ("val", val), ("test", test)]:
print(name, len(part), round((part["y"] == "yes").mean(), 3)) # base rate shifts over time: report itالغلط الشائع: تعمل tuning على الـ test وانت مش واخد بالك (تبص على نتيجته كل شوية). الـ test بيتلمس مرة واحدة في الآخر.
الخطوة 4: baselines
from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import OneHotEncoder, StandardScaler
from sklearn.pipeline import Pipeline
from sklearn.linear_model import LogisticRegression
from sklearn.dummy import DummyClassifier
CAT = ["job", "marital", "education", "default", "housing", "loan", "contact", "month", "day_of_week", "poutcome"]
NUM = ["age", "campaign", "pdays", "previous"] # (+ macro features if present in your version of the dataset)
def preprocess():
return ColumnTransformer([
("cat", OneHotEncoder(handle_unknown="ignore", min_frequency=20), [c for c in CAT if c in train.columns]),
("num", StandardScaler(), [c for c in NUM if c in train.columns]),
])
prior = Pipeline([("prep", preprocess()), ("clf", DummyClassifier(strategy="prior"))])
logreg = Pipeline([("prep", preprocess()), ("clf", LogisticRegression(max_iter=2000, class_weight="balanced"))])
X_tr, y_tr = train.drop(columns="y"), (train["y"] == "yes").astype(int)
X_va, y_va = val.drop(columns="y"), (val["y"] == "yes").astype(int)
for name, m in [("prior", prior), ("logreg", logreg)]:
m.fit(X_tr, y_tr)
print(name, average_precision(y_va, m.predict_proba(X_va)[:, 1])) # PR-AUC: honest under imbalanceكل الـ preprocessing جوه الـ pipeline: الـ scaler والـ encoder بيتعملهم fit على الـ train بس. المقياس: PR-AUC (average precision) أصدق من ROC-AUC مع imbalance، وبعدين precision@N للقرار الحقيقي.
الخطوة 5: gradient boosting والـ tuning
from sklearn.ensemble import HistGradientBoostingClassifier
from sklearn.model_selection import TimeSeriesSplit, RandomizedSearchCV
gbm = Pipeline([("prep", preprocess()),
("clf", HistGradientBoostingClassifier(learning_rate=0.05, max_iter=400, early_stopping=True, random_state=7))])
search = RandomizedSearchCV(gbm, {
"clf__max_leaf_nodes": [15, 31, 63], "clf__min_samples_leaf": [20, 50, 100],
"clf__l2_regularization": [0.0, 0.1, 1.0], "clf__learning_rate": [0.03, 0.05, 0.1]},
n_iter=20, scoring="average_precision", cv=TimeSeriesSplit(n_splits=4), random_state=7, n_jobs=-1)
search.fit(X_tr, y_tr) # time-aware CV inside the training period
best = search.best_estimator_
print(search.best_params_, average_precision(y_va, best.predict_proba(X_va)[:, 1]))إزاي تتأكد: جدول مقارنة على الـ validation (prior، logreg، gbm) بـ PR-AUC و precision@N، والفرق عن logreg لازم يستاهل التعقيد. الغلط الشائع: 500 تجربة hyperparameters مقابل validation set واحد ← overfitting للـ validation. استخدم CV زمني جوه الـ train، و validation للمقارنة النهائية بين العائلات.
الخطوة 6: تقييم بشرائح وفواصل ثقة و calibration
import numpy as np
from sklearn.metrics import average_precision_score
from sklearn.calibration import calibration_curve
def bootstrap_ci(y, p, metric, n=1000, seed=0):
rng = np.random.default_rng(seed); vals = []
y, p = np.asarray(y), np.asarray(p)
for _ in range(n):
idx = rng.integers(0, len(y), len(y))
if y[idx].sum() == 0: continue
vals.append(metric(y[idx], p[idx]))
return np.percentile(vals, [2.5, 97.5])
p_va = best.predict_proba(X_va)[:, 1]
print("PR-AUC", average_precision_score(y_va, p_va), "95% CI", bootstrap_ci(y_va, p_va, average_precision_score))
for col in ["contact", "age_band", "poutcome"]: # slices that matter for fairness and operations
for val_, g in val.assign(age_band=pd.cut(val.age, [0, 30, 45, 60, 120])).groupby(col):
m = g.index
print(col, val_, len(m), round(average_precision_score(y_va.loc[m], p_va[val.index.get_indexer(m)]), 3))
frac_pos, mean_pred = calibration_curve(y_va, p_va, n_bins=10) # are 0.3 scores right ~30% of the time?- Confidence intervals: PR-AUC 0.46 [0.42، 0.50] مقابل logreg 0.44 [0.40، 0.48] ← الفرق جوه الـ noise. اكتب ده بصراحة.
- Slices: الأداء على عملاء الموبايل مقابل الأرضي، الأعمار المختلفة، اللي اتكلموا قبل كده. شريحة ضعيفة جدًا = تحذير في الـ model card.
- Calibration: لو الموديل بيقول 0.3 والفعلي 0.15، أي حساب تكلفة على الاحتمالات هيبقى غلط ←
CalibratedClassifierCV(isotonic/sigmoid) على الـ validation.
الخطوة 7: من احتمالات لقرار
الـ call center عنده سعة 300 مكالمة في اليوم. القرار مش «threshold 0.5»، القرار «أعلى 300 احتمال». قيس precision@300 على الـ validation (مقارنة بالـ base rate ~11% للاتصال العشوائي) — ده الـ lift اللي الإدارة هتفهمه: «من كل 300 مكالمة، هنوصل لـ 120 موافقة بدل 33». ولو مفيش سقف للسعة، استخدم threshold بالتكلفة (FN=10، FP=1) زي ML Evaluation.
الأرقام توضيحية؛ اكتب أرقامك الفعلية من الـ validation ثم أكدها مرة واحدة على الـ test.
best_cal = CalibratedClassifierCV(best, method="isotonic", cv="prefit").fit(X_va, y_va) # calibrate on validation
p_te = best_cal.predict_proba(test.drop(columns="y"))[:, 1]
y_te = (test["y"] == "yes").astype(int).to_numpy()
top = np.argsort(-p_te)[:300]
print("precision@300", y_te[top].mean(), "base rate", y_te.mean(), "lift", y_te[top].mean() / y_te.mean())
joblib.dump(best_cal, "models/bank_v1.joblib") # + write metrics JSON next to itالخطوة 8: Model card
# Bank term-deposit propensity — v1 (2026-11-18)
**Intended use:** rank existing customers for outbound calls. **Not for:** credit decisions, pricing, any decision denying service.
**Data:** UCI Bank Marketing (Portuguese bank, 2008–2010, CC BY 4.0), snapshot sha256 a1b2c3…; `duration` removed (post-call leakage).
**Split:** chronological 65/15/20. **Model:** HistGradientBoosting + isotonic calibration.
**Metrics (test):** PR-AUC 0.xx [CI], precision@300 0.xx vs base rate 0.xx (lift x.x).
**Slices:** weakest = <slice> (PR-AUC 0.xx). **Calibration:** ECE 0.0x.
**Limitations:** old data, single country; behaviour shifted across the 2008 crisis; macro features may not exist at serving time.
**Monitoring:** weekly PSI on top features, monthly precision@N from outcomes; retrain if lift drops below 2.0.
**Owner:** you@… · **Review date:** …الـ model card هو اللي بيفرق مشروعك عن «notebook على Kaggle». ومطلوب فعليًا في بيئات منظمة (Governance).
الخطوة 9 و10: FastAPI و Docker وعميل .NET
from fastapi import FastAPI
from pydantic import BaseModel, Field
import joblib, pandas as pd
# joblib/pickle executes code on load: only load model files you built, from a trusted, hash-verified artifact store.
# For untrusted exchange prefer skops (safe loading) or ONNX.
MODEL = joblib.load("models/bank_v1.joblib"); VERSION = "bank_v1"
app = FastAPI(title="propensity")
class Customer(BaseModel):
age: int = Field(ge=18, le=100)
job: str; marital: str; education: str; default: str; housing: str; loan: str
contact: str; month: str; day_of_week: str | None = None; campaign: int = Field(ge=1); pdays: int; previous: int = Field(ge=0)
poutcome: str
@app.post("/score")
def score(batch: list[Customer]):
df = pd.DataFrame([c.model_dump() for c in batch])
p = MODEL.predict_proba(df)[:, 1]
return {"model_version": VERSION, "scores": [round(float(x), 4) for x in p]}
@app.get("/health")
def health(): return {"status": "ok", "model_version": VERSION}FROM python:3.12-slim
WORKDIR /app
COPY requirements.lock .
RUN pip install --no-cache-dir -r requirements.lock # pinned versions: same sklearn at train and serve time
COPY app.py ./
COPY models/ ./models/
USER 1000
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]public sealed record CustomerFeatures(int Age, string Job, string Marital, string Education, string Default, string Housing,
string Loan, string Contact, string Month, string? DayOfWeek, int Campaign, int Pdays, int Previous, string Poutcome);
public sealed record ScoreResponse(string ModelVersion, double[] Scores);
builder.Services.AddHttpClient<PropensityClient>(c => { c.BaseAddress = new("http://propensity:8000"); c.Timeout = TimeSpan.FromSeconds(2); })
.AddStandardResilienceHandler();
public sealed class PropensityClient(HttpClient http)
{
private static readonly JsonSerializerOptions Snake = new() { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower };
public async Task<ScoreResponse> ScoreAsync(IReadOnlyList<CustomerFeatures> batch, CancellationToken ct)
{
using var res = await http.PostAsJsonAsync("/score", batch, Snake, ct);
res.EnsureSuccessStatusCode();
return (await res.Content.ReadFromJsonAsync<ScoreResponse>(Snake, ct))!;
}
}
// Caller: if the service is down, fall back to the previous day's list (or a rule-based ranking) and log it — never block the call center.الـ contract (أسماء الحقول وأنواعها) لازم يتطابق بين Pydantic والـ record — ده مكان مثالي لـ contract test (Pact) أو OpenAPI المتولد من FastAPI.
الخطوة 11: المراقبة وإعادة التدريب
- Data drift: PSI أسبوعي على أهم features (الفئات العمرية، نوع الاتصال، عدد المكالمات السابقة) بين بيانات الإنتاج والتدريب. PSI > 0.2 = تغيير ملحوظ يستاهل تحقيق.
- Prediction drift: توزيع الـ scores اليومي (لو المتوسط اتحرك جامد، فيه حاجة اتغيرت upstream).
- Outcome monitoring: النتايج الحقيقية (وافق/لأ) بتيجي بعد أيام ← precision@N الفعلي أسبوعيًا مقابل المتوقع.
- Training/serving skew: سجّل الـ features اللي اتبعتت للـ API وقارن توزيعها بالتدريب — bug في التحويل (مثلًا pdays 999 vs −1) بيبان هنا.
- Retraining policy مكتوبة: شهري أو عند drift/انخفاض الـ lift تحت حد، مع نفس الـ evaluation pipeline والـ model card الجديد، و canary قبل الاستبدال (MLOps).
إزاي تعرضه في الـ portfolio
- README: المشكلة، القرار، النتيجة بالأرقام (lift، CI)، وصورة الـ pipeline.
- «الحاجة اللي اكتشفتها»: الـ duration leakage وإزاي عرفته — دي القصة اللي هتحكيها في الإنترفيو.
make train/make serve/docker compose upبيشتغلوا على جهاز نضيف.- Tests: للـ preprocessing (unknown categories، قيم حدية)، وللـ API (schema validation)، و smoke test للموديل (score بين 0 و1، ثبات على مثال معروف).
- Model card وجدول المقارنة مع الـ baselines.
أخطاء شائعة
- إبقاء duration (أو أي feature بعد الحدث) ← نتايج خيالية.
- Random split على بيانات زمنية.
- Accuracy كمقياس مع 89% class واحدة.
- Preprocessing على الداتا كلها قبل الـ split.
- Tuning على الـ test.
- Versions مختلفة لـ scikit-learn بين التدريب والـ serving ← نتايج مختلفة أو crash عند الـ unpickle.
اختبر فهمك
موديل بـ ROC-AUC 0.93 بيستخدم مدة المكالمة كـ feature. المشكلة؟
سعة الـ call center 300 مكالمة/يوم. أنسب مقياس للقرار؟
أسئلة إنترفيو عن المشروع
(Junior/Mid) احكيلي عن مشروع ML عملته.
(Senior) الـ lift وقع من 3.2 لـ 1.8 بعد شهرين. تعمل إيه؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.