بخش 4.5 · هر گذر رو به جلو

آرگومان ‎--grammar-backend‎ و خروجی‌های ساختاریافته

--grammar-backend and structured outputs

فهرست مطالب
  1. راه‌حل بدیهی و دلیل ناکارآمدی آن
  2. نحوه‌ی کارکرد SGLang
  3. فعال نبودن پرش به جلو در نسخه‌ی v0.5.22
  4. مواردی که باید اندازه بگیرید
  5. نتایج ارزیابی ما روی یک GB10
  6. دیدگاه ما
  7. رخدادها

فریم‌ورک SGLang در هر گام رمزگشایی، اسکیمای JSON یا regex را به یک ماسک توکن تبدیل می‌کند و کامپایل هر گرامر را بیرون از حلقه‌ی دسته انجام می‌دهد.

ایجنت شما برای فراخوانی ابزار از مدل درخواست خروجی می‌کند و پاسخ را با json.loads پارس می‌کند. بیشتر پاسخ‌ها بی‌دردسر پارس می‌شوند؛ اما گاهی یک آکولاد جا می‌افتد، کامنتی در انتهای متن می‌آید یا فیلدی در پاسخ دیده می‌شود که اسکیما اجازه نداده است؛ در نتیجه ایجنت دوباره تلاش می‌کند. هر تلاش مجدد هزینه‌ی یک نسل کامل متن و یک رفت‌وبرگشت کامل شبکه را تحمیل می‌کند و دم کند تاخیر شما حالا از همین تلاش‌های مجدد پر شده است.

پس از پایان این بخش، می‌توانید خروجی را با اسکیمای JSON، عبارت باقاعده (regex) یا گرامر EBNF مقید کنید. همچنین می‌توانید هزینه‌ی اعمال ماسک را بسنجید، صف گرامر را بخوانید و تصمیم بگیرید چه مواردی را پس از تولید اعتبارسنجی کنید.

راه‌حل بدیهی و دلیل ناکارآمدی آن

راه‌حل بدیهی این است که خروجی را بعد از تولید اعتبارسنجی کنید و در صورت شکست دوباره بفرستید. این روش کار می‌کند، اما کماکان کند است؛ علاوه‌براین، دقیقاً در مواردی که بیش از همه برایتان مهم هستند شکست می‌خورد: در دمای 0 (temperature 0)، تلاش مجدد با همان پرامپت دقیقاً همان پاسخ خراب قبلی را برمی‌گرداند.

رمزگشایی مقید (Constrained decoding): حذف همه‌ی توکن‌هایی که گرامر را نقض می‌کنند، پیش از آن‌که نمونه‌گیر (sampler) توکنی را انتخاب کند. در نتیجه خروجی به همه‌ی قواعدی که بک‌اند اعمال می‌کند پایبند می‌ماند و این قواعد به بخشی از رفتار خود سرور تبدیل می‌شوند.

نحوه‌ی کارکرد SGLang

هر درخواست یک قید را در پارامترهای نمونه‌گیری خود دارد: json_schema، regex، ebnf یا structural_tag. رابط چت OpenAI نیز response_format را به همین فیلدها نگاشت می‌کند. آرگومان --grammar-backend مشخص می‌کند کدام موتور آن را کامپایل کند. در نسخه‌ی v0.5.22 گزینه‌ی پیش‌فرض xgrammar است و گزینه‌های دیگر outlines، llguidance و none هستند.

