通用决策接口
提供面向分类 / 判定 / 评分的结构化决策接口,兼容 SystemOne 协议,底层为 vLLM 部署的 D3(d3-flash)。
调用方一次性提交材料(state)和若干道问题(questions),接口直接返回每道题的概率分布、胜出标签与置信度,不生成自然语言文本,因此不需要做输出解析。
- 单次请求最多可同时提交 64 道题,
choice(分类选择)、noul(是否成立)、score(有序评分)三种题型可以混批; - 材料支持纯文本、结构化 JSON,以及 PNG / JPEG / WebP 图片;
- 每道题都返回
confidence(最大类别概率),可直接用于阈值过滤; - 当前限时免费,调用不扣减 credits。
与"对话模型 + 结构化输出"相比,本接口不需要撰写提示词、也不需要解析 JSON:标签与档位由
criteria直接声明,返回的是每个选项的概率,而不只是一段文本。
请求方法
POST
请求地址
https://chat.ecnu.edu.cn/open/api/v1/systemone
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| model | string | 是 | 模型名称,固定为 ecnu-decision,详见 模型列表 |
| state | string / object | 是 | 待判断的材料:字符串,或任意结构化 JSON 对象;不能为 null |
| questions | object | 是 | 问题字典,1~64 项。键为自定义的问题 ID,会原样出现在响应中 |
| images | array[string] | 否 | 图片数组,元素为完整的 base64 Data URI,支持 data:image/png、data:image/jpeg、data:image/jpg、data:image/webp |
| instructions | string | 否 | 根级说明。当前不会转发给模型,只在响应 gateway.warnings 中提示已移除;判断要求请写在每道题的 instructions 里 |
未声明的顶层字段会被直接拒绝(
422 Extra inputs are not permitted),不会静默透传。
问题结构
questions 的每个值是一个问题对象:
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| type | string | 是 | 题型,choice / noul / score |
| instructions | string | 是 | 该题的判断要求,随题发给模型 |
| criteria | 依题型 | 依题型 | 见下方各题型说明 |
| allow_none | bool | 否 | 本接口不支持该字段,传入返回 400 |
choice:分类选择
criteria 必须是非空对象:键是标签 ID(响应里原样回传),值是标签的自然语言描述。
{
"route": {
"type": "choice",
"instructions": "应该转到哪个业务?",
"criteria": {
"card": "校园卡业务",
"network": "校园网络业务",
"logistics": "后勤维修"
}
}
}noul:是否成立
type 的取值是 noul,不是 bool。
criteria 可以省略;如果提供,必须是包含 true 和 false 两个键的对象,作为两个方向的口径说明:
{
"ok": {
"type": "noul",
"instructions": "该申请是否符合要求",
"criteria": {
"true": "材料齐全且在有效期内",
"false": "材料缺失或已过期"
}
}
}写成
{"符合": "...", "不符合": "..."}这类自定义键会返回400:noul criteria must be an object with true and false。
score:有序评分
criteria 必须是 2~10 项的有序数组,索引 0 为最低档。
{
"urgent": {
"type": "score",
"instructions": "评价问题的紧急程度",
"criteria": ["不紧急", "一般", "紧急", "非常紧急"]
}
}返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| id | string | 本次请求 ID,形如 decision-86ce0f301c6d823f |
| object | string | 固定为 structured_decision |
| created | int | 请求时间,Unix 秒 |
| model | string | 后端实际模型名,当前为 vllm-sr/d3-flash;与请求时的 model 不同,请勿用它判断模型 |
| answers | object | 结果字典,键与请求的 questions 完全一致 |
| answers.{qid}.type | string | 题型,与请求一致 |
| usage.input_tokens | int | 输入 token 消耗 |
| usage.output_tokens | int | 输出 token 消耗,当前恒为 0(不生成文本) |
| diagnostics | object | 每题的诊断信息,见下 |
| diagnostics.{qid}.label_mass | float | 命中标签的概率质量,正常为 1.0 |
| diagnostics.{qid}.argmax_is_label | bool | 最高概率项是否为合法标签 |
| joint | null | 多题联合结果,当前恒为 null |
| gateway | object | 网关信息,见下 |
| gateway.backend | string | 后端类型,固定 d3 |
| gateway.requested_model | string | 请求的公开模型名,即 ecnu-decision |
| gateway.actual_model | string | 实际执行模型 |
| gateway.upstream_latency_ms | float | 上游推理耗时(毫秒) |
| gateway.confidence_semantics | string | 置信度口径,固定 maximum_class_probability |
| gateway.retry_attempted | bool | 网关是否重试过 |
| gateway.warnings | array[string] | 警告信息,如根级 instructions 被移除 |
各题型的返回字段
choice
| 字段 | 类型 | 描述 |
|---|---|---|
| choice | string | 概率最高的标签 ID,即 criteria 的键 |
| probabilities | object | 每个标签一个概率,键为标签 ID,总和为 1 |
| confidence | float | 最大类别概率,等于 max(probabilities) |
noul
| 字段 | 类型 | 描述 |
|---|---|---|
| noul | float | 判定成立的把握,等于 probabilities.yes |
| probabilities.yes | float | 成立的概率 |
| probabilities.no | float | 不成立的概率 |
| confidence | float | max(yes, no) |
score
| 字段 | 类型 | 描述 |
|---|---|---|
| score | float | 期望档位,0 基:按各档概率对档位索引加权平均 |
| legend | object | 档位索引到 criteria 原文的映射 |
| probabilities | object | 键为档位索引字符串("0"、"1"…),总和为 1 |
| confidence | float | 最大类别概率 |
score返回的是 0 基期望值。例如criteria为["不紧急","一般","紧急","非常紧急"]、返回score: 2.126,含义是"介于紧急与非常紧急之间、偏向紧急";若要得到 1~4 分的直觉刻度,请自行+1。
请求示例
三种题型混批:
POST https://chat.ecnu.edu.cn/open/api/v1/systemone
Content-Type: application/json
Authorization: Bearer sk-UDK3*******************1Y
{
"model": "ecnu-decision",
"state": "学生反映宿舍空调不制冷,已报修三次未解决,希望尽快处理。",
"questions": {
"route": {
"type": "choice",
"instructions": "应该转到哪个业务?",
"criteria": {
"logistics": "后勤维修",
"card": "校园卡业务",
"network": "校园网络业务"
}
},
"urgent": {
"type": "score",
"instructions": "评价紧急程度",
"criteria": ["不紧急", "一般", "紧急", "非常紧急"]
},
"valid": {
"type": "noul",
"instructions": "该诉求是否属于后勤职责范围"
}
}
}结构化材料 + 图片:
POST https://chat.ecnu.edu.cn/open/api/v1/systemone
Content-Type: application/json
Authorization: Bearer sk-UDK3*******************1Y
{
"model": "ecnu-decision",
"state": {
"channel": "web",
"title": "校园卡遗失",
"body": "今天上午在图书馆丢失校园卡,需要挂失。"
},
"images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."],
"questions": {
"scene": {
"type": "choice",
"instructions": "识别图片中的场景",
"criteria": {"classroom": "教室", "library": "图书馆"}
}
}
}返回示例
{
"id": "decision-8b363dffe5dcf75f",
"object": "structured_decision",
"created": 1794119161,
"model": "vllm-sr/d3-flash",
"answers": {
"route": {
"type": "choice",
"choice": "logistics",
"probabilities": {
"logistics": 0.9992193186720891,
"card": 0.00023117074663604222,
"network": 0.0005495105812748063
},
"confidence": 0.9992193186720891
},
"urgent": {
"type": "score",
"score": 2.12643871463392,
"legend": {"0": "不紧急", "1": "一般", "2": "紧急", "3": "非常紧急"},
"probabilities": {
"0": 0.010908747444415013,
"1": 0.09332357218006254,
"2": 0.6541878986727099,
"3": 0.2415797817028125
},
"confidence": 0.6541878986727099
},
"valid": {
"type": "noul",
"noul": 0.9736546788144808,
"probabilities": {
"yes": 0.9736546788144808,
"no": 0.026345321185519244
},
"confidence": 0.9736546788144808
}
},
"usage": {"input_tokens": 345, "output_tokens": 0},
"diagnostics": {
"route": {"label_mass": 1.0, "argmax_is_label": true},
"urgent": {"label_mass": 1.0, "argmax_is_label": true},
"valid": {"label_mass": 1.0, "argmax_is_label": true}
},
"joint": null,
"gateway": {
"backend": "d3",
"requested_model": "ecnu-decision",
"actual_model": "vllm-sr/d3-flash",
"upstream_latency_ms": 82.94,
"confidence_semantics": "maximum_class_probability",
"retry_attempted": false,
"warnings": []
}
}代码示例
curl
curl 'https://chat.ecnu.edu.cn/open/api/v1/systemone' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
-d '{
"model": "ecnu-decision",
"state": "学生校园卡丢失,需要立即挂失。",
"questions": {
"route": {
"type": "choice",
"instructions": "应该转到哪个业务?",
"criteria": {"card": "校园卡业务", "network": "校园网络业务"}
}
}
}'python
import requests
url = "https://chat.ecnu.edu.cn/open/api/v1/systemone"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer your-api-key", # 替换为您的 API 密钥
}
data = {
"model": "ecnu-decision",
"state": "学生校园卡丢失,需要立即挂失。",
"questions": {
"route": {
"type": "choice",
"instructions": "应该转到哪个业务?",
"criteria": {"card": "校园卡业务", "network": "校园网络业务"},
}
},
}
resp = requests.post(url, headers=headers, json=data, timeout=180)
result = resp.json()
if resp.status_code == 200:
answer = result["answers"]["route"]
print(answer["choice"], answer["confidence"])
else:
print(resp.status_code, result)nodejs
const resp = await fetch("https://chat.ecnu.edu.cn/open/api/v1/systemone", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer your-api-key",
},
body: JSON.stringify({
model: "ecnu-decision",
state: "学生校园卡丢失,需要立即挂失。",
questions: {
route: {
type: "choice",
instructions: "应该转到哪个业务?",
criteria: { card: "校园卡业务", network: "校园网络业务" },
},
},
}),
});
const data = await resp.json();
if (resp.ok) {
console.log(data.answers.route.choice, data.answers.route.confidence);
} else {
console.error(resp.status, data);
}图片输入
- 使用完整 base64 Data URI,仅支持
png/jpeg/jpg/webp,其他格式(如gif)返回422; - 图片只通过
images传入,材料的文字说明写在state里; - 一次请求中的所有题目都会看到全部图片;
- 实测单请求 32 张可正常处理(
input_tokens随图片数量线性增长),建议按业务需要控制数量,避免触达上下文上限。
限制
| 项目 | 限制 | 超出表现 |
|---|---|---|
| 单请求问题数 | 最多 64 道 | 400 D3 单请求最多支持 64 道题 |
| 单题上下文长度 | max_model_len = 16384 token | 400 ... more than max_model_len=16384; nothing is truncated |
| 分类标签数量 | choice 实测 100 个标签正常 | — |
| 评分档位 | 2~10 项 | 422 score criteria must contain 2 to 10 ordered items |
| 超时 | Agent 180 秒 / Nginx 185 秒 | 504 |
上下文超限时不会静默截断,而是直接报错,请调用方自行裁剪材料后重试。实测约 8000 个中文字符对应 5000 余 token,接近上限时建议压缩
state。
错误返回
| HTTP 状态 | 含义 | 响应示例 |
|---|---|---|
400 | 参数组合不受支持、超出限制,或上游业务层拒绝 | {"detail":"D3 单请求最多支持 64 道题"} |
401 | 令牌缺失、无效或过期 | {"detail":"token 无效或已过期"} |
401 | 模型名称未登记,或未分配给该令牌 | {"detail":"获取第三方元数据失败"} |
403 | 未分配模型、scope 不足、应用已禁用或 IP 不在白名单 | 见后台配置 |
422 | 字段缺失、类型错误或取值越界 | {"detail":[{"type":"value_error","loc":["body","state"],"msg":"Value error, state must not be null"}]} |
429 | 达到并发或配额限制 | 见配额限制 |
502 | 上游服务不可用 | — |
504 | 上游处理超时 | — |
本接口的错误体有两种形状,网关前置校验(字段缺失、类型错误、越界)使用 detail 数组:
{
"detail": [
{
"type": "value_error",
"loc": ["body", "questions", "s"],
"msg": "Value error, score criteria must contain 2 to 10 ordered items"
}
]
}进入后端后的业务错误使用 error + gateway 结构:
{
"error": {
"message": "question 's': the prompt has 20659 tokens, more than max_model_len=16384; nothing is truncated",
"type": "BadRequestError",
"param": null,
"code": 400
},
"gateway": {"backend": "d3", "retry_attempted": false}
}建议客户端同时兼容 detail 与 error.message 两种取错误信息的方式。
注意事项
- 鉴权方式:请求头使用
Authorization: Bearer <令牌>,令牌在我的令牌页面获取;调用主体需已被分配ecnu-decision模型,否则返回401。 - 当前限时免费:
ecnu-decision限免期间调用不扣减 credits,但响应中的usage.input_tokens仍会返回,可用于观测与容量评估;后续计费方式以开放平台公告为准(见配额限制)。 - 置信度口径:
gateway.confidence_semantics = maximum_class_probability,即max(probabilities),可直接用于阈值过滤,不需要再做归一化; - 不接受推理扰动参数:
think_mode、think_budget、gate、mix、allow_none、none_check、return_details、return_thought、thought_generation(含题级allow_none)均返回400; - 不要用响应里的
model判断模型:它是后端实际模型名(vllm-sr/d3-flash),请以gateway.requested_model为准; - 决策调用无副作用,超时后可安全重发;但网关本身在超时后不会自动重试;
- 部分报错文案仍写作「D3」(如
D3 单请求最多支持 64 道题),指后端实现,不影响参数语义。