بخش 1.2 · شروع

بررسی سلامت سرور

Check that the server is healthy

فهرست مطالب
  1. انتظار تا دریافت پاسخ 200 از health/
  2. انتخاب اندپوینت مناسب
  3. خواندن 3 خط لاگ در زمان راه‌اندازی
  4. گرم‌کردن سرور پیش از اندازه‌گیری
  5. بررسی اولین متریک‌ها

پیش از هدایت ترافیک به سمت سرور، مطمئن شوید پاسخ می‌دهد، می‌تواند توکن تولید کند و اندازه‌ی حافظه را طبق انتظار شما انتخاب کرده است.

خط ready در لاگ نشان می‌دهد سرور راه‌اندازی شده است، اما تضمین نمی‌کند بتواند ترافیک شما را مدیریت کند. اگر استخر حافظه خیلی کوچک باشد، یا سرور نتواند توکن تولید کند، لاگ همچنان همان خط آماده‌باش را چاپ می‌کند.

با مطالعه‌ی این بخش، می‌توانید اندپوینت بررسی سلامت مناسب را برای اسکریپت‌ها یا آزمون‌های ارزیابی (probes) انتخاب کنید. همچنین با نحوه‌ی خواندن 3 خط مربوط به ابعاد حافظه در زمان راه‌اندازی، گرم‌کردن اولیه و بررسی اولین متریک‌های سرور آشنا خواهید شد.

انتظار تا دریافت پاسخ 200 از health/

برای اینکه اسکریپت شما منتظر بالا آمدن سرور بماند، اندپوینت /health را مدام صدا بزنید تا کد 200 برگرداند:

until curl -sf -o /dev/null http://127.0.0.1:30000/health; do sleep 2; done

ابزار تست ما هم دقیقاً همین کار را هر 2 ثانیه یک‌بار انجام داد. در لاگ سرور می‌بینید که پاسخ از 503 به 200 تغییر می‌کند:

وضعیت health/ در هنگام راه‌اندازی سرور L4 ما capture/gpu/out-l4/server-default.log
[2026-10-17 14:43:37] INFO:     127.0.0.1:58250 - "GET /health HTTP/1.1" 503 Service Unavailable
…
[2026-10-17 14:43:38] INFO:     127.0.0.1:58272 - "POST /generate HTTP/1.1" 200 OK
[2026-10-17 14:43:38] INFO:     127.0.0.1:58288 - "POST /freeze_gc HTTP/1.1" 200 OK
[2026-10-17 14:43:38] The server is fired up and ready to roll!
[2026-10-17 14:43:40] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 0.58
[2026-10-17 14:43:40] INFO:     127.0.0.1:58298 - "GET /health HTTP/1.1" 200 OK

خطوط 36 تا 43 لاگ. درخواست model_info/ و دو خط اول پیش‌پرکنی حذف شده‌اند.

به خط قبل از کد 200 دقت کنید؛ اسکژولر (scheduler) برای بررسی سلامت یک پیش‌پرکنی (prefill) تک‌توکنی اجرا کرده است. اندپوینت /health در حالت پیش‌فرض فقط یک پاسخ خالی نمی‌دهد؛ بلکه یک درخواست تک‌توکنی به مدل می‌فرستد و منتظر نتیجه می‌ماند.

انتخاب اندپوینت مناسب

در SGLang سه اندپوینت بررسی سلامت وجود دارد {{code}}. بر اساس نیازی که دارید، یکی را انتخاب کنید:

  • آیا سرور بالاست و درخواست قبول می‌کند؟ از /ready استفاده کنید. این اندپوینت وقتی آماده‌ی مدیریت توکنایزر باشد کد 200 می‌دهد و هیچ درخواستی به مدل نمی‌فرستد.
  • آیا سرور همین حالا می‌تواند توکن تولید کند؟ از /health_generate استفاده کنید. این اندپوینت یک درخواست تک‌توکنی می‌فرستد و اگر تا 20 ثانیه خروجی دریافت نکند، کد 503 برمی‌گرداند.
  • /health کنترل‌کننده‌ای (handler) مشترک با /health_generate دارد. در تنظیمات پیش‌فرض، این اندپوینت هم توکن تولید می‌کند.

