Implementation:Vllm project Vllm StructuredOutputsParams Init

Knowledge Sources	vLLM vLLM Docs
Domains	LLM Inference, Structured Output, Configuration
Last Updated	2026-02-08 13:00 GMT

Overview

Concrete tool for encapsulating a structured output constraint into a validated configuration object, provided by vLLM.

Description

StructuredOutputsParams is a Pydantic dataclass that holds exactly one structured output constraint along with optional behavioral flags. It validates at construction time that exactly one of the mutually exclusive constraint fields is set. If zero or more than one constraint is provided, a ValueError is raised.

The supported constraint types are:

• json: A JSON Schema as a str or dict. Typically produced by pydantic.BaseModel.model_json_schema().
• regex: A regular expression pattern as a str.
• choice: A list of allowed output strings as list[str].
• grammar: A GBNF grammar string as str.
• json_object: A boolean flag that constrains output to valid JSON without a specific schema.
• structural_tag: A structural tag specification as str.

Additional behavioral options control backend fallback, whitespace handling, and additional properties.

Usage

Use this class to wrap a schema definition before passing it to SamplingParams. Construct it with exactly one constraint keyword argument and any desired option flags.

Code Reference

Source Location

• Repository: vllm
• File: vllm/sampling_params.py (lines 34-106)

Signature

@dataclass
class StructuredOutputsParams:
    json: str | dict | None = None
    regex: str | None = None
    choice: list[str] | None = None
    grammar: str | None = None
    json_object: bool | None = None
    disable_fallback: bool = False
    disable_any_whitespace: bool = False
    disable_additional_properties: bool = False
    whitespace_pattern: str | None = None
    structural_tag: str | None = None

Import

from vllm.sampling_params import StructuredOutputsParams

I/O Contract

Inputs

Name	Type	Required	Description
json	dict | None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	JSON Schema as a dict (from Pydantic) or a JSON string
regex	None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	Regular expression pattern the output must match
choice	None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	List of allowed output strings
grammar	None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	GBNF grammar string defining the output language
json_object	None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	If True, constrain output to valid JSON (no specific schema)
structural_tag	None	Exactly one of json/regex/choice/grammar/json_object/structural_tag required	Structural tag specification string
disable_fallback	bool	No (default: False)	If True, do not fall back to an alternative backend on compilation failure
disable_any_whitespace	bool	No (default: False)	If True, produce compact JSON without arbitrary whitespace
disable_additional_properties	bool	No (default: False)	If True, disallow additional properties in JSON output beyond the schema
whitespace_pattern	None	No (default: None)	Custom whitespace regex pattern for JSON output formatting

Outputs

Name	Type	Description
StructuredOutputsParams instance	StructuredOutputsParams	A validated configuration object ready to be passed to SamplingParams(structured_outputs=...)

Usage Examples

JSON Schema Constraint

from pydantic import BaseModel
from vllm.sampling_params import StructuredOutputsParams

class Person(BaseModel):
    name: str
    age: int

params = StructuredOutputsParams(json=Person.model_json_schema())

Regex Constraint

from vllm.sampling_params import StructuredOutputsParams

params = StructuredOutputsParams(regex=r"\w+@\w+\.com\n")

Choice Constraint

from vllm.sampling_params import StructuredOutputsParams

params = StructuredOutputsParams(choice=["Positive", "Negative"])

Grammar Constraint

from vllm.sampling_params import StructuredOutputsParams

sql_grammar = """
root ::= select_statement
select_statement ::= "SELECT " column " from " table
column ::= "col_1" | "col_2"
table ::= "table_1" | "table_2"
"""
params = StructuredOutputsParams(grammar=sql_grammar)

Mutual Exclusivity Validation

from vllm.sampling_params import StructuredOutputsParams

# This raises ValueError: multiple constraints specified
try:
    params = StructuredOutputsParams(
        json={"type": "object"},
        regex=r"\d+"
    )
except ValueError as e:
    print(e)  # "You can only use one kind of structured outputs constraint..."

Related Pages

Implements Principle

• Principle:Vllm_project_Vllm_Structured_Output_Configuration