Inference AIops

Inference AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。**vLLM または Ray のプロジェクト、あるいはいずれの推論サービングベンダーとも提携、推奨、支援関係にありません。**製品名および商標は各所有者に帰属します。MIT ライセンスです。

GPU 推論クラスター向けのガバナンス対応 AI 運用です。vLLM（OpenAI API ＋ Prometheus /metrics）と Ray Serve / Ray Jobs（Ray ダッシュボード）に加え、単一プロセスの サービングエンジン SGLang と **TGI（Text Generation Inference）**に対応し、 ガバナンスハーネスを内蔵しています。統合監査ログ、ポリシーエンジン、トークン／暴走 予算ガード、取り消しトークンの記録、すべての監査行に付与されるリスク階層ラベルを備えています。 各エンジンの Prometheus /metrics を直接解析するため、Prometheus サーバーは不要です。また、Ray ダッシュボードも個別にプローブします。Bearer トークンは 任意です（オープンな状態で稼働しているスタックも多数あります）。

サービングエンジン。 vLLM が主力です（Ray Serve の制御プレーン全機能に対応：スケール、 ドレイン、自動スケーリング、LoRA、ホットスワップ）。SGLang と TGI は、エンジンに 依存しない可観測性に対応しています。各エンジン独自のエンドポイントとメトリクス名から、 ヘルス、稼働中のモデルの識別情報、リクエスト遅延メトリクス、キュー深度、遅延の根本原因分析を 取得します。単一プロセスのサーバーであるため、Ray 型のスケール／ドレイン API はありません。 こうした書き込み操作を行うと、実際の水平スケーリング層（Ray Serve／Kubernetes／ロードバランサー） を利用するよう案内する説明付きエラーが返されます。

できること

主な価値は、ガード付きの読み取り／書き込み操作で実現する根本原因分析です。

• diagnose_latency_spike（主力の根本原因分析）— TTFT／TPOT／e2e 遅延が 上昇した場合、キュー深度（実行中と待機中）、KV キャッシュの 逼迫／プリエンプション、プレフィックスキャッシュの局所性を関連付けて、原因を 順位付けし、具体的に変更すべき設定（レプリカの追加、max-num-seqs の引き上げ、 ルーティングの修正、KV キャッシュの拡大）を提示します。各フラグは数値であり、 ブラックボックスの判定ではありません。
• diagnose_low_utilization — その逆を診断します。アイドル状態の GPU、過剰に プロビジョニングされたレプリカ、あるいはキャッシュが温まったレプリカを使えなくする ルーティングを検出し、スケールダウンする対象を提示します。
• Prometheus ネイティブ — vLLM の /metrics エンドポイントを直接読み取ります。 Prometheus／Grafana のデプロイは不要です。
• ガバナンス水準 — このニッチ分野で初のガバナンス水準の実装です。 監査＋予算＋リスク階層に基づく承認＋取り消しトークン＋プロンプトインジェクションの サニタイズを備えています。コミュニティで危険性が報告されている本番環境の繊細な操作 （スケールダウン、ゼロへのスケール、ドレイン、再デプロイ、ホットスワップ）には、 ドライラン＋二重確認を適用します。
• ノート PC でのセルフテスト — ツールのセルフテストの約 80% を無料で実行できます。 単一 GPU 上の vLLM、または CPU モックと、1 つのローカルコンテナー内の Ray （ray start --head）を使用します。

このツールが判断すること、判断しないこと

推論クラスターの操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを実行してよいかどうかは判断しません。それはエージェントの判断、または接続先環境の権限によるものです。ネットワーク経路を制限して読み取り／メトリクスのエンドポイントにしかアクセスできないようにするか、ジョブ送信 API を無効にした状態で Ray ダッシュボードを実行すれば、書き込みは権限を実際に管理しているサーバー側で失敗します。

