شروع پروژه

چیت‌شیت

ابزارهای تصمیم‌گیری، تغییرات و توتوریال

Decision, Change and Tutorial Tools

چهار ابزار مبتنی بر شواهد: امتیازدهی به گزینه‌ها، گزارش تغییرات صفحات، بررسی توتوریال‌های API و مقایسه‌ی اجرای مدل‌های محلی.

  • ۱۲ بخش
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. چهار پروژه در کنار یکدیگر
  2. اجرای نسخه‌ی مرجع
  3. قوانین امتیازدهی تصمیم‌گیری
  4. گزارش تغییرات وب
  5. یک بلوک درخواست توتوریال
  6. گام‌های اجراکننده‌ی توتوریال API
  7. ثبت و مقایسه‌ی مدل محلی
  8. فیلدهای Scorecard
  9. پیش‌فرض‌ها و محدودیت‌ها
  10. پیام‌های خطا و راه‌حل‌ها
  11. نمونه‌های حل‌شده
  12. نکات کاربردی

چهار پروژه در کنار یکدیگر

مقایسه
فاکتورکاوشگر ارزیابی تصمیمات (Decision Tradeoff Explorer)گزارش تغییرات وب (Web Change Brief)اجراکننده‌ی توتوریال API (API Tutorial Runner)بستر ارزیابی مدل محلی (Local Model Eval Harness)
زبانNode 22.18+Go 1.22 یا جدیدترNode 22.18 یا جدیدترPython 3.10+
ورودیcriteria، optionsدو اسنپ‌شات HTML، یا خط مبنا و URLtutorial، fixture یا endpointmanifest، source، labels، records
خروجی‌هاcriteria.csv، decision-record.json، index.htmlindex.html، changes.json، baseline.jsonrequests.json، results.json، junit.xml، report.htmlscorecard.json، reliability.html
گیت (شرط تایید)گزینه‌ی انتخابی باید واجد شرایط باشد--accept جایگزین خط مبنا می‌شود--allow-network برای اندپوینت‌های واقعی--min-accuracy با کد 2 خارج می‌شود
هرگز این کارها را نمی‌کندتصمیم‌گیری به جای کاربراجرای JavaScript یا واکشی منابع پیوندداده‌شدهتست بار (Load testing)دانلود یا اجرای یک مدل

اجرای نسخه‌ی مرجع

دستورها
دستورعملکرد
node --experimental-strip-types cli.ts fixtures/exhibition.json /tmp/decision-boardبورد تصمیم‌گیری را می‌نویسد
python3 -m http.server 8123 --directory /tmp/decision-boardروی localhost:8123 سرو می‌کند؛ پس از استفاده متوقفش کنید
go run . --before fixtures/before.html --after fixtures/after.html --url <url> --out ./web-change-outputدو اسنپ‌شات ذخیره‌شده را مقایسه می‌کند
go run . --fetch <url> --baseline ./web-change-output/baseline.json --out ./next-reportیک صفحه‌ی زنده را در برابر خط مبنا واکشی می‌کند
node cli.ts sample.json outputتوتوریال را روی یک مجموعه‌داده‌ی نمونه در لوپ‌بک اجرا می‌کند
python3 cli.py samples/input.json --output scorecard.json --html reliability.htmlبه فایل ثبت‌شده‌ی نمونه امتیاز می‌دهد
python3 scripts/project_test.py <project> --all --solution --strictبه نسخه‌ی مرجع نمره می‌دهد

قوانین امتیازدهی تصمیم‌گیری

مفهوم‌ها
منفعت
(v - c.min) / (c.max - c.min).
هزینه
(c.max - v) / (c.max - c.min).
امتیاز
مجموع حاصل‌ضرب مقادیر نرمال‌شده در وزن‌ها، تقسیم بر مجموع وزن‌ها.
مقدار ناموجود
گزینه فاقد شرایط است، حتی اگر وزن آن 0 باشد.
محدودیت
یک حد سخت‌گیرانه؛ هزینه‌ی بالاتر از آن یا منفعت پایین‌تر از آن رد می‌شود.
تساوی‌ها
مرتب‌سازی بر اساس شناسه گزینه.
غلبه‌شده
گزینه‌ی دیگری در تمام معیارها هم‌تراز و در یکی برتر است.
حساسیت
تغییر پیوسته‌ی یک وزن از 0 تا 1 در طی چند steps.

گزارش تغییرات وب

معماری
HTMLبلوک‌هادو اسنپ‌شاتگزارشبعدbefore.html، after.htmlیا --fetch یک URLExtractBlocks()بلوک‌های متنی خواناNewSnapshot()URL اصلی (canonical)، هشCompare()اضافه‌شده، حذف‌شده، بدون‌تغییرExportBrief()index.html، changes.jsonSaveSnapshot()baseline.json

یک بلوک درخواست توتوریال

کد
text
# توتوریال شامل JSON درون حصار درخواست (request fence) است
{"id": "create-loan", "method": "POST", "path": "/loans",
 "status": 201,                                            # وضعیت مورد انتظار، 100..599
 "capture": {"loanId": {"path": "id", "type": "number"}}}  # استخراج مقادیر تایپ‌شده
{"id": "read-loan", "method": "GET",
 "path": "/loans/{{loanId}}",                              # فقط متغیرهای تعریف‌شده
 "status": 200,
 "assert": {"bookName": "Neighborhood Trees"}}             # فیلد منسوخ، شکست می‌خورد

گام‌های اجراکننده‌ی توتوریال API

