پروژه نهایی: پیاده‌سازی داشبورد مشاهده‌پذیری و ارزیابی LLM

وقتی برنامه‌های مبتنی بر مدل‌های زبانی وارد محیط پروداکشن می‌شوند، نظارت سنتی روی سرورها دیگر پاسخگو نیست. پایش مواردی مثل نشت اطلاعات حساس (PII)، پاسخ‌های توهم‌آمیز، ارزیابی کیفیت خروجی، ردیابی هزینه‌ی توکن‌ها به ازای هر کاربر و تغییر توزیع داده‌ها (Drift) چالش‌هایی هستند که توسعه‌دهندگان بدون یک لایه‌ی مشاهده‌پذیری (Observability) اختصاصی توان رهگیری آن‌ها را نخواهند داشت.

استفاده از پلتفرم‌های ابری خارجی برای مانیتورینگ همواره با دغدغه‌های حریم خصوصی و دشواری در پرداخت ارزی برای فعال‌سازی پلن‌های تجاری همراه است. علاوه بر این، محدودیت‌های دسترسی به برخی سرویس‌های خارجی، ریسک قطع ناگهانی این ابزارهای کلیدی را افزایش می‌دهد. در چنین شرایطی، راه‌اندازی یک سیستم خودمیزبان (Self-hosted) روی زیرساخت محلی، کنترل کاملی بر جریان داده‌ها و هزینه‌ها فراهم می‌کند.

در این پروژه‌ی عملی، با تکیه بر استانداردهای جدید OpenTelemetry، یک سیستم کامل مشاهده‌پذیری و ارزیابی طراحی می‌کنید. تریس‌ها را با ClickHouse ذخیره می‌کنید، پایپ‌لاین ارزیابی خودکار با ابزارهایی مانند DeepEval راه می‌اندازید و یک سیستم هشداردهی سریع برای کشف پس‌رفت‌های کیفی مدل در کمتر از 5 دقیقه می‌سازید.

پلتفرم Langfuse به مدل متن‌باز هسته (open-core) روی آورد. پلتفرم Arize Phoenix نگاشت‌های قراردادهای معنایی (semantic conventions) هوش مصنوعی زاینده را برای سال 2026 منتشر کرد. Helicone و Braintrust هر دو تمرکز خود را روی انتساب هزینه به ازای هر کاربر دوچندان کردند. کتابخانه‌ی OpenLLMetry از شرکت Traceloop عملاً به استاندارد ابزاردقیق‌سازی SDKها تبدیل شد. معماری استاندارد در محیط عملیاتی (پروداکشن) اکنون مشخص است: ClickHouse برای ردگیری محاسبات (traces)، دیتابیس Postgres برای متادیتا، Next.js برای رابط کاربری و لشکری کوچک از جاب‌های ارزیابی (DeepEval، RAGAS و LLM-judge) که روی اسپن‌های نمونه‌برداری‌شده اجرا می‌شوند. یک سیستم خودمیزبان (self-hosted) بسازید، داده‌ها را از حداقل چهار خانواده‌ی SDK دریافت کنید و نشان دهید که وقوع یک پس‌رفتِ تزریق‌شده را در کمتر از 5 دقیقه شناسایی می‌کنید.

فازهای تمرین‌شده: P11 · P13 · P17 · P18
زمان: 25 ساعت

صورت مسئله

در سال 2026، هر تیم هوش مصنوعی که ترافیک عملیاتی دارد، یک لایه‌ی مشاهده‌پذیری (observability) در کنار مدل خود نگه می‌دارد: انتساب هزینه، تشخیص توهم (hallucination detection)، پایش جابه‌جایی توزیع (drift monitoring)، سیگنال جیل‌بریک (شکستن قفل ایمنی)، داشبوردهای SLO و هشدارهای نشت داده‌های حساس (PII). مراجع متن‌باز مانند Langfuse، Phoenix و OpenLLMetry، همگی روی قراردادهای معنایی GenAI در OpenTelemetry به‌عنوان اسکیمای دریافت داده به توافق رسیده‌اند. اکنون می‌توانید OpenAI، Anthropic، Google، LangChain، LlamaIndex و vLLM را تنها با یک SDK مجهز به ابزاردقیق کنید و اسپن‌های (spans) کاملاً سازگار بفرستید.

