StandardOne-3B-SH API 实战:/v1/systemone 请求与响应字段完整参考

原创2026-11-14 20:46:381,965 阅读

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 恒为 0
  • metadata.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 监听地址

实践建议与注意事项 ✅

  1. 不要添加默认系统提示词:该模型在无系统提示下训练,参考服务默认 SH_SYSTEM_PROMPT=none 渲染(见 code/render.py);chat_template.jinja 的默认 system message 也是空的。手动加回 Ministral 默认 prompt 会改变隐状态、拉低打分质量。
  2. 概率阈值要自己校准:概率在官方留出数据上校准过,接入真实业务前请用自己的数据重新设定阈值。
  3. 选对场景:在超长文档中的极难决策任务上,同规模的 Standard One 3B(生成式)可能略优;结构化多题打分、长文档定位、上百选项的意图路由则是 SH 的强项。
  4. CPU / Apple 芯片:可改用 GGUF 格式配合 llama.cpp 运行,/v1/systemone 请求格式完全不变。
  5. 权重与校验文件:model-00001-of-00002.safetensors、SHA256SUMS、release-manifest.json。

总结

StandardOne-3B-SH 的 /v1/systemone 接口本质上是一个"结构化判定打分服务":state 给出场景,questions 定义问题,响应按题型返回 probabilities / noul / score 及置信度。理解这一请求—响应契约后,无论是意图路由、文档合规核对还是量表评估,都可以用几行 curl 或标准库 HTTP 客户端完成集成。

登录后查看全文
StandardOne-3B-SH