文档导航

Schema 驱动的决策

把一份 JSON schema 或一个 pydantic 模型变成 Laya 问题,拿回带校准置信度的类型化值。正是这座桥 让 Laya 成为一个结构化输出引擎:你描述想要的形状,Laya 在一次前向传播里给出答案。

import laya

schema = {
    "type": "object",
    "properties": {
        "department": {"type": "string", "enum": ["billing", "support", "sales"],
                       "description": "Which team should handle this?"},
        "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
        "needs_human": {"type": "boolean"},
    },
}

agent = laya.load("convaiinnovations/laya")
values = agent.decide("I was charged twice, refund me.", schema=schema)
# {"department": "billing", "urgency": 2, "needs_human": True}

用 pydantic(安装 laya[structured]):

from typing import Literal
from pydantic import BaseModel

class Ticket(BaseModel):
    department: Literal["billing", "support", "sales"]
    urgency: Literal[0, 1, 2]
    needs_human: bool

ticket = agent.decide("I was charged twice, refund me.", schema=Ticket)

支持的子集

顶层必须是一个带 properties 的对象。每个属性变成一个 Laya 问题。

下面每一行都是真实的 schema:tests/test_structured_docs.py 编译第一列,并断言编译器实际产出的 问题,所以这张表不会和代码脱节。一个单元格要么是单独的属性 schema,要么在那一行需要它的 $defs 时是一个完整的 schema(字段名为 field),要么是对某个入口点的调用。

JSON schema Laya 问题 返回的值
{"enum": ["billing", "support"]} choice 被选中的值,保留它原本的类型
{"const": "billing"} choice 那一个值
{"type": "boolean"} noul true / false
{"type": "integer", "minimum": 0, "maximum": 5} score 概率最高的档位,作为一个整数
{"type": "number", "minimum": 0, "maximum": 5} score 那个档位,作为一个整数
{"type": "string", "enum": ["low", "high"], "description": "How urgent?"} choice How urgent? 就是问题措辞
{"anyOf": [{"enum": ["x", "y"]}, {"type": "null"}]} choice 和普通的 enum 行一样;没有答案时这个键不出现
{"oneOf": [{"type": "boolean"}, {"type": "null"}]} noul 和普通的 boolean 行一样
{"type": ["integer", "null"], "minimum": 1, "maximum": 3} score 和普通的带界整数行一样
{"properties": {"field": {"$ref": "#/$defs/Dept"}}, "$defs": {"Dept": {"enum": ["billing", "support"]}}} choice 和普通的 enum 行一样;一个本地 $ref 会按它指名的定义来规划
{"allOf": [{"enum": ["x", "y"]}]} choice 和普通的 enum 行一样;pydantic v1 给一个带描述的 $ref 套上的单元素包装

Literal[...] 和 Optional[...] 是 pydantic 里对应 enum 和 anyOf 两行的写法: questions_from_pydantic 把它们渲染成那些形状,同样的行适用。一个 Enum 字段(包括 str/int 混入和 IntEnum)对应的是 $ref 那一行,而那一行需要展示整个 schema:pydantic 把成员放进 $defs,并让属性指向它们,所以 Optional[Dept] 是一个套在那个 $ref 外面的 anyOf。

title 不会被读取。pydantic 不管你有没有要求,都会给 model_json_schema() 的每个字段放上 一个,而一个按属性的名字没法给一个问题所据以构建的那些逐选项 choice 打标签,所以措辞的杠杆是 description —— 见下面的它内部如何映射。

投影是精确的:enum: [1, 2, 3] 返回 2,不是 "2";带界整数返回 minimum 和 maximum 之间的一个档位;布尔值就是 noul >= 0.5。

拒绝

一个无法从固定选项集作答的 schema 会抛出 laya.structured.SchemaError(一个 ValueError), 并点出确切的路径。每一行也都会被执行,字段名取 name:

