MLflow signature required 字段的输入收窄

如果一个 MLflow 模型的输入签名把很多字段都标成 required，调用方就不能随意删掉字段；但这不代表所有业务字段都必须长期绑定在模型接口上。收窄输入的关键，是把稳定、不可缺少的字段设为必填，把追踪号、实验标签等可缺省字段明确建模为 optional。

官方地址：https://mlflow.org/docs/latest/model/signatures/

先看输入 schema，而不是先改请求体：required 决定缺字段是否失败，optional 决定字段能否省略。需要稳定兼容时优先显式写 Schema；依赖自动推断时，input_example 必须覆盖真实的缺省场景。

下面只讨论输入签名的字段边界，不延伸到模型效果、部署平台选型或提示词设计。

先分清 required 字段和 optional 字段

MLflow Model Signature 可以描述输入、输出和推理参数。对列式输入来说，ColSpec 的字段名、数据类型和 required 属性共同构成调用契约：缺少必填字段属于输入不符合签名；可选字段可以省略。额外字段是否被传入模型则不应被当作“自动扩展接口”的依据，接口仍应以签名中声明的字段为准。

因此，遇到“请求明明有数据却被拒绝”的问题，先检查三件事：字段名是否一致、类型是否能安全转换、是否漏掉了签名中的 required 字段。只把请求 JSON 补得更大，不能解决必填边界设计不合理的问题。

用显式 Schema 把必填范围收窄

当模型真正依赖的是用户输入和租户标识时，最稳妥的做法是手工声明输入 Schema。下面把 prompt 和 tenant_id 设为稳定输入，把 trace_id 设为可选字段；示例用于说明签名定义，不在本机执行。

import mlflow
from mlflow.models import ModelSignature
from mlflow.types import Schema, ColSpec

# 只把模型预测必需的字段设为 required，避免把追踪信息绑死在接口上。
input_schema = Schema([
    ColSpec("string", "prompt"),
    ColSpec("string", "tenant_id"),
    ColSpec("string", "trace_id", required=False),
])

# 输出字段按模型实际返回值声明；这里用一个简化的文本结果表示。
output_schema = Schema([ColSpec("string", "prediction")])
signature = ModelSignature(inputs=input_schema, outputs=output_schema)

# 记录模型时传入 signature，调用方就以这份输入契约为准。
mlflow.pyfunc.log_model(
    name="text-router",
    python_model=model,
    signature=signature,
)

这段设计的重点不是字段数量少，而是责任清楚：prompt 和 tenant_id 缺失时应直接暴露契约错误；trace_id 只用于链路关联时，不应因为某个完整样例出现过它，就自动变成模型必需输入。

让 input_example 反映真实的缺省场景

如果不手工传入签名，MLflow 可以根据 input_example 推断输入结构。问题在于：样例越“完整”，越容易把临时字段误示为所有请求都必须携带。对于允许缺省的字段，应让样例表达这种事实，而不是只放一条字段齐全的记录。

import mlflow
from mlflow.models import infer_signature

# 一条请求带链路号，另一条请求缺省链路号，样例表达真实兼容范围。
examples = [
    {"prompt": "摘要这段文本", "tenant_id": "team-a", "trace_id": "t-001"},
    {"prompt": "分类这段文本", "tenant_id": "team-a", "trace_id": None},
]

# 用真实预测结果推断输出；不要用与输入契约无关的字段填充样例。
predictions = ["摘要结果", "分类结果"]
signature = infer_signature(examples, predictions)

# 记录模型时提供 input_example，方便文档和服务请求复用同一输入形状。
mlflow.pyfunc.log_model(
    name="text-router",
    python_model=model,
    input_example=examples,
    signature=signature,
)

自动推断适合快速建立接口，但仍要回头查看签名结果：样例中的字段名、空值和数据类型都会影响契约。若字段是否必填是产品接口决策，显式 Schema 更适合长期维护；若只是试验阶段，真实的多条样例可以减少误判。

按收窄后的契约发送请求

签名收窄后，请求体只需要提交必填字段；可选字段有值时再附带。以 MLflow 服务常见的 inputs 包装为例：

# 只提交签名要求的两个必填字段，trace_id 可以省略。
curl -X POST http://127.0.0.1:5000/invocations \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"prompt":"摘要这段文本","tenant_id":"team-a"}}'

# 如果需要链路追踪，再补充已经声明为 optional 的字段。
curl -X POST http://127.0.0.1:5000/invocations \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"prompt":"摘要这段文本","tenant_id":"team-a","trace_id":"t-001"}}'

如果省略了 prompt 或 tenant_id，应该得到清晰的输入签名错误；如果只是省略 trace_id，则不应把它当作请求失败。这个区分能让调用方知道该修正业务数据，还是仅仅减少一项可选元数据。

四个容易把输入契约写窄的误区

• 把 input_example 当成接口全量字段表：完整样例只代表一个样本，不一定代表每次调用都要带齐所有字段。
• 只改请求，不改 signature：请求少字段时仍失败，说明真正的边界还在签名中。
• 混淆输入、输出和参数：输出字段缺失是另一类问题，不能用输入字段的 required 设置解决。
• 把额外字段当作兼容方案：兼容字段应在 schema 中明确声明为 optional，不能依赖未声明字段碰巧被接受。

相关问题

required=False 和传入 None 是一回事吗？

不是。前者表达字段可以缺省；传入 None 还涉及字段类型是否允许空值，以及具体输入格式能否被模型处理。要兼容“字段不存在”和“字段存在但为空”，应分别在样例、Schema 和模型逻辑中说明。

什么时候应该放弃自动推断？

当接口字段是否必填是明确的产品约束，或者样例包含很多实验字段时，改用显式 Schema 更容易审查和维护。自动推断适合快速起步，但不能替代接口边界决策。

收窄 MLflow signature 的顺序可以固定为：先列出模型真正依赖的字段，再决定哪些字段可缺省，最后让 Schema、input_example 和请求体保持同一套命名与类型。这样，required 不再是自动推断留下的意外限制，而是可解释、可维护的接口设计。