برای اسکریپتی که صرفاً منتظر اجرای سرور است، هر سه گزینه مناسبند؛ اما در پروب‌های Kubernetes، این انتخاب زیر بار ترافیک تفاوت چشم‌گیری ایجاد می‌کند. پروبی که توکن تولید می‌کند، درست در همان صف درخواست‌های کاربران منتظر می‌ماند. در بخش 7.1 تنظیمات پیشنهادی ما برای پروب‌ها و تجربه‌ی بحرانیِ پشت این توصیه‌ها را توضیح داده‌ایم.

خواندن 3 خط لاگ در زمان راه‌اندازی

سه خط در لاگ راه‌اندازی به شما می‌گویند سرور چقدر ظرفیت پذیرش دارد. این خطوط را در هر بار راه‌اندازی بررسی کنید، چون SGLang آن‌ها را به‌طور خودکار محاسبه می‌کند:

خطوط مربوط به اندازه‌بندی در سرور L4 ما capture/gpu/out-l4/server-default.log
[2026-10-17 14:42:45] KV Cache is allocated. dtype: torch.bfloat16, #tokens: 22939, K size: 1.58 GB, V size: 1.58 GB
…
[2026-10-17 14:43:36] max_total_num_tokens=22939, chunked_prefill_size=4096, max_prefill_tokens=16384, max_running_requests=2048, context_len=40960, available_gpu_mem=1.31 GB
…
[2026-10-17 14:43:36] Tree cache initialized: source=default impl=UnifiedRadixCache hybrid_swa=False hybrid_ssm=False hicache_attached=False

سه خط از لاگ راه‌اندازی. خطوط بین آن‌ها حذف شده‌اند.

استخر حافظه (KV pool): همان حافظه‌ی GPU است که کلیدها و مقادیر (Keys and Values) تمام توکن‌های نگهداری‌شده در سرور را برای همه‌ی درخواست‌ها ذخیره می‌کند. ظرفیت این استخر در سیستم ما 22,939 توکن است.

این مقدار را با context_len=40960 مقایسه کنید. طول یک درخواست می‌تواند از کل ظرفیت این استخر بیشتر باشد؛ بنابراین یک درخواست طولانی می‌تواند تمام آن را پر کند. 23 کاربر با 1,000 توکن هم کل استخر را اشغال خواهند کرد.

مقدار max_running_requests=2048 بیشترین تعداد درخواست‌هایی است که اسکژولر هم‌زمان پردازش می‌کند. این عدد را خود سرور محاسبه کرده و ما تنظیمش نکرده‌ایم. البته محدودیت اصلی سرور خیلی زودتر از رسیدن به 2,048 درخواست و به خاطر پر شدن استخر حافظه نمایان می‌شود.

خط آخر نام کش پیشوندی (prefix cache) سرور را مشخص می‌کند. UnifiedRadixCache همان کش پیش‌فرض radix است و مقدار hicache_attached=False نشان می‌دهد HiCache خاموش است. در بخش 3.5 توضیح داده‌ایم چه زمانی باید آن را روشن کنید.

اگر استخر حافظه کمتر از نیاز ترافیک شماست، برای محاسبه‌ی ظرفیت حافظه به بخش 3.1 و برای تغییر اندازه به بخش 3.2 بروید.

گرم‌کردن سرور پیش از اندازه‌گیری

کدهای بخش اول نشان می‌دهند که قبل از خط ready، دو درخواست POST /generate و POST /freeze_gc ثبت شده است. سرور ابتدا یک درخواست به خودش فرستاده و سپس زباله‌روب (garbage collector) پایتون را فریز کرده است تا اشیای زمان راه‌اندازی دیگر دوباره اسکن نشوند.