属性 schema 消息
{"type": "string"} properties.name: a free string cannot be a fixed option set; use 'enum' or a boolean
{"type": "array", "items": {"type": "string"}} properties.name: arrays are not supported; ask one field per element
{"type": "object", "properties": {"inner": {"type": "boolean"}}} properties.name: nested objects are not supported; flatten the schema
{"$ref": "#/definitions/node"} properties.name: $ref '#/definitions/node' does not resolve to an entry of this schema's '$defs' or 'definitions'
{"enum": [1, "1"]} properties.name: enum values produce duplicate choice labels
{"enum": []} properties.name: 'enum' must not be empty
{"type": "number"} properties.name: a numeric field needs integer 'minimum' and 'maximum' to become a score
{"type": "integer", "minimum": 5, "maximum": 2} properties.name: 'maximum' 2 is below 'minimum' 5
{"type": "integer", "minimum": 0, "maximum": 10} properties.name: 11 levels exceeds MAX_SCORE_LEVELS=10; narrow the range or use an enum
{"anyOf": [{"type": "string"}, {"type": "integer"}]} properties.name: only 'Optional[...]' unions (one non-null branch) are supported, got 2
{"type": ["string", "integer"]} properties.name: 'type' has multiple non-null types; unions are not supported
{"format": "date"} properties.name: unsupported schema {'format': 'date'}
"boolean" properties.name: property must be an object, got str

入口点自身会拒绝这些;最后一行需要一个完整的 schema,因为一个 $ref 环会穿过它的 $defs:

调用 消息
plan_from_json_schema("not a schema") expected a JSON schema object, got str
plan_from_json_schema({"type": "object"}) the top level must be an object with 'properties'
plan_from_json_schema({"type": "object", "properties": {}}) 'properties' must be a non-empty object
plan_from_json_schema({"type": "object", "properties": {"p%d" % i: {"type": "boolean"} for i in range(33)}}) 33 properties exceeds MAX_PROPERTIES=32
plan_from_json_schema({"type": "object", "properties": {"name": {"enum": ["v%d" % i for i in range(33)]}}}) properties.name: 33 options exceeds MAX_OPTIONS=32
decide(None, "I was charged twice.", schema=42) expected a JSON schema dict or a pydantic model, got int
plan_from_json_schema({"type": "object", "properties": {"name": {"$ref": "#/$defs/Loop"}}, "$defs": {"Loop": {"$ref": "#/$defs/Loop"}}}) properties.name: $ref '#/$defs/Loop' is recursive; flatten the schema

限制:MAX_PROPERTIES = 32、MAX_OPTIONS = 32、MAX_SCORE_LEVELS = 10。

API

函数 用途
laya.decide(runner, state, schema=..., *, questions=..., return_details=..., min_confidence=..., **predict_kwargs) 自由函数,对 Agent 和 Router 都适用
agent.decide(state, schema=..., ...) / router.decide(state, schema=..., ...) 便捷方法
laya.decide_batch(runner, states, schema=..., ...) / agent.decide_batch(...) / router.decide_batch(...) 在多个状态上做同样的事,一次批调用
questions_from_json_schema(schema) schema 转成 Laya 问题
questions_from_pydantic(model) pydantic 模型转成问题(需要 pydantic)
answers_to_json(answers, schema) 把原始答案投影到 schema 的值上
answer_to_pydantic(model, answers) 把原始答案投影成一个 pydantic 实例
plan_from_json_schema(schema) 经过校验的字段计划(进阶)

schema 和 questions 只能传其中一个。传 questions 时,decide 返回原始答案而不是做投影。 额外的关键字参数会转发给 predict,所以钩子、model=、task= 和 token 预算都能用:

router.decide(state, schema=Ticket, model="multilingual", hooks=[Metrics()])

给多个状态打分

decide_batch 是吞吐的形式:schema 只规划一次,它的问题通过 predict_batch 在每一个状态上跑, 于是多个状态共享前向传播,而不是每次调用一次。结果按输入顺序返回,投影方式和 decide 完全一样, 而 return_details=True 会给每个状态一个 DecisionResult:

values = agent.decide_batch(ticket_texts, schema=Ticket)          # values[i] matches ticket_texts[i]
results = router.decide_batch(states, schema=Ticket, return_details=True, batch_size=64)

在 Router 上,每个状态仍然各自路由,所以一次调用可以横跨多个 checkpoint。关键字参数会到达 predict_batch,所以 batch_size=、model= 和钩子都和 decide 一样能用。Agent、ONNXAgent 和 Router 都有它;没有 predict_batch 的 runner 会抛 TypeError,而不是静默回退成一个循环 —— 那种情况就逐状态调用 decide。批处理会像 predict_batch 那样让临界 argmax 发生偏移;README 记录了两种设备上实测的加速。

置信度和概率

默认 decide 只返回值。传 return_details=True 得到一个 DecisionResult,带逐字段的置信度、 概率、原始答案,以及这次调用的 usage 和路由:

