ドキュメント

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 の リリースワークフローは変わりません。