ژرفا — خودآموز یادگیری عمیق و مهندسی هوش مصنوعی (متوسط)

فصل ۵ از ۷

پیشرفت ترم
۰٪

در این فصل چه یاد می‌گیری#

شش ترم مدل ساختی و هیچ‌کدام از نوت‌بوک بیرون نیامد. این فصل یکی را واقعاً سرو می‌کند: یک سرورِ HTTP که خودت می‌نویسی، با اعتبارسنجی، مسیرِ سلامت، شمارهٔ نسخه، و پاسخِ خطای درست.

بعد یک عدد می‌گیریم که کلِ فصل را توجیه می‌کند: ۶۴ درخواست، ۶۴ بار اجرای مدل — یا ۱ بار. همان مدل، همان جواب‌ها، و چند برابر گذردهی فقط چون درخواست‌ها را کنارِ هم گذاشتیم. و آخرش یک batcher پویا می‌سازیم که ۶۴ درخواستِ کاملاً مستقل و هم‌زمان را با دو تا سه بار اجرای مدل جواب می‌دهد — بی‌آنکه هیچ کاربری بفهمد.

درخواست‌های پراکنده که پیش از ورود به دستگاه در یک دسته جمع می‌شوند

آخر این فصل می‌توانی:

  • یک سرویسِ واقعی بنویسی، نه یک دموی نوت‌بوکی
  • ورودی را در مرز اعتبارسنجی کنی و خطای مفید برگردانی
  • گذردهی و تأخیر را از هم جدا کنی
  • batching پویا پیاده کنی

قبل از شروع#

از ترمِ ۵ فصل ۲: اعتبارسنجی در مرز. از ترمِ ۵ فصل ۸: تفاوتِ تأخیر و گذردهی، و p95.

از سرنخ ترمِ ۵: Gradio و Hugging Face Spaces — و این فصل دقیقاً می‌گوید آن دمو با یک سرویس چه فرقی دارد.

💡 نکته: زمانِ تخمینی روی CPU: دو تا سه دقیقه. سرور روی 127.0.0.1 بالا می‌آید و از بیرونِ نوت‌بوک قابلِ دسترسی نیست — که برای یادگیری دقیقاً همان چیزی است که می‌خواهیم.

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

۱. مدل، به‌شکلِ یک تابع#

import torch
from sklearn.linear_model import LogisticRegression
from transformers import AutoModel, AutoTokenizer

NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = AutoTokenizer.from_pretrained(NAME)
encoder = AutoModel.from_pretrained(NAME)
encoder.eval()

FORWARDS = {"n": 0, "rows": 0}


@torch.no_grad()
def embed(texts):
    FORWARDS["n"] += 1
    FORWARDS["rows"] += len(texts)
    b = tokenizer(texts, padding=True, truncation=True, max_length=32, return_tensors="pt")
    hidden = encoder(**b).last_hidden_state
    m = b["attention_mask"].unsqueeze(-1).float()
    return torch.nn.functional.normalize((hidden * m).sum(1) / m.sum(1), dim=1)


head = LogisticRegression(max_iter=2000).fit(embed(train_texts[:400]).numpy(), train_labels[:400])


def predict(texts):
    return [TOPIC_NAMES[i] for i in head.predict(embed(texts).numpy())]


print("نمونه:", predict(val_texts[:3]))
print("دقتِ سرویس روی مجموعهٔ اعتبارسنجی:",
      f"{head.score(embed(val_texts).numpy(), val_labels):.4f}")
نمونه: ['برنامه\u200cنویسی', 'سلامت', 'سلامت']
دقتِ سرویس روی مجموعهٔ اعتبارسنجی: 0.9767

اولین قاعدهٔ سرو کردن: predict باید فهرست بگیرد و فهرست بدهد، حتی وقتی فقط یک ورودی داری.

اگر امضایش را predict(text) بنویسی، بعداً برای batching مجبوری همه‌جا را عوض کنی. predict(texts) از روزِ اول، هزینه‌ای ندارد و راه را باز می‌گذارد.

و آن FORWARDS یک شمارنده است که در بخشِ ۴ کارِ اصلی را می‌کند — به‌جای اینکه دربارهٔ کارایی حرف بزنیم، می‌شماریم.

۲. سرورِ واقعی#

import json
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

VERSION = "1.0.0"