شما یک داشبورد خودمیزبان خواهید ساخت که داده‌ها را از حداقل چهار خانواده‌ی SDK دریافت می‌کند، مجموعه‌ای کوچک از جاب‌های ارزیابی را روی تریس‌های نمونه‌برداری‌شده اجرا می‌کند، جابه‌جایی توزیع را تشخیص می‌دهد و هشدار می‌فرستد. معیار سنجش موفقیت: اگر یک پس‌رفت به عمد تزریق شود (پرامپتی که شروع به افشای PII کند)، داشبورد باید آن را شناسایی کند و در کمتر از 5 دقیقه هشدار بدهد.

مفهوم

دریافت داده از طریق بستر انتقال (transport) با پروتکل OTLP HTTP انجام می‌شود. ابزار SDK اسپن‌هایی منطبق بر قراردادهای معنایی GenAI تولید می‌کند: gen_ai.system، gen_ai.request.model، gen_ai.usage.input_tokens، gen_ai.response.id، llm.prompts و llm.completions. اسپن‌ها برای تحلیل‌های ستونی وارد ClickHouse می‌شوند؛ متادیتا (کاربران، نشست‌ها، برنامه‌ها) در Postgres می‌نشیند.

ارزیابی‌ها به‌صورت جاب‌های دسته‌ای (batch) روی تریس‌های نمونه‌برداری‌شده اجرا می‌شوند. کتابخانه‌ی DeepEval به وفاداری (faithfulness)، سمیت (toxicity) و مرتبط بودن پاسخ نمره می‌دهد. وقتی تریس حاوی کانتکست بازیابی باشد، RAGAS معیارهای بازیابی را می‌سنجد. ارزیاب‌های سفارشیِ مبتنی بر مدل (LLM-judge) بررسی‌های خاص دامنه (نشت PII، پاسخ خارج از خط‌مشی یا off-policy) را اجرا می‌کنند. نتایج این ارزیابی‌ها در قالب اسپن‌های ارزیابیِ متصل به تریس والد، دوباره در همان ClickHouse ذخیره می‌شوند.

تشخیص جابه‌جایی توزیع، تغییرات فضای امبدینگ را در طول زمان زیر نظر می‌گیرد (با شاخص پایداری جمعیت یا PSI، یا واگرایی کولبک-لایبلر روی امبدینگ‌های پرامپت) و روند نمرات ارزیابی را تحلیل می‌کند. هشدارها به Alertmanager در Prometheus فرستاده می‌شوند و از آنجا به Slack یا PagerDuty می‌روند. رابط کاربری نیز با Next.js 15 و Recharts پیاده‌سازی می‌شود.

معماری

production apps:
  OpenAI SDK  +  Anthropic SDK  +  Google GenAI SDK
  LangChain + LlamaIndex + vLLM
       |
       v
  OpenTelemetry SDK with GenAI semconv
       |
       v  OTLP HTTP
  collector (ingest, sample, fan-out)
       |
       +-------------+-----------+
       v             v           v
   ClickHouse    Postgres    S3 archive
   (spans)       (metadata)  (raw events)
       |
       +---> eval jobs (DeepEval, RAGAS, LLM-judge)
       |     sampled or all-trace
       |     write eval spans back
       |
       +---> drift detector (PSI / KL on prompt embeddings)
       |
       +---> Prometheus metrics -> Alertmanager -> Slack / PagerDuty
       |
       v
   Next.js 15 dashboard (Recharts)

استک فنی

