Software Engineer Encyclopedia
0%
Domain 13 · MLOps, LLMOps & Production AI · Pillar

مشروع ML كامل على dataset حقيقي: من البيانات للـ deployment

End-to-End ML Project on a Real Dataset

دليل خطوة بخطوة لمشروع portfolio حقيقي: dataset عام (UCI Bank Marketing) ← فهم المشكلة والتكلفة ← EDA ← split أمين ← baseline ← pipeline بـ scikit-learn ← gradient boosting ← تقييم بشرائح وconfidence intervals وcalibration ← threshold بالتكلفة ← model card ← API بـ FastAPI يستهلكه ASP.NET Core ← Docker ← monitoring للـ drift. كل خطوة فيها: هتعمل إيه، ليه، إزاي تتأكد، والغلط الشائع.

  • Professional Engineering
  • ~8 min read
  • 15 sections
  • 11 code examples
  • 1 diagrams
  • 4 questions
  • Priority L2 · Essential
  • Python 3.12 · pandas · scikit-learn 1.5+ · LightGBM (optional) · FastAPI · .NET 10 client · Docker — dataset: UCI Machine Learning Repository, Bank Marketing (CC BY 4.0), reviewed 2026-11-18

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

  • تحول سؤال بيزنس لمسألة ML قابلة للقياس بتكلفة أخطاء واضحة
  • تعمل EDA بيكشف leakage ومشاكل بيانات قبل الموديل
  • تبني pipeline قابل للتكرار (preprocessing + model) وتتجنب leakage
  • تقارن baseline وlogistic regression وgradient boosting بتقييم أمين
  • تقيّم بشرائح وconfidence intervals وcalibration وتختار threshold بالتكلفة
  • تكتب model card وتنشر الموديل كـ API وتستهلكه من .NET
  • تراقب الموديل في الإنتاج (data drift، performance) وتعرف إمتى تعيد التدريب

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

01

المشروع في صفحة واحدة

The project at a glance
Basics

بنك بيعمل حملات تليفونية لبيع ودائع لأجل. كل مكالمة بتكلف وقت موظف، وأغلب العملاء بيقولوا لأ (~11% بس بيوافقوا). السؤال: مين نتصل بيه الأول؟ ده مشروع مثالي للـ portfolio لأنه حقيقي (بيانات حملات فعلية من بنك برتغالي، منشورة علميًا)، فيه class imbalance، فيه leakage مشهور لازم تكتشفه، وفيه قرار بيزنس واضح بالتكلفة.

1 Framecost of errors2 Data + EDAleakage hunt3 Splittime-aware4 Baselinesprior, LR5 ModelGBM + tuning6 Evaluateslices, CI, calib7 Thresholdby cost/capacity8 Model card9 FastAPI+ Docker10 .NET client11 Monitordrift + outcomeRepo deliverables: notebooks/ (EDA only) · src/ (pipeline) · reports/ (metrics, model card) · service/ · tests/ · Dockerfile · README
The full path you will build and how each step is verified
02

الخطوة 1: صياغة المشكلة والتكلفة

Step 1 — Framing
Practical
السؤالالإجابة في المشروع
القرار اللي الموديل بيساعد فيه؟ترتيب قائمة الاتصال اليومية (call center عنده سعة N مكالمة)
الـ target؟y = هل العميل اشترك في الوديعة (yes/no)
إمتى بنتنبأ؟قبل المكالمة — يعني أي معلومة بتتعرف أثناء/بعد المكالمة ممنوعة كـ feature
تكلفة الأخطاءمكالمة لعميل مش مهتم = ~5 دقايق موظف؛ تفويت عميل مهتم = ربح ضايع أكبر بكتير (افتراض للتمرين: FP=1، FN=10 وحدات)
مقياس النجاحنسبة الموافقات في أول N مكالمة (precision@N / lift) مقارنة بالاتصال العشوائي

إزاي تتأكد: اكتب الجدول ده في الـ README قبل أي كود. لو مش قادر تكمل خانة «إمتى بنتنبأ»، هتقع في leakage. الغلط الشائع: البدء بـ «هعمل classifier accuracy عالية» — accuracy 89% ممكنة بقول «لأ» للكل.

03

الخطوة 2: البيانات والـ EDA (ومصيدة duration)

Step 2 — Data and EDA
Practical
Pythonsrc/data.py — fetch and freeze a snapshot
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 df
Pythonnotebooks/01_eda.py — the questions that matter
df = 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.
الـ leakage المشهور

عمود duration (مدة المكالمة) بيرفع الـ AUC بشكل خرافي، لأن العميل اللي بيوافق بيطول في المكالمة. لكنه مش معروف قبل المكالمة — اللحظة اللي بنتنبأ فيها. مؤلفين الـ dataset نفسهم بيقولوا يتشال لموديل واقعي. لو الـ portfolio بتاعك فيه AUC 0.93 بـ duration، أي interviewer فاهم هيعرف فورًا.

