CWSANDBOX_API_KEY에 설정된 CoreWeave API 액세스 토큰을 사용합니다. Forge API 키 인증은 시작하기를 참조하세요. CKS 요구 사항은 배치 모드를 참조하세요.
이 가이드는 리소스, 마운트된 파일, 포트, 어노테이션, timeout을 포함한 샌드박스 설정 옵션을 다룹니다. 워크로드의 요구 사항에 맞게 샌드박스의 런타임 환경을 조정해야 할 때(예: GPU 용량 예약, 서비스 노출, 오퍼레이션 timeout 설정) 레퍼런스로 사용하세요.
이 페이지는 cwsandbox Python SDK를 사용하여 샌드박스를 시작하고 관리하는 개발자를 위한 것입니다.
개요
샌드박스 설정은 세 곳에서 지정할 수 있으며, 범위가 가장 넓은 것부터 가장 구체적인 것 순으로 나열하면 다음과 같습니다.- SandboxDefaults: 세션 내 모든 샌드박스에 공통으로 적용되는 기본값입니다.
- Sandbox.run() kwargs: 샌드박스별로 기본값을 재정의합니다.
- @session.function() kwargs: 함수별 설정입니다.
리소스
ResourceOptions dataclass 또는 plain dict를 사용하여 CPU, 메모리, GPU 리소스를 설정하세요. Serverless는 기본 배치 모드이며 동일한 requests와 limits를 사용합니다. requests와 limits가 다른 경우, 이를 허용하는 policy를 가진 러너와 함께 CKS 배치를 사용하세요.
다음 예시에서는 동일한 requests와 limits를 사용합니다:
ResourceOptions로 자동 변환합니다.
ResourceOptions는 리소스 요청과 limits를 분리합니다. 요청은 스케줄러에게 샌드박스가 필요한 것을 알려줍니다. limits는 사용할 수 있는 최대치를 설정합니다. Kubernetes가 요청과 limits를 사용하여 Quality of Service classes를 부여하는 방법에 대한 배경 지식은 Kubernetes 문서를 참조하세요.
ResourceOptions 필드
클라이언트에서는 모든 필드가 선택이며 기본값은
None입니다. 최종 확정된 할당은 적용되는 정책을 충족해야 합니다. 리소스 할당을 생략하면 해당 정책에 정의된 완전한 양수 CPU 및 메모리 기본값이 요청량과 제한으로 모두 사용됩니다.
Guaranteed QoS
요청량과 제한이 같을 때, 샌드박스는 Guaranteed Quality of Service 클래스를 받습니다. 스케줄러는 할당량 전체를 예약하며, 노드 리소스가 부족해지면 Kubernetes는 Guaranteed 파드를 가장 마지막에 축출합니다. 다만 제한보다 많은 CPU를 사용하려는 샌드박스는 이 경우에도 스로틀링됩니다. 지연 시간에 민감한 워크로드에 사용하세요.Burstable QoS
CKS 러너의 정책이 요청량과 제한을 다르게 허용하는 경우, 낮은 요청량은 샌드박스에 Burstable Quality of Service 클래스를 부여합니다. 낮은 요청량을 사용하면 스케줄러가 더 많은 샌드박스를 bin-pack할 수 있지만, 각 샌드박스는 용량이 사용 가능하다면 limit까지 burst할 수 있습니다. 자체 컴퓨팅 사용을 완료하고CWSANDBOX_API_KEY를 CoreWeave API 액세스 토큰으로 설정하세요. [RUNNER-ID]를 요청량과 제한을 허용하는 CKS 러너의 ID로 교체하세요:
CPU 값
CPU를 밀리코어 또는 전체 코어 단위로 지정하세요. 자세한 내용은 Kubernetes의 리소스 단위를 참조하세요.메모리 값
메모리는 표준 Kubernetes 메모리 단위를 사용합니다:GPU
CPU 및 메모리와 함께 GPU 리소스를 요청하세요. GPU 요청은 GPU만 예약하므로 CPU와 메모리를 명시적으로 설정하세요.type과 memory_gb는 대안입니다. 둘 중 하나만 설정하세요.
Inspect confirmed resources
샌드박스가 시작된 후, 확인된 리소스 할당을 검사하세요. 이 예제는 CKS에서 불균등한 requests와 limits를 사용합니다. CKS 설정을 완료하고CWSANDBOX_API_KEY를 CoreWeave API access token으로 설정하세요. [RUNNER-ID]를 GPU 용량이 있고 이러한 리소스를 허용하는 정책이 있는 CKS 러너의 ID로 교체하세요:
설정 라이브러리 상호 운용성
모든 설정 유형(NetworkOptions, Secret, ResourceOptions)은 dataclass 또는 plain dict를 허용합니다. 이는 설정을 dict 또는 dict-like 객체로 해결하는 ML 설정 라이브러리가 수동 변환 없이 SDK에 값을 직접 전달할 수 있음을 의미합니다.
SandboxDefaults.from_dict()는 plain dict 또는 OmegaConf DictConfig를 허용하며 중첩된 필드를 자동으로 강제 변환합니다. dict는 필요에 따라 NetworkOptions, Secret 또는 ResourceOptions가 되고, 목록은 튜플이 됩니다.
Sandbox.run() 또는 session.sandbox()에 직접 전달할 때 dict도 허용합니다. 리소스에 대한 중첩 dict 형식은 ResourceOptions 필드에 매핑됩니다. 평면 dict 형식({"cpu": "1", "memory": "1Gi"})도 허용되며 Guaranteed QoS로 처리됩니다.
마운트된 파일
마운트된 파일을 사용하면 시작 시 샌드박스에 설정 파일, 스크립트 또는 기타 읽기 전용 에셋을 제공할 수 있으며, 이를 컨테이너 이미지에 포함하지 않아도 됩니다.마운트 옵션
마운트된 파일은 읽기 전용입니다. 수정이 필요한 파일에는
write_file()을 사용하세요.
포트
샌드박스 내부의 프로세스가 외부 클라이언트에 트래픽을 서빙할 수 있도록 포트를 노출하세요:포트 설정
플랫폼 TLS 또는 TLS 패스스루를 사용하여 포트에 인터넷에서 접근 가능한 주소를 부여하려면 공개 엔드포인트를 참조하세요.
네트워크
네트워크 옵션을NetworkOptions dataclass 또는 plain dict를 사용하여 설정하세요:
NetworkOptions로 자동 변환합니다.
NetworkOptions 필드
모든 필드는 선택 사항이며 기본값은
None으로, backend 기본값을 사용합니다.
SandboxDefaults에서 네트워크 설정
모든 샌드박스에 대한 기본 네트워크 설정을 설정하세요:어노테이션
샌드박스에 Kubernetes 파드 어노테이션을 추가하세요. 어노테이션은 기본 파드에 연결된 키-값 문자열 쌍으로, 스케줄러, 비용 할당 도구 또는 외부 자동화와 같이 파드 메타데이터를 조회하는 인테그레이션에 유용합니다.세션 수준 기본값
세션의 모든 샌드박스에 대한 기본 어노테이션을 설정하세요:병합 동작
SandboxDefaults.annotations와 샌드박스별 annotations를 모두 제공하면 SDK가 이를 병합합니다. 키 충돌 시 명시적인 샌드박스별 값이 우선하며, 이는 environment_variables와 동일한 의미 체계를 따릅니다.
SUNK 인테그레이션
SUNK 인테그레이션을 위해 Slurm 컨텍스트를 파드 어노테이션으로 전달하려면 SUNK Pod Scheduler 인테그레이션 가이드를 참조하세요.검증
SDK는 어노테이션 키나 값을 검증하지 않습니다. 서버는 예약된 키 접두사, 값 형식, 최대 엔트리 수에 대한 검증을 처리합니다.시크릿
Forge 팀 시크릿 주입, 인증 요구 사항 및 Python과 TypeScript 예시에 대해서는 Forge 시크릿 사용을 참조하세요.timeout
샌드박스와 그 오퍼레이션이 실행되는 시간을 제어하는 네 가지 설정이 있습니다. 이름이 비슷하므로 다음 table은 각 설정이 무엇을 제한하는지 매핑합니다.max_lifetime_seconds만 샌드박스를 종료합니다. 나머지 세 가지는 개별 요청을 제한하고 샌드박스는 계속 실행되도록 둡니다.
max_lifetime_seconds
max_lifetime_seconds는 샌드박스의 전체 wall-clock 수명을 설정합니다. 샌드박스가 이 나이에 도달하면, 작업이 진행 중이더라도 플랫폼이 샌드박스를 종료합니다.
max_lifetime_seconds를 설정하지 않으면 러너 정책의 기본값이 적용됩니다. 정책 기본값에 양수 수명이 지정되어 있지 않으면 플랫폼은 10분을 사용합니다. 오래 실행되는 작업에는 값을 명시적으로 설정하세요:
SandboxDefaults에서 설정하세요:
Sandbox.run()의 명시적인 max_lifetime_seconds 인수는 defaults의 값보다 우선합니다. 인수의 기본값이 None이므로, defaults에 이미 설정된 수명을 제거하는 데 이 인수를 사용할 수 없습니다.
요청할 수 있는 수명은 서버리스 배치와 CKS 배치 모두 30일(2,592,000초)입니다. 플랫폼은 이보다 긴 요청을 거부합니다.
생성 예시와 CKS 러너 정책 기본값은 장기 실행 샌드박스 실행을 참조하세요.
최대 실행 시간이 만료될 때의 동작
플랫폼은 샌드박스의 기본 Kubernetes 작업을 종료하여 최대 실행 시간을 강제 적용하므로, 종료는 즉각적이며 우아하지 않습니다. 실제로 중요한 두 가지 결과가 있습니다:- 샌드박스 내부의 프로세스는
stop()에서 제공하는 유예 기간을 받지 못합니다. 이미 기록되지 않은 모든 것은 손실됩니다. - 클라이언트는 종료에 대한 distinct 오류 또는 이유를 받지 못합니다. SDK는
Sandbox에서 종료 이유를 보고하지 않으므로, 최대 실행 시간 만료를 다른 실패와 프로그래밍 방식으로 구분할 수 없습니다. 장기 실행 샌드박스의 수명을 직접 추적하세요.
timeout_seconds
timeout_seconds는 실행 중인 샌드박스에서 단일 오퍼레이션의 시간 제한을 설정합니다:
SandboxTimeoutError 예외를 발생시킵니다. 샌드박스는 계속 실행됩니다. 시간 측정은 샌드박스가 RUNNING 상태에 도달한 후에만 시작되므로 시작 시간은 포함되지 않습니다.
timeout_seconds를 샌드박스의 max_lifetime_seconds보다 낮게 설정하세요. timeout이 샌드박스의 남은 최대 실행 시간을 초과하는 명령은 샌드박스가 종료될 때 중지됩니다.
max_timeout_seconds
max_timeout_seconds는 시도가 실패하기 전까지 서버가 샌드박스를 러너에 배치하기 위해 기다리는 시간을 제한합니다. 이는 서버 측 배치 시간 한도이며 클라이언트의 읽기 timeout이 아닙니다. 또한 이후 샌드박스가 실행되는 시간에는 영향을 주지 않습니다:
max_timeout_seconds는 Sandbox.run()과 session.sandbox()에서 사용 가능하지만, SandboxDefaults에서는 사용할 수 없습니다.
request_timeout_seconds
request_timeout_seconds는 대부분의 RPC에 적용되는 클라이언트 측 HTTP timeout이며, 호출에 자체 timeout_seconds가 전달되지 않으면 이 값이 대신 사용됩니다. SandboxDefaults에서 설정하세요.
poll_rpc_timeout_seconds가 사용되므로, 응답이 멈춘 폴링은 전체 요청 timeout 동안 차단되지 않고 빠르게 실패합니다. 클라이언트 측 튜닝 옵션 전체 목록은 SandboxDefaults 레퍼런스를 참조하세요.