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

Evaluation Engineering: إزاي تعرف إن نظام الـ AI بتاعك شغال فعلًا

Evaluation Engineering for LLM Systems

Golden datasets، offline وonline evals، LLM-as-judge ومعايرته ضد البشر، مقاييس RAG، تقييم الـ agents، وrelease gates إحصائية في CI بتكلفة محسوبة.

  • Professional Engineering
  • ~16 min read
  • 15 sections
  • 7 code examples
  • 1 diagrams
  • 8 questions
  • Priority L2 · Essential
  • Python 3 (المعمل stdlib، executed) · .NET 9 · GitHub Actions · أي LLM provider (الـ judge prompts عامة)

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

  • تبني golden dataset ممثّل ومتنسخ ومحمي من التلوث
  • تختار المقياس الصح لكل نوع feature: deterministic، reference-based، model-graded، human
  • تصمم LLM-as-judge بـ rubric وتعايره ضد human labels بـ agreement وkappa لكل شريحة
  • تفصل مقاييس الـ retrieval عن مقاييس الـ generation في RAG
  • تكتب acceptance criteria إحصائية لميزة غير حتمية وتقارن نسختين بشكل paired
  • تبني CI gates بمستويات (smoke/full/nightly) وتتحكم في تكلفة التقييم

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

01

ليه Evaluation هو الـ «unit tests» بتاعة الـ AI… وأصعب منها

Why evaluation engineering exists
Basics

في الـ backend التقليدي، Assert.Equal(42, Add(40, 2)) بيكفي. في LLM feature، نفس المدخل بيطلع مخرجات مختلفة، وأكتر من مخرج ممكن يكون صح، و«صح» نفسها محتاجة حكم. من غير eval منظم، كل تعديل في الـ prompt أو الـ model أو الـ retrieval هو رهان: ممكن يحسّن 10 حالات ويبوّظ 15 من غير ما حد ياخد باله.

اللي بيبوظ من غير eval engineering:

  • Vibe-checking: المهندس بيجرّب 5 أسئلة ويقول «أحسن». الـ 5 أسئلة دي هي اللي هو فاكرها، مش اللي المستخدمين بيسألوها.
  • Silent regressions: provider بيحدّث نموذج، أو حد غيّر chunk size، والجودة نزلت 6 نقاط على شريحة معينة (مثلًا الأسئلة العربي).
  • قرارات من غير أرقام: «نروح للنموذج الأرخص؟» من غير eval، الإجابة رأي.
Golden datasetversioned · stratifiedOffline eval runchecks · judge · statsCI gateblock / allowCanary → prodrelease artifactOnline evalsampled judge · feedbackTriage of failureshuman label → new cases
Evaluation layers: offline evals gate releases, online evals watch reality, و failures flow back into the dataset

الحلقة دي هي الفكرة كلها: الـ dataset بيكبر من فشل حقيقي، والـ gate بيمنع رجوع أي فشل اتصلّح.

02

بناء Golden Dataset: المصدر، الحجم، التقسيم، والنسخ

Building a representative, versioned golden dataset
Deep dive

من فين تيجي الحالات؟

  1. Production logs (بعد redaction وموافقة الاستخدام): أصدق مصدر لتوزيع الأسئلة الحقيقي. اختار عينة stratified مش عشوائية بحتة (عشان الشرائح النادرة المهمة تظهر).
  2. Domain experts: حالات صعبة وحالات «لازم يرفض فيها».
  3. Failure triage: كل bug report أو thumbs-down مصنّف يتحول لحالة.
  4. Synthetic generation: نموذج يولّد أسئلة من المستندات. مفيد للتغطية والـ bootstrap، لكن بيطلع أسئلة «سهلة» وبصياغة قريبة من نص المستند (فبيضخّم الـ retrieval recall). ما يزيدش عن جزء من الـ dataset، ولازم مراجعة بشرية.

التقسيم (stratification): حدّد الشرائح اللي تفرق معاك: نوع السؤال (fact lookup، multi-hop، comparison، «مش موجود في المستندات»)، اللغة، الـ tenant tier، طول السؤال، الـ intent. وكل تقرير eval لازم يطلع النتيجة لكل شريحة — المتوسط العام بيخبّي الكوارث.