class Handler(BaseHTTPRequestHandler):
    def log_message(self, *args):
        pass                                  # لاگِ پیش‌فرض را خاموش کن

    def _send(self, code, payload):
        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        if self.path == "/healthz":
            self._send(200, {"ok": True, "version": VERSION})
        else:
            self._send(404, {"error": "not found"})

    def do_POST(self):
        if self.path != "/predict":
            return self._send(404, {"error": "not found"})
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            texts = json.loads(raw)["texts"]
            if not isinstance(texts, list) or not texts or len(texts) > 64:
                raise ValueError("texts باید فهرستی بینِ ۱ تا ۶۴ رشته باشد")
            if any(not isinstance(t, str) or not t.strip() for t in texts):
                raise ValueError("هر عضو باید رشتهٔ ناتهی باشد")
        except TypeError:
            return self._send(400, {"error": "بدنه باید یک شیء JSON با کلیدِ texts باشد"})
        except (json.JSONDecodeError, KeyError, ValueError) as error:
            return self._send(400, {"error": str(error)})
        self._send(200, {"labels": predict(texts), "version": VERSION})


server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
threading.Thread(target=server.serve_forever, daemon=True).start()
BASE = f"http://127.0.0.1:{server.server_address[1]}"
print("سرور بالا آمد.")
سرور بالا آمد.

پنج تصمیم در این کلاس هست که یک سرویس را از یک دمو جدا می‌کنند:

  • /healthz — تا سامانهٔ بالادست بفهمد سرویس زنده است. بدونِ آن، تنها راهِ فهمیدنِ خرابی، شکایتِ کاربر است.
  • VERSION در هر پاسخ — وقتی گزارشِ یک جوابِ عجیب می‌رسد، اولین سؤال «کدام نسخه؟» است.
  • ensure_ascii=False — بدونش فارسی به شکلِ \uXXXX برمی‌گردد؛ کار می‌کند ولی حجم را چند برابر و اشکال‌یابی را جهنم می‌کند.
  • Content-Type با charset=utf-8 — بدونش بعضی کلاینت‌ها متن را به‌هم‌ریخته نشان می‌دهند.
  • ThreadingHTTPServer — نسخهٔ تک‌نخی، درخواست‌ها را پشتِ سرِ هم جواب می‌دهد؛ یک درخواستِ کند همه را پشتِ در نگه می‌دارد. بخشِ ۶ از مسیرِ HTTP نمی‌گذرد، ولی وقتی batcher را به این سرور وصل کنی، بدونِ هم‌زمانیِ همین سرور هیچ دسته‌ای تشکیل نمی‌شود.

۳. حالا صدایش بزن — و خرابش کن#

import requests

print("سلامت    :", requests.get(BASE + "/healthz").json())
print("پیش‌بینی  :", requests.post(BASE + "/predict",
                                  json={"texts": val_texts[:2]}).json()["labels"])

bad = requests.post(BASE + "/predict", json={"texts": []})
print("ورودیِ خالی:", bad.status_code, bad.json())

bad2 = requests.post(BASE + "/predict", json={"wrong": 1})
print("کلیدِ غلط  :", bad2.status_code, bad2.json())

print("مسیرِ ناشناخته:", requests.get(BASE + "/nope").status_code)
سلامت    : {'ok': True, 'version': '1.0.0'}
پیش‌بینی  : ['برنامه\u200cنویسی', 'سلامت']
ورودیِ خالی: 400 {'error': 'texts باید فهرستی بینِ ۱ تا ۶۴ رشته باشد'}
کلیدِ غلط  : 400 {'error': "'texts'"}
مسیرِ ناشناخته: 404

چهار تا از پنج پاسخ خوب‌اند. یکی افتضاح است.

✅ چک کن: پیامِ {'error': "'texts'"} را نگاه کن. این متنِ خامِ یک KeyError است و برای کسی که سرویس را صدا می‌زند هیچ معنایی ندارد — نه می‌گوید کدام کلید لازم است، نه می‌گوید چه شکلی باید باشد. درستش این است:

if "texts" not in payload:
    raise ValueError("کلیدِ texts لازم است: {\"texts\": [\"...\"]}")

قاعده: هرگز str(exception) را مستقیم به کاربر نده. استثناها برای برنامه‌نویس نوشته شده‌اند، نه برای صدازننده. و از این بدتر، گاهی مسیرِ فایل، نامِ جدول یا بخشی از پرامپت را لو می‌دهند — که دقیقاً همان نشتِ اطلاعاتی است که ترمِ ۵ فصلِ ۹ دربارهٔ آن بود.

