메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt

Use this file to discover all available pages before exploring further.

Workspace와 Job의 컨테이너는 일회성이에요. 데이터셋, 모델 체크포인트, 큰 설정 파일을 학습 스크립트가 사용할 수 있게 하려면 영구 볼륨에 올리고 그 볼륨을 워크로드에 마운트해야 해요. 이 가이드에서는 데이터를 볼륨에 올리는 실용적인 방법들을 안내해요.
데이터를 Job 명령어에 직접 인코딩해서 넣지 마세요. gzip+base64 블롭, 긴 heredoc, 그 외 큰 페이로드를 --cmd에 붙여 넣는 방식은 API 단에서 거절돼요. 명령어 본문이 256 KiB를 넘거나, 환경변수 값이 8 KiB를 넘거나, 환경변수 쌍이 128개를 초과하면 4xx 오류로 응답해요. 아래 패턴 중 하나를 사용하세요.

​
한눈에 보기

어떤 종류의 볼륨인지에 따라 접근 방식이 달라요.
볼륨 종류데이터 적재 방법
Object storage내 컴퓨터에서 vesslctl volume upload로 직접 업로드하거나, vesslctl volume token으로 발급받은 자격증명을 쓰는 S3 호환 클라이언트로 업로드해요.
Cluster storage볼륨을 Workspace에 마운트한 뒤, 그 Workspace 안에서 마운트 경로로 데이터를 가져와요.

​
Object storage: 내 컴퓨터에서 업로드

vesslctl volume upload가 기본 경로예요. 파일이 내 컴퓨터에서 S3로 바로 전송되기 때문에, 전송 크기는 네트워크 대역폭과 스토리지 할당량으로만 제한돼요.
1

Object storage 볼륨 선택 또는 생성

vesslctl volume list --type object
새 볼륨이 필요하다면 볼륨 만들기를 참고하거나 CLI로 만들 수 있어요:
vesslctl volume create \
  --name training-data \
  --storage <object-storage-slug> \
  --teams <team-name>
--teams는 이 볼륨을 마운트할 수 있는 팀을 지정해요. Object storage에서는 필수예요.
2

로컬 파일 업로드

vesslctl volume upload <volume-slug> ./dataset/ \
  --remote-prefix datasets/v1/ \
  --exclude "*.pyc" \
  --exclude "__pycache__"
--dry-run은 실제 전송 없이 파일 목록을 미리 보여줘요. --overwrite는 기존 원격 키를 덮어쓰고, 기본값은 동일 키를 건너뛰어요. 전체 플래그는 vesslctl volume upload를 참고하세요.
3

확인하고 마운트

vesslctl volume ls <volume-slug> --prefix datasets/v1/
Workspace에 마운트하거나, Job에 --object-volume <volume-slug>:/shared로 전달하세요.
다른 도구(aws s3 cp, rclone, DVC, 또는 자체 파이프라인)에서 업로드를 돌리고 싶다면 vesslctl volume token <volume-slug>로 해당 볼륨에만 한정된 임시 S3 자격증명과 엔드포인트 URL을 받을 수 있어요. vesslctl volume token 참고.

​
Cluster storage: Workspace를 거쳐서 적재

vesslctl volume upload는 Cluster storage 볼륨을 지원하지 않아요. 대신 Cluster storage 볼륨을 Workspace에 마운트한 뒤, 그 Workspace 안에서 마운트 경로로 데이터를 가져오세요.
1

볼륨을 마운트한 Workspace 만들기

Persistent volume에서 Cluster storage 볼륨을 명확한 경로(예: /data)에 마운트하세요:
vesslctl workspace create \
  --name data-loader \
  --cluster <cluster-slug> \
  --resource-spec <spec-slug> \
  --image quay.io/vessl-ai/torch:2.9.1-cuda13.0.1-py3.13-slim \
  --cluster-volume <cluster-volume-slug>:/data
필요한 도구(curl, wget, aws, huggingface-cli, git-lfs 등)가 들어 있는 어떤 컨테이너 이미지든 괜찮아요. 데이터를 옮기는 동안의 시간당 비용을 최소화하려면 vesslctl resource-spec list에서 CPU only 스펙을 골라요.
2

Workspace에 접속

Workspace가 running 상태가 될 때까지 기다린 뒤 SSH 또는 JupyterLab으로 접속하세요. Workspace에 접속하기를 참고하세요.접속한 뒤 cd /data(또는 지정한 마운트 경로)로 이동하세요. 이 경로 아래에 쓰는 모든 데이터는 Cluster storage 볼륨에 저장되고, Workspace를 일시정지하거나 terminate해도 유지돼요.
3

데이터 가져오기(아래 패턴 중 선택)

데이터가 어디에 있는지에 따라 다음 패턴 중 하나를 고르세요.
4

작업이 끝나면 Workspace 일시정지

Cluster storage 데이터는 pause 후에도 유지돼요. 데이터를 보관하려고 Workspace를 계속 켜둘 필요는 없어요. 일시정지하면 컴퓨트 비용 청구가 멈춰요:
vesslctl workspace pause <workspace-slug>
데이터를 추가하거나 수정해야 할 때는 vesslctl workspace start <workspace-slug>로 다시 시작할 수 있어요.

​
패턴 A: 인터넷에서 직접 다운로드

가장 단순하고 흔한 경우예요. 데이터가 이미 공개 URL(또는 토큰 인증 URL)에 있을 때 쓰세요. 
# 볼륨이 /data에 마운트된 Workspace 셸 안에서
cd /data

