學習·系統一

學習 TypeSafe Jev

TypeSafe Jev 從入門到實作教程. TypeSafe Jev 實用指南：面向軟體類型化決策的 System One AI 模型。

制定任務框架

決定 Jev 是否適合

Jev 不是聊天模型。它將現有狀態轉變為封閉的 Choice、Score 或 Noul 決策，並傳回機率分佈。

很合身

使用 Jev 進行有界決策

將一個請求路由到一個命名佇列。
將記錄放在有序的風險或品質等級上。
估計一個明確陳述的條件是否為真。

不太合適

使用生成模型代替

撰寫、總結、翻譯或重寫開放式文字。
進行自然的多輪對話。
當無法提前命名有效輸出時創建答案。

官方心智模型

STATE

要評估的一種狀態

傳遞一個字串、物件或數組，其中包含判斷所需的文字和相關事實。對大多數實際請求使用命名物件欄位。

QUESTIONS

每個問題一次快速判斷

每個問題都應該問一個有知識的人可以根據所提供的狀態快速判斷的重點事項。

PARALLEL

平行獨立問題

一個請求中的問題會看到相同的狀態，獨立運行，並且不會將一個答案洩漏到另一個答案中。

CODE

用程式碼寫答案

權重、閾值、分支以及組合普通程式碼中鍵入的答案，而不是將工作流程邏輯隱藏在一個提示中。

分解測試： 如果判斷權衡多個獨立因素或需要擴展推理，請將其拆分為原子問題並將答案組合到程式碼中。

本章之後：您可以將內容生成任務與結構化決策任務分開。

官方參考： Introduction · State · Primitives

選擇類型

選擇選擇、分數或Noul

使用 Choice 表示互斥標籤，使用 Score 表示有序級別，使用 Noul 表示一個真或假判斷。

類型	您供應	您收到	使用時
`choice`	命名選項 → 描述	選定的鍵 + 每個選項的機率（+ 置信度）	互斥的標籤/路線
`score`	有序级别 (2–10)，低 → 高	概率加权水平分数 + 梯级概率	严重性、质量、风险标准
`noul`	是/否提议（+可选标准）	真實的機率	單一事實檢查

choice多達 255 個選項

獲勝者加上全部分配

用於無序、固定的替代方案。當清單可能無法涵蓋每個州時，添加其他/無。所選值是機率最高的選項。

{
  "choice": "technical",
  "probabilities": { "technical": 0.85, "billing": 0.15 },
  "confidence": 0.78
}

score2–10 個有序級別

機率加權位置

等級從 0 開始索引。分數是等級機率的加權平均值，因此它可以介於兩個等級之間。

{
  "score": 1.43,
  "probabilities": { "0": 0.0, "1": 0.57, "2": 0.43 },
  "confidence": 0.35
}

noul0 = 否 · 1 = 是

陳述為真的機率

用於明確的是/否判斷。接近 0.5 意味著不確定性，而不是屬性的中等量。 Noul 沒有單獨的置信域。

{
  "type": "noul",
  "noul": 0.95
}

分數不是準確性。 0-2 評分標準的 1.5 分是預期水平，而不是「75% 正確」。不要將分數或選擇信心視為準確性承諾。

本章之後：您可以為路由、審核和風險評分選擇正確的答案形狀。

官方參考： Choice · Score · Noul

定義規則

編寫決策契約

保持選項名稱穩定，定義互斥邊界，包括剩餘路徑，並為每個問題提供一個決定。

寫出強而有力的標準

不相交的選項。如果兩個選擇鍵都為真，操作員就會與模型作鬥爭。
描述邊緣。說出購買意願包括哪些內容（庫存、送貨地址）與價格問題。
将剩余物保留在最后。使用其他人/人類作為逃生口，而不是懶惰的包羅萬象。
訂單分數上升。标准数组从最低→最高。
每个问题一个决定。將“路線”從“緊急”拆分為單獨的按鍵。

問題的剖析

question_id

