利用可能なランナーを検出する

ディスカバリー API を使用すると、組織に登録されているランナーの一覧表示や、各ランナーが公開しているハードウェア情報の読み取りに加え、サンドボックスを配置する前にリアルタイムのキャパシティを確認できます。ランナーは CKS クラスター内のデプロイメントです。CoreWeave のマネージドコントロールプレーンに登録され、クラスターのコンピュートをサンドボックスプラットフォームに橋渡しします。そのため、ランナーの機能は背後にあるクラスターのハードウェアに依存します。ディスカバリーは CKS への配置にのみ適用されます。サーバーレスのサンドボックスはお客様が所有するランナー上で実行されるわけではないため、検出する対象がありません。必要なサンドボックスの内容を指定するだけで、プラットフォームが配置を行います。サンドボックスの配置を参照してください。ディスカバリーで報告されるのはランナーの能力であり、何が許可されているかではありません。個々のサンドボックスが要求できる内容は、ランナーに設定されたポリシーによって制限されます。このポリシーは管理者が作成します。ポリシーの概要を参照してください。

プロフィールから移行する場合: クライアントは Profile、list_profiles()、get_profile()、ProfileNotFoundError をエクスポートしなくなりました。profile_names と profile_ids は Sandbox、Session、およびそれらの list() メソッドのパラメーター名として残っていますが、値を渡すと TypeError が送出されます。代わりに runner_ids でランナーを指定してください。ガバナンスモデルはプロフィールからポリシーに置き換わりました。ポリシーはユーザーが選択するものではありません。ポリシーの概要を参照してください。

ランナーの一覧表示

list_runners() は、使用中の認証情報で参照できるすべてのランナーを返します。

from cwsandbox import AuthStrategy, Runner, list_runners

runners: list[Runner] = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY)

for runner in runners:
    print(runner)

Runner には組み込みの表現形式があり、ランナー ID、所有元の組織、健全性、人間が読みやすい単位で表した CPU とメモリ、GPU 数、およびランナーが強制できるサービスの可視性を出力します。出力例:

Runner(runner_id='prod-us-east-1', organization_id='1a2b3c4d', healthy=True, cpu=512.0 vCPU, memory=4.0 TiB, gpus=64, visibilities=['public', 'private'])

ランナーの機能を読み取る

各ランナーは、自身のノードに搭載されたハードウェアを公開しています。これらの属性を読み取り、作成したいサンドボックスの要件を満たすランナーを検索します。

from cwsandbox import AuthStrategy, list_runners

for runner in list_runners(auth=AuthStrategy.COREWEAVE_API_KEY):
    print(runner.runner_id)
    print(f"  gpu types:     {', '.join(runner.supported_gpu_types) or 'none'}")
    print(f"  max gpus:      {runner.max_gpu_count}")
    print(f"  architectures: {', '.join(runner.supported_architectures)}")
    print(f"  storage:       {', '.join(runner.available_storage_classes)}")

supported_gpu_types には、GPU リクエストの type キーにそのまま渡す文字列が格納されています。照合では大文字と小文字が区別されるため、B200 と b200 は別のタイプとして扱われます。 GPU サンドボックスを実行するを参照してください。 max_gpu_count はランナーが報告する GPU キャパシティの合計値であり、サンドボックスごとの上限ではありません。1 つのサンドボックスがリクエストできる GPU 数の上限は、ランナーのポリシーの maxGpuCount と、単一ノード上の空き GPU 数によって決まります。

ランナーの属性

Runner には次の属性があります。

属性	タイプ	説明
`runner_id`	`str`	組織内でのランナーの識別子です。グローバルに一意ではありません。
`organization_id`	`str`	ランナーを所有する組織です。
`runner_group_id`	`str`	ランナーが属するグループです。
`tags`	`tuple[str, ...]`	ランナーに付与されたタグです。
`healthy`	`bool`	ランナーが現在正常かどうかを示します。
`is_shared`	`bool`	ランナーが共有組織に属する場合は `True` です。
`connected_at`	`datetime`	ランナーが接続した日時です (UTC のタイムゾーン情報付き datetime)。
`max_cpu_millicores`	`int`	報告された CPU キャパシティの合計です (単位: ミリコア)。
`max_memory_bytes`	`int`	報告されたメモリキャパシティの合計です (単位: バイト)。
`max_gpu_count`	`int`	報告された GPU キャパシティの合計です。
`supported_gpu_types`	`tuple[str, ...]`	ランナーのノードに搭載されている GPU のタイプです。
`supported_architectures`	`tuple[str, ...]`	ランナーがサポートする CPU アーキテクチャー (`amd64` など) です。
`supports_privileged`	`bool`	特権コンテナーが許可されているかどうかを示します。
`available_storage_classes`	`tuple[str, ...]`	クラスターで利用可能な Kubernetes ストレージクラスです。
`supported_service_visibilities`	`tuple[str, ...]`	ランナーが強制できるサービスの可視性 (`public`、`private`、`custom` のいずれか) です。`ServiceVisibility` を参照してください。
`resources`	`RunnerResources \| None`	現在のリソース可用性です。ランナーが報告しない場合は `None` になります。

