هنطلع من الدرس بإيه؟
الدرس ده بيربط النظرية بكود شغّال: كل مشروع صغير بس بيطبّق قاعدة هندسية حقيقية (leakage، access control، approval gate، regression gate، drift). الكود في EXAMPLES/AI-Projects وبيتشغّل بأمر واحد: ./run_all.sh.
- تبني inference API بـ validation صح وتشرح ليه الـ pipeline بيمنع data leakage.
- تثبت بالأرقام إن accuracy بتخدع مع class imbalance.
- تطبق access control قبل الـ ranking في RAG وتضمن tenant isolation.
- تصمم agent بـ allow-list و approval و idempotency و audit log.
- تبني regression gate وتفهم drift و rollback.
المتطلبات: AI Evaluation وMLOps.
ابدأ بمثال شغال: تشغيل كل حاجة
cd EXAMPLES/AI-Projects
pip install -r requirements.txt
./run_all.sh # 19 tests + model comparison tableالنتيجة المسجّلة وقت التأليف: Ran 19 tests ... OK (Tested)، وجدول المقارنة تحت (بتتغير الأرقام الدقيقة بإصدار المكتبات، لكن الدرس مبني على الاتجاه مش الأرقام).
positive rate: 0.059
baseline_most_frequent {'accuracy': 0.941, 'f1': 0.0, 'recall': 0.0, 'roc_auc': 0.5}
logreg {'accuracy': 0.961, 'f1': 0.524, 'recall': 0.377, 'roc_auc': 0.839}
logreg_balanced {'accuracy': 0.805, 'f1': 0.315, 'recall': 0.751, 'roc_auc': 0.842}
random_forest {'accuracy': 0.961, 'f1': 0.553, 'recall': 0.411, 'roc_auc': 0.879}1 · Classical ML Prediction API
الفكرة: تدريب Pipeline(StandardScaler, LogisticRegression) على breast-cancer dataset، حفظه بـ joblib، وتقديمه عبر POST /predict. الـ scaler جوه الـ pipeline يتعلّم من الـ train بس، فمفيش leakage من الـ test. الـ endpoint بيرفض: body مش JSON (400)، features ناقصة أو مش رقمية أو inf (422). تحذير أمان: ملفات joblib/pickle ممكن تنفّذ كود عند التحميل، فما تحمّلش إلا موديل أنت أنتجته.
Trace للطلب: JSON ← تحقق من الشكل ← ترتيب الـ features بالاسم (مش بالترتيب اللي وصل) ← float() وفحص finite ← predict_proba ← أعلى احتمال + اسم الـ class + إصدار الموديل. وجود model_version في الرد بيخلّي أي مشكلة قابلة للتتبع.
2 · Model Evaluation: ليه accuracy بتخدع
البيانات فيها 5.9% positives. الـ baseline اللي بيتنبأ دايمًا بالأغلبية جاب accuracy 0.941 و recall 0: دقة عالية وهو مش بيلاقي ولا حالة. class_weight="balanced" رفع الـ recall من 0.377 لـ 0.751 لكن الـ accuracy نزلت لـ 0.805: ده trade-off مش «تحسين مجاني»، والاختيار بيعتمد على تكلفة الـ false negative مقابل الـ false positive. الـ cross-validation مع StratifiedKFold بيحافظ على نسبة الـ positives في كل fold. ملاحظة: القيم بالتوسط على 5 folds ومن seed واحد، فمش دليل إحصائي على تفوق نموذج.
3 · RAG Knowledge Assistant
الخطوات: chunking بالكلمات مع overlap (chunk_text) ← TF-IDF ← cosine similarity ← فلترة tenant و role قبل الـ ranking ← رد extractive مع citations ← رفض لو أعلى score أقل من الحد (min_score). الفلترة قبل الترتيب مقصودة: لو رتّبت الأول وفلترت بعدين، chunk غير مصرّح بيه ممكن يوصل للـ prompt لو حصل bug. الاختبارات بتثبت: موظف عادي ما يشوفش مستند الـ HR، ومستند tenant تاني ما بيظهرش أبدًا، والحذف وإعادة الـ ingest بيحدّثوا الإجابة.
للـ debugging لما الـ retrieval ضعيف: اطبع الـ chunks والـ scores، جرّب أحجام chunk مختلفة، وافحص إن السؤال والمستند بيستخدموا نفس المفردات (TF-IDF بيعتمد على تطابق الكلمات؛ للمرادفات محتاج embeddings). ده حد معروف في النسخة دي.
4 · Agent Workflow مع Human Approval
الـ Agent.run بينفّذ plan تحت guardrails: allow-list (tool مش موجود = blocked)، approval للـ tools الخطرة (risky=True)، idempotency key (نفس المفتاح مرتين = مفيش تنفيذ تاني، فمفيش إيميل مكرر)، max_steps، وتسجيل الأخطاء في audit log بدل ابتلاعها. ده مثال إن workflow محدد بحدود واضحة أأمن من agent حر لعمليات الأعمال المتوقعة. الـ planner الحقيقي (LLM) مجرد مصدر للـ plan؛ الحماية في الكود مش في الـ prompt.
5 · Evaluation و Regression Gate
بنقيس hit@k (الإجابة الصح ضمن أول k) و MRR (متوسط 1/ترتيب أول نتيجة صحيحة) على golden set. الـ gate بيفشل لو أي مقياس نزل أكتر من tolerance عن الـ baseline. الاختبار بيحاكي «تغيير ingestion كسر مستند» (حذف expenses) والـ gate بيمسكه. حد: golden set من 3 أسئلة مثال تعليمي؛ في الواقع محتاج عشرات/مئات أسئلة حقيقية، وقياس الـ generation (faithfulness) منفصل عن الـ retrieval.
6 · MLOps: Drift و Registry و Canary
psi() و KS test بيقارنوا توزيع الـ reference بالـ production. عتبة PSI (0.1/0.25) عُرف شائع مش قانون. الـ Registry ملف JSON بيتحدّث بـ atomic replace، والـ promote بيرفض أي موديل ROC-AUC بتاعه أقل من الحد (evaluation gate)، والـ rollback بيرجّع النسخة السابقة. canary_decision بيقول wait/promote/rollback حسب حجم الترافيك والتراجع في الـ error. في الإنتاج هتستخدم أداة (MLflow وغيره)، لكن الفكرة واحدة.
أخطاء شائعة
- عمل scaling على الداتا كلها قبل التقسيم (leakage).
- الحكم بالـ accuracy على بيانات imbalanced.
- فلترة الصلاحيات بعد الـ ranking أو داخل الـ prompt فقط.
- الاعتماد على «تعليمات في الـ prompt» بدل guardrails في الكود للـ agent.
- تحميل ملفات pickle/joblib من مصدر غير موثوق.
- تغيير prompt/chunking/model من غير تشغيل regression gate.
خمس تمارين محلولة
1 (Easy): ليه الـ baseline حقق accuracy 0.941 رغم إنه ما بيلاقيش أي positive؟
الحل: 94.1% من الصفوف negative (positive rate 0.059)، فالتنبؤ بـ negative دايمًا صح في 94.1%. الـ recall = TP/(TP+FN) = 0 لأن TP = 0. ده بيوضح ليه نستخدم recall/F1/AUC مع imbalance.
2 (Easy): إيه فايدة وضع الـ scaler جوه Pipeline؟
الحل: الـ cross-validation هيعمل fit للـ scaler على كل train fold لوحده، فمعلومات الـ validation ما بتتسربش. لو scale الداتا كلها قبل التقسيم، المتوسط والانحراف المعياري بيشملوا الـ test (leakage) والنتيجة بتطلع متفائلة.
/predict_batch بحد أقصى 100 صف">
الحل: استقبل {"rows":[...]}، ارفض (413 أو 422) لو الطول > 100 (حماية من الـ DoS)، وطبّق نفس validation لكل صف، واعمل predict_proba على مصفوفة واحدة بدل loop. اكتب اختبار للحد الأقصى ولصف واحد غلط (هل ترفض الطلب كله أم ترجّع خطأ لكل صف؟ قرر ووثّق).
size=15, overlap=5 في الـ RAG. إيه اللي هيتغير؟">
الحل: chunks أصغر = retrieval أدق لكن سياق أقل وعدد chunks أكبر؛ الـ overlap بيحمي الجمل المقطوعة على الحدود. قيس بـ run_eval على golden set قبل وبعد؛ ما تقررش بالحدس.
5 (Challenging): صمم تغيير يخلي الـ Agent يتحمل «approval timeout»
الحل: خلّي approver يرجّع True/False/None (None = انتهى الوقت). عند None سجّل event="approval_timeout" وخلّي الخطوة pending (متخزنة بمفتاحها) بدل execute أو deny نهائي، وأتح resume(key) لما الموافقة توصل. الأمان: الافتراضي عند الشك = ما ينفذش. اكتب اختبارات: timeout ما بينفذش، resume بعد الموافقة بينفذ مرة واحدة (idempotency).
Mini Project: اربط المشاريع ببعض
اعمل Flask endpoint POST /ask بيستخدم KnowledgeBase و answer، مع header بسيط للـ tenant/role (للتجربة فقط؛ في الإنتاج الهوية تيجي من JWT موثّق)، ويسجل كل سؤال مع grounded و latency. أضف اختبارات: tenant isolation عبر HTTP، رفض سؤال مش موجود، و gate في CI يشغّل run_eval. معيار النجاح: ./run_all.sh أخضر وكل قاعدة أمان ليها اختبار.
أسئلة إنترفيو
ليه فلترة الصلاحيات قبل الـ ranking في RAG؟
إيه الفرق بين hit@k و MRR؟
إمتى الـ agent يحتاج human approval؟
يعني إيه idempotency للأدوات؟
PSI بيقيس إيه، وهل عتبة 0.25 قانون؟
(أصعب) الـ accuracy ارتفعت بعد تغيير لكن الـ recall نزل. تقبل التغيير؟
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) إزاي تختبر نظام فيه LLM؟
(Senior) إيه الفرق بين الـ prototype بتاعك والنسخة production-ready؟
(Staff) فريق جديد عنده 6 prototypes زي دول وعايز يطلع للإنتاج في ربع سنة. ترتّب إزاي؟
الست مشاريع دول بيتركّبوا في نظام واحد
كل مشروع هنا معزول عن قصد عشان القاعدة الهندسية تبان لوحدها. في الشغل الحقيقي (وفي الـ Master Capstone) هما أجزاء من نفس النظام. الرسم ده بيوضح كل مشروع بيتحول لإيه:
من lab لـ production: الترقية لكل مشروع
| المشروع | اللي ناقص للإنتاج | الترقية | درس التفاصيل |
|---|---|---|---|
| 1 · ML API | contract مكتوب، auth، versioning، observability، rate limits | FastAPI + Pydantic schema + OpenAPI، typed client في .NET، OTel، model version في كل response | Applied ML |
| 2 · Model comparison | تقسيم زمني/group، تكلفة القرار، calibration | temporal CV + PR-AUC + threshold من التكلفة | Applied ML |
| 3 · RAG | TF-IDF بيفشل مع المرادفات، الـ ACL في الذاكرة، مفيش freshness | embeddings + pgvector + FTS hybrid + RLS + reranker + outbox reindex | Production Retrieval |
| 4 · Agent | planner deterministic، approval في الذاكرة، مفيش checkpoint | LLM + tool registry بـ scopes + approval مربوط بـ digest + Postgres checkpoints + idempotency منطقي | Agentic Engineering |
| 5 · Eval gate | hit@k/MRR بس، golden صغير، مفيش statistics | retrieval + generation metrics، judge معاير، فواصل ثقة، paired comparison، tiers في CI | Evaluation Engineering |
| 6 · MLOps | registry ملف JSON، canary يدوي | model registry حقيقي، release manifests، sticky canary بـ guardrail metrics، rollback تلقائي | LLMOps |
مثال ترقية كامل: ML API بـ contract و typed client
ليه contract-first؟ الـ .NET backend هو اللي هيكلم الـ Python service. لو الـ contract ضمني («ابعت JSON فيه features»)، أي تغيير في Python بيكسر .NET في الإنتاج. لما الـ schema مكتوب (Pydantic ← OpenAPI)، تقدر تولّد client، وتعمل contract tests في الـ CI بتاع الاتنين.
from fastapi import FastAPI, Depends, HTTPException, Header
from pydantic import BaseModel, Field, ConfigDict
import joblib, hashlib, hmac, os
MODEL_PATH = "models/cancer-v3.joblib"
SERVICE_TOKEN = os.environ["ML_SERVICE_TOKEN"]
# joblib = pickle: loading it executes code. Only load artifacts produced by OUR training pipeline,
# and verify the hash recorded in the model registry before loading (see AI Security: supply chain).
digest = hashlib.sha256(open(MODEL_PATH, "rb").read()).hexdigest()
if digest != os.environ["ML_MODEL_SHA256"]:
raise SystemExit("model artifact hash mismatch: refusing to load")
model = joblib.load(MODEL_PATH)
MODEL_VERSION = "cancer-v3+" + digest[:12]
FEATURES = list(model.feature_names_in_) # the contract comes from the trained artifact
class PredictRequest(BaseModel):
model_config = ConfigDict(extra="forbid") # unknown fields are a client bug -> 422
features: dict[str, float] = Field(..., description="name -> value; all model features required")
class PredictResponse(BaseModel):
label: str
probability: float
model_version: str
app = FastAPI(title="ml-service", version="1.0.0")
def require_service_token(authorization: str = Header(...)):
if not hmac.compare_digest(authorization, "Bearer " + SERVICE_TOKEN): # constant-time; prod: mTLS / managed identity
raise HTTPException(401)
@app.post("/v1/predict", response_model=PredictResponse, dependencies=[Depends(require_service_token)])
def predict(req: PredictRequest):
missing = [f for f in FEATURES if f not in req.features]
if missing:
raise HTTPException(422, detail={"missing_features": missing[:10]})
row = [[req.features[f] for f in FEATURES]] # order by name, never by arrival order
proba = model.predict_proba(row)[0]
i = int(proba.argmax())
return PredictResponse(label=str(model.classes_[i]), probability=float(proba[i]), model_version=MODEL_VERSION)
@app.get("/healthz")
def health():
return {"status": "ok", "model_version": MODEL_VERSION}public sealed record PredictRequest(IReadOnlyDictionary<string, double> Features);
public sealed record PredictResponse(string Label, double Probability, string ModelVersion);
public sealed class MlServiceClient(HttpClient http, ILogger<MlServiceClient> log)
{
public async Task<PredictResponse> PredictAsync(PredictRequest req, CancellationToken ct)
{
using var resp = await http.PostAsJsonAsync("/v1/predict", req, ct);
if (resp.StatusCode == HttpStatusCode.UnprocessableEntity)
{
var body = await resp.Content.ReadAsStringAsync(ct);
log.LogError("ML contract violation: {Body}", body); // a deploy mismatch, page the owner
throw new MlContractException(body);
}
resp.EnsureSuccessStatusCode();
return (await resp.Content.ReadFromJsonAsync<PredictResponse>(cancellationToken: ct))!;
}
}
// Program.cs
builder.Services.AddHttpClient<MlServiceClient>(c =>
{
c.BaseAddress = new Uri(builder.Configuration["MlService:BaseUrl"]!);
c.DefaultRequestHeaders.Authorization = new("Bearer", builder.Configuration["MlService:Token"]);
}).AddStandardResilienceHandler(); // timeouts, retries with jitter, circuit breakerContract test في CI: الـ Python pipeline بيصدّر openapi.json كـ artifact؛ الـ .NET pipeline بيقارن الـ DTOs بتاعته بيه (أو بيولّد الـ client منه بأداة زي NSwag/Kiota). أي breaking change يظهر في الـ PR مش في الإنتاج.
Testing pyramid لنظام AI
| الطبقة | بتختبر | أمثلة | بتتشغل |
|---|---|---|---|
| Unit (حتمي) | الكود حوالين النموذج | chunker، ACL filter، tool gate، idempotency، cost calc، output policy | كل commit، ثواني |
| Integration | المكونات مع بعض ببيانات حقيقية | Postgres + RLS (Testcontainers)، retrieval end-to-end بـ fake embedder | كل PR |
| Contract | الحدود بين الخدمات | OpenAPI بين .NET و Python، MCP tool schemas | كل PR |
| Eval (احتمالي) | جودة السلوك | golden set، judge، security suite | PR (smoke) + nightly |
| Load | latency/throughput/تكلفة تحت ضغط | k6 بسيناريو واقعي + mock LLM بـ latency واقعية | قبل release كبير |
نقطة مهمة: الـ unit/integration tests ما ينفعش تعتمد على LLM حقيقي (بطيئة، مكلفة، غير حتمية). استخدم fake IChatClient بيرجّع ردود ثابتة. الـ LLM الحقيقي مكانه طبقة الـ eval بس.
import http from 'k6/http';
import { check } from 'k6';
export const options = {
scenarios: {
chat: { executor: 'ramping-arrival-rate', startRate: 2, timeUnit: '1s', preAllocatedVUs: 50,
stages: [{ target: 10, duration: '3m' }, { target: 25, duration: '5m' }, { target: 0, duration: '1m' }] },
},
thresholds: {
'http_req_failed': ['rate<0.02'],
'http_req_duration{endpoint:chat}': ['p(95)<6000'],
},
};
const QUESTIONS = JSON.parse(open('./questions.json')); // realistic mix, incl. Arabic and long questions
export default function () {
const q = QUESTIONS[Math.floor(Math.random() * QUESTIONS.length)];
const res = http.post(`${__ENV.BASE_URL}/api/chat`, JSON.stringify({ question: q }), {
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${__ENV.TOKEN}` },
tags: { endpoint: 'chat' },
});
check(res, { 'status 200': (r) => r.status === 200 });
}Load test للـ AI مختلف: الـ bottleneck غالبًا rate limits الـ provider (tokens/minute) مش الـ CPU. فـ load test على الـ provider الحقيقي = فاتورة و rate limiting. الحل: mock LLM server بيحاكي الـ latency و TTFT والـ 429 بنسب واقعية لاختبار الـ API والـ queueing، واختبار صغير منفصل على الـ provider لقياس الـ limits الفعلية.
إزاي تعرض المشاريع دي في الإنترفيو
المشاريع الصغيرة دي قيمتها في الإنترفيو مش «عملت RAG»، قيمتها في القرارات والأرقام. لكل مشروع جهّز:
- Problem → decision: جملة واحدة: إيه المشكلة وإيه القرار اللي النظام بيدعمه.
- رسم واحد (component + data flow).
- رقم قبل وبعد: «recall@10 من 0.61 لـ 0.83 بالـ hybrid»، «الـ breaker نزّل p95 وقت الانقطاع».
- Trade-off واحد واعٍ: «اخترت pgvector بدل vector DB لأن… وده الحد اللي هغيّر عنده».
- Failure حقيقي صلّحته: «refund مكرر رغم loop guard ← idempotency منطقي».
- إيه اللي هتعمله بشكل مختلف لو عندك أسبوعين كمان.
«ليه TF-IDF؟» (عن قصد: offline، deterministic، وبيوضح الـ ACL قبل الـ ranking؛ الترقية embeddings + hybrid). «إزاي عرفت إن الـ gate بيشتغل؟» (كسرت الدفاع عمدًا والـ test فشل). «لو 100x traffic؟» (provider limits، caching، queueing، batching للـ embeddings، read replicas).
المشاريع الجديدة في v7: ML حقيقي end-to-end وموديل حقيقي في الـ Capstone
المشاريع الست فوق مقصود إنها صغيرة وبتشتغل من غير GPU ولا مفاتيح API. خطوتين بعدهم بيقربوك من الشغل الحقيقي:
- End-to-End ML Project: dataset عام حقيقي ← EDA ← baseline ← موديل ← تقييم بشرائح و confidence intervals ← API بـ FastAPI يستهلكه ASP.NET Core ← Docker ← monitoring.
- قسم «استبدال الـ mock LLM والـ hashing embedder بموديل حقيقي (Ollama محلي أو provider مُدار)» في Capstone Build-Along، مع قياس الجودة والتكلفة والـ latency الحقيقيين على الـ golden set.
| المشروع | الـ upgrade الجاي | بتتعلم إيه زيادة |
|---|---|---|
| 1 · ML Prediction API | dataset حقيقي + calibration + drift | بيانات وسخة، leakage، تقييم أمين |
| 3 · RAG Assistant | embeddings و LLM حقيقيين | تكلفة/latency فعلية، فروق الموديلات على العربي |
| 5 · Eval Gate | 400+ سؤال بشرائح | statistical significance، اختيار الـ thresholds |
Knowledge check
ليه الـ unit tests ما ينفعش تنادي LLM حقيقي؟
Load test على الـ chat endpoint بالـ provider الحقيقي فشل بـ 429 كتير. الاستنتاج الأدق؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.