TypeScript SDK 設計

laya-client 是一個無依賴的 HTTP 客戶端，用於自託管的 laya-serve 伺服器。它使用 POST /v1/systemone 端點，不引入任何 Python 生產程式碼或伺服器依賴。這個 npm 包從版本 0.1.0 起步，與 Python 的釋出相互獨立。

邊界

flowchart LR
    A[JavaScript or TypeScript application] --> B[laya-client]
    B -->|POST /v1/systemone| C[Existing Laya server]
    C --> E[Router and local checkpoint]

SDK 匯出 predict 和一個 Laya 專用的 health 探針。它提供 ESM、CommonJS 和宣告檔案，並保留 推斷出的 question ID 和 choice 標籤。當 JavaScript 或 TypeScript 應用通過 HTTP 與自託管的 Python laya-serve 通訊時，用 laya-client。當推理必須在 JavaScript 內部通過它本地的 ONNX 執行時直接跑、不需要 Python 伺服器時，用 laya-ts。

共享契約

請求包含 state 和 questions。除非為一次預測另外配置或提供，laya-client 會省略 model， 讓 laya-serve 自動選擇一個本地 checkpoint。客戶端級或逐呼叫的 model 可以選擇一個本地 checkpoint，下面表格裡的其它逐請求控制項也一樣。choice 標籤陣列在傳輸之前會被規範化成帶 null 描述的對映。

響應保留 model、answers 和 token usage。Laya 的 routing 和答案 action 欄位是可選 擴充套件；Noul 的置信度也是可選的。Choice 和 Score 的置信度、分佈，以及 Score 的檔位說明仍是必需的。 每條答案都攜帶 answer_confidence，即報告出來的那個答案上的 max(p) 機率質量，它在三種問題型別上是同一個量。一次傳入了 min_confidence 的呼叫會在它的每條答案上報出 abstention 和 abstention_threshold，並對低於閾值的那些答案報出 low_confidence: true；沒有設定閾值時，這三個鍵一個都不會發送，而這種缺席本身就是那份報告。 可選擴充套件在場時會被校驗。

/v1/systemone 是客戶端唯一呼叫的端點，它沒有獨立的路由方法：laya-client 只暴露 predict 和 health，別的什麼都沒有，而即時整合測試斷言伺服器對 /v1/route 返回 404。該端點確實支援的這些控制項都是逐請求的，而且只有當呼叫方提供了該選項時才會傳送 —— 預設的選項會讓部署自己的 Router(...) 設定說了算，而不是用客戶端的預設值去覆蓋它：

一個不可能有任何含義的選項會在請求發出之前本地拒絕：一個空白的 task、一個不是正整數的預算、一個在 [0, 1] 之外的閾值，或一個為空、或持有 [0, 1] 之外值的閾值對映。沒有任何東西會被靜默忽略。Laya 公開的 /health 返回 status、loaded 和 device。預測從不先探測健康。

FastAPI 的 detail 字串和校驗陣列會保留為 LayaAPIError 的 messages/details。來自相容後端的 結構化錯誤信封也會被接受。請求有可配置的截止時間和呼叫方取消，且從不自動重試。

驗證與釋出

單元測試覆蓋請求構建、所有答案形狀、Laya 擴充套件、FastAPI 錯誤、JSON 校驗、截止時間和取消，並把這一頁的控制表釘在客戶端實際放到線上的那些欄位上。型別 檢查覆蓋可選後設資料、推斷出的答案型別，以及 ESM/CommonJS 消費者。即時 整合測試用一個小型離線 checkpoint 啟動未改動的 laya.serve 應用，把 SDK 的預測與直接 Python 推理對比，並演練路由、預設、認證和請求上限。CI 在 Node.js 22 和 24 上跑 SDK 檢查。

極小的隨機權重驗證的是傳輸和數值一致性，不是預訓練質量或效能。

設定、示例和 npm 釋出見 SDK 指南。 這個包會以 laya-client 這個名字釋出。Python 的釋出工作流不變。