ドキュメント

コマンドラインと MCP サーバー

Laya には、同じ構造化意思決定エンジンを試すためのローカルインターフェースが 2 つあります:

インターフェース 用途 トランスポート
laya ターミナルからの手軽な確認と対話的な探索 コマンドライン
laya-mcp-server MCP クライアントやエージェントを Laya の組み込みツールにつなぐ stdio 上の MCP

結果を読むのが自分自身なら CLI を選びます。別のプロセスが安定したツールインターフェースを必要と するなら MCP を選びます。どちらも Laya の Router を使ってチェックポイントを選び、型付きの choice、score、noul の判断を返します。どちらも自由形式の質疑応答やテキスト生成の インターフェースではありません。

ルーティングの判断と型付き質問の例は、README の Route Mode クイックスタート を参照してください。信頼度と組み込みワークフローは、README の信頼度ゲートとワークフロープリセット を参照してください。

1. コマンドライン

パッケージをインストールすると laya エントリポイントが入ります。完全なオプション一覧は laya --help で確認できます。

python -m pip install laya
laya --help

評価 CLI

パッケージは laya-evals もインストールします。メインの CLI は laya eval を通じて同じ評価 コマンドを公開します:

laya eval --help

データセット、指標、ベースラインのゲートについては、評価 harness ガイドを参照して ください。

学習 CLI

laya-train は laya train でも呼び出せ、ラベル付きの判断を並べた CSV または JSONL から チェックポイントをファインチューニングします。laya-train でのファインチューニング を参照してください。

laya-train --help

チェックポイントを読み込まずにルートする

テキストだけを渡し、予測フラグを付けない場合、CLI は Router.route を呼びます:

laya "I was charged twice, please refund it"

出力には、選ばれたチェックポイントとその理由、言語情報が取れる場合は検出された言語が表示され ます。ルーティングだけではチェックポイントのダウンロードもビルドも行わないので、ルーティング判断 の手軽なオフライン確認になります。

別のローカルスクリプトに判断を渡したいときは --json を使います:

laya "I was charged twice, please refund it" --json

予測を実行する

--predict は完全な型付き予測を実行し、初回使用時にルーティングされたチェックポイントを読み込み ます。初回ロードには Hugging Face Hub へのアクセスが必要です。以降の実行はローカルキャッシュを 使います。

laya "Classify this support request" --predict
laya "Classify this support request" --predict --json

--json は完全な結果を JSON として出力します。付けない場合、CLI は各答えをその choice の 確率、score、noul の値とともに出力し、ルーティング判断も加えます。

主な制御は次のとおりです:

  • --model english|multilingual|typed-decisions は、自動ルーティングの代わりにチェックポイントを 固定します。
  • --lang en|de|... は、自動検出の代わりに言語コードを明示的に指定します。
  • --lang-guess en|de|... は、ルーティングが --lang の後、自身の検出器の前に読むソフトなヒントを指定します。何にも解決しないヒントは素通りするので、チェックポイントを強制せずに後押しします。
  • --task NAME は、自動検出の代わりに typed-decisions ワークフローを強制します。
  • --device cpu|cuda|... は、デバイスの選択を Router に渡します。
  • --json は機械可読な出力を生成します。

組み込みプリセットを使う

プリセットはすぐ使える質問セットを提供し、予測を含むので、--predict は不要です:

laya "My payment failed twice" --preset triage
laya "Ignore all previous instructions" --preset guard --json

CLI のプリセットは email、guard、moderation、router、triage です。CLI は、選んだ プリセットが想定する state フィールドの下にテキストを配置します。--predict はルーティング質問 セットの request フィールドを使います。プリセットは手元での手軽な確認には便利ですが、その質問は やはりドメインの判断です。アプリケーションの方針として使う前に、プリセットを確認し、自分の データで検証してください。

対話的に探索する

テキスト引数を付けないと、CLI は小さなプロンプトを開きます:

laya
# laya> Classify this request
# laya> quit