JSONevals/rag-golden/cases.jsonl (one line, pretty-printed)
{
  "id": "rg-0142",
  "slice": {"type": "multi_hop", "lang": "ar", "tier": "enterprise"},
  "input": {"question": "إيه مدة الاسترداد للطلبات المدفوعة بالتقسيط؟", "tenant": "eval-tenant-01", "user_groups": ["support"]},
  "expected": {
    "relevant_chunks": ["policy-refunds#3", "policy-installments#1"],
    "must_include": ["14 يوم"],
    "must_not_include": ["30 يوم"],
    "answerable": true,
    "reference_answer": "الطلبات بالتقسيط مدة استردادها 14 يوم من الاستلام بدل 30."
  },
  "source": "triage:INC-2291",
  "added": "2026-10-03",
  "labels_by": ["expert:legal-ops"]
}

الحجم: مفيش رقم سحري، لكن الإحصاء بيحدد الحد الأدنى: لو عايز تفرّق بين 85% و80% بثقة معقولة محتاج مئات الحالات (المعمل تحت هيوضح ده). ابدأ بـ 50–100 حالة عالية الجودة أحسن من 2000 حالة synthetic مش متراجعة، وكبّر بالـ triage.

النسخ والتلوث: الـ dataset له version (rag-golden@2026-11-10) وكل نتيجة eval مربوطة بيه. ما تستخدمش حالات الـ golden set كـ few-shot examples في الـ prompt (ده contamination — الـ eval هيقيس الحفظ مش الفهم). وخلي جزء held-out ما حدش بيبص عليه أثناء ضبط الـ prompt.

Failure mode: Goodhart

لما الفريق يضبط الـ prompt على نفس الـ 80 حالة شهور، الـ score بيطلع والجودة الحقيقية لأ. علامة الخطر: الـ offline score بيتحسن والـ online feedback ثابت أو بينزل. الحل: held-out set، تجديد دوري من الإنتاج، ومراجعة online.

03

أنواع المقاييس: اختار الأرخص اللي بيقيس الحاجة الصح

Deterministic, reference-based, model-graded and human evaluation
Deep dive
النوعأمثلةالتكلفةإمتى
Deterministic checksJSON schema valid، فيه citation IDs موجودة فعلًا، ما فيهوش PII، الطول، regex للأرقام المطلوبة، tool اتنادى بالـ args الصحشبه صفردايمًا أول طبقة. أي حاجة ينفع تتقاس بكود تتقاس بكود
Reference-basedexact match، F1 على tokens، تطابق القيم المستخرجة، recall@k للـ chunksصفرextraction، classification، retrieval
Model-graded (LLM-as-judge)faithfulness، relevance، tone، completeness ضد rubriccall لكل حالةجودة نصية مفتوحة. بعد معايرته
Humanexpert review، side-by-sideعالية جدًامعايرة الـ judge، قرارات كبيرة، domains عالية الخطورة

مثال عملي — feature «استخراج بيانات الفاتورة»: مش محتاج judge خالص. كل حقل له قيمة متوقعة: قارن (بعد normalization للتواريخ والأرقام) واحسب accuracy لكل حقل. feature «اكتب رد مهذب على شكوى» محتاجة judge لـ tone + deterministic check إن الرد ما فيهوش وعود ممنوعة (refund أكبر من الحد).

Pythonevals/checks.py
import json, re

def check_citations(answer: str, retrieved_ids: set[str]) -> dict:
    cited = set(re.findall(r"\[(c-\d+)\]", answer))
    return {
        "has_citation": bool(cited),
        "citations_valid": cited <= retrieved_ids,           # no invented sources
        "invalid": sorted(cited - retrieved_ids),
    }

def check_must(answer: str, must_include: list[str], must_not_include: list[str]) -> dict:
    return {
        "missing": [m for m in must_include if m not in answer],
        "forbidden_present": [m for m in must_not_include if m in answer],
    }

def check_refusal(answer: str, answerable: bool) -> bool:
    refused = bool(re.search(r"(مش موجود|لا تتوفر|I don't know|not in the provided)", answer, re.I))
    return refused == (not answerable)                       # refuse exactly when unanswerable
04

مقاييس RAG: افصل الـ retrieval عن الـ generation

Retrieval metrics vs generation metrics
Deep dive

لو بتقيس «الإجابة صح؟» بس، لما تنزل مش هتعرف السبب. RAG ليه مرحلتين وكل واحدة ليها مقاييسها:

