TypeScript SDK の設計
laya-client は、自前でホストする laya-serve サーバー向けの依存関係のない HTTP
クライアントです。POST /v1/systemone エンドポイントを使い、Python の本番コードや
サーバー依存を追加しません。
npm パッケージは 0.1.0 から始まり、Python のリリースとは独立しています。
境界
| コンポーネント | 責務 |
|---|---|
sdk/typescript |
質問/回答の型、プリセット、検証、ネイティブ fetch、エラーとキャンセル |
laya/serve.py |
既存の HTTP エンドポイント、Bearer 認証、ヘルスチェックとリクエスト上限 |
laya/router.py |
チェックポイントの選択、読み込み、推論のルーティング |
laya/agent.py |
トークナイズ、PyTorch 推論、キャリブレーション済みの回答整形 |
laya/presets.py |
生成される 5 つの TypeScript 質問プリセットのソース |
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、
宣言ファイルを同梱し、推論された質問 ID と choice ラベルを保ちます。JavaScript や
TypeScript のアプリケーションが HTTP 経由で自前ホストの Python laya-serve と話す場合は
laya-client を使ってください。Python サーバーなしで、ローカルの ONNX ランタイムを通じて
JavaScript の中で直接推論を走らせる必要がある場合は laya-ts を使います。
共有される契約
リクエストには state と questions が含まれます。設定も予測のために供給もされない限り、
laya-client は model を省略し、laya-serve にローカルのチェックポイントを自動で選ばせます。
クライアント全体または呼び出しごとの model でローカルのチェックポイントを選べます。以下の表にある他のリクエストごとの制御も同様です。choice
ラベルの配列は、転送前に null の説明を持つマップへ正規化されます。
レスポンスは model、answers、token の usage を保ちます。Laya の routing と回答の
action フィールドは任意の拡張です。Noul の信頼度も任意です。choice と score の信頼度、
分布、score のレベル説明は必須のままです。すべての答えは answer_confidence、つまり報告された答えに乗る max(p) の質量を伴います。これは 3 つの質問タイプすべてで同じ量です。min_confidence が渡された呼び出しは、各答えに abstention と abstention_threshold を、しきい値を下回るものには low_confidence: true を報告します。しきい値が設定されていなければ、これら 3 つのキーはどれも送られず、その不在こそがレポートです。任意の拡張は、存在する場合に検証されます。
/v1/systemone はクライアントが呼ぶ唯一のエンドポイントで、単体のルーティングメソッドはありません。laya-client は predict と health だけを公開し、それ以外は何もありません。ライブ統合テストは、サーバーが /v1/route に対して 404 を返すことを検証します。このエンドポイントが実際に受け付ける制御はリクエストごとで、呼び出し元がそのオプションを供給したときにだけ送られます。欠けているオプションは、クライアント側の既定で上書きするのではなく、デプロイ自身の Router(...) 設定をそのまま有効にします:
| オプション | リクエストフィールド |
|---|---|
model |
model |
task |
task |
lang |
lang |
langGuess |
lang_guess |
maxLen |
max_len |
headMaxLen |
head_max_len |
minConfidence |
min_confidence |
意味を持ちえないオプションは、リクエストが出る前にローカルで拒否されます。空の task、正の整数でない予算、[0, 1] の外側のしきい値、または空であるか [0, 1] の外側の値を含むしきい値マップです。何も黙って無視されません。Laya の公開 /health は status、loaded、revisions、device、device_is_preference、checkpoint_devices、cpu_fallbacks を返します —— laya-serve のデプロイのページが記載するのと同じ 7 つのキーです。HTTP API を参照してください。予測が最初に health を試すことはありません。
FastAPI の詳細文字列と検証配列は LayaAPIError のメッセージ/詳細として保たれます。互換
バックエンドからの構造化エラー envelope も受け付けます。リクエストには設定可能な期限と
呼び出し元によるキャンセルがあり、自動で再試行されることはありません。
検証とリリース
ユニットテストは、リクエストの構築、すべての回答形状、Laya の拡張、FastAPI のエラー、
JSON 検証、期限、キャンセルを対象とし、このページの制御表を、クライアントが実際にワイヤに載せるフィールドに固定します。型チェックは、任意のメタデータ、推論された回答型、ESM/CommonJS の利用者を対象とします。
ライブ統合テストは、変更していない laya.serve アプリケーションを小さなオフライン
チェックポイントで起動し、SDK の予測を直接の Python 推論と比較し、ルーティング、プリセット、
認証、リクエスト上限を実際に動かします。CI は Node.js 22 と 24 で SDK のチェックを
実行します。
小さなランダム重みは、転送と数値の一致を検証するものであり、事前学習済みの品質や性能を 検証するものではありません。
セットアップ、例、npm への公開については
SDK ガイド を
参照してください。パッケージは laya-client という名前で公開される予定です。Python の
リリースワークフローは変わりません。