StandardOne-3B-SH API 实战:/v1/systemone 请求与响应字段完整参考
StandardOne-3B-SH API 实战:/v1/systemone 请求与响应字段完整参考
StandardOne-3B-SH 是一个 3B 参数、带联合 schema head 的开源决策模型:它通过 POST /v1/systemone 接口读取一次场景,单次前向传播即可为所有问题的所有选项打分,并直接返回校准后的概率——全程不生成任何文本。本文将带你从零启动服务,并逐字段讲清 /v1/systemone 的请求体与响应体,帮助新手快速完成集成。
先搞懂:为什么 StandardOne-3B-SH 不生成文本 🤔
| 组件 | 说明 |
|---|---|
| 骨干网络 | Standard One 3B v2.2(Ministral 3 3B 文本 + Pixtral 视觉塔),已合并权重,bfloat16 |
| 决策头 | 联合 schema head,float32,读取最终层与第 19 层隐状态,配置见 head/schema_head_config.json |
| 工作方式 | 单次前向传播,同时回答一个请求内的所有问题,输出每题的校准概率分布 |
| 上下文上限 | 每请求最多 32,768 tokens,超长会被拒绝而非截断 |
与普通 LLM 接口最直观的区别:响应里的 output_tokens 恒为 0,因为你得到的是概率而不是生成的 token。
三步启动 /v1/systemone 服务
👉 完整说明见 README.md,以下是最小可运行步骤(参考服务入口为 code/serve_head.py):
# 1. 下载模型
python -m pip install --upgrade huggingface_hub
hf download StandardThinking/StandardOne-3B-SH --local-dir StandardOne-3B-SH
# 2. 安装依赖
python -m pip install -r StandardOne-3B-SH/code/requirements.txt
# 3. 启动服务(默认监听 127.0.0.1:30171)
python StandardOne-3B-SH/code/serve_head.py \
--snapshot StandardOne-3B-SH --head StandardOne-3B-SH/head --port 30171 \
--served-model-name standardthinking/standard-one-3b-sh
启动成功后验证健康检查:
curl -s localhost:30171/health
# {"status": "ok"}
服务还提供 GET /v1/models、/model_info、/server_info 三个只读端点,方便监控接入。
/v1/systemone 请求体字段全解
请求体是一个 JSON 对象,核心字段只有 state 和 questions 两个。
state:待判定的场景文本
- 支持字符串、dict 或 list;结构化值会被渲染为排序后的 JSON 文本
- 与
questions一起受 32,768 tokens 上限约束
questions:问题集合(1~256 个问题)
每个问题由问题键(字符串,不允许包含换行符和方括号)加一个题型对象组成,支持三种题型:
| 题型 | 选项数 | criteria 形式 |
典型用途 |
|---|---|---|---|
choice |
2~255 | 对象:{选项名: 描述} |
意图分类、路由(支持上百个选项) |
noul |
固定 true/false | 可选对象:{"true": 描述, "false": 描述} |
是/否判断 |
score |
2~10 | 数组,按从低到高排列各档位描述 | 有序量表打分 |
options:可选的评分参数
| 参数 | 默认 | 作用 |
|---|---|---|
permutations |
1 | 对 choice/noul 的选项做 K 轮位置轮换后取平均,消除位置偏差(score 档位顺序不变) |
temperature |
1.0 | 概率分布温度 |
temperature_scaling |
true | 设为 false 时忽略温度,直接使用原始 logit |
return_logprobs |
false | 在响应中额外返回每题每轮的原始 logprob |
另外请求可携带可选的 model 字段,取值必须是启动时 --served-model-name 指定的名称或 jev-latest,否则返回 404。
完整请求示例:客服意图判定
curl -s localhost:30171/v1/systemone -H 'content-type: application/json' -d '{
"state": {"message": "Please close my card, I lost it yesterday."},
"questions": {
"intent": {"type": "choice", "instructions": "What does the customer want?",
"criteria": {"cancel": "close the card", "limit": "change the limit", "other": null}},
"urgent": {"type": "noul", "instructions": "The request is urgent."},
"mood": {"type": "score", "instructions": "How upset is the customer?",
"criteria": ["calm", "annoyed", "angry"]}
}
}'
💡 一次请求里的多个问题共享同一次场景前向计算,这就是 schema head 相比逐题问答的成本优势。更多业务场景(仓储收货对账、数据导入诊断、备份校验等)见 README.md 的 Practical examples 一节。
响应字段逐行解读
下面是一个示意性响应(数值为演示用,字段结构与真实响应一致,来源 code/scoring.py 的 respond 方法):
{
"model": "standardthinking/standard-one-3b-sh",
"answers": {
"intent": {
"type": "choice",
"probabilities": {"cancel": 0.93, "limit": 0.05, "other": 0.02},
"confidence": 0.87,
"choice": "cancel"
},
"urgent": {"type": "noul", "noul": 0.82},
"mood": {
"type": "score",
"probabilities": {"0": 0.10, "1": 0.60, "2": 0.30},
"score": 1.4,
"legend": {"0": "calm", "1": "annoyed", "2": "angry"},
"confidence": 0.71
}
},
"usage": {"input_tokens": 245, "output_tokens": 0},
"metadata": {
"confidence_method": "1 - normalized_entropy",
"temperature": 1.0,
"evaluations": 3,
"prefills": 1,
"label_scheme": "schema-v1",
"cached_tokens": 0,
"prefill_ms": 412.5,
"head_ms": 88.2,
"adapter_elapsed_ms": 503.1,
"batch_requests": 1
}
}
answers:每题一个打分结果
| 字段 | 出现条件 | 含义 |
|---|---|---|
probabilities |
choice / score | 各选项名到概率的映射,总和为 1 |
choice |
仅 choice | 概率最高的选项名(即 argmax) |
noul |
仅 noul | P(true),即"是"的概率(false 概率 = 1 − noul) |
score |
仅 score | 有序量表上的期望位置,是实数,可落在两个档位之间(如 1.4 介于 annoyed 与 angry 之间) |
legend |
仅 score | 档位编号到档位描述的映射,方便回显 |
confidence |
choice / score | 置信度,方法为 1 − 归一化熵,取值 0~1 |
logprobs |
开启 return_logprobs |
每轮 permutation 的原始 logprob,用于自定义聚合 |
usage 与 metadata:用量与性能信息
usage.input_tokens:本次请求编码后的 token 总数(含 permutation 多轮);output_tokens恒为 0metadata.evaluations= 问题数 × permutations,metadata.prefills= 实际前向轮数prefill_ms/head_ms/adapter_elapsed_ms分别对应骨干前向、schema head 前向、端到端耗时,便于做延迟剖析batch_requests显示本次被动态打包进了多少个并发请求
常见错误码速查表 ⚠️
所有错误统一返回 {"error": {"code", "message", "field"}} 结构:
| HTTP | code | 触发原因 | 处理建议 |
|---|---|---|---|
| 400 | invalid_json |
请求体不是合法 JSON | 检查引号与转义 |
| 404 | model_not_found |
model 字段与服务名不匹配 |
与 --served-model-name 保持一致,或省略该字段 |
| 422 | invalid_request |
questions 缺失或结构校验失败 |
field 会指向出错字段 |
| 422 | bad_question_key |
问题键含换行或方括号 | 改用合法标识符 |
| 422 | bad_option_count / bad_score_levels |
选项数越界(choice 2~255,score 2~10) | 增减选项 |
| 422 | duplicate_option_name |
choice 选项名重复 | 重命名 |
| 422 | too_long |
编码后超过 32,768 tokens | 精简 state,field 指向 state |
| 500 | scoring_failed |
推理阶段异常 | 查看服务端日志 |
批量请求与性能调优
参考服务内置动态批处理,排队请求会在 token 预算内被打包一次前向(含图片的请求单独成批):
| 启动参数 | 默认 | 说明 |
|---|---|---|
--max-batch-requests |
8 | 单批最多合并的请求数 |
--max-batch-tokens |
32768 | 单批填充 token 预算 |
--batch-wait-ms |
5 | 等待凑批的最长毫秒数 |
--host / --port |
127.0.0.1 / 30171 | 监听地址 |
实践建议与注意事项 ✅
- 不要添加默认系统提示词:该模型在无系统提示下训练,参考服务默认
SH_SYSTEM_PROMPT=none渲染(见 code/render.py);chat_template.jinja 的默认 system message 也是空的。手动加回 Ministral 默认 prompt 会改变隐状态、拉低打分质量。 - 概率阈值要自己校准:概率在官方留出数据上校准过,接入真实业务前请用自己的数据重新设定阈值。
- 选对场景:在超长文档中的极难决策任务上,同规模的 Standard One 3B(生成式)可能略优;结构化多题打分、长文档定位、上百选项的意图路由则是 SH 的强项。
- CPU / Apple 芯片:可改用 GGUF 格式配合 llama.cpp 运行,
/v1/systemone请求格式完全不变。 - 权重与校验文件:model-00001-of-00002.safetensors、SHA256SUMS、release-manifest.json。
总结
StandardOne-3B-SH 的 /v1/systemone 接口本质上是一个"结构化判定打分服务":state 给出场景,questions 定义问题,响应按题型返回 probabilities / noul / score 及置信度。理解这一请求—响应契约后,无论是意图路由、文档合规核对还是量表评估,都可以用几行 curl 或标准库 HTTP 客户端完成集成。