المرحلةالمقياسبيجاوب علىمحتاج
RetrievalRecall@kهل الـ chunks الصح وصلت لأول k؟relevant_chunks في الـ golden
RetrievalMRR / nDCG@kهل الصح في الأول ولا في الآخر؟نفس اللي فوق (+ درجات relevance لـ nDCG)
RetrievalContext precisionنسبة الـ context اللي ليه علاقة (noise)labels أو judge
GenerationFaithfulness / groundednessكل claim في الإجابة مسنود بالـ context؟judge أو NLI
GenerationAnswer correctnessالإجابة صح مقارنة بالمرجع؟reference_answer + judge
GenerationAnswer relevanceبتجاوب السؤال نفسه؟judge
End-to-endRefusal correctnessبيرفض لما المعلومة مش موجودة وبس؟answerable flag
Pythonevals/retrieval_metrics.py
import math

def recall_at_k(ranked: list[str], relevant: set[str], k: int) -> float:
    return len(set(ranked[:k]) & relevant) / len(relevant) if relevant else 1.0

def mrr(ranked: list[str], relevant: set[str]) -> float:
    for i, cid in enumerate(ranked, 1):
        if cid in relevant:
            return 1.0 / i
    return 0.0

def ndcg_at_k(ranked: list[str], gains: dict[str, int], k: int) -> float:
    dcg = sum(gains.get(c, 0) / math.log2(i + 1) for i, c in enumerate(ranked[:k], 1))
    ideal = sorted(gains.values(), reverse=True)[:k]
    idcg = sum(g / math.log2(i + 1) for i, g in enumerate(ideal, 1))
    return dcg / idcg if idcg else 1.0

قراءة التشخيص: recall@10 عالي + faithfulness قليل ← مشكلة generation (prompt، النموذج، context طويل فيه noise). recall@10 قليل ← ولا prompt هيصلّح؛ روح لـ chunking/embeddings/hybrid (Production Retrieval). faithfulness عالي + correctness قليل ← النموذج أمين للـ context لكن الـ context نفسه غلط/قديم (freshness).

05

تصميم LLM-as-judge

Rubrics, formats and known judge biases
Deep dive

الآلية: نموذج (غالبًا قوي) بياخد السؤال + الإجابة + (المرجع أو الـ context) + rubric، وبيطلع حكم منظّم. ده بيحوّل تقييم بشري مكلف لعملية رخيصة نسبيًا وقابلة للتكرار — بشرط إنه يتفق مع البشر على البيانات بتاعتك.

قواعد تصميم بتفرق:

  • Binary أو مقياس صغير بتعريفات: «faithful: نعم/لا» أثبت من «قيّم من 1 لـ 10». لو مقياس، كل درجة ليها تعريف ومثال.
  • مقياس واحد لكل judge call: judge واحد لـ faithfulness وواحد لـ tone، مش prompt واحد بيقيس 6 حاجات.
  • Reasoning قبل الحكم: خلّيه يكتب التبرير (مثلًا يعدّ الـ claims) قبل الـ verdict، في structured output.
  • Pairwise للمقارنة بين نسختين: «أنهي أحسن A ولا B» أسهل وأدق من درجتين مطلقتين — بس فيه position bias (المعمل).
  • ثبّت الـ judge: model version + prompt version + temperature 0 (أو أقل حاجة متاحة). تغيير الـ judge = تغيير «المسطرة»، ولازم إعادة معايرة.
Markdownjudges/faithfulness@v3.md
You are grading whether an ANSWER is fully supported by the CONTEXT.

Steps:
1. List each factual claim in the ANSWER as a short sentence.
2. For each claim, quote the CONTEXT span that supports it, or write "NONE".
3. A claim with "NONE" is unsupported. Opinions, greetings and "I don't know" are not claims.

Return JSON only:
{"claims": [{"claim": "...", "support": "..." | "NONE"}], "unsupported_count": <int>, "faithful": <true if unsupported_count == 0>}

CONTEXT:
<<<{context}>>>

ANSWER:
<<<{answer}>>>
Bias معروفشكلهالتخفيف
Position biasفي pairwise بيفضّل الأول (أو التاني)اسأل بالترتيبين؛ احسب الحكم المتسق بس
Verbosity biasالإجابة الأطول بتاخد درجة أعلىrubric صريح إن الطول مش ميزة؛ قِس الـ agreement حسب الطول (المعمل)
Self-preferenceبيفضّل outputs من نفس عيلة النموذجjudge من عيلة مختلفة أو معايرة منفصلة
Leniencyبيقول «جيد» لمعظم الحاجاتأمثلة سلبية في الـ calibration set؛ قِس precision على الـ bad
06

معمل: معايرة الـ judge ضد البشر + gates إحصائية

