endpoint-ops

エンドポイント運用

すでに存在する Serverless エンドポイントを運用します。何かを述べたり変更したりする前に、まず現在の状態（エンドポイントの設定、ヘルス状態、ワーカー、ログ）を読み取ります。診断は常に読み取り専用です。設定を変更するのはユーザーが変更を依頼した場合に限り、その場合も合意した設定だけを変更します。

Runpod の更新処理には、この運用の基本ルールとなる性質があります。エンドポイントの更新は PATCH です。リクエスト本文に含まれるフィールドだけが変更され、省略したフィールドはそのまま残るため、変更を依頼された設定だけを送信し、それ以外は何も送信しません。例外は GPU の選択です。gpu.pools と gpu.excludedTypes は一体の選択項目なので、excludedTypes を含めずに pools を送信する PATCH は、除外設定をクリアします。どちらかを変更する場合は、両方を送信します。PATCH では変更の証明は得られません。PATCH 自体のレスポンスは読み取りではないためです。変更前の値を確認するために先に設定を読み取り、変更後の値を確認するためにその後もう一度読み取ります。

必要な機能

機能として記載しています。このサーバーで各機能を提供するツールは、以下のツールバインディングに記載されています。このスキルでは、変更の前に読み取り、ユーザーが許可した内容だけを変更します。

• エンドポイントの一覧表示と確認：「どのエンドポイントか」を特定し、現在の設定全体を読み取ります。
• エンドポイントのヘルス状態の読み取りとワーカーの一覧表示：キューの停止やワーカーの異常終了を示す情報を確認します。
• ワーカーのログの読み取り：クラッシュやモデル読み込み失敗の行を確認します。
• データセンターごとの GPU 在庫と、容量のある CUDA バージョンの読み取り：キューの停止が容量不足によるものかを確認します。
• エンドポイントの更新（ワーカーの最小数／最大数、アイドルタイムアウト、スケーラー、FlashBoot、ディスク、環境変数）：許可された設定変更を行います。
• GPU の固定／GPU 数の設定：プールと excludedTypes の選択、および gpu.count を設定します。set-endpoint-gpus は他の設定を維持しながら、これらを設定します。
• リリース履歴の読み取り：ワーカーが実行しているビルドを確認します。
• ジョブのキャンセルとキューの消去：いずれも個別の許可が必要なキュー管理操作です。
• 変更後の再検証のためのジョブの送信とポーリング。

フェーズ 1 — 診断（常に実施、読み取り専用）

エンドポイントを特定し（必要に応じてエンドポイントの一覧を取得し、名前で照合します）、その設定を読み取ってから、結論を出す前にヘルス状態とワーカーを確認します。症状に照らして分類します。

• ジョブが IN_QUEUE のまま停止している。 ヘルス状態とワーカー一覧を確認します。最大ワーカー数が 0、またはすべてのワーカーがスロットル状態／異常状態なら、キュー内のジョブを実行できません。3 日間アイドル状態のエンドポイントは workers.max が 2 に引き下げられ、7 日後には 0 になります。引き上げるまでそのままなので、長期間アイドル状態だったエンドポイントで最初のジョブが「停止」する場合は、通常これが原因です。原因を切り分けます。ワーカーの上限（最大ワーカー数が低すぎる、アイドル状態により引き下げられた、または min が 0 でコールドスケーラーが動作している）か、キャパシティ（選択した GPU をワーカーが確保できない：throttled が 0 より大きい場合は、product:["SERVERLESS"] を指定してその GPU タイプの利用可能状況を照合し、エンドポイントで CUDA の最低バージョンを指定している場合は、キャパシティの CUDA バージョンも確認します）か、クラッシュループ（ワーカーが再起動を繰り返している：source=system でログを読み取ります。ハンドラーが実行される前にコンテナが終了しても、ジョブがキューに残ったまま、ステータスが RUNNING または INITIALIZING と報告されることがあります。そのため、判断材料になるのはワーカーのステータスではなくログです）。読み取ったヘルス状態／ワーカーの数値を引用して、どの原因かを明示します。
• ワーカーがクラッシュループしている。 ワーカーを一覧表示し、失敗しているものを見つけてログを読み、決定的な行を引用します。モデルファイルの欠落、ゲートによる 403、OOM、ハンドラーのインポートエラーなどです。推測ではなく、ログの内容を報告します。OOM なら、GPU のサイズが実際のメモリ使用パターンに対して不足しています。ロード／インポートエラーなら、イメージまたは環境設定が誤っています。
• コールドスタートが問題になっている。 設定を読み取ります。対策は、次の順です。FlashBoot を有効にする。アイドルタイムアウトを長くして、バースト間もウォーム状態のワーカーを維持する。ゼロ以外の min-worker を設定してキャパシティをウォーム状態に保つ（min-worker は 24 時間課金され、常時稼働ワーカーになります）。モデルキャッシュ（ネットワークボリューム、Runpod のモデルリポジトリ、またはイメージに組み込んだ重み）を使って、起動時のモデルロードをなくす（ユーザー独自のハンドラーを実行するボリュームベースのエンドポイントでは、VolumeCache がロード前に重みをローカルディスクへコピーします）。さらに、リクエストごとにスケーラーがゼロまでスケールダウンしないことを確認します。変更を加える前に、対策とそのコストを明示します。
• ロードバランサーエンドポイントで、ワーカーが ready にならない。 ロードバランサー（custom-HTTP）エンドポイントでは、ロードバランサーがワーカーのヘルスエンドポイントをポーリングして準備状況を判定します。ポーリング先は PORT_HEALTH（デフォルトは 80）上の HEALTH_CHECK_PATH（デフォルトは /ping）で、サービング用の PORT（デフォルトは 80）とは別です。リクエストが届いているのにワーカーが un-ready のままなら、通常、そのポートで該当パスに応答するものがありません。エンドポイントの読み取り結果から、実際にポーリングされているヘルス URL を確認できます。修正には、ポートを公開してヘルスパスに応答するように再デプロイします（serverless-deploy を参照）。スケーラーの変更では解決しません。