result = agent.decide(state, schema=Ticket, return_details=True)
result.values["department"]            # "billing"
result.answer_confidence["department"] # 0.94  max(p): the quantity min_confidence gates on
result.confidence["department"]        # 0.79  1 - H(p)/log(k) on this 3-option `choice` field
result.probabilities["department"]     # {"billing": 0.94, "support": 0.06, "sales": 0.0}
result.usage                           # {"input_tokens": ..., "output_tokens": 0,
                                       #  "state_tokens": ..., "state_tokens_dropped": ...,
                                       #  "truncated": ..., "truncated_questions": [...]}
result.routing                         # the Router decision, when a Router answered

usage 是 predict() 构建出来的那个块,原样转发:input_tokens 把一个 state 上每个问题各一行的量加总,而 output_tokens 永远是 0,因为什么都不生成;其余四个键是截断报告(#174)—— state_tokens 是整个序列化 state 所需的量,state_tokens_dropped 则是任何单个问题的 head 所放弃的最大量,truncated / truncated_questions 则说明是哪一个。第七个键 options,只在 head 预算让某个问题的选项共享了一段 token 范围(#538)时才出现;docs/http-api.md 把这个块和那个字段都记录为响应键,而 tests/test_structured_docs.py 把这一页的清单钉在构建它的代码上。

confidence 和 answer_confidence 是两个不同的量,名字本身就说明了各自的定义。 answer_confidence 是 max(p),即报告出来的那个答案所分到的概率质量。它正是温度缩放所拟合的 东西,是本仓库里每一个校准数字所据以计算的东西,也是 min_confidence 所比较的对象 —— 这正是 该对它、而不是对 confidence 做门控的原因。confidence 不止一个公式。在 choice 或 score 上它是归一化熵,1 - H(p) / log(k),其刻度随问题当时有多少个选项而变。在 noul 上它是 max(p_true, 1 - p_true),即被报告的那一侧的概率,在只有两个选项时就是 max(p)。 tests/test_confidence.py 固定了一个两选项分布在一个 noul 上返回 0.90、在一个等价的 choice 上返回 0.53;0.53 正是熵在 k = 2 时给出的值,所以那个 0.90 是第二个公式,而不是第一个公式在 更小选项数下的结果。上面的 schema 两者兼有 —— department 是 choice,needs_human 是 noul —— 所以一个 DecisionResult.confidence 字典可以同时装两种刻度,这正是两种读法都不能拿去 和某个你没按类型实测过的阈值比较的原因。一个没有报告出可用 answer_confidence 的字段会映射到 None,这和报告出一个 0.0 不是一回事。

门控要和门控本身所用的量一致:

if result.answer_confidence["department"] < 0.6:
    result.values["department"] = "human-review"

answer_confidence 适合用来筛选,这不等于它就是一个可信的概率。把它读作「在 c 处返回的答案里 约有 c 的比例是对的」,只有在温度已经拟合、并且针对该 checkpoint 和问题形状在留出数据上验证过 之后才成立。随包发布的 checkpoint 按发布状态看是过度自信的,而 laya-multilingual 干脆没有自带 任何已拟合的温度 —— 见 README 的 校准 和 诚实的限制 两节,以及 微调 notebook 里的拟合循环。在依赖这个级别之前先拟合;报告它,是因为门控和评估 harness 用的都是它。

它内部如何映射

  • Enum 和 Literal 变成 choice 问题,值作为字符串标签;标签在返回时映射回原来的值,所以整数 仍然是整数。
  • 带界整数变成一个 score 问题,每个值一个档位;返回的值是 minimum + argmax。
  • 布尔值变成一个 noul 问题;值为 noul >= 0.5。
  • description 变成问题的指令,所以一个好的描述正是决策准确的原因。这遵循与钩子指南 相同的规则:把每个选项的含义说清楚。
  • 一个本地 $ref(#/$defs/... 或 #/definitions/...)在字段被规划之前会被替换成它指名的 定义,所以一个 pydantic Enum 问的正是对应的 Literal 所问的问题,并投影到成员的值上,而 answer_to_pydantic 会把它变回那个成员。属性自己的键叠在上面,而定义的 description 被丢弃: pydantic 会从枚举的 docstring 填充它(pydantic v1 在没有时会填 “An enumeration.”),它描述的 是类型而不是问题,所以措辞仍然是该字段的 description。指向另一份文档的 ref、缺失的条目或一个 环都会抛错,而指向一个模型的 ref 是一个嵌套对象。
  • null 分支在字段被规划之前就被丢掉,所以 Optional[X] 问的正是 X 问的问题。没有答案时,该 字段的键就直接从值里缺席,这正是能安全地把一个字段声明为可选、又不改变模型所见内容的原因。

另见