و ۴۰۰ در برابرِ ۵۰۰ هم تصمیمِ مهمی است: ۴۰۰ یعنی «ورودیِ تو خراب است، دوباره نفرست»، ۵۰۰ یعنی «مشکل از من است، بعداً دوباره بزن». کلاینتی که فصلِ ۱ ترمِ ۵ را خوانده، بر اساسِ همین دو عدد تصمیم می‌گیرد retry بکند یا نه — پس اگر کدِ خطا را اشتباه بدهی، کلاینت‌های دیگران را هم خراب می‌کنی.

و آن شاخهٔ except TypeError در کلاسِ Handler را هم بی‌دلیل نگذاشته‌ایم. بدنه‌ای مثلِ [1, 2] یا null یک JSONِ درست است، ولی ["texts"] رویش TypeError می‌دهد. بدونِ این شاخه، نخِ سرور می‌میرد و کلاینت هیچ پاسخی نمی‌گیرد (RemoteDisconnected)، نه ۴۰۰ و نه ۵۰۰. با این شاخه هر چهار بدنهٔ [1, 2]، null، 5 و "x" را امتحان کردیم و هر چهار ۴۰۰ گرفتند. اعتبارسنجی در مرز یعنی شکلِ کلِ بدنه را هم چک کنی، نه فقط محتوایش را.

۴. حالا عددی که کلِ فصل را توجیه می‌کند#

import time

sample = val_texts[:64]

FORWARDS.update(n=0, rows=0)
started = time.perf_counter()
for text in sample:
    requests.post(BASE + "/predict", json={"texts": [text]})
one_by_one = time.perf_counter() - started
solo = dict(FORWARDS)

FORWARDS.update(n=0, rows=0)
started = time.perf_counter()
requests.post(BASE + "/predict", json={"texts": sample})
batched = time.perf_counter() - started
group = dict(FORWARDS)

print(f"  تک‌تک : {solo['n']:>3} بار forward برای {solo['rows']} متن")
print(f"  دسته‌ای: {group['n']:>3} بار forward برای {group['rows']} متن")
print(f"  نسبتِ تعدادِ forward: {solo['n'] // group['n']} برابر")
  تک‌تک :  64 بار forward برای 64 متن
  دسته‌ای:   1 بار forward برای 64 متن
  نسبتِ تعدادِ forward: 64 برابر

۶۴ بار اجرای مدل، یا یک بار. همان ۶۴ متن، همان جواب‌ها.

چرا یک اجرای ۶۴تایی از ۶۴ اجرای تکی خیلی ارزان‌تر است؟ چون بخشِ زیادی از هزینهٔ هر اجرا ثابت است و به تعدادِ ورودی‌ها ربطی ندارد: آماده‌سازیِ تانسورها، فراخوانیِ کرنل‌ها، جابه‌جاییِ وزن‌ها بینِ حافظه و پردازنده. در حالتِ دسته‌ای این هزینهٔ ثابت یک بار پرداخت می‌شود.

۵. و همان به زبانِ زمان#

print(f"  زمانِ تک‌تک : {one_by_one:.2f} ثانیه")
print(f"  زمانِ دسته‌ای: {batched:.2f} ثانیه")
print(f"  گذردهیِ تک‌تک : {len(sample) / one_by_one:.1f} متن در ثانیه")
print(f"  گذردهیِ دسته‌ای: {len(sample) / batched:.1f} متن در ثانیه")
  زمانِ تک‌تک : 0.96 ثانیه
  زمانِ دسته‌ای: 0.16 ثانیه
  گذردهیِ تک‌تک : 66.8 متن در ثانیه
  گذردهیِ دسته‌ای: 394.6 متن در ثانیه

عددهای این سلول به ماشینِ تو بستگی دارند و با کتاب یکی درنمی‌آیند. حتی نسبتشان هم ثابت نیست: اینجا حدودِ شش برابر است و روی ماشینِ دیگری که پنج بار تکرارش کردیم ۱۰ تا ۱۲ برابر شد. آنچه ثابت می‌ماند، جهتِ نتیجه است.

📏 اندازه بگیر: گذردهی چند برابر شد، ولی تأخیرِ یک کاربرِ تنها هیچ بهتر نشد. اگر فقط یک درخواست داشته باشی، دسته‌ای کردن هیچ کمکی نمی‌کند — حتی کمی بدتر است، چون باید صبر کنی تا دسته پر شود. batching گذردهی را می‌خرد، نه تأخیر را. و این تفاوت تصمیم می‌سازد: برای پردازشِ شبانهٔ ده هزار سند، دسته‌های بزرگ؛ برای یک دستیارِ زنده، دسته‌های کوچک با مهلتِ کوتاه.

۶. batcher پویا#

مسئله این است: کاربرانِ واقعی درخواست‌هایشان را از قبل دسته‌بندی نمی‌کنند. پس سرور باید این کار را بکند: چند میلی‌ثانیه صبر کن، هر چه رسید را یکجا اجرا کن.

سه قطعهٔ تازه در کدِ زیر هست و هر سه فقط ابزارِ هم‌زمانی‌اند، نه بخشی از یادگیری ماشین:

  • threading.Thread — یک مسیرِ اجرای موازی. در کدِ آزمایش، هر کاربرِ فرضی یک نخ است تا واقعاً هم‌زمان درخواست بدهند؛ اگر با حلقهٔ ساده می‌نوشتیم، درخواست‌ها پشتِ سرِ هم می‌آمدند و اصلاً دسته‌ای تشکیل نمی‌شد.
  • queue.Queue — یک صفِ امن برای رد و بدل کردنِ کار بینِ نخ‌ها. put می‌گذارد، get برمی‌دارد و اگر خالی باشد صبر می‌کند.
  • daemon=True — یعنی این نخ جلوی بسته شدنِ برنامه را نمی‌گیرد.
import queue

WAIT = 0.02
MAX_BATCH = 32
inbox = queue.Queue()


def batcher():
    while True:
        first = inbox.get()
        jobs = [first]
        deadline = time.perf_counter() + WAIT
        while len(jobs) < MAX_BATCH:
            left = deadline - time.perf_counter()
            if left <= 0:
                break
            try:
                jobs.append(inbox.get(timeout=left))
            except queue.Empty:
                break
        labels = predict([text for text, _ in jobs])
        for (_, box), label in zip(jobs, labels):
            box.append(label)


threading.Thread(target=batcher, daemon=True).start()


def predict_via_queue(text):
    box = []
    inbox.put((text, box))
    while not box:
        time.sleep(0.001)
    return box[0]


FORWARDS.update(n=0, rows=0)
threads = []
answers = {}
for i, text in enumerate(sample):
    t = threading.Thread(target=lambda i=i, text=text: answers.__setitem__(i, predict_via_queue(text)))
    t.start()
    threads.append(t)
for t in threads:
    t.join()

batches = FORWARDS["n"]
print(f"  {len(sample)} درخواستِ هم‌زمان → {batches} بار forward")
print(f"  میانگینِ اندازهٔ دسته: {FORWARDS['rows'] / batches:.0f}")
  64 درخواستِ هم‌زمان → 3 بار forward
  میانگینِ اندازهٔ دسته: 21

⚠️ مواظب باش: این دو عدد پیشِ تو ممکن است متفاوت دربیایند و این خرابی نیست. تعدادِ دسته‌ها به زمان‌بندیِ نخ‌ها بستگی دارد: اگر همهٔ ۶۴ درخواست داخلِ پنجرهٔ WAIT برسند، دو دستهٔ ۳۲تایی می‌شود؛ اگر چندتایشان کمی دیر برسند، یک دستهٔ کوچکِ سوم هم ساخته می‌شود. کمینهٔ ممکن ۲ است (چون MAX_BATCH=32) و در عمل ۲ یا ۳ می‌بینی. علتش هم‌زمانی است، نه تصادف.

