در این فصل چه یاد میگیری#
شش ترم مدل ساختی و هیچکدام از نوتبوک بیرون نیامد. این فصل یکی را واقعاً سرو میکند: یک سرورِ 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 کامل، سوگیریِ اندازهگیریشده نه ادعاشده، حریمِ خصوصیِ دادهٔ آموزش، و هزینهٔ انرژی.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.