vLLM structured outputs 约束 JSON 响应字段的实现方法

我在把模型输出接入下游工单接口时，最先遇到的不是模型不会回答，而是同一个问题有时返回 summary，有时又多出一段说明文字。对下游代码来说，字段名和类型不稳定，比内容本身更难处理。vLLM 当前的做法是使用 structured outputs，把允许的 JSON 结构随请求交给服务端约束。

实际接入时，推荐把字段契约写成 JSON Schema，再通过 OpenAI 兼容接口的 response_format 传入 json_schema。如果你需要使用 vLLM 的额外参数，也可以把同一份 Schema 放进 structured_outputs.json。两条入口选一条即可，不要同时传入两份互相矛盾的定义。

官方地址：https://docs.vllm.ai/en/latest/features/structured_outputs/

要稳定约束 JSON 响应字段，先定义小而明确的 Schema，再选择一个请求入口；约束生成只解决结构边界，业务代码仍然要处理解析失败、空值和服务端错误。

先把响应字段写成 JSON Schema

下面用一个工单分类结果作为例子。字段数量保持少一些，category 用枚举限制取值，priority 用整数范围限制优先级，并用 additionalProperties: false 明确不接受 Schema 之外的字段。这个对象会同时成为提示词约定和请求参数里的结构契约。

# 用一个小 Schema 固定下游真正需要的字段
ticket_schema = {
    "type": "object",
    "properties": {
        "category": {"type": "string", "enum": ["bug", "question", "feature"]},
        "summary": {"type": "string"},
        "priority": {"type": "integer", "minimum": 1, "maximum": 5}
    },
    "required": ["category", "summary", "priority"],
    "additionalProperties": False
}

# 提示词仍说明字段用途，避免模型只看到抽象的类型约束
user_prompt = "把下面的问题归类，summary 写成一句话，priority 使用 1 到 5。"
problem_text = "导入任务完成了，但页面没有显示新记录。"

这里的 required 解决“字段偶尔缺失”，枚举和数值范围解决“字段存在但值不可用”。如果下游只需要两个字段，就不要为了看起来完整而加入一组不会消费的可选字段；Schema 越贴近业务边界，排查结果越清楚。

用一个请求入口把 Schema 交给 vLLM

vLLM 的 OpenAI 兼容 Chat Completions 接口支持 response_format。把 Schema 放进 json_schema.schema，并给这份结构一个稳定名称；返回内容仍然从 message.content 读取，再交给应用层的 JSON 解析器。

import json
from openai import OpenAI

# 连接本地或网关后的 vLLM OpenAI 兼容服务
client = OpenAI(base_url="http://localhost:8000/v1", api_key="-" )

response = client.chat.completions.create(
    model="your-served-model",
    messages=[
        {"role": "system", "content": "只返回符合约束的 JSON，不要添加 Markdown 代码围栏。"},
        {"role": "user", "content": user_prompt + "\n问题：" + problem_text}
    ],
    # 通过 OpenAI 兼容字段传递 JSON Schema
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "support-ticket",
            "schema": ticket_schema
        }
    }
)

# 解析仍放在业务边界，避免把字符串当成已经校验过的对象
ticket = json.loads(response.choices[0].message.content)
print(ticket["category"], ticket["priority"])

如果项目使用 vLLM 的额外请求参数，也可以改成 extra_body={"structured_outputs": {"json": ticket_schema}}。这两种写法表达的是同一个“按 JSON Schema 生成”的意图，工程上应固定一条调用约定，减少客户端封装层的分支。

字段仍然不对时先查参数版本和服务端边界

当前 vLLM 文档把 guided_json 等旧字段列为迁移项，新的请求应使用 structured_outputs 或 response_format。如果服务端日志显示请求成功但约束没有生效，先检查请求是否真的落在 vLLM 的 OpenAI 兼容路由，以及客户端是否把参数放在了错误的层级；不要只在提示词里重复“必须返回 JSON”。

# 启动 OpenAI 兼容服务；backend=auto 交给 vLLM 选择可用后端
vllm serve your-served-model \
  --structured-outputs-config.backend auto

# 旧调用里的 guided_json 应迁移到当前 structured outputs 入口
# extra_body={"structured_outputs": {"json": ticket_schema}}

vLLM 当前文档还说明 structured outputs 可以使用不同后端。通常保留 auto 即可；只有在部署环境明确需要固定后端时，才用服务端配置指定它。后端差异可能影响 Schema、正则或语法的支持范围，因此不能把“请求格式正确”误解为“任意 Schema 都能无条件使用”。

把生成约束和业务校验分开

结构化输出不是业务校验器。请求失败时，响应可能是错误对象而不是模型内容；流式响应也要等到内容片段拼接完成后再解析。对于枚举、范围、权限或数据库存在性这类业务规则，仍应在应用层做第二道检查，并把原始请求 ID 和解析错误记录下来。

总结：先固定契约，再定位入口

这类问题可以收敛成三层：Schema 负责描述允许的字段，vLLM structured outputs 负责生成时的结构约束，业务代码负责解析、错误处理和领域校验。当前新代码优先使用 response_format.json_schema 或 structured_outputs.json；看到 guided_json 时先按当前文档迁移，再检查服务端后端和请求层级。

常见追问

• 只写提示词要求返回 JSON 可以吗？不建议把它当成字段契约；提示词能说明语义，但不能替代 Schema 的字段和类型边界。
• response_format 和 structured_outputs.json 要同时传吗？通常选一个入口，避免两份结构定义不一致。
• 生成符合 Schema 就不用再校验了吗？仍要解析错误响应，并在业务层校验权限、范围和数据库约束。