print("  کمینهٔ ممکن با MAX_BATCH:", -(-len(sample) // MAX_BATCH), "بار")
print("  دستِ‌کم هشت برابر کمتر از حالتِ تک‌تک:", batches <= len(sample) // 8)
print("  همهٔ جواب‌ها رسید:", len(answers) == len(sample))
print("  جواب‌ها با حالتِ تک‌تک یکی است:",
      [answers[i] for i in range(3)] == predict(sample[:3]))
  کمینهٔ ممکن با MAX_BATCH: 2 بار
  دستِ‌کم هشت برابر کمتر از حالتِ تک‌تک: True
  همهٔ جواب‌ها رسید: True
  جواب‌ها با حالتِ تک‌تک یکی است: True

۶۴ درخواستِ کاملاً مستقل، و مدل به‌جای ۶۴ بار فقط دو تا سه بار اجرا شد.

و به شکلِ این سه ادعا دقت کن، چون خودش یک درسِ مهندسی است: عددِ دقیقِ دسته‌ها را نمی‌شود تضمین کرد، ولی چیزهایی که واقعاً مهم‌اند را می‌شود — کف با MAX_BATCH معلوم است، صرفه‌جویی یک کرانِ روشن دارد، هیچ درخواستی گم نمی‌شود، و جواب‌ها دقیقاً همان جواب‌های حالتِ تکی‌اند. در سامانهٔ هم‌زمان، ادعایت را روی چیزی بگذار که مستقل از زمان‌بندی درست بماند.

و هر کاربر همچنان فکر می‌کند درخواستِ خودش را فرستاده و جوابِ خودش را گرفته — دسته‌ای کردن نتیجه را عوض نمی‌کند، فقط ارزان‌ترش می‌کند.

دو ابرپارامتر دارد و هر دو را باید آگاهانه انتخاب کنی:

  • WAIT — بیشتر یعنی دسته‌های بزرگ‌تر و گذردهیِ بالاتر، ولی همهٔ کاربران این مقدار تأخیرِ اضافه می‌گیرند، حتی وقتی سرویس خلوت است.
  • MAX_BATCH — بزرگ‌تر یعنی کاراتر، تا وقتی حافظه جواب بدهد. از یک جایی به بعد یا OOM می‌گیری یا سود ناچیز می‌شود.

🔧 اگر کار نکرد: اگر برنامه قفل کرد، batcher را با daemon=True نساخته‌ای یا نخِ آن مرده و صف پر می‌شود — یک try/except دورِ بدنه‌اش بگذار و خطا را در جعبهٔ جواب برگردان، وگرنه کاربر تا ابد منتظر می‌ماند. و اگر WAIT را خیلی بزرگ گذاشتی، همه‌چیز کار می‌کند ولی کند — و این خرابی هیچ خطایی تولید نمی‌کند.

۷. دمو در برابرِ سرویس#

دموی Gradio سرویسِ واقعی
هدف نشان دادن تکیه کردن
ورودی هر چه کاربر بزند اعتبارسنجی‌شده در مرز
خطا traceback روی صفحه کدِ وضعیتِ درست و پیامِ امن
هم‌زمانی یک نفر ده‌ها، با batching
نسخه «آخرین چیزی که اجرا کردم» در هر پاسخ نوشته می‌شود
پایش ندارد /healthz، لاگ، شمارشِ خطا
هزینه مهم نیست هر درخواست شمرده می‌شود

و چهار چیزِ دیگر که این فصل جا نداشت ولی در سرویسِ واقعی لازم‌اند:

  • محدودیتِ نرخ برای هر کاربر — روی دیگرِ همان 429 که در ترمِ ۵ فصلِ ۱ می‌گرفتی.
  • مهلتِ زمانی برای هر درخواست.
  • خاموشیِ نرم — اول از پذیرشِ درخواستِ تازه دست بکش، بعد بمیر.
  • بارگذاریِ مدل در زمانِ راه‌اندازی، نه در اولین درخواست — وگرنه اولین کاربر ده ثانیه منتظر می‌ماند.

واژه‌های تازهٔ این فصل#

کلمه تلفظ به حروف فارسی یعنی چه
serving سروینگ در دسترس گذاشتنِ مدل به‌شکلِ یک سرویس
endpoint اندپوینت مسیری که سرویس روی آن جواب می‌دهد
health check هلث چک مسیری که می‌گوید سرویس زنده است
throughput تروپوت تعدادِ درخواستِ پردازش‌شده در واحدِ زمان
dynamic batching داینامیک بچینگ جمع کردنِ درخواست‌های هم‌زمان در یک اجرا
graceful shutdown گریسفول شات‌داون مردنِ سرویس بدونِ نصفه گذاشتنِ درخواست‌های در جریان

🤖 از دستیارت بپرس: «ASGI چیست و چرا برای سرویسِ مدل معمولاً از FastAPI استفاده می‌کنند؟» بعد این را بپرس: «چه چیزی به من می‌دهد که http.server نمی‌دهد؟» — و آنجا اعتبارسنجیِ خودکار با schema، مستنداتِ خودکار، و مدیریتِ هم‌زمانی را می‌بینی. ولی حالا که خودت یکی نوشته‌ای، می‌دانی زیرِ آن‌ها چه خبر است.

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

سامانه‌ات کار می‌کند، سریع است، و در دسترس. فصلِ بعد سؤالِ دیگری می‌پرسد: آیا باید وجود داشته باشد؟ model card کامل، سوگیریِ اندازه‌گیری‌شده نه ادعاشده، حریمِ خصوصیِ دادهٔ آموزش، و هزینهٔ انرژی.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.