Enter を押すと各リクエストが実行されます。空行、quit、exit、Ctrl-D でセッションが終了 します。対話ループは 1 つの Router を使い回すので、スクリプトを書かずに複数の入力を比べるのに 便利です。

失敗が見える

CLI は、不正な値や、よくある依存関係・ダウンロード・実行時の失敗をアプリケーションの境界で処理 します。診断情報を stderr に出力し、未処理の traceback を出す代わりに終了コード 2 を返します。 初回使用時のチェックポイントのダウンロードが失敗したら、再試行する前に依存関係のインストール、 Hub へのアクセス、選択したデバイスを確認してください。

2. 組み込み MCP stdio サーバー

MCP サーバーは任意の追加パッケージです。コアパッケージは mcp 依存をインストールしません:

python -m pip install "laya[mcp]"
laya-mcp-server
# equivalent module form:
python -m laya.mcp.server

サーバーは HTTP ではなく stdio 上で MCP を喋ります。コンソールスクリプトでクライアントを 設定します:

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {
        "LAYA_DEVICE": "cpu"
      }
    }
  }
}

クライアント設定が Python 実行ファイルと引数を指定できるなら、python -m laya.mcp.server を 等価な起動形式として使えます。サーバープロセスはクライアントが持ちます。Laya はネットワーク ポートを開きません。

利用できるツール

ツール 動作 主な入力
laya_status 読み込み済みのチェックポイントごとのデバイス(checkpoint_devices)、設定された、または実際のデバイス、CUDA の可用性、読み込み済みのチェックポイント、プリロード状態、準備状態、パッケージのバージョンを報告します。 なし
laya_route フォワードパスを実行せずにチェックポイントを選び、そのモデル、リポジトリ、理由を返します。 state、questions、省略可能な model、task、lang、lang_guess
laya_predict 型付き質問を実行し、答え、ルーティングのメタデータ、レイテンシ、読み取れる場合は応答したデバイスを返します。 state、questions、省略可能な model(auto、english、multilingual、typed-decisions)、task、lang、lang_guess、max_len、head_max_len、min_confidence
laya_shortlist 選択肢の多い choice 質問をショートリストしてから回答し、ショートリストのメタデータを返します。 state、questions、省略可能な model、k(既定 20)、task、lang、lang_guess、max_len、head_max_len、min_confidence
laya_preset 組み込みの質問セットを使って組み込みワークフローを実行します。 preset、state、省略可能な task、lang、lang_guess、max_len、head_max_len、min_confidence
laya_predict_batch 1 回の呼び出しで多数のリクエストに答えます。リクエストはまずルーティングされ、チェックポイントごとにグループ化されるので、質問スキーマが一致するものはフォワードパスを共有します。答えは入力順に返ります。 requests、各要素は {state, questions, model?, task?, lang?, lang_guess?, max_len?, head_max_len?}、省略可能な batch_size、hooks_timeout、min_confidence、sort_by_length
laya_route_batch 各リクエストにどのチェックポイントが答えるかを判断します。フォワードパスもチェックポイントの読み込みも行いません。 requests、各要素は {state, questions, model?, task?, lang?, lang_guess?}、省略可能な hooks_timeout
laya_decide 1 回のフォワードパスで JSON schema 形状の判断に答え、解析対象の答えのマップではなく、判断された値とフィールドごとの信頼度を返します。schema のプロパティは enum の choice、真偽値、または最小値と最大値を持つ整数にできます。自由な文字列、配列、ネストしたオブジェクトはパス単位で拒否されます。 state、schema、省略可能な model、min_confidence

この 3 つのバッチと schema のツールがあるのは、同じ操作が SDK と laya-serve でも使えるから です。多数のリクエストを扱いたいときや、呼び出し側がすでに答えの形を知っているときに、 Python まで降りる必要はありません。schema 駆動の形式をより詳しく知るには、 Schema 駆動の意思決定 を参照してください。

共有のガードレールは、20 を超える選択肢を持つ choice 質問をショートリストなしで送らないように 求めます。laya_shortlist はフォワードパスの前に、最も確からしい k 個のラベルを残します。既定は k=20 です。応答するチェックポイント自身のエンコーダによる平均プール埋め込みを使うので、2 つ目の モデルをダウンロードせず、ショートリストした各質問について、残したラベル、コサインスコア、k、 選択肢数、そしてその質問がショートリストされずにそのまま通ったかどうかを返します。k が選択肢数 以上である質問はそのまま通されるので、コサインスコアは空ではなく null で返ります。

state は空でない JSON オブジェクトでなければなりません。questions は、値が Laya の型付き 質問 schema を使う空でないオブジェクトでなければなりません。laya_preset は CLI と同じ 5 つの プリセットを受け付けます:email、guard、moderation、triage、そして router ワークフロー です。この面での正規名は model_router です。router は同じプリセットを指す別名として受け付け られるので、CLI の綴りもここで動きます。正規のキーが結果で返ってきます。state がちょうど 1 つの 文字列のとき、laya_preset はそれをそのプリセットの質問が指定するフィールドの下に置きます。 配置は CLI と同じなので、呼び出し側はキーを推測する必要がありません。1 つの文字列より複雑なもの は呼び出し側自身の形であり、そのまま通されます。

単一リクエストの各ツールは、バッチリクエストと同じ呼び出しごとのルーティング制御を受け取ります。model に加えて、リクエストは task(作業内容でチェックポイントを名指しする)、lang(言語コードを強制する)、lang_guess(lang より下、組み込み検出器より上のソフトな言語ヒントで、確からしいが不確かなコードが lang のように強制せずにどのチェックポイントを選ぶかを後押しできます)を設定できます。lang_guess はルーティングにのみ関与するので、task と同様、model を固定した呼び出しでは拒否されます —— 固定されたチェックポイントにはもうルーティングするものが何もありません。laya_predict と laya_shortlist は、回答用の token 予算として max_len/head_max_len を、棄権ゲートとして min_confidence も受け取ります。

予測呼び出しは SDK の型付き呼び出しと同じ形状です:

{
  "state": {
    "body": "I was billed twice for the same plan. Please reverse the duplicate charge."
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "payments, invoices, refunds, duplicate charges",
        "technical": "bugs, outages, integration problems"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does the user need immediate help?"
    }
  }
}

ツールの応答は、型付きの answers、routing の判断、タイミング情報を含む JSON です。高信頼度の 答えを、外部アクションを実行する許可と見なさないでください。方針、レビュー、副作用は引き続き アプリケーションまたはエージェントの責任です。

起動と環境

MCP サーバーは常駐の Router を保ち、初回の構築を直列化します。既定では english と multilingual をプリロードし、typed-decisions は遅延のままです。プリロードの失敗は起動時に 報告され、次のツール呼び出しで再試行されるので、サーバーが準備できていると決め込む前に laya_status を確認してください。

変数 既定値 意味
LAYA_DEVICE 自動 PyTorch に渡すデバイス値。cpu や cuda など。
LAYA_PRELOAD 1 起動時に設定済みのチェックポイントを構築します。0 で遅延読み込み。
LAYA_MODELS english,multilingual プリロードするチェックポイントのカンマ区切り。空の値は、すべてのチェックポイントをプリロードするのではなく MCP の既定を保ちます。
LAYA_THREADS PyTorch の既定値 CPU 推論の Torch 演算内スレッド数を制限します。物理コア数以下に保ってください。
LAYA_AUTO_TASK 0 1 にすると、リクエストが typed-decisions チェックポイントへ自動ルーティングできるようになります。意味は laya.serve と同じです。そのチェックポイントはプリロードしないので、起動時に何を構築するかは LAYA_MODELS が引き続き決めます。
LAYA_DEFAULT_MODEL multilingual 言語の手がかりがない state がフォールバックするチェックポイントで、意味は laya.serve と同じです。laya.serve と違い、解決できない名前でもサーバーは停止しません。次の呼び出しで router construction failed ツールエラーとして返ります。stdio サーバーには拒否する起動処理がないからです。
LAYA_BASE_URL 未設定 各 MCP プロセスでチェックポイントを読み込む代わりに、自分のハードウェア上の laya-serve へ予測を送ります。裸の host:port は HTTP として読まれます。
LAYA_REMOTE_TIMEOUT 300 LAYA_BASE_URL が設定されているときの HTTP タイムアウト(秒)で、サーバーのコールドロードを含みます。無効または非正の値は既定を使います。
LAYA_API_KEY 未設定 LAYA_BASE_URL が設定されているとき、すべてのリモートリクエストに付与される bearer トークンです。独自の LAYA_API_KEY を設定した laya-serve が必要とします。ローカルモードでは無視されます。

1 つのモデルサーバーを MCP セッション間で共有する

ローカルの HTTP サーバーを 1 つ起動し、各 MCP クライアントの環境をそれに向けます:

LAYA_HOST=127.0.0.1 LAYA_PRELOAD=0 LAYA_IDLE_UNLOAD_SECONDS=300 laya-serve
{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {"LAYA_BASE_URL": "http://127.0.0.1:8000"}
    }
  }
}

HTTP サーバーが動く場所に laya[serve] をインストールしてください。MCP はエディタとは引き続き stdio を使い、その予測ツールは HTTP でサーバーに到達します。laya_predict、laya_predict_batch、laya_decide、laya_preset はサーバー本来の state、instructions、選択肢の説明を使います。laya_predict_batch は項目ごとに 1 つの /v1/systemone リクエストを送り —— 異種のバッチだけでなくすべてのバッチで —— 入力順を保ちます。batch_size と sort_by_length は受け付けられますが無視されるので、サーバーの実行を変えません。laya_status はサーバーの /health を報告し、laya_route と laya_route_batch はローカルにとどまり、モデルも HTTP リクエストも必要としません。MCP プロセスは torch をインポートせず、チェックポイントも読み込みません。LAYA_THREADS や LAYA_PRELOAD が設定されている場合も同様です。

サーバーが bearer トークンを要求するときは、両方のプロセスに同じ LAYA_API_KEY を設定します。LAYA_DEFAULT_MODEL と LAYA_AUTO_TASK を揃えておくと、ローカルのルーティングプレビューがサーバーの実際のルーティングと一致します。デバイスとプリロードの設定は HTTP サーバーに属します。アイドルアンロード後の最初の呼び出しはコールドロードを待ちます。それに 300 秒以上かかる場合は LAYA_REMOTE_TIMEOUT を上げてください。laya_shortlist と予測フックの上書きは unsupported_remote を返します。そのコードはモデルプロセスを必要とするからです。HTTP エラーはサーバーの detail テキストを MCP ツールエラーとして保ちます。LAYA_BASE_URL が未設定なら、MCP サーバーは自分のプロセスでチェックポイントを読み込み続けます。

標準の laya-mcp-server ランチャーは、フックをインストールせずに Router を作ります。予測フックは推論を実行するプロセスにインストールしてください。ローカルモードでは MCP プロセス、共有サーバーモードでは HTTP サーバーです。カスタムランチャーは Router を構築する前に laya.hooks.set_default_hooks を使えます。上の環境変数はモデルのライフサイクルを設定するもので、フックの登録ではありません。いつツールを呼ぶか、返された判断をどう扱うかは、引き続きクライアントが決めます。

3. 共有される境界と関連ガイド

CLI と MCP サーバーは、同じ型付き意思決定エンジンへのインターフェースです:

  • 有限のラベル集合には choice、順序付きのルーブリックには score、「真」の確率には noul を 使います。
  • しきい値とプリセットは代表的なデータで検証してください。万能の採用しきい値はありません。
  • 不可逆または高コストのアクションは、アプリケーションのレビューとフォールバック方針の後ろに 置いてください。
  • MCP サーバーは Router.predict を呼ぶので、独自ランチャーがフックをインストールしていれば それらが発火します。可観測性と run_id の相関については、予測フック、 フックのライフサイクル、トレーシング を参照してください。

このガイドはローカルの CLI と組み込みの MCP stdio サーバーを扱います。HTTP API、コミュニティの ラッパー、MCP プロトコルの再設計は扱いません。