این فرایند فریز کردن پیشینه‌ای دارد: گزارشی از تیم فنی LinkedIn نشان داد که روی یک مدل رتبه‌بندی کوچک، فرایند زباله‌روبی هر چند ثانیه یک‌بار باعث توقف‌های 100 تا 300 میلی‌ثانیه‌ای می‌شد {{field LinkedIn 2026-02}}. راه‌حل، همین گرم‌کردن اولیه و فریز زباله‌روب بود که در pull request 9241 با پروژه merge شد.

البته گرم‌کردن اولیه باعث نمی‌شود نخستین درخواست روی هر سیستمی سریع باشد. در سرور L4 ما، اولین درخواست بعد از راه‌اندازی در عرض 68 میلی‌ثانیه به اولین توکن رسید، اما در مک، همین درخواست 889 میلی‌ثانیه طول کشید. پیش از اندازه‌گیری و بنچمارک، خودتان چند درخواست بفرستید.

بررسی اولین متریک‌ها

سروری که با --enable-metrics اجرا شده، متریک‌های Prometheus را روی /metrics ارائه می‌دهد. اکنون 4 مورد از آن‌ها را بررسی کنید و این دستور را برای بعد به خاطر بسپارید:

curl -s http://127.0.0.1:30000/metrics | grep -E '^sglang:(num_running_reqs|num_queue_reqs|token_usage|cache_hit_rate)\{'
چهار معیار پس از اجرای سرور L4 ما capture/gpu/out-l4/metrics.txt
sglang:num_running_reqs{engine_type="unified",model_name="Qwen/Qwen3-8B",moe_ep_rank="0",pp_rank="0",tp_rank="0"} 0.0
sglang:num_queue_reqs{engine_type="unified",model_name="Qwen/Qwen3-8B",moe_ep_rank="0",pp_rank="0",tp_rank="0"} 0.0
sglang:cache_hit_rate{engine_type="unified",model_name="Qwen/Qwen3-8B",moe_ep_rank="0",pp_rank="0",tp_rank="0"} 0.956268221574344
sglang:token_usage{engine_type="unified",model_name="Qwen/Qwen3-8B",moe_ep_rank="0",pp_rank="0",tp_rank="0"} 0.0

چهار خط از metrics/، که پس از اجرای بنچمارک‌های سرور پیش‌فرض خوانده شده‌اند.

  • مقادیر num_running_reqs و num_queue_reqs تعداد درخواست‌های در حال پردازش و در صف انتظار را می‌شمارند.
  • token_usage سهم مصرف استخر حافظه را از 0 تا 1 نشان می‌دهد.
  • cache_hit_rate سهم توکن‌های پرامپت است که کش پیشوندی آن‌ها را پیدا کرده است.

نرخ اصابت (hit rate) سیستم ما 0.956 است، چون بنچمارک‌ها پرامپت‌های زیادی با پیشوند مشترک ارسال کردند. در یک سرور غیرفعال، هر 4 مقدار نزدیک به 0 خواهند بود.

این اندپوینت در حالت پیش‌فرض خاموش است. اگر دستور خروجی ندارد، سرور را دوباره با --enable-metrics اجرا کنید. در بخش 5.2 فهرستی از متریک‌هایی را که باید برای آن‌ها هشدار تعریف کنید، آورده‌ایم.

Sources: capture/gpu/out-l4/server-default.log, capture/gpu/out-l4/metrics.txt, capture/gpu/out-l4/generate.txt, capture/gpu/run.py, capture/out/generate.txt; python/sglang/srt/entrypoints/http_server.py (health, health_generate, ready, _execute_server_warmup, _freeze_gc_after_server_warmup) at v0.5.22; LinkedIn Engineering, "Scaling LLM-based ranking systems with SGLang at LinkedIn" (https://www.linkedin.com/blog/engineering/ai/scaling-llm-based-ranking-systems-with-sglang-at-linkedin, 2026-02-20); pull request 9241 (https://github.com/sgl-project/sglang/pull/9241).

ترجمه‌ی فارسی Check that the server is healthy از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما