Skip to content

通用决策接口 ​

提供面向分类 / 判定 / 评分的结构化决策接口,兼容 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

请求参数 ​

参数名类型是否必须描述
modelstring是模型名称,固定为 ecnu-decision,详见 模型列表
statestring / object是待判断的材料:字符串,或任意结构化 JSON 对象;不能为 null
questionsobject是问题字典,1~64 项。键为自定义的问题 ID,会原样出现在响应中
imagesarray[string]否图片数组,元素为完整的 base64 Data URI,支持 data:image/png、data:image/jpeg、data:image/jpg、data:image/webp
instructionsstring否根级说明。当前不会转发给模型,只在响应 gateway.warnings 中提示已移除;判断要求请写在每道题的 instructions 里

未声明的顶层字段会被直接拒绝(422 Extra inputs are not permitted),不会静默透传。

问题结构 ​

questions 的每个值是一个问题对象:

字段类型是否必须描述
typestring是题型,choice / noul / score
instructionsstring是该题的判断要求,随题发给模型
criteria依题型依题型见下方各题型说明
allow_nonebool否本接口不支持该字段,传入返回 400

choice:分类选择 ​

criteria 必须是非空对象:键是标签 ID(响应里原样回传),值是标签的自然语言描述。

json
{
  "route": {
    "type": "choice",
    "instructions": "应该转到哪个业务?",
    "criteria": {
      "card": "校园卡业务",
      "network": "校园网络业务",
      "logistics": "后勤维修"
    }
  }
}

noul:是否成立 ​

type 的取值是 noul,不是 bool。

criteria 可以省略;如果提供,必须是包含 true 和 false 两个键的对象,作为两个方向的口径说明:

json
{
  "ok": {
    "type": "noul",
    "instructions": "该申请是否符合要求",
    "criteria": {
      "true": "材料齐全且在有效期内",
      "false": "材料缺失或已过期"
    }
  }
}

写成 {"符合": "...", "不符合": "..."} 这类自定义键会返回 400:noul criteria must be an object with true and false。

score:有序评分 ​

criteria 必须是 2~10 项的有序数组,索引 0 为最低档。

json
{
  "urgent": {
    "type": "score",
    "instructions": "评价问题的紧急程度",
    "criteria": ["不紧急", "一般", "紧急", "非常紧急"]
  }
}

返回参数 ​

参数名类型描述
idstring本次请求 ID,形如 decision-86ce0f301c6d823f
objectstring固定为 structured_decision
createdint请求时间,Unix 秒
modelstring后端实际模型名,当前为 vllm-sr/d3-flash;与请求时的 model 不同,请勿用它判断模型
answersobject结果字典,键与请求的 questions 完全一致
answers.{qid}.typestring题型,与请求一致
usage.input_tokensint输入 token 消耗
usage.output_tokensint输出 token 消耗,当前恒为 0(不生成文本)
diagnosticsobject每题的诊断信息,见下
diagnostics.{qid}.label_massfloat命中标签的概率质量,正常为 1.0
diagnostics.{qid}.argmax_is_labelbool最高概率项是否为合法标签
jointnull多题联合结果,当前恒为 null
gatewayobject网关信息,见下
gateway.backendstring后端类型,固定 d3
gateway.requested_modelstring请求的公开模型名,即 ecnu-decision
gateway.actual_modelstring实际执行模型
gateway.upstream_latency_msfloat上游推理耗时(毫秒)
gateway.confidence_semanticsstring置信度口径,固定 maximum_class_probability
gateway.retry_attemptedbool网关是否重试过
gateway.warningsarray[string]警告信息,如根级 instructions 被移除

各题型的返回字段 ​

choice

字段类型描述
choicestring概率最高的标签 ID,即 criteria 的键
probabilitiesobject每个标签一个概率,键为标签 ID,总和为 1
confidencefloat最大类别概率,等于 max(probabilities)

noul

字段类型描述
noulfloat判定成立的把握,等于 probabilities.yes
probabilities.yesfloat成立的概率
probabilities.nofloat不成立的概率
confidencefloatmax(yes, no)

score

字段类型描述
scorefloat期望档位,0 基:按各档概率对档位索引加权平均
legendobject档位索引到 criteria 原文的映射
probabilitiesobject键为档位索引字符串("0"、"1"…),总和为 1
confidencefloat最大类别概率

score 返回的是 0 基期望值。例如 criteria 为 ["不紧急","一般","紧急","非常紧急"]、返回 score: 2.126,含义是"介于紧急与非常紧急之间、偏向紧急";若要得到 1~4 分的直觉刻度,请自行 +1。

请求示例 ​

三种题型混批:

http
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": "该诉求是否属于后勤职责范围"
        }
    }
}

结构化材料 + 图片:

http
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": "图书馆"}
        }
    }
}

返回示例 ​

json
{
  "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 ​

bash
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 ​

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 ​

javascript
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 token400 ... 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 数组:

json
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "questions", "s"],
      "msg": "Value error, score criteria must contain 2 to 10 ordered items"
    }
  ]
}

进入后端后的业务错误使用 error + gateway 结构:

json
{
  "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 道题),指后端实现,不影响参数语义。