max_* の値が 0 であっても、リソースがないとは限らず、ランナーがそのキャパシティを開示または報告していないだけの場合があります。共有ランナーではキャパシティが非開示のため 0 が返されます。また、CPU とメモリの値には予約キャパシティが含まれない場合があります。

リアルタイムのキャパシティを確認する

デフォルトでは、list_runners() は機能データのみを返します。 include_resources=True を渡すと、Runner.resources にリアルタイムの可用性が格納されます。 format_bytes() と format_cpu() を使用すると、値を人間が読みやすい単位で出力できます。

from cwsandbox import AuthStrategy, format_bytes, format_cpu, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    include_resources=True,
)

for r in runners:
    print(f"{r.runner_id}  healthy={r.healthy}")
    print(f"  max: {format_cpu(r.max_cpu_millicores)}, {format_bytes(r.max_memory_bytes)}")
    if r.resources:
        free_cpu = format_cpu(r.resources.available_cpu_millicores)
        free_mem = format_bytes(r.resources.available_memory_bytes)
        print(f"  free:  {free_cpu}, {free_mem}, {r.resources.available_gpu_count} GPUs")
        print(f"  running sandboxes: {r.resources.running_sandboxes}")

ランナーが可用性を報告しない場合、resources は None になります。値を読み取る前に None かどうかを確認してください。

RunnerResources の属性

RunnerResources オブジェクトには次の属性があります。

属性	タイプ	説明
`available_cpu_millicores`	`int`	予約されていない CPU (ミリコア単位)。
`available_memory_bytes`	`int`	予約されていないメモリ (バイト単位)。
`available_gpu_count`	`int`	予約されていない GPU の数。
`running_sandboxes`	`int`	ランナー上で現在実行中のサンドボックスの数。

リストをフィルターする

フィルターを組み合わせて、ワークロードを受け入れ可能なランナーにリストを絞り込みます。次の呼び出しは、指定した GPU タイプを搭載し、空き GPU が 2 基以上ある正常なランナーを返します。[GPU-TYPE] は supported_gpu_types の値に置き換えてください。

from cwsandbox import AuthStrategy, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    healthy_only=True,
    min_available_gpu_count=2,
)

for r in runners:
    print(f"{r.runner_id}: {r.resources.available_gpu_count} GPUs free")

ディスカバリーサービスは runner_group_id、gpu_type、architecture、 healthy_only、service_visibility を適用します。3 つの min_available_* フィルターは、結果を受信した後にクライアント側で適用されます。これら 3 つのフィルターを指定すると include_resources が自動的に有効になり、リソースデータを報告しないランナーは除外されます。そのため、これらのフィルターを通過した結果では、resources に常に値が設定されています。

パラメーター

list_runners() では次のパラメーターを指定できます。いずれもキーワード専用引数です。

パラメーター	タイプ	説明
`auth`	`AuthConfig \| None`	このリクエストで使用する認証方式、解決済みヘッダー、またはプロバイダー。
`runner_group_id`	`str \| None`	結果を指定したランナーグループに限定します。
`gpu_type`	`str \| None`	指定した GPU タイプをサポートするランナーのみを返します。
`architecture`	`str \| None`	指定した CPU アーキテクチャーをサポートするランナーのみを返します。
`healthy_only`	`bool`	正常なランナーのみを返します。デフォルトは `False` です。
`include_resources`	`bool`	各ランナーの現在のリソース可用性を結果に含めます。デフォルトは `False` です。
`min_available_cpu_millicores`	`int \| None`	予約されていない CPU ミリコア数の最小値。指定すると `include_resources` が自動的に有効になります。
`min_available_memory_bytes`	`int \| None`	予約されていないメモリバイト数の最小値。指定すると `include_resources` が自動的に有効になります。
`min_available_gpu_count`	`int \| None`	予約されていない GPU 数の最小値。指定すると `include_resources` が自動的に有効になります。
`service_visibility`	`str \| None`	指定したサービスの可視性 (`public`、`private`、または `custom`) を強制できるランナーのみを返します。

単一のランナーを取得する

