Skip to main content
검색 API를 사용하면 조직에 등록된 러너 목록을 조회하고, 각 러너가 제공하는 하드웨어 정보를 확인하고, 샌드박스를 배치하기 전에 러너의 실시간 용량을 확인할 수 있습니다. 러너는 CKS 클러스터에 배포된 구성 요소입니다. 러너는 CoreWeave의 관리형 컨트롤 플레인에 등록되어 클러스터의 컴퓨팅을 샌드박스 플랫폼에 연결합니다. 따라서 러너의 기능은 해당 러너가 속한 클러스터의 하드웨어에 따라 결정됩니다. 검색은 CKS 배치에만 해당합니다. 서버리스 샌드박스는 사용자가 소유한 러너에서 실행되지 않으므로 검색할 대상이 없습니다. 필요한 샌드박스 사양을 지정하면 플랫폼이 알아서 배치합니다. 샌드박스 배치를 참조하세요. 검색 결과는 러너가 지원하는 기능을 보여 줄 뿐, 러너가 허용하는 범위를 보여 주지는 않습니다. 개별 샌드박스가 요청할 수 있는 범위는 러너에 적용된 정책에 따라 제한되며, 이 정책은 Admin이 작성합니다. 정책 개요를 참조하세요.
프로필을 사용하다가 전환하시나요? 클라이언트는 더 이상 Profile, list_profiles(), get_profile(), ProfileNotFoundError를 내보내지 않습니다. profile_names와 profile_ids는 Sandbox, Session 및 각각의 list() 메서드에 매개변수 이름으로 남아 있지만, 값을 전달하면 TypeError가 발생합니다. 대신 runner_ids로 러너를 지정하세요. 거버넌스 모델은 프로필에서 정책으로 대체되었으며, 정책은 사용자가 직접 선택하지 않습니다. 정책 개요를 참조하세요.

러너 목록 조회

list_runners()는 현재 사용자 인증 정보로 조회할 수 있는 모든 러너를 반환합니다.
Runner에는 기본 제공 표현 형식이 있어 러너 ID, 소유 조직, health, 사람이 읽기 쉬운 단위로 나타낸 CPU 및 메모리, GPU 수, 그리고 러너가 강제 적용할 수 있는 서비스 공개 범위를 출력합니다. 출력 예시:

러너 기능 조회

각 러너는 자신의 노드에 탑재된 하드웨어 정보를 제공합니다. 이 속성을 조회하여 생성하려는 샌드박스를 실행할 수 있는 러너를 찾으세요.
supported_gpu_types에는 GPU 요청의 type 키에 전달할 정확한 문자열이 들어 있습니다. 대소문자를 구분하므로 B200과 b200은 서로 다른 유형으로 처리됩니다. GPU 샌드박스 실행을 참조하세요. max_gpu_count는 러너가 보고하는 전체 GPU 용량이며, 샌드박스별 한도가 아닙니다. 샌드박스 하나가 요청할 수 있는 GPU 수는 러너 정책의 maxGpuCount와 단일 노드에서 사용 가능한 GPU 수에 따라 제한됩니다.

러너 속성

Runner에는 다음 속성이 있습니다. max_* 값이 0이라고 해서 러너에 리소스가 없다는 뜻은 아닙니다. 러너가 해당 용량을 공개하거나 보고하지 않는다는 의미일 수 있습니다. 공유 러너는 용량 정보가 공개되지 않으므로 0을 반환합니다. 또한 CPU 및 메모리 값에서는 예약 용량이 제외될 수 있습니다.

실시간 용량 확인

기본적으로 list_runners()는 지원 기능(capability) 데이터만 반환합니다. include_resources=True를 전달하면 Runner.resources에 실시간 가용성 정보가 채워집니다. format_bytes()와 format_cpu()를 사용해 값을 사람이 읽기 쉬운 단위로 출력하세요:
러너가 가용성을 보고하지 않으면 resources는 None이 되므로, 값을 읽기 전에 None인지 먼저 확인하세요.

RunnerResources 속성

RunnerResources 객체에는 다음 속성이 있습니다.

목록 필터링

필터를 조합하면 워크로드를 처리할 수 있는 러너만 남도록 목록을 좁힐 수 있습니다. 다음 호출은 지정한 GPU 유형을 갖추고 있고 사용 가능한 GPU가 두 개 이상인 정상 상태의 러너를 반환합니다. [GPU-TYPE]을 supported_gpu_types의 값으로 바꾸세요.
검색 서비스는 runner_group_id, gpu_type, architecture, healthy_only, service_visibility를 적용합니다. 세 가지 min_available_* 필터는 결과를 받은 후 클라이언트에서 적용됩니다. 이 세 필터를 사용하면 include_resources가 자동으로 활성화되고, 리소스 데이터를 보고하지 않는 러너는 제외되므로 이 필터가 반환하는 결과에는 항상 resources가 채워져 있습니다.

매개변수

list_runners()에서 사용할 수 있는 매개변수는 다음과 같습니다. 모든 매개변수는 키워드 전용입니다.

단일 러너 조회

get_runner()는 러너 ID와 해당 러너를 소유한 조직을 인수로 받습니다. 러너 ID는 전역이 아니라 조직 내에서만 고유하므로 두 값을 모두 지정해야 합니다. 이 호출은 항상 전체 세부 정보를 반환하지만, 리소스 가용량은 사용자의 조직이 소유한 러너에 대해서만 포함됩니다. [RUNNER-ID]와 [ORGANIZATION-ID]를 조회할 러너 및 해당 러너를 소유한 조직의 값으로 바꾸세요:
목록으로 조회한 러너에는 각각 고유한 organization_id가 있으므로, 이전 결과에서 찾은 러너를 조회할 때는 runner.organization_id를 전달하세요.

검색된 러너에서 샌드박스 생성

placement_mode="cks"로 설정하고 선택한 러너를 runner_ids에 전달하세요. [GPU-TYPE]은 supported_gpu_types에 있는 값으로 바꾸세요.
runner_ids를 지정하지 않으면 CKS 배치 시 조직 내에서 조건을 충족하는 모든 러너가 사용될 수 있습니다. runner_ids는 서버리스 배치 또는 placement_spillover="serverless_then_cks"와 함께 사용할 수 없습니다.

세션의 모든 샌드박스에 러너 적용하기

세션의 모든 샌드박스를 동일한 러너로 보내려면 SandboxDefaults를 사용하세요.
나머지 샌드박스 옵션은 샌드박스 구성 가이드를 참조하세요.

오류 레퍼런스

검색 호출은 다음 예외를 발생시킬 수 있습니다. runner_id 또는 organization_id가 비어 있으면 get_runner()는 요청을 보내기 전에 ValueError를 발생시킵니다. 전체 예외 계층 구조는 예외 레퍼런스를 참조하세요. 일반적인 문제 해결 단계는 Sandboxes 지원 아티클을 참조하세요.
마지막 수정일 2026년 10월 15일