كمان من الـ EDA: قيم «unknown» كفئة (مش NaN)، pdays = −1 أو 999 (حسب النسخة) معناها «ما اتصلناش قبل كده» (flag منفصل بدل رقم)، والترتيب الزمني للحملات (البيانات مرتبة زمنيًا من مايو 2008 لنوفمبر 2010). إزاي تتأكد: notebook الـ EDA بيطلع جدول «قرارات البيانات» (عمود ← قرار ← سبب) بيدخل الـ README.

04

الخطوة 3: split أمين

Step 3 — Honest splitting
Practical

البيانات مرتبة زمنيًا، والسلوك اتغير عبر الوقت (أزمة 2008). split عشوائي هيخلط حملات المستقبل بالماضي. الأأمن: آخر 20% من الصفوف (زمنيًا) test، وقبلها validation، والباقي train.

Pythonsrc/split.py
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 بيتلمس مرة واحدة في الآخر.

05

الخطوة 4: baselines

Step 4 — Baselines
Practical
Pythonsrc/pipeline.py — one pipeline object, no leakage across folds
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 للقرار الحقيقي.

06

الخطوة 5: gradient boosting والـ tuning

Step 5 — A stronger model
Practical
Pythonsrc/train.py
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 للمقارنة النهائية بين العائلات.

07

الخطوة 6: تقييم بشرائح وفواصل ثقة و calibration

Step 6 — Evaluation you can defend
Deep dive
Pythonsrc/evaluate.py
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.
08

الخطوة 7: من احتمالات لقرار

Step 7 — Decision threshold
Practical

الـ 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.

Pythonfinal, one-time test evaluation
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
09

الخطوة 8: Model card

Step 8 — Model card
Practical
Markdownreports/model_card.md (skeleton)
# 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).

10

الخطوة 9 و10: FastAPI و Docker وعميل ‎.NET

Steps 9–10 — Serving
Practical
Pythonservice/app.py
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}
Dockerfileservice/Dockerfile
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"]
C#.NET client with typed contract, timeout and fallback
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

الخطوة 11: المراقبة وإعادة التدريب

Step 11 — Monitoring
Deep dive
  • 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).
12

إزاي تعرضه في الـ portfolio

Presenting the project
Basics
  1. README: المشكلة، القرار، النتيجة بالأرقام (lift، CI)، وصورة الـ pipeline.
  2. «الحاجة اللي اكتشفتها»: الـ duration leakage وإزاي عرفته — دي القصة اللي هتحكيها في الإنترفيو.
  3. make train / make serve / docker compose up بيشتغلوا على جهاز نضيف.
  4. Tests: للـ preprocessing (unknown categories، قيم حدية)، وللـ API (schema validation)، و smoke test للموديل (score بين 0 و1، ثبات على مثال معروف).
  5. Model card وجدول المقارنة مع الـ baselines.
13

أخطاء شائعة

Common mistakes
Basics
  • إبقاء duration (أو أي feature بعد الحدث) ← نتايج خيالية.
  • Random split على بيانات زمنية.
  • Accuracy كمقياس مع 89% class واحدة.
  • Preprocessing على الداتا كلها قبل الـ split.
  • Tuning على الـ test.
  • Versions مختلفة لـ scikit-learn بين التدريب والـ serving ← نتايج مختلفة أو crash عند الـ unpickle.
14

اختبر فهمك

Knowledge check
Basics

موديل بـ ROC-AUC 0.93 بيستخدم مدة المكالمة كـ feature. المشكلة؟

سعة الـ call center 300 مكالمة/يوم. أنسب مقياس للقرار؟

15

أسئلة إنترفيو عن المشروع

Defending the project
Basics
(Junior/Mid) احكيلي عن مشروع ML عملته.
المشكلة (ترتيب مكالمات بسعة 300/يوم)، البيانات (UCI Bank Marketing)، الاكتشاف (duration leakage وشلته)، الـ split الزمني، الـ baselines، الموديل والتحسن بفاصل ثقة، الـ calibration، القرار (precision@300 و lift)، والـ deployment والمراقبة. وأقول بصراحة القيود (بيانات قديمة، بلد واحد).
(Senior) الـ lift وقع من 3.2 لـ 1.8 بعد شهرين. تعمل إيه؟
أفحص: training/serving skew (bug في الـ features)، data drift (PSI) في الشرائح، تغيّر في الـ base rate أو في الحملة نفسها (منتج جديد، سعر فايدة)، تغيّر في مين بيتم الاتصال بيه (feedback loop: الموديل بيختار، فالبيانات الجديدة متحيزة). بعدين retrain على بيانات حديثة مع جزء صغير exploration عشوائي، و canary قبل الاستبدال.
↗

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

References & further reading

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

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

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