如何用inference-schema自动生成含可选输入的Azure ML端点Swagger文档？

我想在Azure机器学习部署时，通过inference-schema自动增强Swagger文档，添加模型可选输入、枚举示例等细节。目前使用input_schema装饰器传入包含枚举和必填字段的JSON Schema时，Swagger会将所有字段视为必填，比如下面的示例中input2是request_payload的可选字段，但自动生成的Swagger文档里它被标记为必填。

示例JSON Schema：

{
  "ServiceInput": {
    "type": "object",
    "properties": {
      "request_payload": {
        "type": "object",
        "required": [
          "input1",
          "requestTimestamp",
          "requestTimezone"
        ],
        "properties": {
          "input1": {
            "type": "integer",
            "format": "int64"
          },
          "input2": {
            "type": "integer",
            "format": "int64"
          },
          "requestTimestamp": {
            "type": "string"
          },
          "requestTimezone": {
            "type": "string"
          }
        }
      }
    },
    "example": {
      "request_payload": {
        "input1": 200,
        "requestTimestamp": "2023-05-05T12:12:12.000Z",
        "requestTimezone": "Europe/Berlin",
        "input2": 10
      }
    }
  }
}

我知道可以通过自定义Swagger规格部署，但希望通过inference-schema自动实现，省去手动编辑Swagger文档的步骤，求相关指导。

可以通过inference-schema的Python类型注解或专用Schema类来正确定义可选字段和枚举，确保Swagger文档能准确识别必填/可选属性，以下是具体实现方式：

1. 使用Python数据类+类型注解定义Schema #

inference-schema支持通过Python的dataclasses或pydantic模型来定义输入结构，这种方式能更精准地控制字段的必填性，同时自动生成正确的Swagger Schema。

示例代码：

from dataclasses import dataclass
from inference_schema.schema_decorators import input_schema

@dataclass
class RequestPayload:
    input1: int  # 必填字段（未指定默认值即为必填）
    requestTimestamp: str
    requestTimezone: str
    input2: int = None  # 可选字段（通过默认值标记）

@dataclass
class ServiceInput:
    request_payload: RequestPayload

# 装饰推理函数
@input_schema(input_type=ServiceInput)
def run(data):
    # 推理逻辑示例
    return {"result": data.request_payload.input1 + (data.request_payload.input2 or 0)}

这种方式下，input2因为有默认值None，会被inference-schema标记为可选字段，自动生成的Swagger文档会正确区分必填/可选属性。

2. 调整JSON Schema的传入方式 #

如果坚持使用JSON Schema传入，需要确保inference-schema能正确解析required数组。可尝试将嵌套的request_payload Schema单独定义，并用JsonSchema类包裹后传入顶层Schema：

from inference_schema.schema_decorators import input_schema
from inference_schema.parameter_types.json_schema import JsonSchema

request_payload_schema = {
    "type": "object",
    "required": ["input1", "requestTimestamp", "requestTimezone"],
    "properties": {
        "input1": {"type": "integer", "format": "int64"},
        "input2": {"type": "integer", "format": "int64"},
        "requestTimestamp": {"type": "string"},
        "requestTimezone": {"type": "string"}
    }
}

service_input_schema = {
    "type": "object",
    "properties": {
        "request_payload": JsonSchema(request_payload_schema)
    },
    "example": {
        "request_payload": {
            "input1": 200,
            "requestTimestamp": "2023-05-05T12:12:12.000Z",
            "requestTimezone": "Europe/Berlin",
            "input2": 10
        }
    }
}

@input_schema(input_type=JsonSchema(service_input_schema))
def run(data):
    # 推理逻辑示例
    return {"result": data["request_payload"]["input1"] + (data["request_payload"].get("input2") or 0)}

通过将嵌套Schema用JsonSchema类包裹，能让inference-schema正确识别required数组，从而在Swagger中标记input2为可选。

3. 添加枚举示例 #

要在Swagger中添加枚举字段，只需在Schema中定义enum属性即可，两种定义方式都支持：

数据类方式（结合Pydantic） #

from pydantic import BaseModel
from inference_schema.schema_decorators import input_schema

class RequestPayload(BaseModel):
    input1: int
    requestTimestamp: str
    requestTimezone: str
    input2: int | None = None
    status: str = "pending"  # 枚举字段
    class Config:
        schema_extra = {
            "enum": ["pending", "processing", "completed"]
        }

class ServiceInput(BaseModel):
    request_payload: RequestPayload

@input_schema(input_type=ServiceInput)
def run(data):
    # 推理逻辑示例
    return {"result": data.request_payload.input1 + (data.request_payload.input2 or 0)}

JSON Schema方式 #

request_payload_schema = {
    "type": "object",
    "required": ["input1", "requestTimestamp", "requestTimezone"],
    "properties": {
        "input1": {"type": "integer", "format": "int64"},
        "input2": {"type": "integer", "format": "int64"},
        "requestTimestamp": {"type": "string"},
        "requestTimezone": {"type": "string"},
        "status": {
            "type": "string",
            "enum": ["pending", "processing", "completed"],
            "example": "pending"
        }
    }
}

验证效果 #

部署服务后，访问Swagger UI对应的JSON文件（通常为http://<service-url>/swagger.json），检查request_payload的字段定义：

• 必填字段会出现在required数组中
• 可选字段不会出现在required数组里
• 枚举字段会显示完整的可选值列表

内容的提问来源于stack exchange，提问作者Nishikant Jain