بخش 3.5 · تنظیم متناسب با ترافیک شما

بازگرداندن JSON معتبر و فراخوانی‌های ابزار

Return valid JSON and tool calls

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

خروجی ساختاریافته (Structured Output) مدل را وادار می‌کند JSON معتبر تولید کند؛ البته با هزینه‌ای که می‌توانید روی اسکیمای (Schema) اختصاصی خودتان بسنجید.

برنامه‌ی شما به JSON معتبری نیاز دارد که همیشه بدون خطا پارس شود. پس از اتمام این بخش، می‌توانید خروجی ساختاریافته درخواست کنید و هزینه‌ی پردازشی آن را بسنجید.

درخواست اسکیما

با خروجی ساختاریافته، vLLM دامنه‌ی هر توکن بعدی را فقط به توکن‌هایی محدود می‌کند که خروجی را مطابق اسکیمای شما معتبر نگه دارند. مدل نمی‌تواند متنی تولید کند که اسکیما را نقض کند. این ویژگی را در خود درخواست فعال می‌کنید، نه با فلگ سرور.

با کلاینت OpenAI، از response_format استفاده کنید:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
schema = {
    "type": "object",
    "properties": {"city": {"type": "string"}, "days": {"type": "integer"}},
    "required": ["city", "days"],
}
reply = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Plan a trip to Lisbon. Answer in JSON."}],
    response_format={"type": "json_schema", "json_schema": {"name": "trip", "schema": schema}},
)
print(reply.choices[0].message.content)

برای سایر محدودیت‌ها، structured_outputs را داخل extra_body بفرستید. این گزینه یکی از مقادیر json، json_object، regex، choice، grammar یا structural_tag را می‌گیرد. در نسخه‌ی 0.12.0 فیلدهای قدیمی‌ترِ guided_json و guided_* حذف شدند؛ راهنماهایی که از آن‌ها استفاده کنند قدیمی و منسوخ‌اند.

سازوکار پردازش در سرور

بک‌اند پیش‌فرض سرور روی auto تنظیم شده است که بک‌اند مناسب را برای درخواست انتخاب می‌کند. همچنین می‌توانید یکی از آن‌ها را مشخص کنید: xgrammar، guidance، outlines یا lm-format-enforcer. سرور اولین باری که با یک اسکیما مواجه می‌شود، آن را به یک گرامر کامپایل کرده و نتیجه را کَش می‌کند. سپس در هر گام، ماسکی از توکن‌های مجاز می‌سازد و پیش از نمونه‌برداری (Sampling) اِعمال می‌کند.

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

  • اولین درخواست با یک اسکیمای جدید، باید تا پایان کامپایل منتظر بماند.
  • ساخت ماسک در هر گام، زمان پردازش CPU را برای هر توکن افزایش می‌دهد.

روی سخت‌افزار ما اندازه‌گیری نشده است: زمان کامپایل یا هزینه‌ی پردازشی ماسک را روی L4 یا GB10 ثبت نکرده‌ایم.

بازگرداندن فراخوانی‌های ابزار

برای فراخوانی ابزار (Tool call)، سرور را همراه با پارسر متناسب با قالب ابزارِ مدل اجرا کنید:

vllm serve Qwen/Qwen3-8B --enable-auto-tool-choice --tool-call-parser hermes

پارسر متن مدل را به فیلد tool_calls در پاسخ تبدیل می‌کند. پارسری را انتخاب کنید که با خانواده‌ی مدل شما هم‌خوانی داشته باشد؛ مستندات vLLM فهرست آن‌ها را آورده است.

پیشگیری از دو مشکل شناخته‌شده

  • دیکودینگ حدسی (Speculative Decoding): ممکن است اسکیما و روش حدس زدن روی توکن‌های بعدی اختلاف‌نظر داشته باشند. در یکی از ایشوهای نسخه‌ی 0.31، خروجی JSON نامعتبر با حدس MTP در یک مدل خاص دیده شد که اکنون بسته شده است. پیش از آنکه به هر دو متکی شوید، اسکیمای خود را یک بار با --speculative-config و یک بار بدون آن تست کنید.
  • مدل‌های استدلالی (Reasoning Models): مدلی که پیش از پاسخ فکر می‌کند، نیاز دارد که محدودیت اسکیما فقط روی پاسخ اِعمال شود. پارسر استدلال را برای مدل خود تنظیم کنید تا اِعمال محدودیت پس از پایان تفکر آغاز شود. صفحه‌ی مدل‌های استدلالی این فلگ را نشان می‌دهد.

بررسی نتیجه

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

منابع: سورس‌کد vLLM در نسخه‌ی v0.31.0 (مسیرهای vllm/config/structured_outputs.py و vllm/v1/structured_output/)، مستندات vLLM در نسخه‌ی v0.31.0 (بخش‌های docs/features/structured_outputs.md و docs/features/tool_calling.md)، ایشوی شماره‌ی 60830 در مخزن vLLM.

ترجمه‌ی فارسی Return valid JSON and tool calls از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما