ليه AI features بتحتاج product engineering مختلف
في feature عادية: الزرار بيعمل نفس الحاجة كل مرة، والـ QA بيقول «شغال/مش شغال». في AI feature: الإجابة بتتغير، أحيانًا غلط بثقة، أحيانًا بطيئة 8 ثواني، أحيانًا الـ provider واقع. المنتج الناجح مش اللي الموديل بتاعه «الأذكى»؛ اللي بيتعامل بأمانة مع عدم اليقين: بيوري مصادره، بيقول «مش متأكد»، بيسيب الإنسان يقرر في الحاجات المهمة، وبيفضل مفيد لما الـ AI يقع.
UX للـ AI: الأنماط اللي بتبني الثقة
| النمط | ليه | التنفيذ | غلطة شائعة |
|---|---|---|---|
| Streaming | TTFT هو اللي المستخدم بيحسه؛ 6 ثواني فاضية = «واقع» | SSE من الـ API، رسم تدريجي، زر إيقاف | رسم markdown جزئي بيكسر الصفحة/يحمّل صور قبل الفلترة |
| Citations | المستخدم يتحقق، والثقة تتبني على المصادر | [1] جنب الجملة، panel بالمصدر والفقرة، روابط من metadata موثوقة | citations مؤلّفة أو بتشاور على مستند المستخدم مالوش صلاحية عليه |
| Confidence/uncertainty | منع الثقة الزايدة | «ما لقيتش مصدر مباشر» بدل نسبة مئوية زائفة؛ تمييز الإجابة من المصادر عن الاستنتاج | عرض «92% confidence» من رقم مالوش معنى calibrated |
| Fallback/degraded | الـ AI هيقع | بحث عادي في المستندات، رسالة واضحة، الـ features التانية شغالة | صفحة error كاملة لأن الـ LLM timeout |
| Human-in-the-loop | الأفعال ذات الأثر | draft بيتعدّل، موافقة صريحة بتعرض المعطيات الفعلية | «تم الإرسال» من غير ما المستخدم يشوف النص |
| Feedback | بيانات للتحسين | thumbs + سبب اختياري، والـ implicit signals | feedback بيروح في الفراغ (مفيش triage) |
الإجابات بتخلط عربي وإنجليزي وأكواد وأرقام. استخدم dir="auto" على كل فقرة، وعزل الـ inline code والمصطلحات بـ unicode-bidi: isolate (نفس قواعد الموسوعة دي)، واختبر citations بعد علامات الترقيم العربي. أي bug هنا بيبان كـ «الـ AI بيكتب كلام ملخبط».
Streaming end-to-end: من IChatClient لـ Angular
public sealed record ChatRequest(string Question, Guid? ConversationId);
public sealed record ChatChunk(string Type, string? Text = null, IReadOnlyList<Citation>? Citations = null, string? Error = null);
public sealed record Citation(int N, Guid ChunkId, string Title, string Url);
app.MapPost("/api/chat/stream", async (ChatRequest req, IRagPipeline rag, HttpContext http, CancellationToken ct) =>
{
http.Response.Headers.ContentType = "text/event-stream";
http.Response.Headers.CacheControl = "no-cache";
http.Features.Get<IHttpResponseBodyFeature>()?.DisableBuffering(); // flush tokens as they come
async Task Send(ChatChunk c)
{
await http.Response.WriteAsync($"data: {JsonSerializer.Serialize(c, JsonOpts.Web)}\n\n", ct);
await http.Response.Body.FlushAsync(ct);
}
try
{
var prepared = await rag.PrepareAsync(req.Question, ct); // retrieval + ACL + context budget
await Send(new("citations", Citations: prepared.Citations)); // sources first: the UI can show them early
await foreach (var delta in rag.StreamAnswerAsync(prepared, ct)) // ct fires when the browser disconnects
await Send(new("delta", Text: delta));
await Send(new("done"));
}
catch (OperationCanceledException) { /* user pressed stop or closed the tab: stop paying for tokens */ }
catch (LlmUnavailableException)
{
await Send(new("degraded", Error: "AI assistant unavailable — showing search results instead."));
}
}).RequireAuthorization().RequireRateLimiting("per-tenant");// fetch + ReadableStream (EventSource cannot POST or send an Authorization header)
@Injectable({ providedIn: 'root' })
export class ChatService {
private readonly auth = inject(AuthService);
stream(question: string, onChunk: (c: ChatChunk) => void, signal: AbortSignal): Promise<void> {
return fetch('/api/chat/stream', {
method: 'POST', signal,
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.auth.token()}` },
body: JSON.stringify({ question }),
}).then(async (res) => {
if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
let idx: number;
while ((idx = buffer.indexOf('\n\n')) >= 0) { // one SSE event per blank line
const line = buffer.slice(0, idx).replace(/^data: /, '');
buffer = buffer.slice(idx + 2);
if (line) onChunk(JSON.parse(line) as ChatChunk);
}
}
});
}
}@Component({ selector: 'app-chat', standalone: true, imports: [SafeMarkdownPipe, CitationListComponent], templateUrl: './chat.component.html' })
export class ChatComponent {
private readonly chat = inject(ChatService);
readonly answer = signal('');
readonly citations = signal<Citation[]>([]);
readonly status = signal<'idle' | 'streaming' | 'done' | 'degraded' | 'error'>('idle');
private controller?: AbortController;
ask(q: string) {
this.controller?.abort();
this.controller = new AbortController();
this.answer.set(''); this.citations.set([]); this.status.set('streaming');
this.chat.stream(q, (c) => {
if (c.type === 'citations') this.citations.set(c.citations ?? []);
else if (c.type === 'delta') this.answer.update((a) => a + (c.text ?? ''));
else if (c.type === 'done') this.status.set('done');
else if (c.type === 'degraded') this.status.set('degraded');
}, this.controller.signal).catch((e) => { if (e.name !== 'AbortError') this.status.set('error'); });
}
stop() { this.controller?.abort(); this.status.set('done'); }
}ملاحظات: (1) الـ markdown بيترسم بالـ SafeMarkdownPipe (درس AI Security) ومع CSP. (2) الـ cancellation من الـ browser بيوصل للـ CancellationToken وبيقفل الـ LLM call = توفير فعلي. (3) proxies و CDNs ممكن تعمل buffering للـ SSE؛ اختبر خلف نفس البنية بتاعة الإنتاج.
Acceptance criteria من منظور المنتج
نفس المبدأ اللي في Evaluation Engineering لكن من ناحية المنتج: الـ PM والمهندس بيتفقوا على المقياس، الـ dataset، الحد، والشريحة قبل البناء.
feature: suggested-replies
owner: team-support-ai
user_value: agents answer tickets faster without lowering quality
offline_gates: # must pass before any tenant sees it
dataset: "support-golden@v3 (n=420; slices: lang, category, has_attachment)"
policy_compliance: { min: 0.98 } # deterministic checks: no promises beyond policy limits
answer_quality_judge: { ci_lower_min: 0.80, per_slice_min: 0.70 } # judge kappa >= 0.72 vs humans
refusal_when_no_article: { min: 0.90 }
p95_time_to_first_token_ms: { max: 1500 }
online_success: # measured in the canary / A/B
primary: median_handle_time_reduction >= 15%
guardrails:
- csat_drop <= 1 point
- reopen_rate_increase <= 2%
- ai_cost_per_ticket_usd <= 0.03
adoption_signal: suggestion_used_rate >= 40% # agent sent it with edit distance < 30%Eval-driven development
زي TDD، بس للسلوك الاحتمالي: (1) حالة فشل من الإنتاج أو من الـ PM ← (2) تتضاف للـ golden set بالتوقع الصح ← (3) تشغّل الـ eval وتشوفها فاشلة ← (4) تعدّل (prompt، retrieval، tool) ← (5) الـ eval كله، مش الحالة بس، عشان تتأكد إنك ما كسرتش حاجة تانية ← (6) PR فيه الحالة + الإصلاح + تقرير الـ eval.
python evals/add_case.py --from-trace 4bf92f3577b34da6 --expect-must-include "14 يوم" --slice multi_hop,ar
python evals/run.py --tier smoke --only rg-0143 # see it fail
# ... change chunking for tables / the prompt / the retriever weight ...
python evals/run.py --tier full --baseline-from main # paired comparison, per slice«صلّحنا الحالة» بتعديل الـ prompt بجملة مخصوصة («لو السؤال عن التقسيط قول 14 يوم»). ده overfitting لحالة؛ الإجابة الصح للسؤال ده بقت مزروعة والفهم ما اتحسنش. الإصلاح الصح غالبًا في الـ retrieval أو الـ chunking. الـ held-out set هو اللي بيكشف ده.
الـ prompts والـ models كـ release artifacts
الـ release manifest (LLMOps) هو اللي بيربط المنتج بالـ AI: كل feature flag variant بيشاور على manifest version، وكل trace بيسجله، وكل تقرير A/B بيقسّم عليه. من ناحية المنتج: «النسخة 14 من اقتراح الردود» شيء له changelog وتاريخ إطلاق ونتائج، زي «v2.3 من صفحة الفواتير».
{
"FeatureManagement": {
"assist.suggest-reply": {
"EnabledFor": [{ "Name": "Microsoft.Targeting", "Parameters": {
"Audience": { "Groups": [{ "Name": "beta-tenants", "RolloutPercentage": 100 }], "DefaultRolloutPercentage": 0 }
} }],
"Variants": [
{ "Name": "control", "ConfigurationValue": { "release": "suggest-reply@13" } },
{ "Name": "candidate", "ConfigurationValue": { "release": "suggest-reply@14" } }
],
"Allocation": { "Percentile": [ { "Variant": "control", "From": 0, "To": 90 }, { "Variant": "candidate", "From": 90, "To": 100 } ],
"Seed": "suggest-reply-14" }
}
}
}الـ schema بالظبط بتاع variants والـ allocation بيختلف بين نسخ Microsoft.FeatureManagement — راجع التوثيق. الفكرة هي المهمة: التقسيم sticky ومحسوب بـ seed، والـ variant بيحدد release مش «if» في الكود.
A/B للـ AI: قيس المنتج مش الموديل
- وحدة التوزيع: في B2B غالبًا الـ tenant أو الـ agent (موظف الدعم)، مش الـ request — عشان التجربة ما تبقاش متقطعة لنفس الشخص.
- Primary metric منتجي (وقت حل التذكرة، task completion) + guardrails (جودة، تكلفة، شكاوى). الـ «judge score» online مقياس مساعد مش هدف.
- Novelty effect: الناس بتجرب أي feature جديدة الأسبوع الأول؛ قيس على فترة كافية.
- Interference: لو الـ AI بيقترح ردود والموظفين بيشاركوا الـ templates، المجموعتين بيأثروا على بعض. ده بيخلي التوزيع بالفريق/الـ tenant أنسب.
- التكلفة جزء من النتيجة: candidate أحسن 2% وأغلى 3× ممكن يكون خسارة.
مقاييس نجاح AI feature
| Feature | مقياس قيمة | Implicit signal | Guardrail |
|---|---|---|---|
| Q&A على المستندات | نسبة الأسئلة اللي اتحلت من غير تذكرة (deflection) | rephrase خلال دقيقة، فتح citation | إجابات غلط مبلّغ عنها، تكلفة/سؤال |
| اقتراح ردود | وقت المعالجة | edit distance بين المقترح والمرسل | CSAT، reopen rate |
| استخراج بيانات | وقت الإدخال، نسبة الحقول المقبولة | تصحيحات يدوية لكل حقل | أخطاء downstream |
| Agent ينفذ أفعال | مهام مكتملة من غير تدخل | نسبة الرفض في الموافقات | policy violations = 0، rollbacks |
Human-in-the-loop: approvals للأفعال الحساسة
لما الـ AI بيقترح فعل مش بس نص (يبعت email لعميل، يعمل refund، يعدّل سجل)، المنتج لازم يقرر: ينفذ لوحده، ولا يستنى موافقة إنسان؟ القرار ده product decision بأثر أمني وقانوني، ومكانه في التصميم مش في الـ prompt.
| قرار التصميم | الخيار الافتراضي المعقول |
|---|---|
| مين يوافق؟ | دور محدد (مش «أي admin») + separation of duties: اللي طلب ما يوافقش لنفسه |
| إيه اللي يتعرض؟ | الفعل بالظبط (tool + arguments) بشكل مقروء، السبب، المصادر، وأي diff |
| صلاحية الموافقة | expiry (مثلًا 24 ساعة)؛ الـ args متجمدة — أي تعديل = طلب جديد |
| عند التنفيذ | إعادة فحص الـ policy والصلاحيات (الدنيا ممكن تكون اتغيرت)، idempotency key |
| Fatigue | لو كل حاجة محتاجة موافقة الناس هتوافق من غير قراءة؛ قلل الموافقات للـ high-risk فعلًا |
التنفيذ الكامل (MCP tools + approval tokens) موجود في CAPSTONE/mcp وشرحه في Capstone Build-Along، والتهديدات اللي بيحمي منها في AI Security.
Latency و cost budgets لكل feature
قبل ما تختار موديل، اكتب الـ budget: «الرد الأول خلال 1.5s (p95)، والتكلفة أقل من 0.4 سنت للسؤال، والدقة ≥ 85% على الـ golden set». الـ budget بيحوّل نقاش «أنهي موديل أحسن؟» لقرار قابل للقياس.
Step p95 latency cost/request
embed query 60 ms ~0.0002 ¢
hybrid retrieval 80 ms infra
rerank top-30 150 ms ~0.01 ¢ (or self-hosted)
LLM first token 600 ms --
LLM full answer (300 tok) 2.4 s ~0.25 ¢ (≈3k input + 300 output tokens)
------------------------------------------------------------
time-to-first-token ≈ 0.9 s (streaming hides the rest)
cost per answer ≈ 0.26 ¢ x 40k answers/day ≈ $104/day- Time-to-first-token أهم من الوقت الكلي في الـ chat (streaming).
- التكلفة غالبًا input tokens: chunks كتير في الـ context = فلوس. قلّل top-k بعد ما تقيس أثره على الجودة، واستخدم prompt caching لو الـ provider بيدعمه للـ system prompt الثابت.
- Routing: موديل صغير للأسئلة السهلة/التصنيف، والكبير للباقي — بشرط إن الـ eval بيثبت إن الجودة ماتأثرتش.
Feedback loop: من 👎 لتحسين حقيقي
تصنيف الفشل بيحدد الإصلاح: retrieval miss (المستند الصح ما اتجابش ← chunking/hybrid/reranking)، grounding failure (اتجاب بس الموديل ما استخدموش أو هلوس ← prompt/موديل)، policy (رفض غلط أو سماح غلط ← guardrails)، UX (الإجابة صح بس مش مفهومة). نسبة الـ 👎 لوحدها مضللة (معظم الناس ما بتضغطش)؛ اربطها بإشارات ضمنية: إعادة صياغة السؤال، نسخ الإجابة، فتح المصدر، تصعيد لدعم بشري.
الخصوصية: traces الإنتاج فيها بيانات عملاء. تخزين بـ retention محدد، صلاحيات وصول، وموافقة/عقد واضح قبل ما حالة من عميل تتحط في golden set مشترك — أو anonymize.
UX لحالات الفشل
| الحالة | UX سيء | UX كويس |
|---|---|---|
| مفيش مصادر كافية | إجابة واثقة مخترعة | «مش لاقي ده في مستنداتك» + اقتراح بحث أو رفع مستند |
| Provider down/429 | spinner للأبد | timeout واضح، retry، أو fallback لموديل تاني مع إشارة |
| Limit الخطة خلص | 500 Internal Error | رسالة الحد + زر upgrade للـ admin |
| Guardrail رفض | «Error» | سبب عام مهذب من غير كشف تفاصيل الـ policy |
| إجابة طويلة اتقطعت | نص ناقص من غير إشارة | «الإجابة اتقطعت» + زر استكمال |
Offline evals مقابل online evals
| Offline (قبل الـ release) | Online (في الإنتاج) | |
|---|---|---|
| البيانات | golden set ثابت بإجابات/معايير معروفة | طلبات حقيقية، من غير إجابة مرجعية |
| المقاييس | groundedness، correctness، refusal accuracy، latency، cost | 👍/👎، إعادة صياغة، escalation، conversion، LLM-judge على عيّنة |
| القرار | gate في CI: «مفيش regression فوق الحد» | A/B أو canary: «الـ variant الجديد أحسن للمستخدم؟» |
| العيب | ممكن ما يمثلش الواقع | بطيء، noisy، ومحتاج traffic كفاية |
الاتنين مكملين لبعض: الـ offline بيمنعك تشحن حاجة مكسورة، والـ online بيقولك هل التحسين اللي شايفه في الـ offline بيفرق مع الناس. الحالات اللي بتفشل online بتتحول offline cases (الـ feedback loop فوق).
id: support-answer
version: 2026-11-14.2
model: { provider: azure-openai, deployment: chat-main, temperature: 0.2, max_output_tokens: 600 }
retrieval: { top_k: 8, hybrid_alpha: 0.5, reranker: on, min_score: 0.35 }
prompt_file: prompts/support-answer.v14.md
eval_gate: { suite: golden-v3, min_groundedness: 0.90, max_cost_cents_p95: 0.5, max_ttft_ms_p95: 1500 }
rollout: { flag: support-answer-v14, start: 5%, tenants_excluded: [enterprise-pilot] }أسئلة إنترفيو إضافية
(Mid) الإجابات بقت أغلى 40% الأسبوع ده من غير تغيير في الكود. تدوّر فين؟
(Senior) إمتى تعمل الفعل automatic من غير approval؟
(Staff) إزاي تقنع الـ product إن feature AI مش جاهزة للإطلاق؟
أخطاء شائعة في AI product engineering
- إطلاق من غير معايير قبول مكتوبة قبل البناء، فكل نتيجة «كويسة كفاية».
- قياس الموديل بس (accuracy) وتجاهل المنتج (هل المستخدم خلّص مهمته أسرع؟).
- تغيير prompt في الإنتاج من غير version و eval gate.
- Streaming من غير cancellation: المستخدم قفل الصفحة والـ tokens لسه بتتولد وبتتحسب.
- UI بيعرض ثقة عالية (نص طويل منسق) لإجابة ضعيفة المصادر.
Knowledge check إضافي
الـ agent اقترح refund بـ 5,000 جنيه والـ policy بتقول approval فوق 1,000. المدير وافق بعد 30 ساعة والـ expiry 24 ساعة. الصح؟
اختبر فهمك
الـ LLM provider واقع. إيه أحسن سلوك للـ chat feature؟
ليه الـ citations بتتبعت قبل الـ text في الـ stream؟
Candidate prompt حسّن الـ judge score 3% في A/B لكن وقت حل التذاكر ما اتغيرش وتكلفته ضعف. القرار؟
تمارين محلولة
1: اكتب الحالات البصرية لـ chat panel
الحل: idle (أمثلة أسئلة)، retrieving («بدوّر في المستندات…» مع عدد المصادر)، streaming (نص + زر إيقاف + citations)، done (feedback + نسخ)، no-sources («ما لقيتش مستند بيجاوب ده» + اقتراح)، degraded (بحث عادي)، rate-limited (إمتى يقدر يسأل تاني)، forbidden (الـ feature مش مفعّلة لخطتك + للـ admin: كيف يفعّلها).
2: الـ PM عايز «confidence score» جنب كل إجابة. ردك؟
الحل: رقم من الموديل مش calibrated بيضلل. البديل: مؤشرات قابلة للتحقق (عدد المصادر المطابقة، هل كل جملة ليها citation، «الإجابة استنتاج مش نص صريح»). لو عايز رقم: calibrate على eval set (زي الـ calibration في Applied ML) وقيس reliability قبل العرض.
3: إزاي تقيس «edit distance» للاقتراحات بشكل عادل؟
الحل: normalized (Levenshtein أو token-level) بين المقترح والمرسل، مستبعد منه التحية والتوقيع، ومقسّم حسب نوع التذكرة. وقيس كمان نسبة «تجاهل الاقتراح وكتب من الصفر» لأن الـ edit distance مش بيتحسب لو ما استخدموهوش.
Mini project: Chat feature production-grade
في الـ CAPSTONE/: SSE endpoint بـ citations أولًا و degraded mode و cancellation، Angular component بالـ signals وكل الحالات (عربي/إنجليزي RTL)، acceptance.yaml للـ feature، feature flag بـ variants مربوطة بـ releases، و events للـ implicit signals. معيار القبول: فصل الـ LLM (env var) ← الـ UI يدخل degraded في أقل من 3 ثواني والبحث شغال؛ زر الإيقاف بيوقف الـ LLM call في الـ trace.
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) ليه streaming مهم في AI chat؟
(Senior) إزاي تكتب acceptance criteria لـ AI feature؟
(Senior) صمّم UX لـ agent بيعمل أفعال في حساب العميل.
(Staff) org عايزة «AI في كل حتة» السنة دي. إزاي توجّه؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.