如何使用 Jev API：Typed Decisions 實作指南

Jev API 的用法跟一般大型語言模型的 API 很不一樣。你不是把提示詞丟進去等一段文字回來，而是先把「可能的答案」定義好，再請模型從中挑一個、打一個分數，或回一個是非機率。這篇 Jev API 指南會從頭帶你走一遍，包含第一次呼叫、三種提問原語、還有上線前該注意的事。

如果你已經寫過 OpenAI 或 Anthropic 的 API，這裡最大的差別是：你要開始習慣「定義答案空間」而不是「描述任務」。

使用 Jev API 前要先理解的三件事

動手之前，先建立三個正確的預期。

第一，Jev 不生成文字。你的程式碼拿到的會是結構化的值，例如一個選項、一個數字、或一個 0 到 1 的機率，附帶信心分數。這代表你不用再寫一堆程式去解析模型輸出，但也代表它不會幫你解釋它為什麼這樣判斷。

第二，TypeSafe API 的輸入分成兩塊：state 與 questions。state 是你要它評估的內容，可以是純文字、JSON 物件或文字陣列；questions 則是一組你命名的問題。每個問題都會看到同一份 state，而且它們是平行評估的，多加問題不太影響回應時間。

第三，Jev 目前只吃文字。圖像、音訊、影片都還不支援，遇到這些輸入得先轉成文字或結構化欄位再送進去。

Jev API 金鑰申請與環境準備

取得存取權是第一步。TypeSafe AI 的 Jev 目前以早期存取的形式提供，你可以從官方 API 主控台申請金鑰。在主控台裡建立 API Key 之後，把它放進環境變數，不要寫死在程式碼裡。

準備工作包含三項：

1. 到 TypeSafe 的 API 主控台申請帳號並建立 API 金鑰。
2. 把金鑰存成環境變數，例如 TYPESAFE_API_KEY。
3. 安裝官方 SDK，Python 與 TypeScript 都有提供，也可以直接用 HTTP 呼叫。

如果想先試手感再決定要不要申請，TypeSafe 也放出了 Jev Playground，不用金鑰就能在瀏覽器裡試 Choice、Score 與是非三種判斷，先看回傳的機率分布長什麼樣子。

步驟一：用 System One API 送出第一次呼叫

Jev 的所有請求都走同一個端點，POST /v1/systemone。請求的主體有三個必填欄位。

• state：要評估的內容，純文字或結構化資料。
• model：要哪顆模型處理，範例與 SDK 預設都用 jev-latest。
• questions：一個問題的對照表，每個 key 由你命名，答案會用同一個 key 回傳。

最簡單的一次呼叫長這樣：state 放一句客服訊息，questions 放一個是非問題。

{
  "state": "救命！我的提款已經連續三天失敗了。",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "這句話有沒有表達出急迫性？"
    }
  }
}

回傳的就會是 is_urgent 對應的一個機率值。重點在於：key 由你自己取，而且不會被送進模型、不參與推理，純粹是給你的程式對號入座用。

步驟二：選擇 Jev 的三種提問原語

Jev API 支援三種問題型別，都由 type 欄位指定。

三種原語共享 type 與 instructions，各自再加自己的 criteria。Noul 的 criteria 可以描述「是」與「否」各代表什麼；Choice 的 criteria 是選項對照表，最多 255 個；Score 的 criteria 是排序好的層級陣列，至少兩級、最多十級。

以下是一個 Choice 的實作範例，把客服訊息分流到三個部門：

{
  "state": "救命！我的提款已經連續三天失敗了。",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "這則訊息該由哪個團隊處理？",
      "criteria": {
        "billing": "付款、帳單、退款",
        "technical": "程式錯誤、服務中斷、整合問題",
        "sales": "定價、升級、新帳號"
      }
    }
  }
}

步驟三：在 TypeSafe API 請求裡組合多個問題

真正的威力在於把多個原子問題塞進同一次呼叫。

官方文件建議每個問題只問一件明確的事，也就是「一個懂行的人幾秒鐘內能做出的直覺判斷」。與其問一個大而模糊的問題，不如拆成三、四個小問題，再讓程式碼把答案組合起來。

以前面的退款案例來說，你可以一次問三件事：這是不是退款請求、有沒有重複扣款的跡象、政策上是否支持退款。三個問題共用同一份 state，平行評估，回傳後由你的程式碼搭配確定性的檢查邏輯，決定直接處理還是轉人工。

這種拆法的好處不只是準，還讓每個判斷都能單獨測試。哪個問題老是出錯，你可以單獨調它的 instructions 與 criteria，不必整個流程重來。

步驟四：用 Jev Playground 驗證與調整判斷

上線前，先把每個問題單獨驗證過。

Jev Playground 很適合做這件事。你可以把真實的 state 貼進去，切換 Choice、Score 與是非三種模式，直接看它回傳的機率分布與信心分數。看到某個問題的分布老是模稜兩可，就代表那道問題的 instructions 還要再收窄。

驗證時要盯兩個數字。一個是答案本身對不對，另一個是信心分數與準確度有沒有對上。Jev 的機率是校準過的，意思是它說「七成把握」的時候，長期下來應該真的有大約七成是對的。如果你的資料顯示門檻設在 0.9 卻只有六成準，那代表這個任務對它來說太難了，得考慮換問題拆法或轉人工。

使用 Jev API 的實用技巧

幾個實際踩過才知道的訣竅。

• 精簡 state。Jev 按輸入詞元計費，只送判斷真正需要的上下文，能省下可觀成本。
• 打包問題。多個問題共用一份 state 在同一次往返完成，不要在迴圈裡一題一題打。
• 依信心分流。讓 Jev 自動處理高信心的案例，把低信心或需要解釋的少數案例轉給 LLM 或人工。
• 版本要釘住。jev-latest 這種別名會隨新版本移動，如果你已經把信心門檻調校在某個版本上，就改用版本化的 ID，別讓它自己偷偷換。
• 問題命名要一致。key 由你取，取一個之後別亂改，否則後續程式碼會找不到對應的答案。

Jev API 常見問題排查

實作時最容易卡住的幾個狀況。

回傳 429 Too Many Requests。 這是撞到費率上限，目前是每秒 25 萬詞元、每分鐘 1,200 次請求。官方 SDK 預設會退避重試並尊重 retry-after 標頭；如果你直接打 HTTP，就得自己處理。

請求被拒，說超出上下文。 每次請求上限是 64k 詞元，包含 state 加上所有問題。state 太長就精簡，或把問題分批送。

非英語內容的表現不穩。 官方明說英語是主要訓練語言、準確度最好，其他語言包含中日韓文字都有支援但沒有同等水準。要拿 Jev 跑中文工作負載，先用自己的資料實測，並且特別盯緊信心分數。

資料隱私與留存。 官方文件說明 Jev 不會拿客戶的請求和回應去訓練模型，企業方案另有零資料留存的選項。如果你的流程會送進個資或機密內容，記得先確認方案的資料處理條款，必要時在送出前就先把敏感欄位處理掉。

答案型別對不上。 檢查 criteria 的格式：Choice 要是選項對照表，Score 要是有序陣列。型別定義錯了，模型就沒有正確的答案空間可挑。

用 Jev API 建立可靠的 Typed Decisions 流程

回頭看整條流程，Jev API 的實作其實圍繞一個核心觀念：把判斷拆小、把答案定義清楚、把不確定的部分交出去。

你不需要在第一次就把系統做完美。先用 Jev Playground 把幾個關鍵問題試出來，再用 API 接進流程，跑影子模式跟歷史資料比對，量準確度與信心校準。等數字站得住腳，再讓它真正影響正式決策。想開始的話，到 TypeSafe 的 API 主控台取得金鑰，就能把第一個 Typed Decisions 呼叫接進你的程式裡。