النموذج الحبيس في notebook لا يساعد أحدًا. وكي يغيّر ما يفعله Cartwheel، يجب أن يعمل الـ pipeline البطل على بيانات عملاء جديدة، وفق جدول زمني أو عند الطلب، وأن تصل درجاته إلى الأشخاص الذين يرسلون عروض الاسترجاع. يغطي هذا الدرس الميل الأخير: حفظ النموذج، وحراسة مدخلاته، والاختيار بين مهمة دفعية وAPI، وإثبات أنه يعمل.
\nالشيء الذي يُطلق هو الـ pipeline المدرَّب كاملًا. فمتوسطات الـ scaler وانحرافاته المعيارية جزء من النموذج بقدر المعاملات؛ ودونها ستوحّد بيئة الإنتاج مقاييس العملاء الجدد بشكل مختلف، وستكون كل درجة منحرفة.
\nيغطي دليل حفظ النماذج في scikit-learn عدة صيغ (pickle وjoblib وskops وONNX)؛ وjoblib هو الأكثر شيوعًا حين تتولّى Python الحفظ والتحميل معًا. احفظ حزمة صغيرة فيها ما سيحتاجه أحدهم لاحقًا: الـ pipeline، وقائمة الـ features بالضبط، ووسم الإصدار، وإصدار المكتبة الذي دُرِّب به.
import os\nimport tempfile\n\nimport joblib\nimport pandas as pd\nimport sklearn\nfrom sklearn.linear_model import LogisticRegression\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.preprocessing import StandardScaler\n\nchurn = pd.read_csv(\"churn.csv\")\nfeatures = [\"tenure_days\", \"orders\", \"total_spent\", \"avg_order_value\",\n \"days_since_last_order\", \"used_coupon\", \"support_tickets\", \"mobile_share\"]\nchampion = make_pipeline(StandardScaler(), LogisticRegression()).fit(churn[features], churn[\"churned\"])\n\nbundle = {\"model\": champion, \"features\": features,\n \"version\": \"churn-2025-09-30.1\", \"sklearn_version\": sklearn.__version__}\n\nwith tempfile.TemporaryDirectory() as folder:\n path = os.path.join(folder, \"churn_model.joblib\")\n joblib.dump(bundle, path)\n print(\"saved\", os.path.getsize(path), \"bytes\")\n\n loaded = joblib.load(path)\n same = (loaded[\"model\"].predict_proba(churn[features]) == champion.predict_proba(churn[features])).all()\n print(\"identical predictions after reload:\", same, \"| trained with scikit-learn\", loaded[\"sklearn_version\"])لاحظ أن النموذج النهائي مدرَّب على العملاء الـ 398 ذوي الـ labels كلهم. فمهمة بيانات الاختبار كانت قياس عملية النمذجة؛ وبعد أن قستها، تعطي إعادة التدريب على كل صف ذي label النموذجَ المُطلَق شيئًا أكثر يتعلّم منه. سجّل أنك فعلت ذلك، واحتفظ بالمقياس المنشور من تقييم بيانات الاختبار.
\n\nسيقيّم النموذج الهراء بكل سرور. عميل لديه orders = 0، أو mobile_share يساوي 7، أو عمود مفقود، ينتج احتمالًا يبدو واثقًا كأي احتمال آخر. ضع طبقة رقيقة أمام predict_proba تتحقق من المُدخل وتفشل بوضوح:
# assumes `import pandas as pd` and a loaded `bundle` as above\ndef predict_churn(record: dict, bundle: dict) -> float:\n missing = [f for f in bundle[\"features\"] if f not in record]\n if missing:\n raise ValueError(f\"missing fields: {missing}\")\n if not 0 <= record[\"mobile_share\"] <= 1:\n raise ValueError(\"mobile_share must be between 0 and 1\")\n row = pd.DataFrame([record])[bundle[\"features\"]]\n return float(bundle[\"model\"].predict_proba(row)[0, 1])اختيار [bundle["features"]] يثبّت ترتيب الأعمدة، وهو ما يصرّ عليه scikit-learn كما بيّن القسم 1.
هناك طريقتان شائعتان لتشغيل النموذج:
\nوإذا احتجت فعلًا إلى API، فخدمة FastAPI صغيرة خيار شائع في Python. هذا المخطّط لا يعمل في المتصفّح، لكنه مكتمل بما يكفي لتشغيله محليًا بـ uvicorn app:app:
import joblib\nimport pandas as pd\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, Field\n\n# joblib uses pickle: load only model files from your own trusted, access-controlled store\nbundle = joblib.load(\"churn_model.joblib\")\napp = FastAPI()\n\nclass Customer(BaseModel):\n tenure_days: int = Field(ge=0)\n orders: int = Field(ge=1)\n total_spent: float = Field(ge=0)\n avg_order_value: float = Field(ge=0)\n days_since_last_order: int = Field(ge=0)\n used_coupon: int = Field(ge=0, le=1)\n support_tickets: int = Field(ge=0)\n mobile_share: float = Field(ge=0, le=1)\n\n@app.post(\"/predict\")\ndef predict(customer: Customer):\n row = pd.DataFrame([customer.model_dump()])[bundle[\"features\"]]\n prob = float(bundle[\"model\"].predict_proba(row)[0, 1])\n return {\"churn_probability\": round(prob, 3), \"model_version\": bundle[\"version\"]}يتولّى نموذج Pydantic التحقق من المدخلات بشكل تصريحي: الطلب الذي فيه orders: 0 أو حقل مفقود يحصل على خطأ 422 قبل أن يراه النموذج أصلًا. وإعادة إصدار النموذج مع كل إجابة تتيح تتبّع أي تنبؤ إلى النموذج المحدّد الذي أنتجه. سجّل كل طلب واستجابة؛ فهذه السجلّات هي ما تعمل عليه فحوص الانجراف من الدرس السابق.
الـ ROC AUC الجيد يعني أن النموذج يرتّب العملاء جيدًا. ولا يعني أن عرض الاسترجاع يغيّر رأي أحد. ولقياس ذلك، احجز شريحة عشوائية من العملاء المُعلَّمين (لنقل 20%) لا يتلقّون العرض. وبعد 90 يومًا، قارن الانقطاع بين المجموعة التي تواصلت معها والمجموعة المحجوزة. الفرق هو أثر العرض على العملاء الذين يختارهم النموذج، ومضروبًا في قيمة العميل يصبح الرقم الذي تهتم به الشركة فعلًا. ودون المجموعة المحجوزة، قد يكون أي انخفاض في الانقطاع بسبب الموسم، أو تعثّر منافس، أو الحظ.
\n\nبدأت بسؤال وجدول، وصار لديك الآن إجراء يصمد: صُغ المسألة، وقسّم قبل أن تنظر، وتفوّق على نموذج وهمي للفئة الأكثر شيوعًا وعلى قاعدة، واختر المقاييس بحسب كلفة كل خطأ، وقارن النماذج بالتحقق المتقاطع داخل pipelines خالية من التسرّب، وتحقّق ممن يخدمهم النموذج بشكل أسوأ، وأطلق شيئًا تستطيع مراقبته واختباره. وتبيّن أن البطل هو أبسط نموذج جادّ، وأنت تعرف بالضبط لماذا. عادة السؤال “مقارنةً بماذا؟” هي أثمن ما كان لدى هذه الدورة لتعلّمه، وهي تنطبق دون تغيير على النموذج القادم الذي ستبنيه، أيًّا كان.
\n","toc":[{"id":"sec-1","text":"احفظ الـ pipeline، لا النموذج وحده","level":2},{"id":"sec-2","text":"احرس المدخلات","level":2},{"id":"sec-3","text":"مهمة دفعية أم API؟","level":2},{"id":"sec-4","text":"هل نجح؟ أجرِ تجربة","level":2},{"id":"sec-5","text":"أين أنت الآن","level":2}],"takeaways":["احفظ الـ pipeline المدرَّب كاملًا، لا النموذج وحده، كي تنتقل المعالجة المسبقة معه؛ وخزّن بجانبه قائمة الـ features ورقم إصدار وإصدار scikit-learn.","ملفاتjoblib وpickle قد تنفّذ كودًا عند تحميلها، فلا تحمّل إلا ملفات نماذج أنشأتها أنت أو تثق بها، وحمّلها بإصدار scikit-learn نفسه.","[object Object]","كثير من نماذج الأعمال، ومنها نموذج الانقطاع، يُطلق على أفضل وجه كمهمة دفعية مجدولة؛ أما الـ API المباشر فللقرارات التي يجب أن تحدث أثناء الطلب.","الاختبار الحقيقي للنموذج تجربة مضبوطة: قارن نتائج العملاء المُعلَّمين الذين تلقّوا العرض بمجموعة محجوزة عشوائيًا لم تتلقَّه."],"further":[{"title":"Model persistence","url":"https://scikit-learn.org/stable/model_persistence.html"},{"title":"pickle: security warning","url":"https://docs.python.org/3/library/pickle.html"}],"quiz":[{"q":"لماذا نحفظ الـ pipeline المدرَّب بدل خطوة LogisticRegression وحدها؟
أرسل لك زميل بالبريد الملف model.joblib من مصدر مجهول وطلب منك تقييمه. ما الخطر؟
يتواصل فريق التسويق مع كل عميل يُعلِّمه النموذج، فينخفض الانقطاع بينهم من 79% إلى 60%. هل يمكنك أن تنسب الفضل إلى النموذج والعرض؟
","options":[{"text":"نعم؛ انخفض الانقطاع بعد الإطلاق، فالنظام يعمل.","why":"ربما كان الانقطاع سينخفض على أي حال (الموسم، أو مشكلة لدى منافس). ودون مجموعة مقارنة لا يمكنك الجزم."},{"text":"نعم، ما دام الـ ROC AUC على الاختبار أعلى من 0.8.","why":"يُظهر الـ AUC أن النموذج يرتّب جيدًا؛ ولا يقول شيئًا عمّا إذا كان العرض يغيّر السلوك."},{"text":"لا، لأن الانقطاع يجب أن يُقاس على 30 يومًا لا 90.","why":"النافذة تعريف عملي؛ والمشكلة في غياب المقارنة."},{"text":"ليس بعد؛ تحتاج إلى مجموعة محجوزة عشوائيًا من العملاء المُعلَّمين لم تتلقَّ أي عرض لتقارن بها.","why":"صحيح. الفرق بين المجموعتين هو أثر العرض."}],"answer":3}],"exercise":{"kind":"python","files":["churn.csv"],"starter":"import io\n\nimport joblib\nimport pandas as pd\nimport sklearn\nfrom sklearn.linear_model import LogisticRegression\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.preprocessing import StandardScaler\n\nchurn = pd.read_csv(\"churn.csv\")\nfeatures = [\"tenure_days\", \"orders\", \"total_spent\", \"avg_order_value\",\n \"days_since_last_order\", \"used_coupon\", \"support_tickets\", \"mobile_share\"]\nchampion = make_pipeline(StandardScaler(), LogisticRegression()).fit(churn[features], churn[\"churned\"])\n\ngood = {\"tenure_days\": 400, \"orders\": 2, \"total_spent\": 180.0, \"avg_order_value\": 90.0,\n \"days_since_last_order\": 150, \"used_coupon\": 0, \"support_tickets\": 1, \"mobile_share\": 0.5}\n\n# 1. A bundle with the fitted pipeline, the feature list, a version string and sklearn's version\nbundle = {\"model\": champion}\n\n# 2. Save it with joblib to an in-memory buffer, then load it back into `reloaded`\nbuffer = io.BytesIO()\nreloaded = None\n\n# 3. Validate, then predict. Raise ValueError if any feature is missing,\n# or if orders < 1, or if mobile_share is outside 0..1.\ndef predict_churn(record, bundle):\n row = pd.DataFrame([record])\n return bundle[\"model\"].predict_proba(row)[0, 1]\n","solution":"import io\n\nimport joblib\nimport pandas as pd\nimport sklearn\nfrom sklearn.linear_model import LogisticRegression\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.preprocessing import StandardScaler\n\nchurn = pd.read_csv(\"churn.csv\")\nfeatures = [\"tenure_days\", \"orders\", \"total_spent\", \"avg_order_value\",\n \"days_since_last_order\", \"used_coupon\", \"support_tickets\", \"mobile_share\"]\nchampion = make_pipeline(StandardScaler(), LogisticRegression()).fit(churn[features], churn[\"churned\"])\n\ngood = {\"tenure_days\": 400, \"orders\": 2, \"total_spent\": 180.0, \"avg_order_value\": 90.0,\n \"days_since_last_order\": 150, \"used_coupon\": 0, \"support_tickets\": 1, \"mobile_share\": 0.5}\n\nbundle = {\"model\": champion, \"features\": features,\n \"version\": \"churn-2025-09-30.1\", \"sklearn_version\": sklearn.__version__}\n\nbuffer = io.BytesIO()\njoblib.dump(bundle, buffer)\nbuffer.seek(0)\nreloaded = joblib.load(buffer)\n\ndef predict_churn(record, bundle):\n missing = [f for f in bundle[\"features\"] if f not in record]\n if missing:\n raise ValueError(f\"missing fields: {missing}\")\n if record[\"orders\"] < 1:\n raise ValueError(\"orders must be at least 1\")\n if not 0 <= record[\"mobile_share\"] <= 1:\n raise ValueError(\"mobile_share must be between 0 and 1\")\n row = pd.DataFrame([record])[bundle[\"features\"]]\n return float(bundle[\"model\"].predict_proba(row)[0, 1])\n\nprint(round(predict_churn(good, reloaded), 3))\n","checks":[{"id":"bundle","test":"set(bundle) >= {'model', 'features', 'version', 'sklearn_version'} and list(bundle['features']) == features and bundle['sklearn_version'] == sklearn.__version__"},{"id":"reloaded","test":"reloaded is not None and (reloaded['model'].predict_proba(churn[features]) == champion.predict_proba(churn[features])).all()"},{"id":"predicts","test":"isinstance(predict_churn(good, reloaded), float) and abs(predict_churn(good, reloaded) - float(champion.predict_proba(pd.DataFrame([good])[features])[0, 1])) < 1e-12 and abs(predict_churn(dict(reversed(list(good.items()))), reloaded) - predict_churn(good, reloaded)) < 1e-12"},{"id":"missing","test":"exec('try:\\n predict_churn({k: v for k, v in good.items() if k != \"orders\"}, reloaded)\\n _raised = False\\nexcept ValueError:\\n _raised = True', globals()) or _raised"},{"id":"ranges","test":"exec('try:\\n predict_churn({**good, \"mobile_share\": 7}, reloaded)\\n _raised = False\\nexcept ValueError:\\n _raised = True', globals()) or _raised and exec('try:\\n predict_churn({**good, \"orders\": 0}, reloaded)\\n _raised = False\\nexcept ValueError:\\n _raised = True', globals()) or _raised"}],"title":"احزم البطل","prompt":"جهّز البطل للإطلاق.
\nbundle: قاموس فيه "model" (الـ pipeline المدرَّب)، و"features" (قائمة الـ features)، و"version" (أي نص)، و"sklearn_version" (sklearn.__version__).bundle بـ joblib.dump في الـ buffer الموجود في الذاكرة، وأرجعه إلى البداية، ثم حمّله من جديد في reloaded.predict_churn(record, bundle): ارفع ValueError إذا كان أي feature مفقودًا، أو كان orders أقل من 1، أو كان mobile_share خارج النطاق 0–1. وإلا فأعِد احتمال الانقطاع كـ float في Python، مع ترتيب الأعمدة بحسب ترتيب الـ features في الحزمة (فمفاتيح السجلّ قد تأتي بأي ترتيب).joblib.dump(bundle, buffer)، ثم buffer.seek(0) قبل joblib.load(buffer): فالتحميل يقرأ من الموضع الحالي.","ابنِ missing = [f for f in bundle["features"] if f not in record] وارفع خطأً إذا لم تكن فارغة.","pd.DataFrame([record])[bundle["features"]] يثبّت ترتيب الأعمدة؛ وغلّف نتيجة predict_proba(...)[0, 1] بـ float()."],"explanation":"تحمل الحزمة كل ما تحتاجه مهمة في بيئة الإنتاج: الـ pipeline مع الـ scaler المدرَّب، وترتيب الأعمدة، وإصدارًا يُسجَّل مع كل تنبؤ، وإصدار المكتبة لتثبيته. وإعادة التحميل تعطي تنبؤات متطابقة. ويحوّل الحارس المدخلات السيئة إلى خطأ صريح بدل احتمال يبدو معقولًا، واختيار bundle["features"] يجعل ترتيب الأعمدة مستقلًا عن طريقة بناء المستدعي للسجلّ. وفي خدمة حقيقية سيكون الـ buffer ملفًا في مخزن نماذج موثوق.