get_runner() は、ランナー ID と、そのランナーを所有する組織を受け取ります。ランナー ID はグローバルではなく組織内でのみ一意であるため、両方の指定が必須です。この呼び出しでは常に完全な詳細が返されますが、リソース可用性が含まれるのは自分の組織が所有するランナーの場合のみです。[RUNNER-ID] と [ORGANIZATION-ID] を、対象のランナーとそれを所有する組織の ID に置き換えてください：

from cwsandbox import AuthStrategy, RunnerNotFoundError, get_runner

try:
    runner = get_runner(
        "[RUNNER-ID]",
        organization_id="[ORGANIZATION-ID]",
        auth=AuthStrategy.COREWEAVE_API_KEY,
    )
    print(f"{runner.runner_id}  healthy={runner.healthy}")
    if runner.resources:
        print(f"  running sandboxes: {runner.resources.running_sandboxes}")
except RunnerNotFoundError as e:
    print(f"Runner not found: {e.runner_id}")

一覧で取得した各ランナーには、それぞれ固有の organization_id が含まれています。そのため、前の結果で見つけたランナーを検索するときは、 runner.organization_id を渡してください。

検出したランナーでサンドボックスを作成する

placement_mode="cks" を設定し、選択したランナーを runner_ids に渡します。 [GPU-TYPE] は supported_gpu_types に含まれる値に置き換えてください。

from cwsandbox import AuthStrategy, ResourceOptions, Sandbox, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    min_available_gpu_count=1,
)

if runners:
    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=[runners[0].runner_id],
        resources=ResourceOptions(
            requests={"cpu": "2", "memory": "8Gi"},
            limits={"cpu": "2", "memory": "8Gi"},
            gpu={"count": 1, "type": "[GPU-TYPE]"},
        ),
        max_lifetime_seconds=3600,
    ) as sandbox:
        print(sandbox.exec(["nvidia-smi", "-L"]).result().stdout)

runner_ids を指定しない場合、CKS への配置では、組織内の条件を満たす任意のランナーを使用できます。 runner_ids は、サーバーレスへの配置、および placement_spillover="serverless_then_cks" とは併用できません。

Session 内のすべてのサンドボックスにランナーを適用する

SandboxDefaults を使用すると、Session 内のすべてのサンドボックスを同じランナーに割り当てることができます。

from cwsandbox import AuthStrategy, SandboxDefaults, Session, list_runners

runners = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY, healthy_only=True)

if runners:
    defaults = SandboxDefaults(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=(runners[0].runner_id,),
    )

    with Session(defaults) as session:
        sb = session.sandbox()
        print(sb.exec(["echo", "running on a discovered runner"]).result().stdout)

サンドボックスのその他のオプションについては、サンドボックスの設定ガイドを参照してください。

エラーリファレンス

ディスカバリーの呼び出しでは、次の例外が発生する場合があります。

例外	原因
`RunnerNotFoundError`	指定された `runner_id` と `organization_id` に一致するランナーが存在しません。
`DiscoveryValidationError`	ディスカバリーリクエストがフィールド単位の検証に失敗しました。
`DiscoveryError`	ディスカバリー操作中にネットワークエラーまたはサービスエラーが発生しました。上記 2 つの例外の基底クラスです。
`CWSandboxAuthenticationError`	認証情報が無効であるか、指定されていません。

runner_id または organization_id が空の場合、get_runner() はリクエストを送信する前に ValueError を送出します。例外の階層全体については、例外リファレンスを参照してください。一般的なトラブルシューティング手順については、 Sandboxes のサポート記事を参照してください。

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

利用可能なランナーを検出する

ランナーの一覧表示

ランナーの機能を読み取る

ランナーの属性

リアルタイムのキャパシティを確認する

RunnerResources の属性

リストをフィルターする

パラメーター

単一のランナーを取得する

検出したランナーでサンドボックスを作成する

Session 内のすべてのサンドボックスにランナーを適用する

エラーリファレンス

​ランナーの一覧表示

​ランナーの機能を読み取る

​ランナーの属性

​リアルタイムのキャパシティを確認する

​RunnerResources の属性

​リストをフィルターする

​パラメーター

​単一のランナーを取得する

​検出したランナーでサンドボックスを作成する

​Session 内のすべてのサンドボックスにランナーを適用する

​エラーリファレンス

ランナーの一覧表示

ランナーの機能を読み取る

ランナーの属性

リアルタイムのキャパシティを確認する

RunnerResources の属性

リストをフィルターする

パラメーター

単一のランナーを取得する

検出したランナーでサンドボックスを作成する

Session 内のすべてのサンドボックスにランナーを適用する

エラーリファレンス