گام‌به‌گام
  1. extractRequestsهر حصار درخواست را می‌خواند؛ حداکثر 20 گام مجاز است.
  2. CLIدر صورت نبود endpoint، سرور لوپ‌بک را از روی fixture اجرا می‌کند.
  3. runTutorialمقدار {{name}} را از استخراج‌های قبلی پر می‌کند؛ نام تعریف‌نشده منجر به خطا می‌شود.
  4. runTutorialدرخواست را بدون بازهدایت‌ها، با مهلت زمانی و محدودیت بایت ارسال می‌کند.
  5. runTutorialوضعیت و تمام مسیرهای assert را چک کرده و سپس استخراج‌ها را ذخیره می‌کند.
  6. runTutorialپس از یک شکست، گام‌های بعدی رد شده و درخواستی ارسال نمی‌شود.
  7. exportResultsگزارش‌های JUnit، HTML و corrections.json را برای هر خطا تولید می‌کند.

ثبت و مقایسه‌ی مدل محلی

کد
bash
python3 record.py samples/cases.json \         # فقط اندپوینت HTTP لوپ‌بک
  --endpoint http://127.0.0.1:11434/v1/chat/completions \
  --model <model> --revision <rev> --hardware <hw> \
  --output measured.json                       # manifest، source، labels، records
python3 cli.py measured.json --baseline samples/input.json \
  --output compared.json                       # برچسب‌های نامطابق مجموعه‌داده را رد می‌کند
python3 cli.py <recording> --min-accuracy <n>  # خروج با کد 2 در صورت پایین‌تر بودن از گیت

فیلدهای Scorecard

مفهوم‌ها
accuracy
پاسخ دقیق پس از یکسان‌سازی حروف بزرگ/کوچک و فاصله‌ها، روی کل برچسب‌ها.
coverage
پیش‌بینی‌ها تقسیم بر برچسب‌ها.
ece
شکاف اطمینان در هر بازه (bin)، وزن‌دهی‌شده با تعداد اعضای بازه.
p50_ms, p95_ms
صدک‌های تاخیر بر اساس نزدیک‌ترین رتبه.
dataset_sha256
هش برچسب‌ها؛ خط مبنا باید با آن مطابقت داشته باشد.
manifest
به model، model_revision، prompt_revision، hardware و confidence_method نیاز دارد.

پیش‌فرض‌ها و محدودیت‌ها

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
--outweb-change-outputپوشه‌ی گزارش مختصر وب
MaxHTMLBytes2_000_0002 مگابایت به ازای هر صفحه
timeoutMs1500به ازای هر درخواست، 1 تا 30000
maxBytes65536محدودیت بایت پاسخ
Request steps20حداکثر به ازای هر توتوریال
bins5بازه‌های کالیبراسیون
--min-accuracy0کد خروج 2 زیر این مقدار
Sensitivity `steps`101 تا 100

پیام‌های خطا و راه‌حل‌ها

عیب‌یابی

  • chosen option must be eligible

    علت
    گزینه فاقد مقدار است یا از محدودیتی عبور کرده
    راه‌حل
    یک گزینه‌ی دارای امتیاز را انتخاب کنید

  • value outside declared range

    علت
    مقدار درون بازه‌ی min و max نیست
    راه‌حل
    مقدار یا بازه را اصلاح کنید

  • Snapshots must refer to the same canonical URL

    علت
    دو URL متفاوت
    راه‌حل
    اسنپ‌شات‌های مربوط به یک صفحه را مقایسه کنید

  • Live fetch requires --baseline JSON

    علت
    --fetch بدون مشخص کردن خط مبنا
    راه‌حل
    ابتدا حالت فایل‌های ذخیره‌شده را اجرا کنید

  • Baseline checksum mismatch

    علت
    فایل خط مبنا دستکاری شده است
    راه‌حل
    یک خط مبنای جدید بسازید

  • Network endpoint requires explicit allowNetwork

    علت
    اندپوینت روی لوپ‌بک نیست
    راه‌حل
    پرچم --allow-network را اضافه کنید

  • Earlier step failed; no request sent

    علت
    گام قبلی با خطا مواجه شد
    راه‌حل
    اولین گام ناموفق را برطرف کنید

  • cannot compare different datasets

    علت
    برچسب‌ها با خط مبنا مغایرت دارند
    راه‌حل
    همان نمونه‌ها را مجدداً ضبط کنید

نمونه‌های حل‌شده

پرسش و پاسخ
کدام گزینه در نمونه‌ی نمایشگاهی برنده می‌شود؟
pods با 0.68؛ در حالی که open دارای 0.67 است.
چرا archive رتبه‌بندی نشده است؟
مقدار flow آن null است، بنابراین فاقد شرایط است.
چه زمانی open برنده می‌شود؟
در پیمایش وزن access، در وزن 0.6 یا بیشتر.
چرا read-loan ناموفق می‌شود؟
روی فیلد منسوخ‌شده‌ی bookName شرط assert گذاشته است.
نمونه‌ی ارزیابی چه امتیازی می‌گیرد؟
دقت 2/3، پوشش کامل، صدک p95 معادل 200 میلی‌ثانیه.

نکات کاربردی

نکته‌ها
  • از یک سیاست فیلتر یکسان برای هر دو اسنپ‌شات استفاده کنید؛ عبارت‌های فیلتر می‌توانند تغییرات را پنهان کنند.
  • خط مبنا دست‌نخورده باقی می‌ماند مگر اینکه پرچم --accept را وارد کنید.
  • وزن‌ها اولویت‌های ترجیحی هستند، نه احتمال.
  • میزان اطمینان گزارش‌شده، خوداظهاریِ مدل است؛ ECE بر اساس بازه‌ها و تعداد نمونه‌ها تغییر می‌کند.
  • دستور توتوریال پس از ثبت شواهد با موفقیت پایان می‌یابد؛ رسیدها و گزارش‌ها را بررسی کنید.