• دریافت داده: OpenTelemetry SDKها به همراه قراردادهای معنایی GenAI؛ بستر انتقال از نوع OTLP HTTP
• جمع‌آوری‌کننده: OpenTelemetry Collector با پردازنده‌ی tail-sampling (برای مدیریت هزینه‌ها)
• ذخیره‌سازی: ClickHouse برای اسپن‌ها، Postgres برای متادیتا، S3 برای بایگانی رویدادهای خام
• ارزیابی‌ها: DeepEval، RAGAS 0.2، بسته‌ی ارزیاب‌های Arize Phoenix و LLM-judge سفارشی
• جابه‌جایی داده: محاسبه‌ی هفتگی PSI یا KL روی امبدینگ‌های تجمیعی پرامپت (با sentence-transformers)
• ارسال هشدار: Prometheus Alertmanager -> Slack / PagerDuty
• رابط کاربری: Next.js 15 App Router به همراه Recharts و اکشن‌های سمت سرور (server actions)
• SDKهای پشتیبانی‌شده به‌شکل پیش‌فرض: OpenAI، Anthropic، Google GenAI، LangChain، LlamaIndex و vLLM

پیاده‌سازی

1. پیکربندی Collector. یک OpenTelemetry Collector با گیرنده‌ی OTLP HTTP، یک نمونه‌گیر انتهایی (tail-sampler) که 100% تریس‌های دارای خطا و 10% تریس‌های موفق را نگه می‌دارد، و صادرکننده‌های داده به ClickHouse و S3 تنظیم کنید.

2. اسکیمای ClickHouse. جدول spans را با ستون‌هایی متناظر با قراردادهای معنایی GenAI بسازید: gen_ai_system، gen_ai_request_model، input_tokens، output_tokens، latency_ms، prompt_hash، trace_id، parent_span_id، به همراه یک فیلد JSON برای داده‌های متنی حجیم. ایندکس‌های ثانویه روی user_id و app_id تعریف کنید.

3. تست پوشش SDKها. با استفاده از ابزاردقیق‌سازی خودکار OpenLLMetry، یک برنامه‌ی کلاینت کوچک برای هر SDK بنویسید (OpenAI، Anthropic، Google، LangChain، LlamaIndex و vLLM). مطمئن شوید که هر کدام اسپن‌های استاندارد GenAI را تولید کرده و در ClickHouse ثبت می‌کنند.

4. جاب‌های ارزیابی. یک تسک زمان‌بندی‌شده بسازید که تریس‌های نمونه‌برداری‌شده‌ی 15 دقیقه‌ی گذشته را بخواند و معیارهای وفاداری، سمیت و ارتباط پاسخ را با DeepEval بسنجد. خروجی‌ها به‌شکل اسپن‌های ارزیابیِ متصل به تریس والد ذخیره می‌شوند.

5. ناقد مبتنی بر مدل (LLM-judge) سفارشی. یک ناقد نشت PII بسازید: با دریافت هر پاسخ، یک مدل زبانی محافظ را فراخوانی کنید تا درست‌نمایی (likelihood) نشت اطلاعات هویتی را نمره‌دهی کند. پاسخ‌هایی که نمره‌ی بالایی می‌گیرند به صف بازبینی هدایت می‌شوند.

6. تشخیص جابه‌جایی توزیع. یک جاب هفتگی طراحی کنید که شاخص پایداری جمعیت (PSI) را میان امبدینگ‌های تجمیعی پرامپت این هفته و خط مبنای (baseline) 4 هفته‌ی گذشته حساب کند. اگر PSI از آستانه بالاتر رفت، هشدار بدهد.

7. داشبورد. با Next.js 15 صفحاتی بسازید شامل: نمای کلی (اسپن بر ثانیه، هزینه به ازای کاربر، صدک 95 تاخیر)، تریس‌ها (جست‌وجو و نمودار آبشاری)، ارزیابی‌ها (روند وفاداری، سمیت)، جابه‌جایی توزیع (تغییرات PSI در طول زمان) و هشدارها.

