ドキュメント

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を参照してください。