您的程式碼的回應查找鍵。它不會發送到模型，因此說明仍必須包含完整的問題。

type

選擇、分數或 noul。選擇您的程式碼可以直接作用的形狀。

instructions

完整、具體的判斷。它可以是字串、物件或數組，並且可以引用命名狀態路徑。

criteria

Noul 的選擇選項、有序分數等級或可選的真/假說明。

例 · 一個決定，不相交的邊界

route: {
  type: 'choice',
  instructions: 'Route this ticket to one queue.',
  criteria: {
    tech: 'Bugs, outages, API failures, or integrations',
    sales: 'Pricing, plans, demos, or new-purchase intent',
    billing: 'Charges, invoices, receipts, or subscriptions',
    human: 'Ambiguous, sensitive, legal, or multi-issue'
  }
}

結構狀態和引用精確字段

將證據保留在命名狀態欄位中，並使用點和索引路徑將指令指向它們。這減少了關於哪個文本、記錄或策略應該控制答案的歧義。

const state = {
  ticket: {
    message: 'I was charged twice. Please refund the duplicate.',
    orderId: 'A-104'
  },
  order: { charges: [49, 49] },
  refundPolicy: 'Duplicate charges are eligible for a refund.'
};

const questions = {
  refund_requested: {
    type: 'noul',
    instructions: 'Does `ticket.message` request a refund?'
  },
  policy_supports_refund: {
    type: 'noul',
    instructions: 'Does `refundPolicy` support the request given `order.charges`?'
  }
};

預設批量： 提出在一個請求中使用相同狀態的所有問題，甚至是推測性問題。僅在其狀態或選項確實依賴先前的答案時才發出第二個請求。

本章之後：您可以編寫程式碼可以使用的穩定、可測試的問題定義。

官方參考： Primitives · State

連接模型

撥打您的第一個 Jev 電話

從您的伺服器呼叫官方 System One 端點或 SDK，檢查鍵入的回應，並處理驗證、速率限制和過載錯誤。網關仍然是可選的存取路徑。

從官方 HTTP 端點開始

將 TYPESAFE_API_KEY 保留在伺服器上。將狀態、模型和命名問題圖傳送至 POST /v1/systemone.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Stripe has failed for 3 days. I am losing sales.",
    "model": "jev-latest",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payment or subscription issues",
          "technical": "Bugs or integration problems",
          "sales": "Pricing or account questions"
        }
      },
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this message convey urgency?"
      }
    }
  }'

使用官方 SDK 進行輸入答案並重試

Python SDK 從環境中讀取 TYPESAFE_API_KEY，預設為 jev-latest，公開類型化問題/答案類，並應用其預設重試策略。

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"message": "Stripe has failed for 3 days.", "impact": "Losing sales"},
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "billing": "Payment or subscription issues",
                    "technical": "Bugs or integration problems",
                    "sales": "Pricing or account questions",
                },
            ),
            "is_urgent": Noul(
                instructions="Does `message` and `impact` convey urgency?"
            ),
        },
    )

department = response.answers["department"]
print(department.choice, department.confidence)
print(response.answers["is_urgent"].noul)

閱讀問題 ID 下的每個答案

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": { "technical": 0.85, "billing": 0.15, "sales": 0.0 }
    },
    "is_urgent": { "type": "noul", "noul": 0.95 }
  },
  "usage": { "input_tokens": 392, "output_tokens": 54 }
}

處理完整的誤差面

401

API 金鑰缺失或無效。檢查承載令牌。

422

請求形狀無效。檢查違規欄位的回應。

429

超出速率限制。在重試之前先退出。

529

服務暫時超載。在重試之前先退出。

對於 429 和 529，請使用指數退避而不是立即重試。官方 SDK 根據其預設重試策略自動執行此操作。

替代方案：Vercel AI 網關

該網站還記錄了網關作為 AI SDK 評估的存取層。它是一種替代整合路徑，不是 Jev 或 TypeSafe 的一部分。

