TypeSafe 相容性

TypeSafe 閉源的 Jev 模型開創了「System One」這一決策模型類別。Ollaya 的 /v1/* API 與 TypeSafe 的線上格式完全一致 —— 以 typesafe-sdk 0.7.1 的線上 schema 和錯誤處理為準 —— 所以為 TypeSafe 寫的程式碼能跑在你本機上的開放模型上。

把 SDK 指向 Ollaya

官方的 TypeSafe Python SDK 0.7.1 無需改動即可使用。設定這些環境變數：

export TYPESAFE_BASE_URL=http://localhost:11435
export TYPESAFE_API_KEY=local           # the SDK needs a non-empty key; any value works
export TYPESAFE_DEFAULT_MODEL=winnow:e4b   # otherwise the SDK sends its default, "jev-latest"
export NO_PROXY=localhost,127.0.0.1    # keep local requests off any system proxy

• 預設模型。 winnow:e4b 最接近 Jev（型別化決策上 0.722，Jev 是 0.738），在 RTX 4090 上約 90 ms 作答。沒有 NVIDIA GPU 就用 laya，它在 CPU 上零點幾秒就能回答。
• API key。 Ollaya 接受任何 key，除非伺服器設定了 OLLAYA_API_KEY；那之後 SDK 的 key 必須與它一致。
• 請求 ID。 每個響應都帶 x-typesafe-request-id，所以 response.request_id 可用。
• 重試。 SDK 在 10 秒後超時並重試。對某個模型的第一次請求會等它載入，而比請求活得更久的載入會繼續，所以重試時模型已經是熱的。
• 系統代理。 在帶系統 HTTP 代理的 Mac 上，TypeSafe SDK（和 httpx 一樣）會把發往 localhost 的請求也走代理，無視系統的例外列表。於是你的狀態會穿過代理，而 Ollaya 關著時，SDK 報的是 502 status code (no body)，而不是連線被拒。把 NO_PROXY=localhost,127.0.0.1 寫在 TYPESAFE_BASE_URL 旁邊。
• 預熱與耗時。 想在第一次請求前載入模型，就向 /api/decide 傳送 {"model": "winnow:e4b", "keep_alive": -1}（不帶 state）。/v1/* 的響應不帶耗時，和 TypeSafe 的一樣；/api/decide 會報告 total_duration、load_duration 和 eval_duration。

端點

請求與響應

curl http://localhost:11435/v1/systemone \
  -H "Authorization: Bearer local" \
  -d '{
  "model": "laya",
  "state": "Can I get an invoice for last month?",
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "What does the customer want?",
      "criteria": {
        "invoice": "Needs an invoice or receipt",
        "refund": "Wants money back",
        "other": "Anything else"
      }
    }
  }
}'

{
  "model": "laya:en",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "invoice",
      "confidence": 0.9547,
      "probabilities": {"invoice": 0.9698, "refund": 0.0172, "other": 0.013}
    }
  },
  "usage": {"input_tokens": 43, "output_tokens": 0}
}

響應裡的 model 是實際作答的 checkpoint：laya 是一個 router，這個英語請求發去了 laya:en。TypeSafe 的 schema 允許這樣（“may differ from the alias supplied in the request”）。數值保留 4 位小數，probabilities 與 criteria 的順序一致。

curl http://localhost:11435/v1/models -H "Authorization: Bearer local"

{
  "models": [
    {
      "name": "laya:en",
      "description": "English decision model (ModernBERT-large): guardrails, email and ticket triage.",
      "release_date": "2026-09-23"
    },
    {
      "name": "laya:latest",
      "description": "Routes each request to laya:en or laya:multilingual by the text's script and language.",
      "release_date": "2026-09-23"
    },
    {
      "name": "laya:multilingual",
      "description": "Decision model for 100+ languages (mmBERT-base).",
      "release_date": "2026-09-23"
    }
  ]
}

/v1/models 列出拉到本機上的模型，包括 router；不列出 registry。

錯誤

錯誤帶 TypeSafe 的狀態碼，以及一個 SDK 能正確讀取的響應體：一個字串 error（SDK 會顯示它）、一個機器可讀的 code，以及在 422 上 TypeSafe 的 detail 校驗問題列表。每個程式碼見錯誤。

{"error": "model \"jev-latest:latest\" not found, try pulling it first", "code": "MODEL_NOT_FOUND"}

哪裡不一樣

相容覆蓋的是 API，不是模型：

• 模型名是 Ollaya 的（laya、laya:en），所以要設定 TYPESAFE_DEFAULT_MODEL 或傳入 model。
• 缺 instructions。 一個問題沒有它時，模型會讀取問題 id 來頂替，所以給問題起描述性的名字（is_urgent、tone）。
• 限制。 每個請求最多 256 個問題，2–255 個選項，2–10 個 score 檔位。每個模型還有選項預算：laya:en 約 125 個選項，laya:multilingual 是 250 個。
• 長狀態。 TypeSafe 最多讀 65,536 個 token；開放模型的上下文更短（laya:en 是 512 個 token，laya:multilingual 是 1,024 個，含問題在內）。狀態放不下時，/v1/* 返回 422 STATE_TRUNCATED，而不是拿它的一部分來作答。換一個上下文更長的模型、縮短狀態，或呼叫 /api/decide，它會截斷並報告 state_truncated。
• /v1/* 保持純淨。 keep_alive、extras 這類原生欄位在那裡會被忽略；路由、耗時和截斷都在 /api/decide 上報告。
• 質量來自開放模型，所以按任務不同而與 Jev 有差別：
  • laya:typed-decisions 在型別化決策上得 0.766，Jev 1.13 公佈的是 0.727。
  • 基礎的 Laya checkpoint 在型別化決策上零樣本接近隨機（0.362）。
  • 選項很多的 choice 問題（超過約 20 個）更弱：Banking77 上 0.425，Jev 是 0.870。

切換生產流量之前，先在你自己的資料上量一量。Laya 頁面有細節。

沒有關聯

Ollaya 是一個獨立的開源專案。它與 TypeSafe 沒有關聯，也未獲 TypeSafe 認可。