フェーズ 1 の最後に診断結果と推奨する変更を示します。ただし、プロンプトで変更が許可されていない限り、変更は適用しません。依頼が「なぜ／何が問題なのか」だけであれば、ここで終了します。

フェーズ 2 — 安全に調整する（ユーザーが変更を許可した場合のみ）

プロンプトで名前を指定したエンドポイントの設定変更を求められた場合に限り、次に進みます。

• 読み戻しの不変条件。 まずエンドポイントの設定全体を読み取り、変更前の値を把握します。ユーザーが許可したフィールドのみを含む PATCH で変更を適用します。指定されていないフィールドを送信すると、ユーザーが手動で調整した設定を上書きすることになります。その後、設定を読み戻し、対象フィールドが新しい値になっていることと、併記した周辺の設定が変更されていないことを確認します。
• バースト性の高いトラフィック向けのオートスケーリング調整。 バースト性の高いワークロードでは、スケーラーとワーカーの範囲を調整します。バースト時の上限に合わせて最大ワーカー数を増やし、キュー遅延またはリクエスト数を基準とするスケーラーの目標値を、バーストを吸収したい速さに設定します。また、波の合間にワーカーを稼働状態で維持する時間に合わせてアイドルタイムアウトを設定します（リクエスト数でスケーリングするキューエンドポイントでは workers.idleTimeout が拒否され、アカウントのワーカー割り当て上限により workers.max の増加が拒否されることがあります）。ユーザーが同意したフィールドのみを変更し、最小ワーカー数を増やした場合のコストを伝えます。
• GPU タイプを 1 種類に固定する。 ユーザーがエンドポイントで特定のカード 1 種類のみを使うよう求めた場合は、そのカードを含むプールを選択し、プール内の他の GPU タイプを gpu.excludedTypes に列挙します（少なくとも 1 種類は残す必要があります）。指定があれば CUDA の下限も設定します。set-endpoint-gpus はこの除外リストを作成し、エンドポイントの他の設定を変更せずに再送信します。update-endpoint でも同じ gpu オブジェクトを指定できますが、その場合 pools と excludedTypes は 1 つの選択として扱われるため、両方をまとめて送信します。allowedCudaVersions と minCudaVersion は相互に排他的です（両方送信すると 400）。CUDA の制約またはプールを変更しても、稼働中のワーカーは排除されません。変更をすぐに反映する必要がある場合は、workers.max を 0 にしてから元に戻します。固定後にエンドポイントの設定を読み戻し、スケーリング設定が維持されていることを確認します。

フェーズ 3 — キューを管理する（条件付き操作）

• ジョブを 1 件キャンセルする。 ユーザーがキャンセルするジョブを指定した場合は、そのジョブを ID でキャンセルします。キャンセルの対象は、キュー内または処理中のジョブのみです。キャンセル後、新たに get-job-status を読み取って検証します。キャンセル呼び出し自体の応答は検証にはなりません（読み取りで確認されていない書き込みは未検証の書き込みです）。最終回答では、読み戻した状態を報告します。読み戻しで、キャンセル前にジョブがすでに終了状態に達していたことが判明した場合は、そのとおり正確に伝えます。それが完全かつ正直な結果です。
• キューをパージする。 ユーザーが保留中のすべてのジョブの消去を求めた場合は、キューをパージします。これにより保留中のジョブはすべて削除されますが、処理中のジョブは実行を継続します。不良なジョブだけでなく、保留中のキュー全体が消去されることを明確に伝え、明示的に「purge / clear the queue」と指示された場合に限り実行します。その後、ヘルスを読み直し、キューが空になったことを確認します。

厳守事項

