核心指南
决策
从决策模型获取类型化的概率、选项和评分
POST /v1/systemone 针对一段 state 回答多个具名问题，每个问题返回一个类型化答案。响应是同步 JSON：概率、选项名或评分，代码可以直接比较和分支处理。它不返回生成的文字。
决策还是聊天
| 适合用决策 | 适合用聊天 |
|---|---|
| 代码需要一个数值或标签来决定下一步 | 答案给人或其他模型阅读 |
| 对请求做路由、分类或拦截：是否退款、交给哪个团队、紧急程度 | 需要解释、摘要或起草文字 |
| 对同一份输入一次性提出若干固定问题 | 需要工具、流式输出、图片或多轮消息 |
决策接口不接受 messages、tools、stream 或其他聊天参数，也不能通过 Batch 调用。主聊天模型请单独配置。
选择模型
curl "https://api.tokenlab.sh/v1/models?recommended_for=decision" \
-H "Authorization: Bearer sk-your-api-key"也可以用 category=decision 筛选。发送请求前先读取所选模型的 GET /v1/models/{model}，并在请求里明确写出模型 ID。本页示例使用 jev-1.13。
请求格式
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 决策模型 ID |
state | string、JSON 对象或 JSON 数组 | 要评估的输入，例如工单、对话记录或一条数据 |
questions | object | 至少一个问题。键是你起的问题名；值包含 type、instructions 和 criteria |
instructions 和每条判定标准同样接受 string、JSON 对象或 JSON 数组。请求中出现未知字段会被拒绝。
type | criteria | 答案 |
|---|---|---|
noul | 可选。同时包含 true 和 false 说明的对象 | noul：陈述为真的概率，范围 0 到 1 |
choice | 必填。包含 1–255 个选项名的对象，每个选项对应说明或 null | choice：你给出的某个选项名。可能附带 probabilities 和 confidence |
score | 必填。包含 2–10 个等级说明的有序数组 | score：0 到数组最后一个下标之间的数，可以是小数。可能附带 legend、probabilities 和 confidence |
评估一张工单
curl https://api.tokenlab.sh/v1/systemone \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-1.13",
"state": "I was charged twice. Please refund the duplicate payment.",
"questions": {
"refund_requested": {"type": "noul", "instructions": "Is a refund requested?"},
"department": {
"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"refunds": "Charges and refunds", "technical": "Software bugs"}
},
"urgency": {
"type": "score", "instructions": "Rate urgency",
"criteria": ["Routine enquiry", "Money affected", "Safety emergency"]
}
}
}'响应在 answers 下沿用你的问题名。以下数值仅作示意：
{
"model": "jev-1.13",
"answers": {
"refund_requested": {"type": "noul", "noul": 0.97},
"department": {"type": "choice", "choice": "refunds"},
"urgency": {"type": "score", "score": 1}
},
"usage": {"input_tokens": 96, "output_tokens": 12}
}使用答案
- 每个问题都会在同名键下得到一个同类型的答案。
noul答案是概率，不是布尔值。请为每个动作自行设定阈值。choice答案一定是你发送的选项名之一。score答案是criteria数组的下标：上例中的1表示 "Money affected"。- 在决策结果驱动退款、升级等动作之前，先用你自己标注好的样例测试。
通过 MCP 使用
TokenLab MCP Server 在 core 和 full 配置中提供 evaluate_decisions。先用 {"category":"decision"} 调用 list_models，再调用 get_model，然后把同样的 model、state 和 questions 作为工具参数传入。从结果的 structuredContent.answers 和 structuredContent.usage 读取答案与用量。该工具同步返回结果，不使用异步任务轮询。
通过 SDK 使用
TokenLab JavaScript SDK 0.1.2+ 提供 evaluateDecisions(body)；Python SDK 0.1.2+ 提供 evaluate_decisions(body)。body 与 HTTP 请求的 JSON 相同。两者都保留类型化答案和 usage，失败后不会自动重复请求。详见 SDK 与库。
费用与重试
- 决策按 token 计费，依据响应中的
usage.input_tokens和usage.output_tokens，按模型当前的 token 价格计算。 - 价格可能变化。请读取模型的价格详情或 获取价格 接口，不要在代码里写死价格。
- 即使模型的输出价格为零，也可能报告输出 token。
- 请求遵循你选择的交付方式。参见 账单与定价。
- 超时后结果不确定。再次发送付费请求前，先在日志或 Console 里核对该请求。
常见错误
| 现象 | 可能原因 | 处理 |
|---|---|---|
messages、stream 等字段返回 400 | 聊天字段不属于这个接口 | 只发送 model、state 和 questions |
criteria 返回 400 | choice 有 0 个或超过 255 个选项，score 少于 2 个或多于 10 个等级，或 noul 对象缺少 true 或 false | 修正问题定义 |
| 信号很弱时也触发了动作 | 把 noul 概率直接当成真或假 | 与经过测试的阈值比较 |