بخش 2.5 · مسیر درخواست

استریمینگ، رشته‌های توقف و OpenAI API

Streaming, stop strings, and the OpenAI API

فهرست مطالب
  1. دو API روی یک سرور واحد
  2. پاسخ بومی چه اطلاعاتی به شما می‌دهد
  3. پاسخ OpenAI چه اطلاعاتی به شما می‌دهد
  4. رشته‌های توقف در کجا بررسی می‌شوند
  5. چرا متن در حالت استریمینگ معطل می‌شود
  6. ماجرای یک اختلال: دی‌توکنایزری که از کار افتاد
  7. موضع ما

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) صفر ارسال می‌کند.

یک پاسخ نیتیو generate/ capture/out/generate.txt
{
  "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 چه اطلاعاتی به شما می‌دهد

پاسخ چت به سبک OpenAI capture/out/generate.txt
  "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) بررسی می‌شود. کامنت‌های درون کد دلیل این موضوع را توضیح می‌دهند: دیکودینگ حدسی می‌تواند در یک گام بیش از یک توکن را بپذیرد. اگر بررسی بر اساس تک‌توکن انجام می‌شد، فقط توکن آخر حذف می‌شد و ادامه‌ی رشته‌ی توقف به خروجی نشت می‌کرد. دی‌توکنایزر فقط متنِ منطبق بر رشته‌ی توقف را از خروجی پاک می‌کند.

یک درخواست استریم‌شده به همراه رشته توقفاسکژولر زمان توقف درخواست را تعیین می‌کند، دیتوکن‌آیزر شناسه‌ها را به متن تبدیل می‌نماید و استریمر خروجی، متنی را که می‌تواند آغازگر رشته توقف باشد موقتاً نگه می‌دارد.
یک درخواست استریم‌شده به همراه رشته توقف چهار خط عمر: کلاینت، TokenizerManager، اسکژولر، و دیتوکن‌آیزر. کلاینت یک درخواست استریم ارسال می‌کند، اسکژولر شناسه‌های توکن را به دیتوکن‌آیزر می‌فرستد، که آن هم متن را در قالب چانک‌های SSE برای کلاینت پس می‌فرستد. اسکژولر متنی را که انتهای آن ممکن است آغازگر رشته توقف باشد نگه می‌دارد، سپس رشته توقف مطابقت داده شده و کار تمام می‌شود، و دیتوکن‌آیزر پیش از ارسال چانک آخر، متن توقف را برش می‌دهد. کلاینت TokenizerManager اسکژولر دیتوکن‌آیزر 1 POST، مقدار stream=true 2 درخواست توکنایز‌شده 3 شناسه‌های توکن جدید 4 متن جدید 5 چانک SSE 6 نگه‌داشتن پیشوند احتمالی توقف 7 تطابق با رشته توقف، پایان 8 last ids, finish_reason stop 9 متن با حذف عبارت توقف 10 last chunk, then [DONE]
از بالا به پایین بخوانید. خطوط عمر آبی‌رنگ فرایندهای SGLang هستند، خط عمر زیتونی کلاینت است، فلش‌های نقطه‌چین نیلی چانک‌های استریم‌شده هستند. رفتار برگرفته از schedule_batch.py، output_streamer.py و detokenizer_manager.py در نسخه v0.5.22.

چرا متن در حالت استریمینگ معطل می‌شود

دو قاعده می‌توانند ارسال یک قطعه از پاسخ (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.

ترجمه‌ی فارسی Streaming, stop strings, and the OpenAI API از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما