SGLang شرایط توقف را در اسکژولر بررسی میکند و ساخت متن را در دیتوکنایزر انجام میدهد. همچنین اندپوینت بومی
generate/آن اطلاعات زمانبندی و دادههای کشی را گزارش میکند که قالب OpenAI نادیده میگیرد.
پاسخی را به یک پنجرهی چت استریم میکنید، اما آخرین کلمهی قبل از رشتهی توقف (stop string) با تاخیر میرسد. یا وقتی دیکودینگ حدسی (speculative decoding) فعال است، خود رشتهی توقف به داخل متن نشت میکند. شاید هم کلاینت اصلاً هیچ cached_tokensای نشان نمیدهد و نمیتوانید بفهمید پرامپت شما به کش خورده است یا نه. هر سه مورد به این برمیگردند که متن در کجا تولید میشود و چه بخشی چه دادهای را گزارش میکند.
پس از پایان این بخش، میتوانید بهدرستی میان اندپوینت بومی generate/ و اندپوینتهای OpenAI دست به انتخاب بزنید. همچنین تکتک فیلدهای زمانبندی را در پاسخ بومی میخوانید و علت تاخیر گاهبهگاه متن در حالت استریمینگ را متوجه میشوید.
دو API روی یک سرور واحد
API بومی (Native API): اندپوینتهای اختصاصی خود SGLang، بهویژه POST /generate. این اندپوینت متن یا شناسههای توکن (token IDs) و sampling_params را دریافت میکند و یک شیء meta_info برمیگرداند که شامل دادههای خود SGLang است.
OpenAI API: اندپوینتهای v1/chat/completions/، v1/completions/ و v1/models/ با همان قالبی که کلاینتهای OpenAI انتظار دارند. سرور پیش از توکنایز کردن، الگوی چت (chat template) را اعمال میکند.
هر دو اندپوینت در پشت صحنه همان درخواست داخلی یکسان را میسازند و از همان سه فرایند بخش 2.1 عبور میکنند. تفاوت اصلی در دادههایی است که در پاسخ برمیگردد.
پاسخ بومی چه اطلاعاتی به شما میدهد
ابزار ثبت دادهی ما یک درخواست بومی را با 12 توکن خروجی و در دمای (temperature) صفر ارسال میکند.
{
"text": " Paris, and the capital of Germany is Berlin. The capital",
…
"meta_info": {
"id": "e272e3ffc4064bfeaa0223b86408e107",
"finish_reason": {
"type": "length",
"length": 12
},
"prompt_tokens": 5,
…
"num_retractions": 0,
…
"queue_time": 0.0002437499351799488,
"reasoning_tokens": 0,
"completion_tokens": 12,
"cached_tokens": 2,
…
"cached_tokens_details": {
"device": 2,
"host": 0
},
"dp_rank": null,
"e2e_latency": 0.9496850408613682,
…
"first_token_latency": 0.8885334208607674,
…
"decode_throughput": 179.8807619469758,
…
}
}لیست output_ids و لیست weight_versions خلاصه شدهاند.
تکتک این فیلدها به پرسشهایی پاسخ میدهند که در محیط عملیاتی (production) با آنها روبهرو میشوید:
- فیلد
finish_reasonعلت توقف را مشخص میکند: در اینجاlengthاست، چون درخواست 12 توکن خواسته بود و دقیقاً 12 توکن هم تحویل گرفت. - فیلد
queue_timeبرابر با 0.24 میلیثانیه است؛ یعنی درخواست معطل نمانده است. زیر بار کاری سنگین، همزمان با انتظار درخواستها در صف، این عدد بالا میرود. - فیلد
first_token_latencyمعادل 889 میلیثانیه وe2e_latencyمعادل 950 میلیثانیه است. روی یک سرور تازه راهاندازیشده (cold server)، تولید اولین توکن بیشترین زمان را گرفته است. - فیلد
num_retractionsبرابر با 0 است. بخش 2.3 هزینههای غیرصفر بودن این مقدار را توضیح میدهد. - فیلد
cached_tokensنشان میدهد 2 توکن از 5 توکن پرامپت در حافظهی کش بودهاند؛ همگی روی خود دستگاه (device) قرار داشتهاند و نه در حافظهی میزبان (host memory).
وجود دو توکن کششده در اولین درخواست ابزار ما معمای کوچکی است که پاسخی روشن دارد. سرور پیش از پذیرش ترافیک، با پرامپت The capital city of France is پیشگرمایش (warm-up) میشود {{code}}. پرامپت ما The capital of France is بود. دو توکن اول در درخت مبنا (Radix Tree) با پرامپت پیشگرمایش مطابقت داشتند. برای کش اصلاً فرقی نمیکند کدام کاربر پیشوند را فرستاده است.
پاسخ OpenAI چه اطلاعاتی به شما میدهد
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Ardens",
"reasoning_content": null
},
"logprobs": null,
"finish_reason": "stop",
"matched_stop": 151645
}
],
"usage": {
"prompt_tokens": 21,
"total_tokens": 25,
"completion_tokens": 4,
"prompt_tokens_details": {
"cached_tokens": 0
},
"reasoning_tokens": 0
},شناسه id، زمان ایجاد created و بلوک metadata خلاصه شدهاند.
ما نام یک سیاره را در قالب یک کلمه خواستیم. مدل 0.6 میلیارد پارامتری 4-بیتی با کلمهی «Ardens» پاسخ داد که اصلاً سیاره نیست. هنگام قضاوت روی یک موتور سروینگ با مدلی بسیار کوچک، این نکته را گوشهی ذهن داشته باشید. موتور کار خودش را انجام داد: روی توکن 151645 یعنی توکن پایان نوبت گفتوگو (end-of-turn) متوقف شد و matched_stop را گزارش کرد.
فیلد cached_tokens تنها به این دلیل در خروجی آمده که سرور ما با فلگ --enable-cache-report اجرا میشود. بدون این فلگ، SGLang جزئیات کش را از گزارش مصرف (usage) قالب OpenAI حذف میکند؛ هرچند این محاسبات را برای تکتک درخواستها انجام میدهد {{code}}. در مقابل، فیلد meta_info در خروجی بومی تحت هر شرایطی cached_tokens را گزارش میکند.
نکتهای برای کاربران Mac: روی MLX در نسخهی v0.5.22، رمزگشایی به صورت حریصانه (greedy) انجام میشود، مگر اینکه آرگومان --mlx-enable-sampling را پاس بدهید؛ در غیر این صورت، پارامترهای temperature، ماسکهای گرامر و احتمالهای لگاریتمی خروجی (logprobs) هیچ تاثیری در آنجا نخواهند داشت. راهنمای متنی دستور sglang serve هم این را میگوید. کیت ما از دمای 0 استفاده میکند، بنابراین خروجیهای آن در هر دو حالت یکسان است. در بخش 4.6 به مبحث نمونهبرداری (sampling) و logprobها روی GPUها میپردازیم.
رشتههای توقف در کجا بررسی میشوند
شرط توقف (Stop condition): قاعدهای که به یک درخواست پایان میدهد. این شرط میتواند یک توکن توقف، یک رشتهی توقف، یک regex، محدودیت max_new_tokens، لغو دستی (abort)، یا پایان یک ساختار گرامری باشد.
SGLang شرایط توقف را در اسکژولر (scheduler)، پس از هر گام و با ترتیبی مشخص بررسی میکند {{code}}. رشتهی توقف پیش از توکن پایان توالی (end-of-sequence) بررسی میشود. کامنتهای درون کد دلیل این موضوع را توضیح میدهند: دیکودینگ حدسی میتواند در یک گام بیش از یک توکن را بپذیرد. اگر بررسی بر اساس تکتوکن انجام میشد، فقط توکن آخر حذف میشد و ادامهی رشتهی توقف به خروجی نشت میکرد. دیتوکنایزر فقط متنِ منطبق بر رشتهی توقف را از خروجی پاک میکند.
چرا متن در حالت استریمینگ معطل میشود
دو قاعده میتوانند ارسال یک قطعه از پاسخ (chunk) را به تاخیر بیندازند {{code}}:
- کاراکترهای ناقص. دیتوکنایزر متن را به شکل افزایشی و با دو آفست به ازای هر درخواست رمزگشایی میکند. اگر انتهای متن جدید روی یک کاراکتر ناقص UTF-8 بماند، دیتوکنایزر صبر میکند تا توکن بعدی بیاید و بعد چیزی ارسال کند.
- احتمال شروع یک رشتهی توقف. اگر انتهای متن بتواند آغاز یک رشتهی توقف باشد، استریمرِ خروجی (output streamer) آن را نگه میدارد. اگر توکنهای بعدی رشتهی توقف را کامل کنند، آن متن اصلاً نمایش داده نمیشود. اگر نکنند، متن نگهداشتهشده همراه با قطعهی بعدی ارسال میشود.
با مقدار پیشفرض --stream-interval 1، SGLang خروجی را بعد از هر گام استریم میکند. حتی در یک درخواست غیراستریمینگ هم پیشرفت کار به صورت داخلی درون سرور هر 50 توکن یک بار (SGLANG_FORCE_STREAM_INTERVAL) گزارش میشود تا TokenizerManager بتواند آن را دنبال کند {{code}}.
ماجرای یک اختلال: دیتوکنایزری که از کار افتاد
قاعدهی کاراکترهای ناقص زمانی که توکنها هیچوقت یک کاراکتر را کامل نمیکنند، هزینهساز میشود {{issue #34740}}. دیتوکنایزر تا زمانی که انتهای متن روی کاراکتر جایگزین U+FFFD بماند، دست نگه میدارد. توکنهای بایتی که هیچگاه به یک کاراکتر کامل تبدیل نمیشوند، آفستها را جلو نمیبرند. در نتیجه، در هر گام کل بخش انتهایی متن دوباره رمزگشایی میشود و حجم محاسبات با توان دو طول متن رشد میکند. این گزارش با یک تنظیمات آزمایشی کشف شد که شناسهی 100 را پر میکرد؛ شناسهای که روی DeepSeek-V4-Pro به U+FFFD رمزگشایی میشود. هنگام بررسی ما، این ایشو هنوز باز بود.
موضع ما
هنگام دیباگ، سنجش کارایی، یا ساخت کلاینت اختصاصی خودتان، از اندپوینت بومی generate/ استفاده کنید. شیء meta_info در این اندپوینت زمان انتظار در صف، تاخیر اولین توکن، موارد اصابت به کش (cache hits)، و نرخ ابطالها (retractions) را به ازای هر درخواست گزارش میدهد؛ مواردی که قالب OpenAI جایی برای بیشتر آنها در نظر نگرفته است.
برای برنامههایی که از قبل با استاندارد OpenAI پیادهسازی شدهاند، از همان اندپوینتهای OpenAI استفاده کنید. همیشه تمام سرورها را با فلگ --enable-cache-report اجرا کنید تا آن کلاینتها هم بتوانند اصابت به کش را ببینند. ما افت سرعتی در استفاده از آن اندازهگیری نکردیم و در بخش 3 نشان میدهیم این رقم چقدر ارزشمند است.
منابع: فایل python/sglang/srt/entrypoints/http_server.py (پرامپت پیشگرمایش، generate/)؛ فایل python/sglang/srt/entrypoints/openai/serving_chat.py (enable_cache_report)؛ فایل python/sglang/srt/managers/schedule_batch.py (توابع update_finish_state و check_match_stop_str_prefix)؛ فایل python/sglang/srt/managers/scheduler_components/output_streamer.py؛ فایل python/sglang/srt/managers/detokenizer_manager.py؛ فایل python/sglang/srt/environ.py (متغیر SGLANG_FORCE_STREAM_INTERVAL)؛ فایل python/sglang/srt/arg_groups/fields/serving.py در نسخهی v0.5.22؛ فایلهای خروجی capture/out/generate.txt و اسکریپت capture/one_request.py؛ خروجی capture/out/serve-help.txt برای mlx-enable-sampling--؛ ایشوی https://github.com/sgl-project/sglang/issues/34740.