Executed lab: judge calibration, position bias, confidence intervals, paired comparison
Practical

المعمل بيحاكي 300 إجابة متصنّفة من بشر، و judge دقيق عمومًا لكن متساهل مع الإجابات الطويلة الغلط (verbosity bias). وبعدين بيوضح position bias في الـ pairwise، وإزاي تكتب gate على metric غير حتمي، وإزاي تقارن نسختين على نفس الحالات.

Pythoneval_lab.pyExecuted ✓
import random, math
random.seed(21)

# ---- 1) Calibrate an LLM judge against human labels -------------------------------------
# 300 answers labelled by humans as good (1) / bad (0). The simulated judge is right most of
# the time but is *lenient on long answers* (a known verbosity bias).
items = []
for i in range(300):
    human = 1 if random.random() < 0.7 else 0
    long_answer = random.random() < 0.4
    if human == 1:
        judge = 1 if random.random() < 0.93 else 0
    else:
        judge = 1 if random.random() < (0.55 if long_answer else 0.15) else 0   # bias: long + bad -> often "good"
    items.append((human, judge, long_answer))

def agreement(rows):
    tp = sum(1 for h, j, _ in rows if h == 1 and j == 1); tn = sum(1 for h, j, _ in rows if h == 0 and j == 0)
    fp = sum(1 for h, j, _ in rows if h == 0 and j == 1); fn = sum(1 for h, j, _ in rows if h == 1 and j == 0)
    n = len(rows); po = (tp + tn) / n
    pe = ((tp + fp) / n) * ((tp + fn) / n) + ((tn + fn) / n) * ((tn + fp) / n)   # chance agreement
    kappa = (po - pe) / (1 - pe)
    return dict(n=n, accuracy=round(po, 3), kappa=round(kappa, 3), tp=tp, tn=tn, fp=fp, fn=fn,
                judge_precision_on_bad=round(tn / (tn + fp), 3) if tn + fp else None)

print("judge vs human, all:        ", agreement(items))
print("judge vs human, short only: ", agreement([r for r in items if not r[2]]))
print("judge vs human, long only:  ", agreement([r for r in items if r[2]]))

# ---- 2) Position bias in pairwise judging ----------------------------------------------
# Ask "is A better than B?" twice with the order swapped. A consistent judge flips its answer.
def biased_pairwise(a_quality, b_quality, first_bonus=0.15):
    pa = 0.5 + (a_quality - b_quality) + first_bonus      # prefers whatever is shown first
    return random.random() < max(0, min(1, pa))
inconsistent = 0
for _ in range(400):
    qa, qb = random.random() * 0.3, random.random() * 0.3
    first = biased_pairwise(qa, qb); swapped = biased_pairwise(qb, qa)
    if first == swapped: inconsistent += 1                    # said "first wins" both times
print(f"\npairwise: order-swap inconsistency = {inconsistent/400:.1%}  (count only consistent verdicts, or average both orders)")

# ---- 3) Release gate on a non-deterministic metric ------------------------------------
def wilson(k, n, z=1.96):
    p = k / n; d = 1 + z * z / n
    c = (p + z * z / (2 * n)) / d; h = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
    return round(c - h, 3), round(c + h, 3)

for n in (30, 120, 500):
    k = round(0.86 * n)
    print(f"pass rate 86% on n={n:3d}: 95% CI = {wilson(k, n)}  -> gate 'lower bound >= 0.80' {'PASS' if wilson(k, n)[0] >= 0.80 else 'FAIL'}")

# ---- 4) Paired comparison of two prompt versions on the same 200 cases ----------------
base = [random.random() < 0.80 for _ in range(200)]
cand = [b if random.random() < 0.9 else (random.random() < 0.86) for b in base]   # mostly same outcome per case
only_cand = sum(1 for b, c in zip(base, cand) if c and not b)
only_base = sum(1 for b, c in zip(base, cand) if b and not c)
diffs = []
for _ in range(2000):                                         # paired bootstrap over cases
    idx = [random.randrange(200) for _ in range(200)]
    diffs.append(sum(cand[i] - base[i] for i in idx) / 200)