8. زنجیره‌ی هشدار. یک اکسپورتر Prometheus بنویسید که داده‌های تجمیعی نمرات ارزیابی و صدک‌های تاخیر را بخواند؛ سپس Alertmanager اخطارها را به Slack و هشدارهای بحرانی را به PagerDuty بفرستد.

9. آزمون ارزیابی (probe) پس‌رفت. یک باگ عمدی تزریق کنید: چت‌بات تحت ارزیابی در 1% مواقع شروع به افشای شماره‌های تامین اجتماعی جعلی کند. زمان شناسایی (MTTD) را اندازه بگیرید: از لحظه‌ی استقرار باگ تا دریافت هشدار در Slack. فرایند شناسایی بخشی از زمان میانگین بازیابی (MTTR) است که مسئولیتش با داشبورد است؛ اصلاح و استقرار مجدد بعد از آن اتفاق می‌افتد.

استفاده از سیستم

$ curl -X POST https://my-otel-collector/v1/traces -d @trace.json
[collector]  accepted 1 trace, 3 spans
[clickhouse] inserted 3 spans (app=chat, user=u_42)
[eval]       DeepEval faithfulness 0.82, toxicity 0.03
[drift]      weekly PSI 0.08 (below 0.2 threshold)
[ui]         live at https://obs.example.com

تحویل پروژه

خروجی نهایی فایل outputs/skill-llm-observability.md است. داشبورد تریس‌های هر برنامه‌ی مبتنی بر مدل‌های زبانی را می‌گیرد، ارزیابی‌ها را انجام می‌دهد، جابه‌جایی داده را هشدار می‌دهد و ریز هزینه‌ها به ازای هر کاربر را در رابط کاربری Next.js نمایش می‌دهد.

تمرین‌ها

1. ابزاردقیق‌سازی سفارشی برای فریم‌ورک Haystack بنویسید. بررسی کنید که اسپن‌های استاندارد با اتریبیوت‌های دقیق gen_ai.* در ClickHouse ذخیره شوند.

2. روی همان تریس‌ها، ارزیاب‌های Phoenix را جایگزین DeepEval کنید. میزان اختلاف نمرات ارزیابی را میان این دو موتور بسنجید.

3. حساسیت تحلیل‌گر جابه‌جایی توزیع را افزایش دهید: شاخص PSI را به‌جای حالت سراسری، به ازای هر app-id محاسبه کنید. ردپای جابه‌جایی را به تفکیک هر برنامه نمایش دهید.

4. یک صفحه‌ی «اثر بر کاربر» بسازید: هزینه به ازای کاربر و نرخ خطای هر کاربر را با نمودارهای درون‌خطی و کوچک (sparklines) نشان دهید.

5. یک سیاست نمونه‌گیری انتهایی (tail-sampling) تدوین کنید که 100% تریس‌های با سمیت بالای 0.5 را به همراه نمونه‌برداری طبقه‌بندی‌شده‌ی 10 درصدی از بقیه‌ی تریس‌ها نگه دارد. میزان اریب نمونه‌گیریِ (sampling bias) ایجادشده را محاسبه کنید.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• Langfuse — پلتفرم مرجع مشاهده‌پذیری با مدل هسته‌ی متن‌باز
• Arize Phoenix — پلتفرم مرجع جایگزین با پشتیبانی قوی از تحلیل جابه‌جایی توزیع
• OpenLLMetry (Traceloop) — مجموعه‌ی SDKهای ابزاردقیق‌سازی خودکار
• قراردادهای معنایی GenAI در OpenTelemetry — اسکیمای دریافت داده
• Helicone — پلتفرم مشاهده‌پذیری میزبانی‌شده‌ی جایگزین
• Braintrust — پلتفرم جایگزین با اولویت ارزیابی
• مستندات ClickHouse — پایگاه داده ستونی برای ذخیره‌ی اسپن‌ها
• DeepEval — کتابخانه‌ی ابزارهای ارزیابی