> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPU 샌드박스 실행

> 가상화된 서버리스 용량 또는 가상화되지 않은 자체 CKS 클러스터에서 샌드박스용 GPU를 요청하세요.

이 가이드에서는 하나 이상의 GPU가 있는 샌드박스를 생성하고, 샌드박스 내부에서 GPU가 표시되는지 확인하며, 이에 맞는 CPU와 메모리 요청량을 설정하는 방법을 설명합니다. GPU 샌드박스는 두 가지 배치 모드로 실행됩니다. CoreWeave가 운영하는 서버리스 용량에서 실행하거나, 사용자가 소유한 CoreWeave Kubernetes Service (CKS) 클러스터에서 실행합니다. 두 모드는 샌드박스의 격리 방식, 사용할 수 있는 GPU, 한도를 설정하는 주체가 다르므로, 이 페이지에서는 별도의 섹션으로 다룹니다.

CPU 전용 샌드박스에 대한 내용은 [시작하기](/ko/products/sandboxes/get-started)를 참조하세요. 서버리스 용량과 CKS 용량을 비교하려면 [샌드박스 배치 및 스필오버](/ko/products/sandboxes/placement)를 참조하세요.

<Note>
  GPU 샌드박스는 비공개 프리뷰 상태이며, 이미 CPU 전용 샌드박스를 사용하고 있더라도 조직이 허용 목록에 등록되어야 합니다. 액세스를 요청하려면 계정 담당 팀에 문의하거나 [forge-support@coreweave.com](mailto:forge-support@coreweave.com)으로 이메일을 보내세요. 조직이 허용 목록에 등록되기 전까지 GPU 샌드박스 생성 요청은 `CWSANDBOX_GPU_NOT_ALLOWED` 오류와 함께 실패합니다.
</Note>

동시 샌드박스 할당량과 리소스 제한에 대한 내용은 [제한 및 할당량](/ko/products/sandboxes/reference/limits-and-quotas)을 참조하세요.

<h2 id="isolation-depends-on-the-placement-mode">
  격리 수준은 배치 모드에 따라 달라집니다
</h2>

GPU 가상화는 서버리스 용량에서만 지원됩니다. 직접 소유한 CKS 클러스터에서는 GPU 샌드박스가 가상화되지 않습니다.

| | 서버리스 | 자체 CKS 클러스터 |
| - | - | - |
| 런타임 | 자동으로 선택되는 GPU 가상 머신 런타임 | `runc`로 컨테이너를 실행하는 클러스터의 기본 런타임 클래스 |
| GPU 가상화 | 예. GPU가 샌드박스의 가상 머신에 연결됩니다. | 아니요. 샌드박스는 노드의 커널을 공유하는 표준 컨테이너입니다. |
| 보안 컨테이너 런타임 | 예 | **아니요** |
| 신뢰할 수 없는 코드 실행에 적합 | 예 | **아니요.** 신뢰할 수 있는 코드만 실행하세요. |