diffs.sort()
print(f"\nbase={sum(base)/200:.3f} cand={sum(cand)/200:.3f}  discordant: cand-only={only_cand} base-only={only_base}")
print(f"paired bootstrap 95% CI of (cand - base) = [{diffs[50]:+.3f}, {diffs[1949]:+.3f}]")
print("decision:", "candidate better" if diffs[50] > 0 else ("candidate worse" if diffs[1949] < 0 else "no detectable difference -> decide on cost/latency"))
ConsoleOutput — captured from a real run
judge vs human, all:         {'n': 300, 'accuracy': 0.86, 'kappa': 0.653, 'tp': 195, 'tn': 63, 'fp': 27, 'fn': 15, 'judge_precision_on_bad': 0.7}
judge vs human, short only:  {'n': 165, 'accuracy': 0.909, 'kappa': 0.798, 'tp': 101, 'tn': 49, 'fp': 7, 'fn': 8, 'judge_precision_on_bad': 0.875}
judge vs human, long only:   {'n': 135, 'accuracy': 0.8, 'kappa': 0.392, 'tp': 94, 'tn': 14, 'fp': 20, 'fn': 7, 'judge_precision_on_bad': 0.412}

pairwise: order-swap inconsistency = 50.2%  (count only consistent verdicts, or average both orders)
pass rate 86% on n= 30: 95% CI = (0.703, 0.947)  -> gate 'lower bound >= 0.80' FAIL
pass rate 86% on n=120: 95% CI = (0.785, 0.91)  -> gate 'lower bound >= 0.80' FAIL
pass rate 86% on n=500: 95% CI = (0.827, 0.888)  -> gate 'lower bound >= 0.80' PASS

base=0.795 cand=0.805  discordant: cand-only=4 base-only=2
paired bootstrap 95% CI of (cand - base) = [-0.015, +0.035]
decision: no detectable difference -> decide on cost/latency

اللي المفروض تطلع بيه:

  1. الـ agreement الكلي بيخدع: accuracy 86% و kappa مقبول. لكن على الإجابات الطويلة الـ kappa نزل جدًا والـ judge بيقول «good» لأغلب الإجابات الطويلة الغلط. لو الـ prompt الجديد بيطوّل الإجابات، الـ judge ده هيقول «تحسّن» والحقيقة عكس كده. عاير لكل شريحة، وخصوصًا الشرائح اللي تغيير النظام بيأثر عليها.
  2. Kappa مش accuracy: لو 70% من الإجابات good، judge بيقول «good» دايمًا هياخد accuracy 70% و kappa = 0. الـ kappa بيطرح الاتفاق اللي ممكن يحصل بالصدفة.
  3. Position bias: نسبة كبيرة من الأحكام اتقلبت لما بدّلنا الترتيب. احسب الحكم بالترتيبين.
  4. حجم العينة: نفس الـ 86% على 30 حالة فاصل الثقة بتاعها واسع جدًا والـ gate «الحد الأدنى ≥ 80%» فشل؛ على 500 نجح. يعني الـ gate لازم يكون على الحد الأدنى للفاصل مش على النسبة الخام، والـ dataset لازم يكون كبير كفاية للقرار اللي عايز تاخده.
  5. المقارنة paired: النسختين اتقيّموا على نفس الحالات. الفرق الظاهري نقطة واحدة، والـ bootstrap CI بيعدّي الصفر ← مفيش فرق مُثبت. القرار يبقى على التكلفة والـ latency، مش «الجديد أحسن».
بروتوكول معايرة عملي

(1) 150–300 حالة متصنّفة من خبيرين (احسب الاتفاق بينهم الأول — لو البشر مختلفين، الـ rubric مش واضح). (2) شغّل الـ judge واحسب accuracy/kappa/confusion لكل شريحة. (3) عدّل الـ rubric على جزء واقيس على الجزء التاني. (4) حدد حد قبول (مثلًا kappa ≥ 0.7 و precision على الـ bad ≥ 0.8). (5) أعد المعايرة عند تغيير الـ judge model أو تغيير كبير في شكل المخرجات.

07

Acceptance criteria لميزة غير حتمية

Writing testable requirements when outputs vary
Deep dive

الـ PM بيقول «المساعد لازم يجاوب صح». ده مش acceptance criterion. الصيغة القابلة للاختبار:

بدلاكتب
«يجاوب صح»على rag-golden@v7 (n ≥ 400): answer correctness ≥ 82% بحد أدنى للفاصل 95% ≥ 78%، وما فيش شريحة أقل من 70%
«ما يألّفش»faithfulness (judge معاير kappa ≥ 0.7) ≥ 92%؛ citation validity = 100% (deterministic)
«يرفض لو مش عارف»على 60 سؤال غير قابل للإجابة: refusal ≥ 90%؛ وعلى القابلة للإجابة: false refusal ≤ 5%
«سريع»TTFT p95 ≤ 1.5s، full answer p95 ≤ 6s على load profile محدد
«آمن»security suite: 0 نجاح لحالات الأثر العالي عبر 5 تكرارات لكل حالة
«ثابت»كل حالة critical بتعدّي في 5/5 تشغيلات (pass^5)، مش في المتوسط

ليه pass^k؟ لو حالة بتنجح 80% من المرات، المتوسط هيقول 80%، لكن المستخدم اللي بيسأل 5 مرات هيشوف فشل غالبًا. للحالات الحرجة (فلوس، صلاحيات، أمان) القبول يكون «كل مرة».

08

Offline vs Online evaluation

What you can only learn in production
Deep dive
OfflineOnline
البياناتgolden set ثابتtraffic حقيقي
بيجاوب على«هل النسخة دي أحسن/أسوأ على الحالات المعروفة؟»«هل المستخدمين بيستفيدوا؟ إيه الحالات الجديدة؟»
Signalschecks، judge، referencesthumbs up/down، copy، retry/rephrase، escalation لإنسان، task completion، judge على عينة
الدورGate قبل الإطلاقمراقبة + مصدر حالات جديدة + A/B

Implicit feedback أهم من الـ thumbs (أقل من نسبة صغيرة من المستخدمين بيضغطوها، وغالبًا الغاضبين): المستخدم أعاد صياغة نفس السؤال خلال دقيقة؟ نسخ الإجابة؟ فتح الـ citation؟ طلب إنسان؟ دي signals لكل interaction.

C#OnlineEvalSampler.cs
// Sample a small, stratified share of production traces into an evaluation queue.
public sealed class OnlineEvalSampler(IEvalQueue queue, IOptionsMonitor<OnlineEvalOptions> opts)
{
    public async Task OnAnswerCompletedAsync(AnswerTrace t, CancellationToken ct)
    {
        var o = opts.CurrentValue;
        var rate = t switch
        {
            { UserFeedback: Feedback.ThumbsDown } => 1.0,            // always look at explicit complaints
            { RetrievalResultCount: 0 }           => 0.5,            // suspicious: answered with no context
            { Release.IsCanary: true }            => o.CanaryRate,   // oversample the candidate
            _                                     => o.BaseRate      // e.g. 0.02
        };
        if (Random.Shared.NextDouble() >= rate) return;
        // Store IDs + redacted text only; raw PII never leaves the tenant boundary.
        await queue.EnqueueAsync(new EvalItem(t.TraceId, t.TenantId, t.Release.Id, t.Release.Version,
                                              Redactor.Redact(t.Question), Redactor.Redact(t.Answer),
                                              t.ContextChunkIds, t.Slice), ct);
    }
}
09

تقييم الـ agents باختصار

Trajectory evaluation (pointer)
Basics

الـ agents بتتقيّم على المسار (tools، arguments، ترتيب، عدد خطوات، policy violations) وعلى الحالة النهائية للعالم (الـ DB بعد التشغيل) أكتر من النص. وبتتكرر k مرات لكل سيناريو. التفاصيل ومعمل executed في Agentic Workflow Engineering.

10

Regression gates في CI

Tiered eval runs that block bad releases
Practical
Tierإمتىالمحتوىالوقت/التكلفة
Smokeكل PR بيلمس prompts/AI code30–50 حالة حرجة + كل الـ deterministic checks + security high-severityدقايق، تكلفة صغيرة
Fullقبل الـ merge لـ main أو قبل releaseالـ golden set كامل + judge + كل الشرائحعشرات الدقايق
Nightlyكل يوم على mainFull + تكرارات (pass^k) + held-out + drift على providerالأغلى؛ يكشف تغيّر الـ provider
YAML.github/workflows/ai-evals.yml
name: ai-evals
on:
  pull_request:
    paths: ["prompts/**", "ai-release/**", "src/Ai/**", "ingestion/**", "evals/**"]
  schedule: [{ cron: "0 2 * * *" }]           # nightly full run
jobs:
  evals:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -r evals/requirements.lock
      - name: Restore eval result cache
        uses: actions/cache@v4
        with:
          path: .eval-cache
          key: evals-${{ hashFiles('ai-release/**', 'prompts/**', 'evals/datasets/**', 'evals/judges/**') }}
      - name: Run tier
        run: >
          python evals/run.py
          --tier ${{ github.event_name == 'schedule' && 'nightly' || 'smoke' }}
          --release ai-release/rag-answer.yaml
          --baseline-from main
          --report out/report.json
        env:
          EVAL_LLM_KEY: ${{ secrets.EVAL_LLM_KEY }}
      - name: Gate
        run: python evals/gate.py out/report.json --policy evals/gates.yaml
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: eval-report, path: out/ }
YAMLevals/gates.yaml
# Gates compare the candidate with the baseline on the SAME cases (paired), per slice.
absolute:
  citation_validity: { min: 1.0 }             # deterministic: no invented sources, ever
  security_high_severity_successes: { max: 0 }
  answer_correct: { ci_lower_min: 0.78 }
  faithfulness: { ci_lower_min: 0.90 }
relative_to_baseline:
  answer_correct: { max_drop: 0.02, per_slice_max_drop: 0.05 }
  p95_latency_ms: { max_increase_pct: 15 }
  cost_per_request_usd: { max_increase_pct: 20 }
flaky_policy:
  rerun_failed_cases: 2                       # re-run only failures to separate noise from regressions
  critical_cases_require: "pass^3"
Failure modes في الـ gates

(1) Baseline بيتحسب من run قديم بـ judge مختلف ← المقارنة باطلة؛ الـ baseline يتحسب بنفس الـ judge version. (2) Gate «متوسط» من غير شرائح ← regression في العربي يعدّي. (3) Flaky gate بيفشل عشوائيًا ← الفريق يتعلم يعمل override؛ استخدم reruns للحالات الفاشلة وفواصل ثقة.

11

التحكم في تكلفة الـ eval

Keeping evaluation affordable
Deep dive

احسبها قبل ما تتفاجئ: تكلفة الـ run ≈ (عدد الحالات × تكرارات) × (تكلفة النظام نفسه لكل حالة + عدد الـ judges × تكلفة الـ judge لكل حالة). 500 حالة × 3 تكرارات × (نظام + 3 judges) = 6,000 call في الـ nightly. اضرب في سعر الـ tokens عندك.

  • Cache بالـ hash: نتيجة حالة = f(case، release manifest، judge version). لو مفيش حاجة من دول اتغيرت، استخدم النتيجة المحفوظة. في PR بيغيّر ملف Angular بس، الـ eval مش هيتشغل أصلًا (path filters).
  • Deterministic أولًا: لو الحالة فشلت في check حتمي، ما تدفعش judge عليها.
  • Judge أصغر بعد المعايرة: لو نموذج أرخص بيحقق نفس الـ kappa على الـ calibration set، استخدمه.
  • Stratified subsets للـ smoke، والـ full في الأوقات اللي تفرق.
  • Batch APIs لو الـ provider بيوفرها للـ nightly (أرخص غالبًا مقابل تأخير).
  • ميزانية للـ eval بتتتبع زي أي تكلفة (key منفصل للـ CI بـ quota).
12

اختبر فهمك

Knowledge check
Basics

Judge accuracy مع البشر 86% على 300 حالة. إيه الخطوة اللي لازم تعملها قبل ما تعتمد عليه في الـ gate؟

Prompt جديد جاب 81% مقابل 80% على نفس 200 حالة، والـ paired bootstrap CI للفرق [-1.5%, +3.5%]. القرار؟

إيه المشكلة في إضافة حالات الـ golden set كـ few-shot examples في الـ prompt؟

13

تمارين محلولة

Solved exercises
Practical
1 (Easy): اكتب deterministic checks لـ feature «لخّص الاجتماع في JSON فيه decisions و action_items بأصحابها»

الحل: JSON valid ضد schema؛ كل action item ليه owner من قائمة الحضور (مش اسم مؤلّف)؛ عدد الـ decisions ≤ عدد المذكور في الـ transcript؛ مفيش تاريخ خارج نطاق معقول؛ الطول ≤ حد. الـ judge بعد كده يقيس الاكتمال والدقة.

2 (Intermediate): عندك 2000 حالة synthetic و120 حالة من الإنتاج. تعمل إيه؟

الحل: الـ 120 هي الأساس (مع مراجعة و labels). من الـ synthetic خد عينة stratified تغطي الشرائح الناقصة، راجعها بشريًا، واشيل اللي صياغته منسوخة من المستند. علّم مصدر كل حالة (source) واطلع النتيجة لكل مصدر — لو الـ synthetic بيطلع أعلى بكتير، ده دليل إنه أسهل من الواقع.

