Skip to main content
이 가이드에서는 CWSandbox 클라이언트를 사용하여 CoreWeave 샌드박스 인스턴스 내부에서 파일을 조회하고, 쓰고, 관리하는 방법을 설명합니다. 샌드박스 안팎으로 데이터를 이동하는 워크플로를 구축하는 개발자를 대상으로 하며, 병렬 업로드 및 다운로드, 오류 처리, 대용량 파일 패턴 등을 다룹니다.

인증 방식 선택

이 예시는 섹션에서 CKS를 별도로 지정하지 않는 한 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하는 방법은 사용자 인증 정보 선택 및 조회를 참조하세요. 설치 명령어는 활성화된 Python 가상 환경에서 실행하세요. 사용 중인 사용자 인증 정보 탭의 Python 코드를 sandbox_auth.py로 저장하되, 이 페이지에서 실행할 Python script와 같은 위치에 두세요. 이 파일에는 사용자 인증 정보 자체가 아니라 어떤 인증 방식을 사용할지만 저장됩니다. 예시에서는 이 파일에서 AUTH를 임포트한 뒤 새 샌드박스나 세션을 만들 때마다 명시적으로 전달합니다.
SDK의 W&B 인증 전략으로 Forge API 키를 사용하세요.
sandbox_auth.py
CKS 배치를 사용하려면 CoreWeave 토큰을 선택하고 러너를 활성화한 다음, 샌드박스를 생성할 때 또는 SandboxDefaults에서 placement_mode="cks"를 설정하세요. auth=AUTH로 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나 목록을 조회하거나 정리할 때도 동일한 사용자 인증 정보를 사용하세요.

기본 오퍼레이션

이 섹션의 예시에서는 가장 일반적인 파일 오퍼레이션인 샌드박스 내 경로에 데이터를 쓰고 다시 조회하는 방법을 다룹니다. 파일 오퍼레이션은 OperationRef 객체를 반환합니다. 완료될 때까지 대기하려면 .result()를 사용하세요.

파일 쓰기

파일을 쓰고 읽는 동안에는 샌드박스를 계속 실행 상태로 두세요. 이 예제에서는 파일 두 개를 생성한 다음, 컨텍스트 관리자가 샌드박스를 중지하기 전에 해당 파일을 읽습니다.

파일 조회

read_file()은 파일 내용을 바이트로 반환합니다. 파일 쓰기의 예시에서는 decode()로 텍스트를 조회하고 json.loads()로 JSON을 파싱합니다. 두 조회 작업 모두 활성 샌드박스 컨텍스트 안에서 실행됩니다.

병렬 오퍼레이션

파일 오퍼레이션은 즉시 반환되어 자연스러운 병렬 처리를 가능하게 합니다. 여러 독립 파일에 대해 업로드 또는 다운로드를 병렬로 실행하면 전체 전송 시간을 줄일 수 있습니다.

병렬 업로드

병렬 다운로드

업로드-처리-다운로드 패턴

일반적인 워크플로: 입력 파일을 업로드하고, 처리를 실행한 후, 결과를 다운로드합니다.

오류 처리

파일 오퍼레이션은 경로가 존재하지 않거나 쓰기 권한이 없는 경우 실패할 수 있습니다. 이러한 경우를 처리하고 영향을 받는 경로를 검사하려면 SandboxFileError를 catch하세요.

파일을 찾을 수 없음

쓰기 오류

바이너리 파일

파일 오퍼레이션은 이미지와 직렬화된 Python 객체를 포함한 모든 바이너리 콘텐츠를 처리합니다:
신뢰할 수 있는 소스에서만 데이터를 언피클하세요. 피클 파일을 로드하면 임의의 코드가 실행될 수 있습니다.

텍스트 인코딩

파일은 바이트로 전송되므로 비ASCII 문자가 손상되지 않도록 텍스트를 명시적으로 인코딩하고 디코딩해야 합니다.

대용량 파일 고려 사항

read_file 및 write_file API는 소형 또는 중간 크기의 파일에 가장 적합합니다. 대용량 파일을 다룰 때는 다음 사항을 고려하세요.
  • 파일이 API를 통해 전송되므로 대역폭을 감안하세요.
  • 대용량 데이터 세트는 가능하면 스트리밍을 사용하세요.
  • API를 통해 데이터를 전송하는 대신 객체 저장소에 직접 액세스하세요.
object_storage_access 매개변수는 임시 CoreWeave AI Object Storage 사용자 인증 정보를 생성하여 샌드박스의 컨테이너에 제공합니다. 이를 통해 워크로드가 버킷을 직접 읽고 쓸 수 있으므로 대용량 객체가 read_file이나 write_file을 거치지 않습니다. 이 기능을 사용하려면 먼저 조직에서 샌드박스 컨트롤 플레인에 워크로드 아이덴티티 제휴 설정을 등록해야 합니다. 자세한 내용은 객체 저장소 액세스를 참조하세요. 다음 예시에서는 CoreWeave 인증을 사용하여 버킷 하나에 대한 읽기/쓰기 액세스 권한을 가진 샌드박스를 시작한 다음, 사용자 인증 정보가 주입되었는지 확인합니다. CWSANDBOX_API_KEY를 설정이 완료된 조직의 CoreWeave API 액세스 토큰으로 지정하고, [BUCKET-NAME]을 사용할 버킷 이름으로 바꾸세요.
샌드박스는 AWS SDK가 컨테이너 사용자 인증 정보를 가져올 때 조회하는 환경 변수를 설정합니다. 따라서 샌드박스 내부의 모든 S3 호환 클라이언트는 키를 명시적으로 지정하지 않아도 작동합니다. 해당 변수와 Boto3 예시는 샌드박스 내부에서 사용자 인증 정보 사용을 참조하세요. 사용자 인증 정보의 범위를 특정 키 접두사로 제한하려면 object_prefix를 사용하세요. 데이터를 읽기만 하는 워크로드에는 ObjectStoragePermission.READ를 사용하세요. 샌드박스 내에서만 사용하는 대용량 임시 데이터라면 볼륨을 연결하는 것이 좋습니다. 자세한 내용은 볼륨을 참조하세요.
마지막 수정일 2026년 10월 27일