<Warning>
  자체 CKS 클러스터의 GPU 샌드박스는 가상화 없이 기본 런타임 클래스(`runc`)로 실행됩니다. 노드의 다른 컨테이너와 동일한 수준의 격리만 제공하므로 **보안 컨테이너 런타임으로 간주할 수 없습니다**. 모델이 생성한 코드나 사용자가 제출한 코드처럼 신뢰할 수 없는 코드는 CKS GPU 샌드박스에서 실행하지 마세요. GPU에서 신뢰할 수 없는 코드를 실행하려면 [서버리스 용량](#run-a-gpu-sandbox-on-serverless-capacity)을 사용하세요.
</Warning>

<h2 id="before-you-begin">
  시작하기 전에
</h2>

다음 항목이 필요합니다.

* 조직에 GPU 샌드박스가 활성화되어 있어야 합니다.
* 서버리스 예시에 사용할 [Forge API 키](https://forge.coreweave.com/settings#apikeys). CKS 배치에는 `SANDBOX_USER` ID 및 액세스 관리(IAM) 액션이 있는 CoreWeave API 액세스 토큰이 필요합니다. [사용자 인증 정보 선택 및 조회](/ko/products/sandboxes/placement#choose-and-get-credentials)를 참조하세요.
* Python 클라이언트 `cwsandbox` 1.14.2 이상:

  ```bash theme={"system"}
  uv pip install 'cwsandbox>=1.14.2'
  ```

TypeScript 클라이언트는 아직 GPU 리소스를 지원하지 않습니다. GPU 샌드박스에는 Python 클라이언트를 사용하세요.

<h2 id="how-gpu-requests-work">
  GPU 요청의 작동 방식
</h2>

두 배치 모드 모두에 동일한 규칙이 적용됩니다.

* **GPU 요청은 GPU만 예약합니다.** GPU와 함께 실행할 작업에 맞춰 CPU와 메모리를 명시적으로 설정하세요. CPU와 메모리 값을 생략하면 정책의 `defaultCpu` 및 `defaultMemory`가 사용될 수 있지만, 최종적으로 결정된 할당은 여전히 정책의 리소스 요구 사항을 충족해야 합니다.
* **샌드박스는 GPU를 통째로 할당받습니다.** GPU는 샌드박스 간에 공유, 분할 또는 시분할되지 않습니다.
* **샌드박스는 단일 노드에서 실행됩니다.** 서버리스 용량에서는 샌드박스에 정확히 GPU 1개가 할당됩니다. CKS 클러스터에서는 샌드박스의 최대 크기가 노드 하나 전체이며, 여기에 포함되는 GPU 수는 GPU 유형에 따라 다릅니다. GPU가 8개인 노드에서는 CKS 샌드박스가 GPU를 1개부터 최대 8개까지 요청할 수 있습니다. GPU를 여러 개 요청하려면 요청한 수만큼의 가용 GPU와 요청한 CPU 및 메모리가 하나의 노드에서 동시에 확보되어야 합니다.
* **GPU 유형은 선택 메뉴가 아니라 필터입니다.** 선택 항목인 `type` 키는 러너가 제공하는 GPU 유형 중 하나와 대소문자까지 정확히 일치해야 합니다. 러너의 모든 GPU를 허용하려면 이 키를 생략하세요.

<h2 id="run-a-gpu-sandbox-on-serverless-capacity">
  서버리스 용량에서 GPU 샌드박스 실행하기
</h2>

서버리스 배치는 자체 러너와 정책이 필요하지 않습니다. CoreWeave가 정책과 하드웨어를 소유합니다. GPU 샌드박스는 가상 머신에서 실행되므로 신뢰할 수 없는 코드를 실행하는 데 적합합니다.

<h3 id="available-gpus">
  사용 가능한 GPU
</h3>

서버리스 용량에서는 NVIDIA RTX PRO 6000 Blackwell Server Edition이라는 단일 GPU 모델을 사용합니다. 서버리스 용량에서는 GPU 1개짜리 샌드박스만 지원됩니다. GPU가 2개 이상인 샌드박스를 실행하려면 [CKS 클러스터](#run-a-gpu-sandbox-on-your-cks-cluster)를 사용하세요.

| GPU | GPU 메모리 | 샌드박스당 GPU 수 |
| - | - | - |
| NVIDIA RTX PRO 6000 Blackwell Server Edition | 96 GB | 1 |

이 GPU를 탑재한 인스턴스 유형은 [High Memory](/platform/instances/gpu/rtxp6000-8x)와 [Standard Memory](/platform/instances/gpu/rtxp6000-8x-v2) 두 가지입니다. 두 유형은 GPU가 아니라 호스트 RAM이 다르며, 샌드박스에는 동일한 GPU 유형을 제공하므로 샌드박스가 어느 유형에 배치될지는 선택할 수 없습니다.

플랫폼이 CoreWeave 관리형 컴퓨팅에서 GPU를 부여하도록 GPU 요청에서 `type` 키를 제외하세요. 여기서도 이 필드를 사용할 수 있지만, 선택이 아닌 필터 역할을 합니다. 어떤 러너와도 일치하지 않는 `type`을 지정하면 `CWSANDBOX_RUNNER_UNAVAILABLE` 오류로 실패합니다. 지원되지 않는 유형을 받은 러너는 `CWSANDBOX_PLACEMENT_CONSTRAINT_UNSATISFIED` 오류를 반환하며 이를 거부합니다.

다음 예시와 같이 `resources`를 사용하여 GPU 수와 함께 CPU와 메모리를 선택하세요.

디스크는 CPU, 메모리, GPU와 함께 요청하는 것이 아니라 별도로 요청합니다. `ResourceOptions`에는 디스크 필드가 없습니다. 컨테이너의 루트 파일 시스템은 노드 로컬 임시 저장소이며, 샌드박스는 이 저장소의 일정 부분을 예약하지 않습니다. 따라서 샌드박스 내부의 `df`는 샌드박스별 할당량이 아닌 노드의 파일 시스템을 보고합니다. 전용 쓰기 가능 경로가 필요하면 스크래치 볼륨을 선언하세요:

```python theme={"system"}
import os
from cwsandbox import AuthHeaders, Sandbox, ScratchVolumeOptions

forge_auth = AuthHeaders(
    headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
    strategy="wandb_api_key",
)

with Sandbox.run(
    auth=forge_auth,
    resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
    volumes=[ScratchVolumeOptions(name="work", mount_path="/work", size="20Gi")],
    max_lifetime_seconds=3600,
) as sandbox:
    result = sandbox.exec(["df", "-h", "/work"]).result()
    print(result.stdout)
```

기본값인 디스크 기반 볼륨은 루트 파일 시스템과 동일한 노드 로컬 저장소를 사용합니다. tmpfs를 사용하려면 `medium="memory"`를 설정하세요. 메모리 기반 볼륨은 반드시 크기를 선언해야 하며, 한 컨테이너에 있는 메모리 기반 볼륨의 합계는 해당 컨테이너 메모리 요청량의 80%를 초과할 수 없습니다.

`runtime_class`도 설정하지 마세요. GPU를 요청하면 GPU 가상 머신 런타임 클래스가 자동으로 선택되지만, 직접 고정한 런타임 클래스는 지정한 그대로 사용됩니다. 따라서 GPU를 요청하면서 CPU 클래스를 고정하면 GPU에 접근할 수 없는 샌드박스가 생성됩니다.

<h3 id="create-the-sandbox">
  샌드박스 생성
</h3>

`FORGE_API_KEY`를 Forge API 키로 설정한 다음, 아래 예시를 실행하세요. 이 예시는 GPU 1개, CPU 2개, 메모리 8GiB로 샌드박스를 생성한 후 `nvidia-smi`가 보고하는 GPU를 출력합니다.

<Tabs>
  <Tab title="Python">
    이 예제는 `AuthHeaders`를 통해 Forge API 키를 전달합니다.

    ```python theme={"system"}
    import os
    from cwsandbox import AuthHeaders, Sandbox

    forge_auth = AuthHeaders(
        headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
        strategy="wandb_api_key",
    )

    with Sandbox.run(
        auth=forge_auth,
        resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
        max_lifetime_seconds=3600,
    ) as sandbox:
        result = sandbox.exec(
            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv"]
        ).result()
        print(result.stdout)
        print(sandbox.resource_gpu)
    ```

    평면 구조의 `resources` dict는 요청량과 제한을 같은 값으로 설정합니다. `"gpu": 1`은 `"gpu": {"count": 1}`의 축약형입니다. 서버리스는 샌드박스당 GPU 1개만 지원하므로 count 값을 `1`로 유지하세요.

    `resource_gpu` 속성은 플랫폼이 확정한 GPU 할당(예: `{'count': 1}`)을 반환합니다.
  </Tab>

  <Tab title="TypeScript">
    `@coreweave/cwsandbox` 패키지는 아직 GPU 리소스를 지원하지 않습니다. `resources` 옵션은 CPU와 메모리만 지원하며 `gpu` 키는 무시되므로, 샌드박스가 GPU 없이 시작됩니다. GPU 샌드박스를 생성하려면 Python 클라이언트를 사용하세요.
  </Tab>
</Tabs>

샘플 출력:

```text theme={"system"}
name, memory.total [MiB]
NVIDIA RTX PRO 6000 Blackwell Server Edition, 97887 MiB

{'count': 1}
```

GPU 샌드박스는 CPU 전용 샌드박스보다 시작하는 데 더 오래 걸립니다. 플랫폼이 GPU를 샌드박스의 가상 머신에 연결하기 때문입니다. request timeout을 설정한 경우 몇 분 정도 기다리세요.

<h2 id="run-a-gpu-sandbox-on-your-cks-cluster">
  CKS 클러스터에서 GPU 샌드박스 실행하기
</h2>

CKS 배치에서 Admin은 샌드박스가 사용할 수 있는 GPU와 그 수를 결정합니다. 러너는 클러스터의 노드에 있는 GPU 유형을 제공하며, 러너가 가진 정책은 샌드박스가 요청할 수 있는 범위를 제한합니다.

<Warning>
  자체 CKS 클러스터에서는 GPU 가상화가 지원되지 않습니다. CKS의 GPU 샌드박스는 기본적으로 클러스터의 기본 런타임 클래스에서 실행되며, 이 런타임 클래스는 `runc`를 사용합니다. 샌드박스는 노드의 커널을 공유하고 자신에게 부여된 GPU 디바이스에 직접 액세스하는 일반 컨테이너입니다. 이 모드는 **보안 컨테이너 런타임이 아니므로** 신뢰할 수 없는 코드를 실행하는 데 사용하지 마세요. 클러스터에서 일반 파드로 실행해도 이미 문제가 없다고 판단되는 워크로드에만 사용하세요. 신뢰할 수 없는 코드에는 [서버리스 용량](#run-a-gpu-sandbox-on-serverless-capacity)을 사용하세요.
</Warning>

<h3 id="prerequisites">
  사전 요구 사항
</h3>

CKS에서 GPU를 요청하기 전에 다음을 완료하세요.

* GPU 노드와 `Ready` 상태의 러너가 있는 CKS 클러스터. [자체 컴퓨팅 사용하기](/ko/products/sandboxes/get-started-cks)를 참조하세요.
* 해당 러너에 GPU를 허용하는 정책. `resources` 아래의 `maxGpuCount`는 샌드박스 하나가 요청할 수 있는 GPU 수의 한도를 지정합니다. 한도를 두지 않으려면 이 필드를 생략하고, GPU 요청을 거부하려면 `0`으로 설정하세요. GPU 샌드박스가 클러스터의 기본 런타임 클래스로 실행되도록 `defaultGpuRuntimeClass`는 설정하지 마세요. `cw-kata-nvidia-gpu`와 같은 Kata 기반 GPU 런타임 클래스는 고객 CKS 클러스터에서 지원되지 않습니다. 전체 필드는 [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure)을 참조하세요.
* `SANDBOX_USER` IAM 액션과 `CWSANDBOX_API_KEY`로 설정된 CoreWeave API 액세스 토큰.

<h3 id="find-the-gpu-types-on-your-runner">
  러너의 GPU 유형 찾기
</h3>

각 러너는 노드가 탑재한 GPU 유형을 표시합니다. `type`을 선택하기 전에 목록을 확인하세요.

```python theme={"system"}
from cwsandbox import list_runners

for runner in list_runners():
    print(runner.runner_id, runner.supported_gpu_types, runner.max_gpu_count)
```

`type`으로 전달할 정확한 문자열 값입니다. 일치 여부는 대소문자를 구분하므로 `B200`과 `b200`은 같은 유형이 아닙니다. 대신 GPU 유형으로 러너를 필터링하려면 `list_runners()`에 `gpu_type`을 전달하세요. 자세한 내용은 [사용 가능한 러너 검색](/ko/products/sandboxes/client/guides/discovery)을 참조하세요.

<h3 id="create-the-sandbox-2">
  샌드박스 만들기
</h3>

다음 예시는 CKS에 특정 유형의 GPU 2개, CPU 8개, 메모리 32 GiB를 갖춘 샌드박스를 배치합니다. `[GPU-TYPE]`을 러너가 지원하는 유형 중 하나로 바꾸거나, `type` 키를 삭제하여 러너의 모든 GPU를 허용하세요. 샌드박스가 클러스터의 기본 런타임 클래스를 사용하도록 `runtime_class`는 설정하지 마세요.

```python theme={"system"}
from cwsandbox import ResourceOptions, Sandbox

with Sandbox.run(
    placement_mode="cks",
    resources=ResourceOptions(
        requests={"cpu": "8", "memory": "32Gi"},
        limits={"cpu": "8", "memory": "32Gi"},
        gpu={"count": 2, "type": "[GPU-TYPE]"},
    ),
    max_lifetime_seconds=3600,
) as sandbox:
    result = sandbox.exec(["nvidia-smi", "-L"]).result()
    print(result.stdout)
    print(sandbox.resource_gpu)
```

조직 내의 모든 CKS 러너가 아닌 특정 러너 하나를 대상으로 하려면 `runner_ids=["[RUNNER-ID]"]`를 추가하세요. `resource_gpu`의 확인된 할당은 요청한 유형이 있더라도 개수만 보고합니다(예: `{'count': 2}`).

GPU 개수는 정책의 `maxGpuCount`와 단일 노드의 사용 가능한 GPU 수에 의해 한도됩니다. 정책 한도를 초과하는 요청은 `CWSANDBOX_RESOURCE_CEILING_EXCEEDED` 오류와 함께 실패합니다. 러너가 제공하지 않는 `type`이거나 대소문자가 다른 경우, 적합한 러너를 찾지 못해 `CWSANDBOX_RUNNER_UNAVAILABLE` 오류와 함께 실패합니다.

<h2 id="container-images">
  컨테이너 이미지
</h2>

다음 예시에서는 서버리스 용량과 앞에서 설정한 Forge API 키를 사용합니다.

플랫폼은 GPU 샌드박스 내부에 NVIDIA 드라이버와 `nvidia-smi` 도구를 제공하므로 기본 이미지가 이미 GPU를 인식할 수 있습니다. CUDA 애플리케이션을 실행하려면 코드에 필요한 CUDA 런타임과 라이브러리를 포함하는 이미지(예: `pytorch/pytorch` 또는 `nvidia/cuda` 이미지)를 사용하세요.

이미지를 GPU에 맞추세요. RTX PRO 6000 Blackwell Server Edition은 컴퓨트 capability 12.0(`sm_120`)이며 CUDA 12.8 이상이 필요하고, PyTorch 2.7이 이를 위해 빌드된 첫 릴리스였습니다. 이전 이미지도 GPU의 이름을 올바르게 보고하는데, 이는 드라이버를 통해 디바이스 메타데이터를 조회하기 때문입니다. 그런 다음 첫 번째 커널 실행에서 `CUDA error: no kernel image is available for execution on the device` 오류와 함께 실패합니다. 디바이스 이름을 신뢰하기보다는 프레임워크가 `sm_120`을 나열하는지 확인하세요:

```python theme={"system"}
import os
from cwsandbox import AuthHeaders, Sandbox

forge_auth = AuthHeaders(
    headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
    strategy="wandb_api_key",
)

CHECK_GPU = """
import torch

print(torch.cuda.get_device_capability(0))
print(torch.cuda.get_arch_list())

x = torch.ones(32, device="cuda")
print((x + x).sum().item())
torch.cuda.synchronize()
"""

with Sandbox.run(
    auth=forge_auth,
    container_image="pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime",
    resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
) as sandbox:
    result = sandbox.exec(["python", "-c", CHECK_GPU]).result()
    print(result.stdout)
```

샘플 출력:

```text theme={"system"}
(12, 0)
['sm_70', 'sm_75', 'sm_80', 'sm_86', 'sm_90', 'sm_100', 'sm_120']
64.0
```

대형 프레임워크 이미지는 기본 이미지보다 pull하는 데 더 오래 걸리므로, 샌드박스가 ready가 될 때까지 몇 분 정도 기다리세요.

<h2 id="common-errors">
  일반적인 오류
</h2>

| 오류 | 원인 | 조치 방법 |
| - | - | - |
| `CWSANDBOX_GPU_NOT_ALLOWED` | 조직이 GPU 샌드박스 허용 목록에 등록되어 있지 않습니다. | 액세스를 요청하려면 계정 담당 팀 또는 [forge-support@coreweave.com](mailto:forge-support@coreweave.com)에 문의하세요. |
| `SandboxResourceExhaustedError` (`runner capacity exhausted`) | 현재 요청을 처리할 만큼 GPU, CPU 또는 메모리 여유가 있는 노드가 없습니다. | 잠시 후 다시 시도하세요. CKS에서는 GPU 수를 줄여서 요청할 수도 있습니다. |
| `CWSANDBOX_RUNNER_UNAVAILABLE` (`no eligible runner is available`) | 요청 조건에 맞는 러너가 없습니다. 어떤 러너도 제공하지 않는 GPU `type`을 지정한 경우가 원인일 수 있으며, 대소문자를 잘못 입력한 경우도 포함됩니다. 현재 연결된 적격 러너가 없을 때도 같은 코드가 표시됩니다. | 서버리스에서는 `type`을 제거하세요. CKS에서는 `supported_gpu_types`에 있는 유형을 사용하거나 `type`을 제거하세요. `type`이 이미 올바르다면 다시 시도하세요. |
| `CWSANDBOX_RESOURCE_CEILING_EXCEEDED` (`gpu count exceeds the policy maximum`) | 요청한 GPU 수가 정책의 `maxGpuCount`를 초과합니다. | GPU 수를 줄이거나 Admin에게 한도 상향을 요청하세요. |
| `nvidia-smi: not found` | 샌드박스에 GPU가 없거나 이미지에서 NVIDIA 도구를 제공하지 않습니다. | 먼저 `sandbox.resource_gpu`를 확인하세요. 0보다 큰 값이 표시되면 GPU는 할당된 것이므로 이미지를 변경해야 합니다. |

<h2 id="next-steps">
  다음 단계
</h2>

* [샌드박스 설정](/ko/products/sandboxes/client/guides/sandbox-configuration)에서는 모든 `ResourceOptions` 필드, QoS 클래스, timeout을 다룹니다.
* [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure)에서는 Admin이 CKS 러너에 설정하는 GPU, 런타임 클래스, 리소스 제약 조건을 설명합니다.
* [시작하기](/ko/products/sandboxes/get-started)에서는 CPU 전용 서버리스 샌드박스와 사용자 인증 정보를 다룹니다.
* [자체 컴퓨팅 사용하기](/ko/products/sandboxes/get-started-cks)에서는 러너를 설정하고 클러스터에서 첫 번째 샌드박스를 실행하는 방법을 다룹니다.