# 일반 HTTP(S) 다운로드
wget https://example.com/datasets/imagenet-subset.tar.gz
tar -xzf imagenet-subset.tar.gz

# Hugging Face datasets / 모델 저장소
pip install -U "huggingface_hub[cli]"
huggingface-cli download <org>/<repo> --local-dir ./hf-cache --repo-type dataset

# S3 / GCS / Azure (각 클라우드의 CLI 사용)
aws s3 sync s3://my-bucket/datasets/v1/ ./datasets/v1/
대용량 전송에서는 aria2c -x 16이 HTTP 다운로드를 병렬화해 주고, rclone copy는 클라우드 스토리지 제공자별 retry/검증을 자동으로 처리해요.

​
패턴 B: 내 컴퓨터에서 SSH로 푸시

데이터가 내 컴퓨터에만 있고 인터넷을 한 번 거치는 게 번거로울 때, SSH로 마운트 경로에 직접 복사하세요. 
# scp: 단일 파일 또는 디렉터리
scp -i /path/to/<key> -P <port> ./dataset.tar.gz \
  root@<workspace-host>:/data/

# rsync: 재시작 가능, 변경분만 전송. 큰 디렉터리에 추천.
rsync -avh --progress -e "ssh -i /path/to/<key> -p <port>" \
  ./dataset/ root@<workspace-host>:/data/
호스트, 포트, 키 경로는 Workspace의 Connect 탭에서 확인할 수 있어요. 자세한 내용은 Workspace에 접속하기를 참고하세요. 수 GB 이상의 전송은 rsync가 더 안전해요. 연결이 끊겨도 이어서 진행할 수 있고(--partial), 다시 실행하면 변경된 파일만 보내요.

​
패턴 C: Object storage를 중간 단계로 거치기

내 컴퓨터의 데이터를 다른 클러스터의 Cluster storage(또는 한 클러스터에서 다른 클러스터)로 일회성 복사할 때, Object storage를 휴대 가능한 중간 저장소로 활용해요. Object storage는 모든 클러스터에서 접근 가능하니까요. 
# 1. 내 컴퓨터에서: Object storage 볼륨에 업로드
vesslctl volume upload <object-volume-slug> ./dataset/ \
  --remote-prefix v1/

# 2. 두 볼륨을 모두 마운트한 data-loader Workspace 생성
vesslctl workspace create \
  --name data-loader \
  --cluster <cluster-slug> \
  --resource-spec <spec-slug> \
  --image quay.io/vessl-ai/torch:2.9.1-cuda13.0.1-py3.13-slim \
  --object-volume <object-volume-slug>:/shared \
  --cluster-volume <cluster-volume-slug>:/data

# 3. Workspace 안에서: /shared의 내용을 /data로 복사
cp -r /shared/v1/. /data/v1/
복사가 끝나면 Object storage에 있는 사본은 보관 여부를 선택할 수 있어요. 더 이상 필요 없으면 볼륨에서 지우거나, 백업 용도로 그대로 두면 돼요.

​
패턴 D: Custom HTTP 포트 열기

브라우저로 끌어다 놓는 업로드 UI, 동기화 서버, 외부 서비스의 webhook 같은 게 필요할 때 쓰세요. Workspace 생성 시 custom HTTP 또는 TCP 포트를 열고(Workspace 만들기 → Advanced settings → 포트 참고) 마운트 경로에서 직접 서비스하면 돼요. 
# 브라우저용 간단 업로드 UI를 custom HTTP 포트(예: 8000)에 띄우기
pip install --no-cache-dir uvicorn fastapi python-multipart
# … 또는 작은 업로드 서버 도구: filebrowser, miniserve --upload-files 등

# rclone serve: /data를 HTTP/WebDAV/SFTP로 노출
rclone serve http /data --addr :8000  # 내 컴퓨터의 rclone에서 이 엔드포인트로 동기화
CLI 업로드(Object)도, SSH 복사(패턴 B)도 맞지 않을 때 쓰세요. 예를 들어 SSH 접근 권한이 없는 동료가 파일을 떨궈야 하거나, 외부 서비스가 Workspace로 데이터를 푸시해야 하는 경우예요.
Custom 포트는 Workspace URL이 닿을 수 있는 어디서든 접근 가능해요. 다른 공개 엔드포인트와 똑같이 다뤄야 해요. basic auth, 일회성 토큰을 붙이거나, 적재가 끝나면 포트를 닫아 주세요.

​
안티패턴: --cmd에 데이터를 박지 마세요

특히 LLM 코딩 에이전트가 빠지기 쉬운 함정이 있어요. 데이터셋을 gzip+base64로 인코딩해 셸 한 줄로 --cmd에 통째로 넣는 방식이에요: 
# 이렇게 하지 마세요. API가 256 KiB 초과 --cmd를 거절하고,
# 그보다 짧더라도 인라인 블롭은 재현·관찰이 어려워져요.
vesslctl job create \
  --cmd "echo 'H4sIAA...<3 MiB의 base64>...' | base64 -d | gunzip > /tmp/data && python eval.py"
API가 이를 거절해요. Job.command는 256 KiB, 환경변수 값은 각 8 KiB, 환경변수 쌍의 총 개수는 128개로 제한되고, 이 한도를 넘으면 4xx로 응답해요. 언제든 데이터는 볼륨에 올린 뒤(이 페이지) 마운트해서 사용하세요.

​
다음으로