# Laya 结构化决策

> 通用

提交一次 Laya 结构化决策请求。`model` 为平台模型名（`laya`，或指定 checkpoint 的
`laya-english` / `laya-multilingual` / `laya-typed-decisions`），用于选路；
`state` 为待分析内容，`questions` 为题目集合。
每道题按 `type` 返回对应的结构化答案，一次性返回，非流式。

## 请求地址

`POST https://api.modelverse.cn/v1/systemone`

## 请求体

## 响应

- **200** — Laya 结构化决策结果（`x_` 前缀为扩展字段）。
- **default** — 错误响应（网关侧参数/鉴权错误或上游非 200）。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Laya 结构化决策接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **Laya（System One 结构化决策模型）** 的接口文档。\n统一入口 `POST /v1/systemone`，通过请求体中的 `model` 字段选路（`laya` 及 `laya-*` checkpoint 名）。\n请求字段与 Jev 协议一致；响应遵循 System One 协议，并以 `x_` 前缀附带 Laya 扩展信息。响应为非流式，一次性返回 JSON。\n\nLaya 不是聊天模型：你给它一段 `state`（待分析的文本/结构化数据）和一组 `questions`（每题声明\n`type`/`instructions`/`criteria`），它在一次前向中对每道题返回一个类型安全的结构化答案（`noul` 概率、\n`choice` 选项、`score` 分级），不生成自由文本。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "System One",
      "description": "Laya 结构化决策。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/systemone": {
      "post": {
        "tags": [
          "System One"
        ],
        "operationId": "createLayaSystemOneDecision",
        "summary": "Laya 结构化决策",
        "description": "提交一次 Laya 结构化决策请求。`model` 为平台模型名（`laya`，或指定 checkpoint 的\n`laya-english` / `laya-multilingual` / `laya-typed-decisions`），用于选路；\n`state` 为待分析内容，`questions` 为题目集合。\n每道题按 `type` 返回对应的结构化答案，一次性返回，非流式。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemOneRequest"
              },
              "examples": {
                "customerTicket": {
                  "summary": "对一条客服工单同时做三类判定（自动路由到多语言 checkpoint）",
                  "value": {
                    "model": "laya",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "客户是否在要求退款？"
                      },
                      "queue": {
                        "type": "choice",
                        "instructions": "这条工单应转给哪个队列？",
                        "criteria": {
                          "billing": "账单部门",
                          "technical": "技术支持",
                          "sales": "销售团队"
                        }
                      },
                      "urgency": {
                        "type": "score",
                        "instructions": "该问题的紧急程度？",
                        "criteria": [
                          "可以等一周",
                          "本周内处理",
                          "今天就得回复"
                        ]
                      }
                    }
                  }
                },
                "noulOnly": {
                  "summary": "仅做一个 noul（是否要退款）判定",
                  "value": {
                    "model": "laya",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "客户是否在要求退款？"
                      }
                    }
                  }
                },
                "choiceOnly": {
                  "summary": "仅做一个 choice（转派队列）判定",
                  "value": {
                    "model": "laya",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "queue": {
                        "type": "choice",
                        "instructions": "这条工单应转给哪个队列？",
                        "criteria": {
                          "billing": "账单部门",
                          "technical": "技术支持",
                          "sales": "销售团队"
                        }
                      }
                    }
                  }
                },
                "scoreOnly": {
                  "summary": "仅做一个 score（紧急程度）判定",
                  "value": {
                    "model": "laya",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "urgency": {
                        "type": "score",
                        "instructions": "该问题的紧急程度？",
                        "criteria": [
                          "可以等一周",
                          "本周内处理",
                          "今天就得回复"
                        ]
                      }
                    }
                  }
                },
                "structuredStateEnglish": {
                  "summary": "state 为 JSON 对象、指定英文 checkpoint、noul 带 true/false 语义",
                  "value": {
                    "model": "laya-english",
                    "state": {
                      "subject": "Server down",
                      "body": "prod API returns 500 since 9am"
                    },
                    "questions": {
                      "is_outage": {
                        "type": "noul",
                        "instructions": "Is this an outage?",
                        "criteria": {
                          "true": "service unavailable",
                          "false": "not an availability issue"
                        }
                      },
                      "severity": {
                        "type": "score",
                        "instructions": "How severe is this?",
                        "criteria": [
                          "low",
                          "medium",
                          "high"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Laya 结构化决策结果（`x_` 前缀为扩展字段）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneResponse"
                },
                "examples": {
                  "decision": {
                    "summary": "三道题的结构化答案 + 用量（真实返回）",
                    "value": {
                      "id": "gen-dec-1789972637-oljFHZz1M-dMxKNtCqDb",
                      "model": "laya-multilingual",
                      "provider": "Laya",
                      "answers": {
                        "wants_refund": {
                          "type": "noul",
                          "noul": 0.9943,
                          "x_confidence": 0.9943,
                          "x_act_probability": 1
                        },
                        "queue": {
                          "type": "choice",
                          "choice": "billing",
                          "confidence": 0.9782,
                          "probabilities": {
                            "billing": 0.9965,
                            "technical": 0.0002,
                            "sales": 0.0033
                          },
                          "x_act_probability": 1
                        },
                        "urgency": {
                          "type": "score",
                          "score": 2,
                          "confidence": 0.5997,
                          "legend": {
                            "0": "可以等一周",
                            "1": "本周内处理",
                            "2": "今天就得回复"
                          },
                          "probabilities": {
                            "0": 0.0166,
                            "1": 0.1152,
                            "2": 0.8682
                          },
                          "x_expected_score": 1.8516,
                          "x_argmax_score": 2,
                          "x_act_probability": 1
                        }
                      },
                      "usage": {
                        "input_tokens": 171,
                        "output_tokens": 0,
                        "cost": 0
                      },
                      "u_trace_id": "41c727bf-0f68-438b-b9e9-c60236b54291",
                      "x_routing": {
                        "requested_model": "laya",
                        "checkpoint": "multilingual",
                        "reason": "non-Latin script (han, 100% of letters); the English checkpoint cannot read it",
                        "workflow": null
                      },
                      "x_latency_ms": 230,
                      "x_request_id": "req-b8689788276345ca"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应（网关侧参数/鉴权错误或上游非 200）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/SystemOneError"
                  },
                  "modelNotFound": {
                    "$ref": "#/components/examples/ModelNotFound"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "平台下发的 API Key，通过 `Authorization: Bearer <API Key>` 传入。"
      }
    },
    "schemas": {
      "SystemOneRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "state",
          "questions"
        ],
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "laya",
              "laya-english",
              "laya-multilingual",
              "laya-typed-decisions"
            ],
            "description": "平台模型名，用于选路。`laya` 按 state 的语言/文字自动选择 checkpoint（推荐）；\n`laya-english` 英文（512 token 上下文）；`laya-multilingual` 100+ 语言含中文（1024 token）；\n`laya-typed-decisions` 类型化决策工作流（1024 token）。不区分大小写。\n",
            "examples": [
              "laya"
            ]
          },
          "state": {
            "description": "待分析的内容，可为字符串、JSON 对象或数组。对象/数组会被序列化为 JSON 文本输入模型；超过上下文长度的部分从右侧截断。",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              },
              {
                "type": "array",
                "items": {},
                "title": "array"
              }
            ]
          },
          "questions": {
            "type": "object",
            "minProperties": 1,
            "description": "题目集合，key 为题目 ID，value 为题目对象。所有题目在一次前向中并行作答，建议合并到一次请求。",
            "additionalProperties": {
              "$ref": "#/components/schemas/Question"
            }
          }
        }
      },
      "Question": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "instructions"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "noul",
              "choice",
              "score"
            ],
            "description": "题型：\n- `noul`：返回 0~1 概率；`criteria` 可选（`{true, false}` 语义描述）。\n- `choice`：从若干选项中选一个；`criteria` 必填，为「选项名→描述」映射。协议上限 255 个选项，\n  Laya 受 192 token 选项预算限制，实际约 20~60 个，超限返回 `criteria_too_long`。\n- `score`：分级打分；`criteria` 必填，为从低到高有序的等级描述数组。\n"
          },
          "instructions": {
            "type": "string",
            "description": "评估说明，描述这道题要判断什么。"
          },
          "criteria": {
            "description": "判定标准，形态随 `type` 而定：`choice` 为对象（选项名→描述），`score` 为字符串数组（有序等级），\n`noul` 可为对象（仅允许 `true`/`false` 两个 key）或省略。非字符串的描述值会被序列化为 JSON。\n",
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "title": "object"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "title": "array"
              }
            ]
          }
        }
      },
      "SystemOneResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "description": "决策 ID（`gen-dec-` 前缀）。"
          },
          "model": {
            "type": "string",
            "enum": [
              "laya-english",
              "laya-multilingual",
              "laya-typed-decisions"
            ],
            "description": "实际作答的 checkpoint。"
          },
          "provider": {
            "type": "string",
            "const": "Laya",
            "description": "上游 provider，固定为 `Laya`。"
          },
          "answers": {
            "type": "object",
            "description": "每道题的结构化答案，key 与请求 `questions` 一致。",
            "additionalProperties": {
              "$ref": "#/components/schemas/Answer"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "u_trace_id": {
            "type": "string",
            "description": "平台注入的 trace ID，用于按平台 trace 反查。"
          },
          "x_routing": {
            "$ref": "#/components/schemas/Routing"
          },
          "x_latency_ms": {
            "type": "integer",
            "description": "扩展：模型推理耗时（毫秒）。"
          },
          "x_request_id": {
            "type": "string",
            "description": "扩展：服务端请求 ID，与错误响应 `error.param` 同源。"
          }
        }
      },
      "Routing": {
        "type": "object",
        "description": "扩展：自动路由决策。",
        "properties": {
          "requested_model": {
            "type": "string",
            "description": "请求中的 `model` 值。"
          },
          "checkpoint": {
            "type": "string",
            "enum": [
              "english",
              "multilingual",
              "typed-decisions"
            ],
            "description": "实际选用的 checkpoint。"
          },
          "reason": {
            "type": "string",
            "description": "路由原因，如 `non-Latin script (han, 100% of letters); the English checkpoint cannot read it`、`English Latin text`、`explicit model='multilingual'`。"
          },
          "workflow": {
            "type": [
              "string",
              "null"
            ],
            "description": "匹配到的 typed-decisions 工作流名，未匹配为 null。"
          }
        }
      },
      "Answer": {
        "description": "结构化答案，字段随 `type` 而定（`noul` / `choice` / `score`）。`x_` 前缀为扩展字段。",
        "oneOf": [
          {
            "$ref": "#/components/schemas/NoulAnswer"
          },
          {
            "$ref": "#/components/schemas/ChoiceAnswer"
          },
          {
            "$ref": "#/components/schemas/ScoreAnswer"
          }
        ]
      },
      "NoulAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "noul"
          },
          "noul": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0~1 的概率信号（无单独 confidence 字段，概率本身即信号）。"
          },
          "x_confidence": {
            "type": "number",
            "description": "扩展：`max(noul, 1 - noul)`。"
          },
          "x_act_probability": {
            "type": "number",
            "description": "扩展：模型 act 头输出，当前恒为 1.0，可忽略。"
          }
        }
      },
      "ChoiceAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "choice"
          },
          "choice": {
            "type": "string",
            "description": "选中的选项名（对应请求 `criteria` 的 key，取概率最大项）。"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "置信度：归一化熵 `1 - H(p)/log(k)`，分布完全集中为 1，均匀分布为 0。"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "各选项的概率分布（softmax，四位小数）。"
          },
          "x_act_probability": {
            "type": "number",
            "description": "扩展：当前恒为 1.0，可忽略。"
          }
        }
      },
      "ScoreAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "score"
          },
          "score": {
            "type": "integer",
            "description": "选中的等级下标（从 0 开始，对应请求 `criteria` 数组，取概率最大项）。"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "置信度：归一化熵 `1 - H(p)/log(k)`。"
          },
          "legend": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "等级下标→等级描述的映射。"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "各等级的概率分布。"
          },
          "x_expected_score": {
            "type": "number",
            "description": "扩展：等级期望值 `Σ i·p(i)`，Laya 原生输出，适合需要连续分值的场景。"
          },
          "x_argmax_score": {
            "type": "integer",
            "description": "扩展：与 `score` 相同。"
          },
          "x_act_probability": {
            "type": "number",
            "description": "扩展：当前恒为 1.0，可忽略。"
          }
        }
      },
      "Usage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "输入 token 数。每道题独立成一条序列，`state` 按题目数重复计数。"
          },
          "output_tokens": {
            "type": "integer",
            "description": "输出 token 数，恒为 0（非生成模型）。"
          },
          "cost": {
            "type": "number",
            "description": "上游侧成本，恒为 0（自托管），平台计费以自有价目表为准。"
          }
        }
      },
      "SystemOneErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/SystemOneError"
          }
        }
      },
      "SystemOneError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "enum": [
              "invalid_request_error",
              "authentication_error",
              "server_error"
            ],
            "description": "错误类型。"
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_json",
              "missing_model",
              "model_not_found",
              "missing_state",
              "invalid_state",
              "invalid_questions",
              "invalid_question",
              "invalid_question_type",
              "missing_instructions",
              "invalid_criteria",
              "too_many_options",
              "criteria_too_long",
              "invalid_api_key",
              "model_loading",
              "gpu_oom",
              "internal_error"
            ],
            "description": "机器可读的错误码。"
          },
          "param": {
            "type": "string",
            "description": "请求 ID，用于反馈或排查错误原因。"
          }
        }
      }
    },
    "examples": {
      "SystemOneError": {
        "summary": "标准 JSON 错误响应",
        "value": {
          "error": {
            "message": "question 'queue': choice `criteria` must be a non-empty object {option: description}",
            "type": "invalid_request_error",
            "code": "invalid_criteria",
            "param": "req-fac9605f69d745ce"
          }
        }
      },
      "ModelNotFound": {
        "summary": "model 不是 laya 系列",
        "value": {
          "error": {
            "message": "unknown model 'jev-1.13.0'; supported: laya, laya-english, laya-multilingual, laya-typed-decisions",
            "type": "invalid_request_error",
            "code": "model_not_found",
            "param": "req-dd569f9b15c948ef"
          }
        }
      }
    }
  }
}
```