3 (Intermediate): احسب: محتاج كام حالة عشان فاصل ثقة 95% لنسبة ~85% يكون عرضه ±3 نقاط؟

الحل: تقريب: n ≈ z²·p(1−p)/E² = 1.96² × 0.85 × 0.15 / 0.03² ≈ 544. يعني ~550 حالة. لو ±5 نقاط كفاية: ~196. ده بيوضح ليه 50 حالة مش كفاية لقرار «الفرق 2 نقطة».

4 (Challenging): الـ online thumbs-down زاد 40% بعد release، والـ offline gate كان أخضر. حلّل.

الحل: (1) قسّم الـ thumbs-down حسب الشرائح والـ release (canary vs stable) — هل الزيادة في الـ candidate فعلًا؟ (2) خد عينة وصنّفها: نوع فشل جديد مش موجود في الـ golden set؟ (توزيع الأسئلة اتغيّر، أو tenant جديد بمستندات مختلفة). (3) الـ judge ممكن متساهل في نوع الفشل ده (أعد المعايرة على العينة). (4) ضيف الحالات للـ golden set وخلّي الـ gate يمسكها، و rollback لو الأثر كبير.

5 (Challenging): صمّم eval لـ feature «اقتراح رد على تذكرة دعم» والموظف بيعدّل قبل الإرسال

الحل: Offline: judge لـ correctness ضد سياسة الشركة + deterministic (ما فيش وعود ممنوعة، اللغة صح). Online: edit distance بين المقترح والمرسل فعلًا (أقل = أنفع)، نسبة «استخدم الاقتراح» مقابل «كتب من الصفر»، وقت حل التذكرة. ده online metric ممتاز لأنه implicit وبيتقاس لكل تذكرة.

14

Mini project: Eval harness بـ CI gate للـ capstone

Mini project
Practical

في CAPSTONE/evals/: (1) datasets/rag-golden.jsonl بـ 100 حالة على الأقل في 5 شرائح (منهم 15 غير قابلة للإجابة). (2) run.py بيشغل النظام الحقيقي، بيحسب retrieval metrics + deterministic checks + faithfulness judge، وبيكاش النتايج بالـ hash. (3) calibration/ فيها 150 حالة متصنّفة وتقرير kappa لكل شريحة. (4) gate.py بفواصل ثقة ومقارنة paired بالـ baseline. (5) GitHub Actions بـ smoke/nightly.

معيار القبول: PR بيغيّر الـ prompt بحيث يبطّل يذكر citations ← الـ gate يفشل برسالة واضحة. PR بيغيّر comment في الكود ← الـ eval ما يتشغلش. تقرير الـ nightly فيه جدول لكل شريحة.

15

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) إيه الفرق بين offline و online eval؟
Offline على dataset ثابت قبل الإطلاق كـ gate؛ online على traffic حقيقي بعد الإطلاق بـ feedback و judge على عينة، وبيكشف الحالات الجديدة.
(Junior) ليه بنفصل retrieval metrics عن generation metrics في RAG؟
عشان نعرف المرحلة المسؤولة عن الفشل: لو الـ chunk الصح ما وصلش، ولا prompt هيصلّح؛ لو وصل والإجابة غلط، المشكلة في الـ generation.
(Senior) إزاي تثق في LLM-as-judge؟
بالمعايرة: dataset متصنّف من بشر (مع اتفاق بين البشر نفسهم)، accuracy و kappa و confusion لكل شريحة، اختبار الـ biases (position، verbosity)، تثبيت نسخة الـ judge، وإعادة المعايرة عند أي تغيير.
(Senior) اكتب acceptance criteria لميزة RAG.
مقاييس محددة على dataset معيّن بحجم معيّن: correctness بحد أدنى للفاصل، faithfulness بـ judge معاير، citation validity 100%، refusal correctness، latency p95، security suite صفرية، وحد أدنى لكل شريحة، و pass^k للحالات الحرجة.
(Staff) إزاي تبني ثقافة eval-driven في org من 6 فرق؟
Platform مشترك (harness، judges معايرة، gates، dashboards)، قالب acceptance criteria إجباري في الـ design review لأي AI feature، ownership للـ datasets لكل فريق، triage أسبوعي بيحوّل فشل الإنتاج لحالات، ميزانية eval، ومقاييس للـ platform نفسه (وقت الـ eval، نسبة الـ releases اللي اتمنعت صح). والأهم: القيادة تقبل «ما نطلقش» لما الـ gate يفشل.
↗

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

References & further reading

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

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

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