HTTP API
laya-serve は Laya を TypeSafe Jev の /v1/systemone ワイヤプロトコルで公開します。Jev 向けに書かれたクライアント —— hs-jev、typesafe-sdk、自作のもの —— は、ベース URL をこのサーバーに向けるだけでそのまま動きます。Laya の predict() の出力はすでにスキーマ互換で、サーバーが足すのは HTTP の表面だけです。意思決定のルートが 1 つ、ヘルスプローブ、任意の bearer チェック、リクエスト制限です。
laya-serve を対象にしたクライアントが PHP にもあります。marcreichel/laya-php は Composer SDK(PHP 8.4+)で、enum と属性のクラスを質問に対応づけてインスタンスを返し、デプロイ確認のために GET /health を読み、サーバーを起動せずに単体テストできるテスト用フェイクも同梱します。
pip install "laya[serve]"
laya-serve # http://0.0.0.0:8000
同じエントリポイントは任意の ASGI サーバーに埋め込んで動きます。laya.serve.create_app() が FastAPI アプリを構築し、任意で環境から作ったものではなく注入した Router を使えます(create_app(router))。
設定
すべて環境変数なので、1 つのイメージがノート PC の開発実行と systemd ユニットの両方を担えます。
| 環境変数 | 意味 | 既定 |
|---|---|---|
LAYA_HOST |
バインドアドレス | 0.0.0.0 |
LAYA_PORT |
バインドポート | 8000 |
LAYA_ROOT_PATH |
リバースプロキシの背後で提供するときの公開 URL プレフィックス | 空 |
LAYA_DEVICE |
すべてのチェックポイントの torch デバイス | auto |
LAYA_PRELOAD |
起動時にチェックポイントを構築する(遅延ではなく) | 1 |
LAYA_MODELS |
プリロードするカンマ区切りリスト(english,multilingual,typed-decisions)。空 = すべて |
すべて |
LAYA_THREADS |
CPU での torch の intra-op スレッド数を制限します。物理コア数以下に保ってください —— 論理コアへの過剰割り当ては大きな劣化です | torch の既定 |
LAYA_AUTO_TASK |
typed-decisions チェックポイントへ自動ルーティング | 0 |
LAYA_IDLE_UNLOAD_SECONDS |
この秒数だけアイドルが続いたら常駐チェックポイントをアンロードします。次のリクエストでそのチェックポイントを再びロードします。0 でアンロード無効 | 0 |
LAYA_MAX_LOADED |
同時に常駐させるチェックポイント数。ルーティングが選ぶ数より低い上限は切り替えごとに 1 つを再構築させ、preload() は構築するものを保持するために上限を引き上げます |
2 |
LAYA_MAX_TOKEN_BUDGET |
リクエストごとの max_len と head_max_len の上書きに対するサーバー側の天井。それより大きい値は 422。解析できない値や非正の入力は警告をログしてフォールバックします |
8192 |
LAYA_DEFAULT_MODEL |
言語の手がかりがない state がフォールバックするチェックポイント。ml のようなエイリアスは core が解決するのと同じように解決され、解決できない名前は起動時にサーバーを停止させます |
english |
LAYA_EXTRA_MODELS |
同梱のチェックポイントに加えて追加のチェックポイントを登録する JSON オブジェクト {name: source}:文字列としての Hub リポジトリ ID かローカルのチェックポイントディレクトリ、または ["repo", "subfolder"] のペア。名前は組み込みと同じ model= の固定を受けます。不正な値や不正な名前は起動時にサーバーを停止させます |
なし |
LAYA_API_KEY |
設定すると Authorization: Bearer <key> を要求します |
なし |
LAYA_LOG_LEVEL |
uvicorn のログレベル | info |
LAYA_MAX_CONCURRENT |
認証を通過して同時に受け入れるリクエスト数。超過分は 503 |
16 |
LAYA_MAX_BATCH_TOKENS |
1 回の /v1/systemone/batch フォワードパスがまとめてよいトークン数(states x 質問数 x 行幅)。これより大きいバッチは拒否されず複数のパスに分割されます |
131072 |
LAYA_JEV_STRICT |
厳格な Jev ワイヤ契約で提供します。ルートの routing なし、答えごとの action / answer_confidence なし、noul の答えの confidence なし、usage は input_tokens + output_tokens に縮小。余分なフィールドなしでレスポンスを Jev 契約に検証するクライアント向け |
0 |
/laya のようなプレフィックスの下で公開するデプロイでは、LAYA_ROOT_PATH=/laya を設定します。FastAPI は OpenAPI と Swagger UI の URL を生成するときにこれを使います。Laya へリクエストを転送する前に /laya を剥がすようリバースプロキシを設定してください。アプリのルートは内部的には /health と /v1/systemone のままです。
CUDA や ARM64 のイメージを含むコンテナについては Docker クイックスタートを参照してください。
突発的なローカル利用には LAYA_IDLE_UNLOAD_SECONDS=300 を設定します。推論とアンロードは同じ worker で走り、単一またはバッチのフォワードパスが終わると(失敗したリクエストも含めて)アイドル窓が再び始まります。次の予測はコールドロードのコストを払います。アンロードはモデル参照とデバイスキャッシュ(Metal を含む)を解放しますが、プロセスのアロケータは RAM ページを保持することがあるため、プロセスの RSS がチェックポイントのサイズ分だけ下がるとは限りません。
エンドポイント
GET /health
常に開いていて(認証なし)、推論中も応答し続けます。CPU 依存のフォワードパスがイベントループではなく専用の worker で走るからです。liveness より下のフィールドは、LAYA_API_KEY を設定したデプロイでは開いていません。bearer なしでは /health は {"status": "ok"} だけを返し、それ以外は何も返しません。残りは常駐チェックポイント、その正確なリビジョン SHA、デバイス状態、各チェックポイントの最後のフォールバック理由を名指しし、それはホストのハードウェアを引用するからです。プローブに必要なのは 200 だけなので、ヘルスチェックは影響を受けず、誤った bearer でも 401 ではなく依然として 200 です。LAYA_API_KEY が未設定なら、どの呼び出し元にもここに示す完全なペイロードが返ります。
{"status": "ok", "loaded": ["english", "multilingual"], "revisions": {"english": "...", "multilingual": "..."},
"device": "cuda", "device_is_preference": false,
"checkpoint_devices": {"english": "cuda", "multilingual": "cuda"},
"cpu_fallbacks": {"english": {"count": 0, "last_reason": null}, "multilingual": {"count": 0, "last_reason": null}}}
ある 1 台のサーバーの答えなので、各ブロックは互いに整合します。revisions、checkpoint_devices、cpu_fallbacks のすべてのキーは loaded 内の名前です。tests/test_serve.py がこのサンプルを、それを生成するハンドラに対してフィールドごとに固定しています。
アイドルアンロードが有効なときは、認証済みの health レスポンスに idle_unload_seconds(設定された窓)と idle_seconds(最後の推論リクエストまたは完了からの経過時間)も含まれます。ヘルスプローブはその時計をリセットしません。アイドルアンロード後の空の loaded リストは正常です。
statusはプロセスが応答する限り常にokです。チェックポイントについては何も述べていません。loadedはメモリに常駐するチェックポイントを列挙します。リクエストが 1 つ構築するまでは空で、LAYA_PRELOAD=0はプロセスをその状態のままにします。revisionsは常駐チェックポイント 1 つずつが読み込まれた成果物リビジョンで、loadedと同じ名前をキーにします。これでデプロイは実際に何を提供しているかを確認できます。deviceは常駐チェックポイントが実際に計算するデバイスで、LAYA_DEVICEが要求したものとは限りません。得られない GPU を求めるチェックポイントは黙って CPU にフォールバックし、それでも正しく答えます。何も常駐していなければ、代わりに設定された設定値になります。device_is_preferenceは何も常駐していない間だけtrueで、ハンドラが測定できるようになるとすぐfalseになります。それが、設定を報告するサーバーと仕事の場を報告するサーバーの違いです。GPU を静かに失ったサーバーは、cudaと答え続けるのではなく、deviceがcpuでfalseと言います。checkpoint_devicesはチェックポイントごとの測定値を、loadedの名前をキーに与えます。deviceはそれらの値の最初のものです。cpu_fallbacksは常駐チェックポイントごとに、GPU メモリを使い果たして CPU で 1 度だけ再試行されたリクエストを数えます。countはプロセス開始以降、last_reasonは最新のもののエラーテキストです。降格は失敗したリクエストに限定されるので、GPU がそもそも利用できなかったために CPU で構築されたチェックポイントはフォールバックではなく、ここでは0を数えます —— それはdeviceに現れます。
POST /v1/systemone
1 つのリクエストが state と、それに対する任意個の質問を運びます。
curl -s localhost:8000/v1/systemone -H 'content-type: application/json' -d '{
"state": "I was charged twice this month, I want my money back",
"questions": {
"queue": {"type": "choice", "instructions": "Which team?",
"criteria": {"billing": "billing and refunds", "tech": "login and app issues",
"other": "everything else"}},
"urgency": {"type": "score", "instructions": "How urgent?",
"criteria": ["calm", "firm", "angry", "furious"]}
}
}'
| フィールド | 必須 | 意味 |
|---|---|---|
state |
はい | 判断対象のテキスト、メール、チケット、JSON 文書。欠落または null の state は 400 |
questions |
はい | 質問 id をキーにしたオブジェクト。各質問は instructions と criteria を持つ choice / score / noul |
model |
いいえ | チェックポイントを名指しします。パスや未公開の Hub id は 422、それ以外の値は無視されます(下記参照) |
task |
いいえ | ルーティングに任せずワークフロー名でチェックポイントを強制します。未知の名前はそれを名指しする 422 |
lang |
いいえ | 言語を名指しするときに検出をスキップする言語コード(de、en-US)。空または認識できないコードは検出に流れます |
lang_guess |
いいえ | クライアント自身の識別子による言語コード。lang の後、検出の前に参照されます。英語以外のコードは多言語チェックポイントへルーティングされます |
max_len |
いいえ | このリクエストのトークン窓の合計。LAYA_MAX_TOKEN_BUDGET で上限されます |
head_max_len |
いいえ | 選択肢プロンプトが共有するトークン窓。同じ上限。ある質問がそれを必要とするのはいつかは トークン予算の拡張を参照 |
min_confidence |
いいえ | 棄権しきい値:[0.0, 1.0] の数値、または選択肢数のバケットをキーにしたバケットごとのマップ({"choice:3-5": 0.9, "default": 0.4})で、選択肢数によってしきい値を変えられます。answer_confidence が自身のしきい値を下回る答えは low_confidence の印を付けて返り、答え自体は保持されます |
model、task、lang、lang_guess、max_len、head_max_len、min_confidence は、JSON ボディが述べられる Router.predict の引数です。それぞれはリクエストが送ったときにだけ転送されるので、欠けていればそのデプロイ自身の Router(...) 設定が支配します。predict が取る 5 つのフック引数 —— hooks、on_predict_start、on_predict_end、hooks_raise、hooks_timeout —— は黙って捨てられるのではなく 422 で拒否されます。フックはサーバープロセス内で走る callable であり、最後の 2 つはデプロイがインストールしたフックがどう実行されるかを述べるもので、呼び出し元が送る値にここでの意味はありません。同じ 5 つは base_url を持つ LangChain ノード(laya.integrations.langchain)でもクライアント側で拒否されるので、チェーンと生の HTTP クライアントが同じ答えを得ます。
model を受け付けるのは、Jev クライアントがそれを送り続けられるようにするためです。公開 Hugging Face の id(convaiinnovations/laya-multilingual、convaiinnovations/laya-typed-decisions)、チェックポイント名(english、multilingual、typed-decisions)、およびそれらのエイリアスがチェックポイントを選びます。このサーバーの Router に LAYA_EXTRA_MODELS が登録したすべての名前も同様です —— 組み込みを指し直す名前も含み、これがコード変更なしにファインチューンを english の下で提供する方法です。convaiinnovations/laya、およびパスや Hub リポジトリ id でないその他の値 —— jev-1 のような Jev の id を含む —— は「router に選ばせる」という意味で、レスポンスの routing ブロックが何がなぜ選ばれたかを記録します。ファイルシステムのパスや未公開の Hub id に見える値(/path/to/checkpoint、org/repo、~/ckpt、.\ckpt)は /v1/systemone と /v1/systemone/batch の両方で 422 です。このサーバーはそれをロードできず、別のチェックポイントで答えるとそれを隠してしまうからです。detail は core が送出するのと同じ unknown model のテキストに、router に選ばせるには model を省くという注意を加えたものです。
レスポンス
{
"model": "laya-rl-agent",
"answers": {
"queue": {"type": "choice", "choice": "billing",
"probabilities": {"billing": 0.9519, "tech": 0.0327, "other": 0.0154},
"confidence": 0.797, "answer_confidence": 0.9519,
"action": {"act_probability": 1.0}, "x_jev_confidence": 0.9278},
"urgency": {"type": "score", "score": 1.6994,
"legend": {"0": "calm", "1": "firm", "2": "angry", "3": "furious"},
"probabilities": {"0": 0.0249, "1": 0.4136, "2": 0.3985, "3": 0.1629},
"confidence": 0.1925, "answer_confidence": 0.4136,
"action": {"act_probability": 1.0}, "x_jev_confidence": 0.2507}
},
"usage": {"input_tokens": 83, "output_tokens": 0, "state_tokens": 12,
"state_tokens_dropped": 0, "truncated": false, "truncated_questions": []},
"routing": {"model": "english", "repo": "convaiinnovations/laya", "reason": "English Latin text",
"detection": {"script": "latin", "script_profile": {"latin": 1.0}, "language": "en",
"is_english": true, "language_undecided": false, "diacritic_rate": 0.0,
"non_latin_fraction": 0.0, "mixed_segment": null},
"workflow": null}
}
このサンプルは、このサーバーが実際に返した 1 つの答えをそのまま載せたものです。上のリクエストを、CPU 上のキャッシュ済み english チェックポイントで処理したものです。answers と usage は Jev クライアントがデコードするキーです。model は意思決定ヘッドの定数名で、答えたチェックポイントは routing にあります。
| 答えの型 | キー |
|---|---|
choice |
choice(argmax の選択肢)、選択肢ごとの probabilities、x_jev_confidence |
score |
score(期待水準インデックス。水準の間に落ちることがあります)、"0".. "k-1" をキーにした probabilities、インデックスを水準テキストへ対応づける legend、x_jev_confidence |
noul |
noul、yes の選択肢の確率 |
| すべて | type(判別子で、質問自身の型を反映します)、confidence、answer_confidence、action.act_probability |
| gate | abstention、abstention_threshold、low_confidence。棄権ゲートが書き込みます —— 下記参照 |
gate の行は棄権レポート(#361)で、呼び出し元が、支払ったゲートが走ったことを確認できる唯一の方法です。min_confidence を設定したリクエストはそれを得て、設定しないものは 3 つのキーのどれも得ません。abstention は 3 つの状態のいずれかで、ゲート付きリクエストのすべての答えに書かれます。passed(その信頼度がしきい値を上回った)、abstained(下回り、ちょうどそれらの答えで low_confidence が true)、または unevaluated(答えが使える信頼度を持たず、ゲートが判断できなかった —— それを pass として報告するのは、flag として報告するのと同じ嘘です)。abstention_threshold はそれらの状態を測ったしきい値をそのまま返し、それがあるのでクラスごとのしきい値でのバッチ実行が事後に再分割できます。min_confidence が未設定なら 3 つのキーはどの答えにも現れません。不在がレポートであり、4 つ目の状態ではなく、呼び出し元がゲートなしの実行とクリアされたゲートを見分ける方法です。ちょうど 0.0 の min_confidence は設定されているので状態が報告され、何もそれを下回れないのですべての答えが passed と読めます —— 返された 0.0 が、それを実際のしきい値での pass と区別するものです。答え自体はどの状態でも保持されます。ゲートは印を付けるだけで、落としません。
usage はフォワードパスが何から組み立てられたかを報告します。モデルが state のどれだけを読むかはトークン予算であって文字数ではなく、予算は max_len、head_max_len、そして各質問自身の選択肢プロンプト(#174)で動くので、これらのキーがその事実の見える唯一の場所です。
usage のキー |
意味 |
|---|---|
input_tokens |
state の行の非パドトークン —— 質問ごとに 1 行なので、コンテキスト長ではなく質問とともに増えます |
output_tokens |
常に 0 —— ヘッドは 1 パスで答え、何も生成しません |
state_tokens |
シリアライズされた state 全体が必要とするトークン |
state_tokens_dropped |
そのうち少なくとも 1 つの質問が得られなかったトークン。質問ごとに state に残す余地が違うので、質問全体での最悪ケースです |
truncated |
その最悪ケースが何かを落としたとき true |
truncated_questions |
自身の窓が切られた質問の id。なければ [] |
options |
ある質問の選択肢がもはやそれぞれトークン幅を持たないときにだけ現れます。質問 id をキーに、total(その質問が定義する選択肢数)、distinct(系列に届いた幅の数)、tokens_per_option を持ちます |
切り詰められた答えも答えです —— ヘッドは与えられた証拠で判断します —— ただし文字数で state を測る呼び出し元は、レスポンスのどこにもその切れ目を見られません。
routing はどのチェックポイントがなぜ答えたかを記録します:
routing のキー |
意味 |
|---|---|
model |
答えたチェックポイント: english、multilingual、typed-decisions |
repo |
どこから読み込まれたかで、repo または repo/subfolder の形です。既定のサーバーは 3 つすべてを convaiinnovations/laya バンドルから読み込むので、multilingual と typed-decisions は convaiinnovations/laya/multilingual と convaiinnovations/laya/typed-decisions を報告します —— 読みやすい id であり、取得に使う Hub リポジトリ id ではありません |
reason |
選択のための文で、働きかけた証拠を名指しします |
detection |
state に対する laya.lang.analyse() —— script、script_profile、language、is_english、language_undecided、diacritic_rate、non_latin_fraction、mixed_segment —— またはルートがテキストを読む前に決めたときは null |
workflow |
質問 id が一致する typed-decisions ワークフロー、または null |
detection は state を読まずに決めるすべての経路で null です。model や task で強制されたもの、lang や lang_guess で答えたもの、質問 id から typed-decisions ワークフローに一致したものです。lang_guess はそれ自身のキーを残しません —— 働きかけたヒントは reason に名指しされます。model と task の分岐も workflow を null と報告します。質問 id が読まれる前に答えるからです。
信頼度:3 つの数値は交換できません
answer_confidenceは報告された答えに載る確率の塊(max(p))です。temperature スケーリングが当てはめる量であり、このリポジトリの ECE の数値が計算される量でもあるので、ベンチマークと既知の制約ページが依拠するゲートの性質を担います —— ただし自分のトラフィックで temperature の当てはめが検証済みのチェックポイントに限ります。confidenceは型ごとに意味が異なります。choiceとscoreでは正規化エントロピー1 - H(p)/log(k)、noulではmax(p_yes, p_no)です(ここではanswer_confidenceと等しくなります)。x_jev_confidenceは、同じ確率に対して Jev が報告するであろうconfidenceで、choiceとscoreの答えにだけ付きます(Jev のnoulの答えに confidence はありません)。TypeSafe 自身の式を使います:choiceでは(p_max - 1/n)/(1 - 1/n)、scoreでは最も確からしい水準からの確率重み付き距離を 1 から引き、一様分布に対する同じ距離でスケールしたものです。
3 つを 1 つのしきい値で比較しないでください。Jev から移植するとき、Jev のデプロイから持ち込んだしきい値は Laya のエントロピーの confidence に対しては別のゲートの仕方をします(#302)。代わりに x_jev_confidence と突き合わせてください。x_ の接頭辞は、Jev が後で加えるどんな名前ともこのフィールドが衝突しないようにします。
厳格な Jev 契約:LAYA_JEV_STRICT
上のペイロードは完全な Laya ペイロードです。クライアントがそれを準拠させる Jev 契約は、それより少なく定義します。トップレベルの 3 フィールド(model、answers、usage)、各答えの契約されたキーだけ、そして 2 つのトークン数の usage です。余分なフィールドなしでその契約に対してレスポンスを検証するクライアント —— OpenClaw の TypeSafe プロバイダプラグインがその 1 つ —— は完全なペイロードを拒否するので、LAYA_JEV_STRICT=1 は答える前にレスポンスを契約へ射影します。/v1/systemone と /v1/systemone/batch の両方です。
- ルートは
model、answers、usageだけを保ちます。routingは送られません。 choiceの答えはtype、choice、probabilities、confidenceを保ちます。scoreの答えはtype、score、probabilities、confidence、legendを保ちます。noulの答えはtypeとnoulを保ちます。usageはinput_tokensとoutput_tokensを保ちます。切り詰めの事実と圧縮された選択肢の上限は送られません。x_jev_confidenceは、他の追加分と同じく送られません。
射影は契約されたキーだけを保ち、何も再計算しません。すべての値は結果がすでに持っているもので、厳格なクライアントが読む確率とスコアは完全なペイロードが報告するものと同一です。既定は完全なペイロードのままで、フラグを有効にしたデプロイは usage が提供する切り詰めの可視性を失います —— 切れた state はそのときレスポンスではなくログに見えます。厳格な契約の下では score の criteria はプレーンな文字列のままにすべきです。厳格なクライアントは返された legend を送った criteria と比較し、Laya は構造化された criterion を Python の JSON で描画しますが、自分の criteria を文字列化する JavaScript の呼び出し元はそれをバイト単位で一致できないことがあります。
成功したレスポンスは Server-Timing: inference;dur=<ms> と X-Inference-Time-Ms も運びます。
制限
リクエストのガードレールはトークン化の前に検査されるので、大きすぎるリクエストはサーバーに読んだバイト以外のコストをかけません。下のサイズ制限はすべて 413 で、detail がどの制限に当たったかを述べます。最後の行だけが例外です。同時実行の上限はサイズではなく受け入れの制限で、Retry-After: 1 とともに 503 を返します。
| 制限 | 値 |
|---|---|
| リクエストボディ | 2 MiB。ストリーミング中に強制 —— チャンク化や過少申告の Content-Length では回避できません |
state |
モデルに与えるテキストの 50,000 文字 —— 文字列の state ならその文字列そのもの、オブジェクトや配列なら json.dumps(state, ensure_ascii=False) |
| リクエストあたりの質問数 | 64 |
バッチリクエストあたりの states |
64 |
choice の質問あたりの選択肢数 |
100 |
score の質問あたりの水準数 |
32 |
| すべての質問を通じた選択肢数 | 512 |
同時に受け入れるリクエスト数(503、413 ではない) |
LAYA_MAX_CONCURRENT(16) |
/v1/systemone/batch は別の形で境界づけられ、拒否によってではありません。各 state を質問ごとに 1 度トークン化し、すべての行を 1 つのテンソルにまとめるので、フィールドの上限が掛け算になります。64 states の 64 質問は 4096 行で、このページの他のどの制限もそれを許します。1 行のコストはその幅で、max_len 自体がリクエストフィールドなので、バッチのコストは states x questions x width です。
大きいバッチを拒否する代わりに、エンドポイントはそれを分割します。その積が LAYA_MAX_BATCH_TOKENS(既定 131,072)を超えると、各フォワードパスが予算内に収まるように batch_size を選び、Router.predict_batch がバッチを複数のパスで実行します。どの state も依然として答えられ、レスポンスは変わりません。行がすでに収まるリクエストには batch_size がまったく渡されないので、以前とまったく同じに振る舞います —— これは重要です。バッチの形が浮動小数点の結果を動かしうるからです。呼び出し元が送る batch_size は常に優先されます。それは形を求めたのです。
既定では 256 行が 1 パスで通ります —— 64 states の 4 質問、または 8 の 32 質問です。それより大きいバッチは分割され、max_len を上げると 16 倍の仕事になるのではなく各パスが狭くなります。これが制限しないのは、1 つのリクエストがサーバーを占める時間です。それは LAYA_MAX_CONCURRENT と単一の推論 worker であり、50,000 文字の state にわたる 1 つの /v1/systemone リクエストについてすでに真です。
選択肢の上限は HTTP 専用の増幅ガードです。モデル自身は選択肢のトークンを head_max_len=192 の窓に収めるので、HTTP の上限内の質問でも、選択肢のテキストが合計でその予算を超えると 422 で拒否されえます。評価ハーネスは同じリクエストを HTTP 層なしでインプロセスで実行します。
エラー
| ステータス | いつ | ボディの detail |
|---|---|---|
400 |
ボディが有効な JSON でない、オブジェクトでない、questions がない、state が欠落または null、questions がオブジェクトでない、またはボディ内のどこかの文字列が対になっていない \udXXX サロゲートエスケープを含む |
何がおかしいか |
401 |
LAYA_API_KEY が設定されていて bearer トークンが欠落または誤り |
invalid or missing bearer token |
413 |
上記のいずれかの制限 | どの制限がどれだけ超過したか |
422 |
質問が整形式の JSON だが Laya にとって不正(未知の型、head 予算を超える選択肢)、またはリクエスト制御(lang、min_confidence、フック引数)がこのエンドポイントの受け付ける形でない |
質問かフィールドを名指しし、何を直すか |
500 |
その他の理由で推論が失敗 | inference failed —— 常にこの文字列なので、パス・重み・メモリの状態が決して漏れません。原因はサーバーログにあります |
503 |
LAYA_MAX_CONCURRENT 個のリクエストがすでに処理中 |
server busy, try again later |
対になっていないサロゲートの 400 は珍しく見えるものです。対のない \udXXX は合法な JSON ですが、それが名指す文字は UTF-8 にエンコードできず、トークナイザーが TypeError を送出します —— 呼び出し元自身の文字列が、リクエストごとにトレースバックを伴うサーバーの障害として届くのです。そこで両方の意思決定ルートは解析済みボディを走査して孤立したサロゲートを見つけ、推論に届く前に拒否します。走査はサイズ検査の後に走るので、大きすぎるボディは依然として先に拒否され、文字と質問の制限がそれが届く範囲を制限します。対になったサロゲートは、パーサーが終えた頃には 1 つの普通の補助文字なので、state 内の絵文字は影響を受けません。
上限超過の負荷はキューされずに拒否されます。遅いボディをストリーミングしながら受け入れスロットを保持するクライアントが /health を飢えさせられず、拒否されたクライアントが残したスロットを再試行が取れます。
並行モデル
推論は CPU で数百ミリ秒から秒単位かかる同期の torch 呼び出しなので、イベントループでは決して走りません。リクエストは単一 worker の executor に渡され、一度に 1 つのフォワードパスになります —— 1 つのデバイス上の 1 つのチェックポイントが望む形です。受け入れ(LAYA_MAX_CONCURRENT セマフォ)はボディのどのバイトも読む前に検査され、推論を通じて保持されます。推論ゲートはボディが完了した後にだけ取得されるので、遅いクライアントは受け入れスロットは保持しても推論スロットは決して保持しません。
まだここにないもの
このサーバーは意図的に 1 つのプロトコルだけを話します。OpenAI 互換のエンドポイントはありません。代わりに 1 つのリクエストで複数の質問を実行してください。質問セットごとに 1 回のフォワードパスを共有するからです。もう 1 つのルートは POST /v1/systemone/batch で、states の配列に対して 1 つの questions セットを答えます。このページにはまだ節がありません —— そのリクエスト形状は README のセルフホスティングの節にあります —— そして上のすべての検査が POST /v1/systemone に対するのと同じように適用されます。同じ形の 400、同じ unpaired-surrogate 拒否、同じ auth、admission、サイズ制限、body-control 検証、500 マッピングです。laya CLI と MCP サーバーがローカルの用途を担います —— READMEを参照してください。