vLLM OpenAI 兼容服务怎样用 JSON Schema 约束结构化输出

如果下游程序要读取模型结果，单靠提示词写“请返回 JSON”并不稳：字段可能缺失，枚举值可能漂移，额外说明文字也会混进响应。vLLM 的 OpenAI 兼容服务可以把 JSON Schema 放进结构化输出参数，让生成结果在字段和类型层面受到约束。

官方文档：https://docs.vllm.ai/en/latest/features/structured_outputs/

本文用一个小型“工单分类”示例串起服务入口、Schema 请求、应用解析和常见迁移问题。重点是请求契约怎么写，不讨论模型性能对比。

先明确 vLLM 结构化输出解决什么问题

结构化输出解决的是“模型应该生成什么形状”的问题。例如工单结果需要固定为 title、priority 和 tags 三个字段，其中 priority 只能是几个枚举值。Schema 可以把这些约束表达给 vLLM 的结构化输出后端。

它不等于业务系统的最终校验：权限、字段长度、工单是否真的存在等规则，仍然应该由应用层负责。把两层职责分开，排查时才知道问题是在生成契约还是业务契约。

准备 OpenAI 兼容服务和请求地址

vLLM 的 OpenAI 兼容服务通常暴露 /v1 地址。启动时可以显式保留默认的自动后端选择：

# 启动一个 OpenAI 兼容接口；模型名替换成实际部署的模型
vllm serve your-model-name \
  --host 0.0.0.0 \
  --port 8000 \
  --structured-outputs-config.backend auto

客户端只需要把 base_url 指向这个服务。下面的示例使用 vLLM 文档中的 extra_body 入口，把 JSON Schema 放在 structured_outputs.json 下。

把 JSON Schema 放进 structured_outputs.json

先定义一个足够小的对象 Schema，再把它作为请求参数传入。Schema 越贴近下游真正要消费的字段，越容易定位“生成格式”和“业务规则”的分界。

import json
from openai import OpenAI

# 通过 vLLM 的 OpenAI 兼容地址创建客户端；本地服务通常不校验这个占位 key
client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="dummy",
)

# 只描述机器要读取的字段，避免把展示文案混进结构化结果
ticket_schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "priority": {"type": "string", "enum": ["low", "medium", "high"]},
        "tags": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["title", "priority", "tags"],
    "additionalProperties": False,
}

# structured_outputs.json 是 vLLM 当前文档推荐的结构化输出字段
completion = client.chat.completions.create(
    model="your-model-name",
    messages=[
        {"role": "system", "content": "只提取工单信息，不添加额外字段。"},
        {"role": "user", "content": "登录页在移动端显示空白，影响线上用户。"},
    ],
    extra_body={"structured_outputs": {"json": ticket_schema}},
)

# content 仍然是字符串，交给应用层解析后再进入业务逻辑
raw_content = completion.choices[0].message.content
print(raw_content)

这里的关键不是提示词里出现了“JSON”三个字，而是请求中明确传入了 structured_outputs.json。如果你的客户端封装层更习惯 OpenAI 风格的 response_format，也要确认它最终是否把 Schema 转成了 vLLM 当前支持的结构化输出参数，不要只看客户端方法名。

在应用边界解析，并保留业务校验

返回内容经过约束后，仍建议按“解析 JSON、检查字段、执行业务规则”三个层次处理。第一层只关心字符串是不是合法 JSON，第二层关心字段类型和必填项，第三层才处理业务含义。

def read_ticket(completion: object) -> dict:
    # 先读取模型文本；缺少 content 时让调用方得到明确错误
    raw = completion.choices[0].message.content
    if not raw:
        raise ValueError("模型没有返回结构化内容")

    # JSON 语法错误属于响应解析问题，不要伪装成业务缺陷
    data = json.loads(raw)

    # 这里做轻量字段检查；更复杂的长度、权限和数据库规则放到业务层
    required = {"title", "priority", "tags"}
    if set(data) != required:
        raise ValueError(f"字段集合不符合约定：{set(data)}")
    if data["priority"] not in {"low", "medium", "high"}:
        raise ValueError("priority 不在允许的枚举范围内")
    if not isinstance(data["tags"], list):
        raise TypeError("tags 必须是数组")
    return data

这段代码没有把 Schema 当成“永远正确”的证明。它只是让模型更容易稳定地产生目标形状；应用层仍要面对空响应、服务异常、客户端字段为空和业务规则不满足等情况。

旧参数、后端和提示词的三个误区

• 继续使用 guided_json：当前 vLLM 文档把它列为迁移项，新的请求应改为 structured_outputs 下的 json。不要同时混用两套字段，先统一请求形状。
• 把 Schema 当成业务校验：additionalProperties: false 可以限制额外字段，但不能判断工单编号是否存在，也不能替代权限检查。
• 只改提示词不改契约：提示词可以说明字段含义和填充方式，真正的字段、类型和枚举边界应写进 Schema；两者职责不同。

后端方面，官方文档说明 OpenAI 兼容服务默认支持结构化输出，并可以通过 --structured-outputs-config.backend 选择后端策略。刚开始接入时保持 auto 更容易减少额外配置，遇到特定 Schema 或后端差异时再单独调整。

小结：把生成约束和业务约束分成两层

最小接入路径可以归纳为三件事：启动 OpenAI 兼容服务；把 JSON Schema 放入 structured_outputs.json；在应用层解析响应并继续做业务校验。这样即使下游字段变化，也能快速判断是 Schema、模型响应还是业务代码需要修改。

常见问题

vLLM 的结构化输出只能返回对象吗？

不只能返回对象。官方接口还支持选择值、正则和语法等结构化方式；本文选择 JSON Schema，是因为工单这类结果通常需要多个有类型字段。

用了 JSON Schema 还需要 json.loads 吗？

需要。结构化约束影响模型生成形状，但客户端收到的 message.content 仍通常是文本字符串，应用要先解析它，再进入自己的字段和业务检查。