import { experimental_evaluate as evaluate } from 'ai';
import { gateway } from '@ai-sdk/gateway';

const result = await evaluate({
  model: gateway('typesafe-ai/jev'),
  state,
  questions,
});

本章之後：您可以將憑證保留在伺服器端並接收帶有機率的鍵入答案。

官方參考： Quick start · API reference · SDKs

處理不確定性

將信心轉化為政策

不要將最高機率直接轉化為最終行動。根據業務風險設定建議、確認和人工審核的範圍。

PROBABILITY

每個選項或等級的證據

選擇和分數返回完整的分佈。當亞軍選項、模糊性或自訂不確定性度量很重要時使用它。

CONFIDENCE

分佈形狀總結

置信度將分佈的集中度或平坦度壓縮為 0-1。它與所選選項的機率不同。

Noul: Noul已經回傳P(true)，所以它沒有單獨的置信度。接近 0.5 的值是不確定的；根據風險設定是和否的閾值。

TypeSafe 揭示了选项分布的置信度。一个实用的政策是：

高置信度

在使用者介面中自動建議選擇（標籤、路線或判決）。

中等置信度

顯示建議，但請操作員確認後再繼續。

信心度低

發送到人工隊列，沒有預設操作。

校準流或收件匣中標記範例的截止值。閾值是特定於用例的。切勿將建議轉化為金錢或退款。

在全球範圍內限制行動而不是模型

action = response.answers["action"]

if action.confidence < 0.5:
    route_to_human(state)             # uncertain: do not guess
elif action.choice == "check_balance":
    show_balance(account_id)          # reversible, low stakes
elif action.choice == "approve_transfer":
    if action.confidence > 0.9:
        confirm_then_execute(account_id)
    else:
        ask_user_to_confirm(account_id)  # higher stakes, higher bar

自動化前校準

從真實的工作流程中收集有代表性的、有標籤的範例。
記錄答案、分佈、置信度、延遲和人類決策。
分別為可逆、昂貴和不可逆的操作選擇閾值。
監視漂移並在更改狀態、指令、標準或模型別名後重新評估。

狀態提示

傳遞字串、物件或陣列作為狀態。當只有一條訊息重要時，更喜歡結構化記錄（評論文字+元資料），而不是轉儲整個聊天日誌。

本章之後：您可以設計低置信度回退並使用標記資料校準閾值。

官方參考： Confidence

練習

從原型轉向實際任務

建構一個完整的工作流程，包含結構化狀態、平行問題、程式碼擁有的策略、稽核證據、重試和人工後備。

建立一個完整的支援分類工作流程

發送一份結構化工單狀態並並行詢問三個獨立問題。將路由和安全性原則保留在程式碼中。

STATE→CHOICESCORENOUL→POLICY

const questions = {
  department: {
    type: 'choice',
    instructions: 'Which team should handle `ticket.message`?',
    criteria: {
      returns: 'Exchanges, wrong or damaged items',
      shipping: 'Delivery status, delays, or lost packages',
      billing: 'Charges, invoices, or payment problems',
      other: 'None of the above'
    }
  },
  frustration: {
    type: 'score',
    instructions: 'How frustrated is the customer?',
    criteria: ['Calm', 'Concerned but civil', 'Very angry']
  },
  refund_requested: {
    type: 'noul',
    instructions: 'Does `ticket.message` request money back?'
  }
};

將輸入的答案轉化為可審核的決策

const department = result.answers.department;
const frustration = result.answers.frustration;
const refundProbability = result.answers.refund_requested.noul;

if (department.confidence < 0.5) {
  return { action: 'manual_triage', reason: 'uncertain_department' };
}

const flags = [];
if (frustration.score > 1.4) flags.push('senior_agent');
if (refundProbability > 0.75) flags.push('refund_review');

return {
  action: 'route',
  team: department.choice,
  flags,
  evidence: {
    departmentProbabilities: department.probabilities,
    frustrationScore: frustration.score,
    refundProbability
  }
};