W&B 서버 외부에 저장된 파일을 추적하고 사용하려면 reference artifacts를 사용하세요. 일반적인 외부 스토리지 솔루션으로는 CoreWeave AI Object Storage, Amazon Simple Storage Service (Amazon S3) 버킷, GCS 버킷, Azure blob, HTTP 파일 서버 또는 NFS 공유 등이 있습니다.
Reference artifacts는 일반 아티팩트와 유사하게 동작합니다. 주요 차이점은 reference artifacts가 파일의 크기 및 MD5 체크섬과 같은 파일에 대한 메타데이터만 포함한다는 것입니다. 파일 자체는 시스템을 떠나지 않습니다.
일반 아티팩트와 마찬가지로 reference artifact와 상호작용할 수 있습니다. W&B 앱에서 파일 브라우저를 사용하여 reference artifact의 콘텐츠를 탐색하고, 전체 종속성 그래프를 조사하며, 아티팩트의 버전 관리 히스토리를 스캔할 수 있습니다. 그러나 데이터 자체가 아티팩트 내에 포함되어 있지 않기 때문에 UI에서 이미지, 오디오와 같은 리치 미디어를 렌더링할 수는 없습니다.
외부 파일을 추적하지 않는 아티팩트를 로그하면, W&B는 아티팩트 파일을 W&B 서버에 저장합니다. 이는 W&B Python SDK로 아티팩트를 로그할 때의 기본 행동입니다.외부 파일을 추적하는 아티팩트를 로그하면, W&B는 오브젝트의 ETag 및 크기와 같은 오브젝트에 대한 메타데이터를 로그합니다. 버킷에 오브젝트 버전 관리가 활성화되어 있으면 버전 ID도 함께 로그됩니다.
외부 버킷의 아티팩트 추적하기
W&B 외부에 저장된 파일에 대한 레퍼런스를 추적하려면 W&B Python SDK를 사용하세요.
wandb.init()으로 run을 초기화합니다.wandb.Artifact()로 아티팩트 오브젝트를 생성합니다.- 아티팩트 오브젝트의
wandb.Artifact.add_reference() 메소드를 사용하여 버킷 경로에 대한 레퍼런스를 지정합니다.
run.log_artifact()로 아티팩트의 메타데이터를 로그합니다.
import wandb
# W&B run 초기화
with wandb.init(project="my-project") as run:
# 아티팩트 오브젝트 생성
artifact = wandb.Artifact(name="name", type="type")
# 버킷 경로에 대한 레퍼런스 추가
artifact.add_reference(uri = "uri/to/your/bucket/path")
# 아티팩트 메타데이터 로그
run.log_artifact(artifact)
s3://my-bucket
|datasets/
|-- mnist/
|models/
|-- cnn/
datasets/mnist/ 디렉토리에는 이미지 컬렉션이 포함되어 있습니다. datasets/mnist/ 디렉토리를 dataset 아티팩트로 추적하려면 다음과 같이 지정합니다.
- 아티팩트 이름을
"mnist"와 같이 입력합니다.
- 아티팩트 오브젝트를 생성할 때
type 파라미터를 "dataset"으로 설정합니다 (wandb.Artifact(type="dataset")).
wandb.Artifact.add_reference()를 호출할 때 datasets/mnist/ 디렉토리에 대한 경로를 Amazon S3 URI (s3://my-bucket/datasets/mnist/)로 제공합니다.run.log_artifact()로 아티팩트를 로그합니다.
다음 코드 예시는 mnist:latest라는 reference artifact를 생성합니다.
import wandb
with wandb.init(project="my-project") as run:
artifact = wandb.Artifact(name="mnist", type="dataset")
artifact.add_reference(uri="s3://my-bucket/datasets/mnist")
run.log_artifact(artifact)
W&B Artifacts는 CoreWeave Storage 및 MinIO를 포함한 모든 Amazon S3 호환 인터페이스를 지원합니다. 아래에 설명된 스크립트는 AWS_S3_ENDPOINT_URL 환경 변수를 CoreWeave Storage 또는 MinIO 서버를 가리키도록 설정하면 두 제공업체 모두에서 그대로 작동합니다.
기본적으로 W&B는 오브젝트 접두사(prefix)를 추가할 때 10,000개의 오브젝트 제한을 둡니다. wandb.Artifact.add_reference()를 호출할 때 max_objects=를 지정하여 이 제한을 조정할 수 있습니다.
외부 버킷에서 아티팩트 다운로드하기
W&B는 아티팩트가 로그될 때 기록된 메타데이터를 사용하여 reference artifact를 다운로드할 때 기본 버킷에서 파일을 가져옵니다. 버킷에 오브젝트 버전 관리가 활성화되어 있는 경우, W&B는 아티팩트가 로그된 시점의 파일 상태에 해당하는 오브젝트 버전을 가져옵니다. 버킷의 콘텐츠가 변경되더라도 아티팩트가 트레이닝 run 동안의 버킷 스냅샷 역할을 하므로, 특정 모델이 트레이닝된 데이터의 정확한 버전을 항상 가리킬 수 있습니다.
다음 코드 예시는 reference artifact를 다운로드하는 방법을 보여줍니다. 아티팩트를 다운로드하기 위한 API는 reference artifact와 일반 아티팩트 모두 동일합니다.
import wandb
with wandb.init(project="my-project") as run:
artifact = run.use_artifact("mnist:latest", type="dataset")
artifact_dir = artifact.download()
워크플로우의 일부로 파일을 덮어쓰는 경우 스토리지 버킷에서 ‘오브젝트 버전 관리(Object Versioning)‘를 활성화하는 것이 좋습니다.버전 관리가 활성화되어 있으면 아티팩트가 로그된 이후 파일이 덮어쓰여졌더라도 W&B는 아티팩트를 다운로드할 때 항상 정확한 버전의 파일을 가져올 수 있습니다.사용자의 유스 케이스에 따라 오브젝트 버전 관리를 활성화하는 지침을 읽어보세요: AWS, Google Cloud, Azure. 버킷에서 외부 파일 추가 및 다운로드하기
다음 코드 예시는 데이터셋을 Amazon S3 버킷에 업로드하고, 이를 reference artifact로 추적한 다음 다운로드하는 과정을 보여줍니다.
import boto3
import wandb
with wandb.init() as run:
# 여기서 트레이닝 진행...
s3_client = boto3.client("s3")
s3_client.upload_file(file_name="my_model.h5", bucket="my-bucket", object_name="models/cnn/my_model.h5")
# 모델 아티팩트 로그
model_artifact = wandb.Artifact("cnn", type="model")
model_artifact.add_reference("s3://my-bucket/models/cnn/")
run.log_artifact(model_artifact)
import wandb
with wandb.init() as run:
artifact = run.use_artifact(artifact_or_name = "cnn", type="model")
datadir = artifact.download()
Google Cloud 또는 Azure에서 레퍼런스로 아티팩트를 추적하는 방법에 대한 엔드투엔드 워크스루는 다음 리포트를 참조하세요: 클라우드 스토리지 인증 정보
W&B는 사용하는 클라우드 제공업체에 기반하여 인증 정보를 찾는 기본 메커니즘을 사용합니다. 사용되는 인증 정보에 대해 자세히 알아보려면 클라우드 제공업체의 문서를 읽어보세요.
| 클라우드 제공업체 | 인증 정보 문서 |
|---|
| CoreWeave AI Object Storage | CoreWeave AI Object Storage 문서 |
| AWS | Boto3 문서 |
| Google Cloud | Google Cloud 문서 |
| Azure | Azure 문서 |
AWS_REGION 환경 변수를 버킷 리전과 일치하도록 설정해야 합니다.
버킷의 CORS 구성에 따라 이미지, 오디오, 비디오 및 포인트 클라우드와 같은 리치 미디어가 앱 UI에서 렌더링되지 않을 수 있습니다. 버킷의 CORS 설정에 app.wandb.ai를 허용 목록(allowlist)에 추가하면 W&B 앱에서 이러한 리치 미디어를 적절하게 렌더링할 수 있습니다.이미지, 오디오, 비디오 및 포인트 클라우드와 같은 리치 미디어가 앱 UI에서 렌더링되지 않는 경우, 버킷의 CORS 정책에 app.wandb.ai가 허용 목록에 포함되어 있는지 확인하세요.
파일 시스템의 아티팩트 추적하기
데이터셋에 액세스하는 일반적인 패턴은 트레이닝 작업을 실행하는 모든 머신에서 원격 파일 시스템에 대한 NFS 마운트 포인트를 노출하는 것입니다. 트레이닝 스크립트 입장에서는 파일이 로컬 파일 시스템에 있는 것처럼 보이기 때문에 클라우드 스토리지 버킷의 대안이 될 수 있습니다.
파일 시스템의 아티팩트를 추적하려면 다음 단계를 따르세요.
wandb.init()으로 run을 초기화합니다.wandb.Artifact()로 아티팩트 오브젝트를 생성합니다.- 아티팩트 오브젝트의
wandb.Artifact.add_reference() 메소드를 사용하여 파일 시스템 경로에 대한 레퍼런스를 지정합니다.
run.log_artifact()로 아티팩트의 메타데이터를 로그합니다.
마운트된 파일 시스템의 파일을 추적하려면 다음 코드 조각을 복사하여 붙여넣으세요. 꺾쇠괄호(< >)로 묶인 값들을 사용자의 값으로 교체하세요.
import wandb
# run 초기화
with wandb.init(entity="<entity>", project="<project>") as run:
# 아티팩트 오브젝트 생성
artifact = wandb.Artifact(name="<name>", type="<type>")
# 파일 시스템 경로에 대한 레퍼런스 추가
artifact.add_reference("file:///path/to/dataset/")
# 아티팩트 로그 (메타데이터만)
run.log_artifact(artifact)
file:// 접두사입니다. 두 번째 부분은 파일 시스템의 루트 /입니다. 나머지 부분은 추적하고자 하는 디렉토리 또는 파일의 경로입니다.
예를 들어, 다음과 같은 구조의 /mount에 마운트된 파일 시스템이 있다고 가정해 보겠습니다.
mount
|datasets/
|-- mnist/
|models/
|-- cnn/
datasets/mnist/ 디렉토리를 dataset 아티팩트로 추적하고 싶다면 다음 코드 조각을 사용할 수 있습니다.
import wandb
with wandb.init() as run:
artifact = wandb.Artifact("mnist", type="dataset")
artifact.add_reference("file:///mount/datasets/mnist/")
run.log_artifact(artifact)
/mount/datasets/mnist/ 아래에 저장된 파일을 가리키는 mnist:latest reference artifact가 생성됩니다.
기본적으로 W&B는 디렉토리에 레퍼런스를 추가할 때 10,000개의 파일 제한을 둡니다. wandb.Artifact.add_reference()를 호출할 때 max_objects=를 지정하여 이 제한을 조정할 수 있습니다.
models/cnn/my_model.h5에 저장된 모델을 추적하려면 다음 코드 조각을 사용할 수 있습니다.
import wandb
with wandb.init() as run:
# 여기서 트레이닝 진행...
# 디스크에 모델 쓰기
# 아티팩트 오브젝트 생성
model_artifact = wandb.Artifact("cnn", type="model")
# 모델 파일 경로에 대한 레퍼런스 추가
model_artifact.add_reference("file:///mount/cnn/my_model.h5")
# W&B에 아티팩트 로그
run.log_artifact(model_artifact)
외부 파일 시스템에서 아티팩트 다운로드하기
일반 아티팩트와 동일한 API를 사용하여 레퍼런스된 파일 시스템에서 파일을 다운로드합니다.
wandb.init()으로 run을 초기화합니다.wandb.Run.use_artifact() 메소드를 사용하여 다운로드하려는 아티팩트를 지정합니다.- 아티팩트의
wandb.Artifact.download() 메소드를 호출하여 레퍼런스된 파일 시스템에서 파일을 다운로드합니다.
with wandb.init() as run:
artifact = run.use_artifact("entity/project/mnist:latest", type="dataset")
artifact_dir = artifact.download()
/mount/datasets/mnist의 콘텐츠를 artifacts/mnist:v0/ 디렉토리로 복사합니다.
Artifact.download()는 아티팩트를 재구성할 수 없는 경우 에러를 발생시킵니다. 예를 들어, 아티팩트에 덮어써진 파일에 대한 레퍼런스가 포함되어 있는 경우, 아티팩트를 더 이상 재구성할 수 없으면 Artifact.download()는 에러를 발생시킵니다.
