核心指南
決策 (Decisions)
從決策模型獲取類型化的機率、選項和分數
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 object, or JSON array | 要評估的輸入，例如工單、文字記錄或記錄 |
questions | object | 至少一個問題。每個鍵都是您的問題名稱；每個值都包含 type、instructions 和 criteria |
instructions 和每個準則也接受字串、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}
}使用答案
- 每個問題都會在相同的名稱下獲得相同
type的答案。 noul答案是機率，而非布林值。請為每個操作選擇您自己的閾值。choice答案永遠是您發送的選項名稱之一。score答案會索引您的criteria陣列：上述的1代表「Money affected」。- 在將決策用於驅動退款、升級或其他操作之前，請先針對您自己的標記案例進行測試。
從 MCP 使用
TokenLab MCP server 在 core 和 full 設定檔中公開了 evaluate_decisions。請先呼叫 list_models（帶有 {"category":"decision"}）和 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 相同。兩者皆保留類型化答案和使用量，且不會自動重試失敗的請求。請參閱 SDKs。
成本與重試
- 決策按 Token 計費，根據回應中的
usage.input_tokens和usage.output_tokens以及模型當前的 Token 價格計算。 - 價格可能會變動。請閱讀模型的定價詳情或 Pricing API，而不是將價格寫死。
- 即使輸出價格為零，模型也可能回報輸出 Token。
- 請求遵循您的交付選項。請參閱 計費與定價。
- 超時會導致結果不確定。在再次發送付費請求之前，請先檢查您的日誌或 Console 中的請求。
常見錯誤
| 徵狀 | 可能原因 | 修正 |
|---|---|---|
400 (針對 messages 或 stream 等欄位) | 聊天欄位不屬於此端點 | 僅發送 model、state 和 questions |
400 (針對 criteria) | choice 有 0 個或超過 255 個選項，score 少於 2 個或超過 10 個等級，或者 noul 物件缺少 true 或 false | 修正問題定義 |
| 操作在微弱訊號下觸發 | noul 機率被視為 true 或 false | 與您測試過的閾值進行比較 |