• すべての設定変更は、読み取り → 更新 → 読み取りの順に行います：（1）現在の設定を読み取る、（2）更新を適用する、（3）その後に FRESH な get-endpoint の読み取りを行う。最終回答で引用する変更前／変更後の値は、読み取り（1）と（3）から取得します。更新呼び出し自体の応答は読み取りではありません。実施していない再読み取りを行ったと主張してはいけません。
• ユーザーが許可した設定のみを、ユーザーが指定したエンドポイントで変更します。ユーザーが指定していないエンドポイントの調整、固定、パージは行いません。
• 診断は読み取り専用であり、読み取り専用にはジョブの送信が一切含まれません。診断中に「テストプローブ」として run／runsync を実行してはいけません。ジョブを送信すると計算料金が発生し、キューが変更されるため、これは変更操作です。また、エンドポイントが壊れている場合は、ワーカーの状態にすでに示されている内容を再現するために費用を浪費することになります。診断はエンドポイント、ヘルス、ワーカー、ログの読み取りのみで行います。推奨する修正は提示しますが、依頼で許可されていない限り適用しません。
• キューのパージは、保留中のキュー全体を消去します。実行前にその旨を伝えてください。「これをきれいにして」のような曖昧な依頼でパージしてはいけません。
• 継続的に料金が発生する設定については、適用前にそのコストを伝えます（min-worker を 0 以外にすると、ワーカーが起動状態を維持し、料金が発生し続けます）。
• 読み取ったヘルス／ワーカー／ログのフィールドを引用してください。ツールが返した数値について「おそらく」と述べてはいけません。
• ユーザーから指示されていないジョブをキャンセルまたはパージしてはいけません。診断中に「親切心で」キューを消去してはいけません。
• 読み取り（ヘルス、ワーカー、ログ）が失敗した場合は、そのことを報告して終了します。原因を推測してはいけません。

エラー処理

• 変更していない設定が変更された状態で返ってきた場合、PATCH が原因ではありません。PATCH は省略されたフィールドをそのまま維持します（ただし、excludedTypes を指定せずに gpu.pools を送信した場合は、除外設定がクリアされます）。ほかの書き込み経路を確認してください。GPU 固定時に設定全体を再送した、テンプレートを保存した、再デプロイした、または他の人が同時に変更した可能性があります。再適用する前に、もう一度読み取ってください。
• 準備完了ワーカーがあり、処理中のジョブがないのに IN_QUEUE と表示される場合、解消を待ってはいけません。ワーカーのログ（source=system）を読み取ってください。ハンドラーが実行される前にコンテナが終了すると、まさにこの状態になり、スケーラーではなくイメージの不具合を示しています。
• ワーカーのログに OOM が表示される場合、GPU の性能が不足しています。修正には、スケーラーの調整ではなく、より大きな GPU（serverless-deploy による再デプロイ）が必要です。
• キャンセル／パージが成功を返しても、ヘルスにキュー内のジョブが表示される場合は、少し待ってから再読み取りしてください。操作後、キューの件数が反映されるまで少し時間がかかります。
• 有効だったジョブ ID に対して get-job-status が 404 を返す場合、ジョブの TTL（デフォルトでは送信から 24 h）が切れて削除されています。ID が間違っているわけではありません。
• セッションに set-endpoint-gpus がない状態で GPU 固定を依頼された場合は、gpu.pools と gpu.excludedTypes を両方送信して、update-endpoint で同じ選択を行います。

ツールの対応表

機能	ツール
エンドポイントの一覧表示／詳細確認	list-endpoints、get-endpoint
エンドポイントのヘルス	endpoint-health
ワーカーの一覧表示（ワーカーごとの詳細）	list-endpoint-workers
ワーカーのログの読み取り	stream-worker-logs（コンテナのライフサイクルには source=system）
データセンターごとの GPU 在庫	list-gpu-types / get-gpu-type（include:["AVAILABILITY"]、product:["SERVERLESS"]）
GPU タイプごとの、容量がある CUDA バージョン	同じ読み取り（cudaVersions）；マトリックス表示には get-capacity
エンドポイント設定の更新	update-endpoint（PATCH；gpu.pools と gpu.excludedTypes を併せて送信）
GPU の固定／GPU 数の設定	set-endpoint-gpus
リリース履歴	list-endpoint-releases
1 件のジョブのキャンセル	cancel-job
キューのパージ	purge-endpoint-queue
ジョブの送信／ポーリング	run-endpoint、get-job-status、runsync-endpoint

ここに記載されたツールがセッションのツール一覧にない場合は、その旨を伝え、結果を捏造せずに、最も近い読み取りツールを使用してください。

契約

複数のジャーニーに共通する回答契約（読み取り結果に基づく確定した事実、曖昧な表現を避けてコミットすること、変更はこの会話で作成したものに限定すること、最終メッセージは単独で提示すること、失敗を正直に伝えること、許可されたツールのみを使うこと）は、runpod-mcp スキルで定義されており、このジャーニーからのすべての返信に適用されます。この会話でrunpod-mcpスキルをまだ読み込んでいない場合は、次のツール呼び出しの前に読み込んでください。変更してよいリソース、依頼を実行に移すタイミング、ユーザーの指示を待って停止するタイミングに関するルールは、ここでは繰り返しません。