یک درخواست مقید از ورود تا نمونه‌گیریاسکیما یک بار در یک استخر رشته‌ها کامپایل می‌شود در حالی که درخواست در صف گرامر منتظر می‌ماند، سپس لاجیت‌ها را در هر مرحله رمزگشایی ماسک می‌کند.
یک درخواست مقید از ورود تا نمونه‌گیری درخواستی با json_schema به مدیر گرامر می‌رسد، که کلید json به همراه اسکیما را در حافظه پنهان گرامر جستجو می‌کند. در صورت اصابت، درخواست مستقیماً به صف انتظار می‌رود. در صورت عدم اصابت، کامپایل در یک استخر رشته‌ها اجرا می‌شود و درخواست در صف گرامر منتظر می‌ماند تا گرامر در همه رتبه‌ها آماده شود. در طول هر مرحله رمزگشایی، گرامر یک بیت‌ماسک واژگان را پر می‌کند که پیش از انتخاب توکن توسط نمونه‌گیر، لاجیت‌ها را ماسک می‌کند؛ سپس گرامر توکن را می‌پذیرد. درخواست sampling_params.json_schema حافظه پنهان گرامر کلید ("json"، اسکیما) صف انتظار قابل زمان‌بندی است اصابت استخر رشته‌ها کامپایل کرده، فیوچر می‌دهد صف گرامر آماده در همه رتبه‌ها؟ عدم اصابت آماده لاجیت‌ها یک سطر برای هر درخواست بیت‌ماسک واژگان حذف توکن‌های نامعتبر نمونه‌گیر انتخاب توکن معتبر هر مرحله رمزگشایی پس از نمونه‌گیری، گرامر توکن را می‌پذیرد و وضعیت خود را تغییر می‌دهد
از چپ به راست بخوانید. کلید حافظه پنهان نوع قید و متن آن است. اصابت به حافظه پنهان از استخر رشته‌ها عبور می‌کند. از GrammarManager و ModelRunner._preprocess_logits در v0.5.22.
  1. جست‌وجو (Look up): مدیر گرامر با استفاده از نوع قید و متن آن کلیدی می‌سازد؛ مانند ("json", schema). اگر گرامر کامپایل‌شده‌ی این کلید در حافظه‌ی کش موجود باشد، بلافاصله برمی‌گردد.
  2. کامپایل (Compile): در صورت نیافتن گرامر در کش، کامپایل داخل یک استخر نخ (thread pool) شروع می‌شود و یک شیء future برمی‌گرداند. درخواست به‌جای صف انتظار به صف گرامر می‌رود.
  3. پذیرش (Admit): حلقه‌ی اسکژولر در هر چرخش وضعیت futureها را بررسی می‌کند. در موازی‌سازی تنسور یا موازی‌سازی داده، درخواست تنها زمانی وارد پردازش می‌شود که گرامر آن روی تمام رتبه‌ها (ranks) آماده شده باشد؛ اگر کامپایل روی هر کدام از رتبه‌ها با خطا مواجه شود، درخواست رد می‌شود. گرامر نامعتبر هم به‌عنوان نامعتبر کش می‌شود تا درخواست بعدی با همان اسکیما بلافاصله رد شود.
  4. ماسک‌گذاری (Mask): گرامر در هر گام یک بیت‌ماسک برای واژگان می‌سازد و اجراکننده‌ی مدل (model runner) آن را پیش از نمونه‌گیری روی لاجیت‌ها اعمال می‌کند. با اسکژولر همپوشانی (overlap scheduler)، ماسکِ گام بعدی درست حین پردازش گام فعلی روی GPU ساخته می‌شود.
  5. پیشروی (Advance): گرامر پس از نمونه‌گیری، توکنِ انتخاب‌شده را می‌پذیرد. در دیکودینگ حدسی (speculative decoding)، گرامر توکن‌های حدسی ردشده را به عقب برمی‌گرداند (rollback).

روی تراشه‌های Apple silicon، محیط اجرای MLX تنها زمانی ماسک‌های گرامر را اعمال می‌کند که آرگومان --mlx-enable-sampling فعال باشد. بدون این فلگ، همان‌طور که متن راهنمای بخش 4.6 نشان می‌دهد، هر گام رمزگشایی بالاترین لاجیت را برمی‌دارد.

صف گرامر (Grammar queue): فهرست درخواست‌هایی که گرامر آن‌ها هنوز در حال کامپایل است. مسیر /metrics طول این صف را با شناسه‌ی sglang:num_grammar_queue_reqs خروجی می‌دهد.