そのため、読み取り専用の切り替え機能も、ポリシーファイルも、設定すべき承認ゲートもありません。このツールが保証するのは、何もひそかに実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しが監査レコードとして~/.inference-aiops/audit.dbに記録され、破壊的な書き込みでは実行前の状態も保存し、可能な場合は取り消し操作も記録します。

各ツールは risk_level を宣言します。テストによって [READ]／[WRITE] のドキュメントタグとの整合性が保たれ、説明用のリスク階層として監査レコードにも記録されます。そのため、レビュー担当者はレコードを見れば、リスクの高いゼロスケール操作だったことがひと目でわかります。これはラベルであり、ゲートではありません。

小型モデルやローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが適用するガードレール（プロンプトの予算を使って繰り返し指定する必要はありません）と、残りの条件に使えるすぐに利用可能なシステムプロンプトを記載しています。

機能マトリックス（MCP ツール 39 個）

グループ	ツール	数	読み取り／書き込み（リスク）
メトリクスと RCA（vLLM）	request_metrics、queue_depth、kv_cache_stats、diagnose_latency_spike、diagnose_low_utilization	5	読み取り
エンジン非依存（vLLM／SGLang／TGI）	engine_health、engine_inventory、engine_request_metrics、engine_queue_depth、diagnose_engine_latency	5	読み取り
Ray Serve（読み取り）	serve_deployment_list、deployment_status、replica_list、autoscale_config_get	4	読み取り
Ray Serve（書き込み）	scale_replicas_up、scale_replicas_down、scale_to_zero、autoscale_config_update、drain_replica	5	書き込み（中／高）
モデル／vLLM	model_list、model_info、model_is_sleeping、lora_load、lora_unload	5	読み取り＋書き込み（中）
スリープモード／vLLM（VLLM_SERVER_DEV_MODE=1 が必要）	model_sleep、model_wake	2	書き込み（高／中）
Ray クラスター／ジョブ／GPU	ray_cluster_resources、ray_dashboard_status、ray_job_list、gpu_utilization、ray_job_cancel、replica_restart	6	読み取り＋書き込み（中／高）
デプロイのライフサイクル	model_deploy、model_undeploy、deployment_redeploy、routing_policy_update	4	書き込み（中／高）
コスト	cost_per_token	1	読み取り

エンジン非依存グループは、サポート対象のあらゆるエンジン（vLLM を含む）で動作します。SGLang／TGI の対象にはこのグループを使用するか、混在フリートを一貫した形式で確認できます。Ray Serve／クラスター／デプロイの書き込みグループは vLLM 専用（Ray コントロールプレーン）であり、SGLang／TGI の対象では説明を表示して実行を拒否します。

**読み取り 23 個、書き込み 16 個。**高リスクの書き込み（scale_replicas_down、scale_to_zero、drain_replica、lora_unload、model_sleep、replica_restart、model_undeploy、deployment_redeploy）はすべて、dry_run と二重確認に対応しています。元に戻せる書き込みでは、取り消し用の記述子が記録されます。

スリープモードには開発モードのサーバーが必要です。vLLM は VLLM_SERVER_DEV_MODE=1 を指定して起動した場合に限り、/sleep、/wake_up、/is_sleeping を登録します。これ以外のサーバーでは、これら 3 つのツールはルートが存在しないこととその理由を報告するため、曖昧なエラーにはなりません。スリープモードは同じモデルを一時停止します。ベースモデルの切り替えは行いません。別のベースモデルを提供するには、異なる --model を指定して vLLM を再起動してください。

インストール

uv tool install inference-aiops          # or: pipx install inference-aiops

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を提供します。

/plugin marketplace add AIops-tools/marketplace
/plugin install inference-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査ログの各行を、その記録を書き込んだコードまで追跡できます。認証情報は引き続き inference-aiops init で設定します。詳しくは以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて利用できます。

openclaw plugins install clawhub:@zw008/inference-aiops
openclaw skills info inference-aiops          # expect: Visible to model: yes

その後、OpenClaw ゲートウェイを再起動して、プラグインを読み込ませてください。MCP サーバーは uv で取得され、このリリースの正確なバージョンに固定されているため、uvx が PATH 上にある必要があります。これがない場合もスキルはインストールされますが、Visible to model: no と報告されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロンの MCP サーバーとして

inference-aiops init                     # wizard: engine (vllm/sglang/tgi) + host + port + scheme
inference-aiops doctor                   # vLLM: probes Ray + vLLM; SGLang/TGI: engine health + inventory
inference-aiops overview                 # deployments + total replicas + queue backpressure
inference-aiops metrics diagnose         # why is inference slow? ranked RCA + the knob to turn
inference-aiops serve list               # Ray Serve deployments + replica counts

全 39 ツールを利用するには、MCP サーバー（stdio）として実行します。

export INFERENCE_AIOPS_MASTER_PASSWORD=...   # only if a bearer token is stored
inference-aiops mcp

そのパスワードが保存される場所：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取ることができ、シェルの履歴にも記録されます。共有ホストまたは長時間稼働するホストでは、対話型プロンプトを使用するか、必要な 1 つのコマンドの実行中だけシークレットマネージャーから注入する方法をおすすめします。

CLI は便利なサブセット（init、overview、serve …、metrics …、secret …、doctor、mcp）です。全 39 ツールは MCP サーバー経由で利用できます。

ガバナンス

すべての MCP ツールは、同梱の @governed_tool ハーネスを経由します。このハーネスは書き込みが許可されるかどうかを判断するものではありません。上記の「このツールが判断することと、判断しないこと」をご覧ください。ただし、すべての呼び出しを記録します。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスク階層、承認者／理由の注釈がある場合はその内容）を ~/.inference-aiops/audit.db に記録します（INFERENCE_AIOPS_HOME で保存先を変更できます）。
• 予算／暴走防止ガード — 認可ではなく安全策です。トークン予算と呼び出し予算により、短い間隔でのポーリング／再試行ループでサーキットブレーカーが作動します。
• リスク階層 — 各監査ログ行には、ツールの risk_level から導出された説明用の階層が記録されます。これはラベルであり、ゲートではありません。INFERENCE_AUDIT_APPROVED_BY と INFERENCE_AUDIT_RATIONALE は任意の注釈で、設定されている場合に記録されます。必須ではありません。
• 取り消しの記録 — 取り消し可能な書き込み（スケーリング、自動スケーリング設定、ルーティング、ホットスワップ、LoRA の読み込み）では、逆操作の記述子を記録します。

サポート対象の範囲と制限事項

動作は、モックした vLLM /metrics、vLLM OpenAI API、Ray ダッシュボードのレスポンスを使ってテストスイートで検証しています。ノート PC でツールのセルフテストの約 80% を実施できます。単一 GPU の vLLM、または CPU モックとローカルの 1 ノード Ray ヘッドを使います。本番環境の実クラスターでは実行していません。実環境での検証チェックリストは docs/VERIFICATION.md をご覧ください。

実際のハードウェア／トポロジーで未検証の項目：

• マルチ GPU の テンソル並列／パイプライン並列デプロイ
• 実 GPU の温度／スロットリングテレメトリー（使用率は Ray ダッシュボードの /api/nodes からベストエフォートで取得）
• 複数ノードのドレインとノード再起動のオーケストレーション

実環境で最も手早く確認するには inference-aiops doctor を実行してください。完全なチェックリストは docs/VERIFICATION.md にあります。

必要な機能がありませんか？

これは AIops-tools ファミリーの GPU 推論向けツールです（監査、予算、取り消し、リスク階層によるガバナンス付き AI 運用）。必要な vLLM または Ray の機能がない場合や、お使いのスタックがこれらのツールでまだ扱えない方言を使用している場合は、issue または PR を作成してください。貢献を歓迎します。