فعال نبودن پرش به جلو در نسخه‌ی v0.5.22

مقاله‌ی SGLang دیکودینگ پرش به جلو (jump-forward decoding) را توصیف می‌کند. وقتی گرامر تنها یک ادامه‌ی ممکن را مجاز می‌داند—مثلاً متن ثابت {"name": "—سرور بدون اجرای مدل آن را می‌نویسد. کلاس‌های گرامر در نسخه‌ی v0.5.22 هنوز متدهای پرش به جلو را دارند؛ اما با جست‌وجو در محیط اجرا هیچ فراخواننده‌ای بیرون از کلاس‌های گرامر پیدا نمی‌شود. اسکژولر از این متدها استفاده نمی‌کند، بنابراین حتی برای متن‌های ثابت هم انتظار یک بار اجرای رفت‌وبرگشت مدل (forward pass) را به ازای هر توکن داشته باشید. ما این نکته را از روی کدها خواندیم و آزمون زمان‌سنجی برای آن اجرا نکردیم.

مواردی که باید اندازه بگیرید

روی اسکیماهای خودتان سه چیز را اندازه بگیرید: نخست، زمان تا اولین توکن برای نخستین درخواست با یک اسکیمای جدید در مقایسه با دومین درخواست با همان اسکیما؛ تفاوت این دو زمان همان مدت کامپایل است. دوم، تاخیر بین توکن‌ها (inter-token latency) با و بدون قید در همروندی واقعی سیستمتان؛ محاسبه‌ی ماسک در هر گام زمان CPU مصرف می‌کند. سوم، طول صف گرامر زیر بار کاری.

یک گزارش میدانی از Varad More {{field Varad More 2026-04}} تولید ساختاریافته را روی یک کارت A10G در 16 مدل مختلف از 2B تا 9B سنجیده است. در 14 مدل از این 16 مورد، پلتفرم vLLM سریع‌تر بود. این گزارش زمان کامپایل را از هزینه‌ی هر توکن تفکیک نمی‌کند؛ بنابراین به آن به چشم دلیلی برای اندازه‌گیری در محیط خودتان نگاه کنید، نه یک حکم ارزیابی نهایی.

نتایج ارزیابی ما روی یک GB10

ما یک آزمون ارزیابی کوچک روی مدل Qwen/Qwen3-30B-A3B-Instruct-2507 با یک کارت NVIDIA GB10 و بک‌اند پیش‌فرض xgrammar اجرا کردیم. این آزمون پنج بار، هربار یک درخواست، پرامپت «یک پردازنده‌ی گرافیکی مناسب برای یک سرور مدل را در قالب یک شیء JSON توصیف کن.» را می‌فرستد. اسکیما چهار فیلد اجباری دارد: فیلد عدد صحیح memory_gb از 1 تا 1024، یک enum برای سازنده، و عدم اجازه‌ی فیلدهای اضافه.

درخواست قید تاخیر توکن‌های خروجی معتبر
1 بدون قید 3,943.9 میلی‌ثانیه 128 بدون اسکیما
2 یک اسکیمای جدید 1,636.6 میلی‌ثانیه 41 بله
3 همان اسکیما 1,309.2 میلی‌ثانیه 41 بله
4 همان اسکیما 1,310.9 میلی‌ثانیه 41 بله
5 دومین اسکیمای جدید 1,291.1 میلی‌ثانیه 41 بله

ارزیابی ما بر اساس یک دور اجراست، پس جدول را صرفاً جهت ارزیابی کلی در نظر بگیرید. همه‌ی پاسخ‌های مقید، JSON معتبر با دقیقاً همان چهار فیلد بودند. در مقابل، پاسخ بدون قید تا سقف محدودیت 128 توکن پیش رفت و کلیدهایی از خودش درآورد؛ مثل gpu_id و power_consumption.

نخستین درخواست مقید حدود 330 میلی‌ثانیه بیشتر از درخواست‌های تکراری زمان برد. دومین اسکیمای جدید چنین هزینه‌ای نشان نداد. برداشت ما این است که هزینه‌ی اول مربوط به نخستین گرامر پس از بالا آمدن سرور است. کامپایل یک اسکیمای کوچک در برابر زمان رمزگشایی 41 توکن آن‌قدر کوتاه بود که به چشم نیامد.

اسکیما قالب را تثبیت کرد، نه حقایق را. پاسخ‌های مقید از یک "NVIDIA A100" با 40 گیگابایت حافظه نام بردند، درحالی‌که پاسخ بدون قید حافظه‌ی آن را "80 GB GDDR6" اعلام کرد. گرامر ساختار نحوی را بررسی می‌کند و اعتبارسنجی معنایی همچنان برعهده‌ی خود شماست.

دیدگاه ما

هر پاسخی را که قرار است برنامه‌ای آن را پارس کند مقید کنید. ماسک در هر گام کار اضافه ایجاد می‌کند، اما تلاش مجدد کل درخواست را از نو تکرار خواهد کرد. ما هزینه‌ی هر گام ماسک را اندازه نگرفتیم.

برای اجرای تک‌تک کلیدواژه‌های JSON Schema به بک‌اند گرامر اعتماد نکنید. هر کلیدواژه‌ای را که کد مصرف‌کننده‌ی شما به آن متکی است—مانند minLength، pattern، minimum و enum—با درخواستی که سعی در شکستن آن دارد تست کنید. برای فیلدهای مهم، یک اعتبارسنج سبک پشت سرور نگه دارید.

پس از هر بار استقرار، یک درخواست مقید بفرستید تا اولین درخواست کاربر هزینه‌ی اولیه‌ی راه‌اندازی بک‌اند گرامر را نپردازد. روی کارت GB10 ما، آن درخواست اول حدود 330 میلی‌ثانیه تاخیر اضافه داشت. در آزمون ما، یک اسکیمای کوچک جدیدِ دیگر هزینه‌ی اضافه‌ای ایجاد نکرد.

رخدادها

افتادن یکی از قوانین اسکیما بدون اعلام خطا. ایشوی #37707 (تاریخ 2026-09-03): در xgrammar، اگر یک فیلد متنی هم‌زمان pattern هم داشت، مقادیری کوتاه‌تر از minLength را می‌پذیرفت. همین گزارش می‌گوید outlines نیز pattern و محدودیت‌های بازه‌ی عددی را نادیده گرفته است. این ایشو در زمان بازبینی این کتابچه همچنان باز بود.

رشد کار گرامر با طول خروجی در دیکودینگ حدسی. ایشوی #38863 (تاریخ 2026-09-10): با دیکودینگ حدسی، زمان صرف‌شده روی CPU میزبان برای ساخت بیت‌ماسک‌ها همراه با طول خروجی افزایش می‌یافت. دلیل این امر متد بازگشت به عقبی (rollback) بود که در هر فراخوانی از یک لیست دیباگ کپی می‌گرفت. این ایشو به‌عنوان گزارش کارایی باز بود.

منابع: capture/out/serve-help.txt، capture/gpu/out-gb10/structured.txt، capture/gpu/structured_probe.py، فایل python/sglang/srt/constrained/grammar_manager.py متدهای (process_req_with_grammar و get_ready_grammar_requests)، constrained/base_grammar_backend.py، constrained/xgrammar_backend.py، model_executor/model_runner.py متد (_preprocess_logits)، sampling/sampling_params.py، arg_groups/serving_hook.py متد (handle_grammar_backend)، arg_groups/choices.py متغیر (GRAMMAR_BACKEND_CHOICES) و observability/metrics_collector.py در نسخه‌ی v0.5.22؛ مقاله‌ی SGLang با شناسه‌ی (arXiv 2312.07104)؛ ایشوهای #37707 و #38863؛ گزارش میدانی از Varad More (تاریخ 2026-04-22).

ترجمه‌ی فارسی --grammar-backend and structured outputs از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما