Track external files - CoreWeave Docs

참조 아티팩트를 사용하면 W&B 서버 외부에 저장된 파일을 추적하고 사용할 수 있습니다. 대표적인 외부 저장소 솔루션으로는 CoreWeave AI Object Storage, Backblaze B2 Cloud Storage, Amazon Simple Storage Service(Amazon S3) 버킷, GCS 버킷, Azure 블롭, HTTP 파일 서버, NFS 공유 등이 있습니다. 참조 아티팩트는 비참조 아티팩트와 비슷하게 동작합니다. 가장 큰 차이점은 참조 아티팩트에는 파일 크기, MD5 체크섬 등 파일에 대한 메타데이터만 포함된다는 것입니다. 파일 자체는 사용자의 시스템 밖으로 나가지 않습니다. 참조 아티팩트는 비참조 아티팩트와 같은 방식으로 다룰 수 있습니다. W&B App에서 파일 브라우저로 참조 아티팩트의 내용을 탐색하고, 전체 의존성 그래프를 살펴보고, 아티팩트의 버전 이력을 확인할 수 있습니다. 단, 데이터 자체는 아티팩트에 포함되지 않으므로 UI에서 이미지, 오디오 같은 리치 미디어를 렌더링할 수 없습니다.

외부 파일을 추적하지 않는 아티팩트를 로깅하면 W&B는 아티팩트의 파일을 W&B 서버에 저장합니다. W&B Python SDK로 아티팩트를 로깅할 때는 이 방식이 기본 동작입니다.외부 파일을 추적하는 아티팩트를 로깅하면 W&B는 객체의 ETag, 크기 등 객체에 대한 메타데이터를 로깅합니다. 버킷에 객체 버전 관리가 활성화되어 있으면 버전 ID도 함께 로깅됩니다.

다음 섹션에서는 외부 참조 아티팩트를 추적하는 방법을 설명합니다.

외부 클라우드 스토리지 버킷의 아티팩트 추적하기

W&B Python SDK를 사용하여 W&B 외부에 저장된 파일의 레퍼런스를 추적하세요.

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/ 디렉터리를 데이터셋 아티팩트로 추적하려면 다음과 같이 지정하세요.

아티팩트의 이름을 지정합니다(예: "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를 생성합니다.

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 App에서는 파일 브라우저로 참조 아티팩트의 내용을 살펴보고, 전체 의존성 그래프를 탐색하고, 아티팩트의 버전 이력을 확인할 수 있습니다. 단, 데이터 자체는 아티팩트에 포함되어 있지 않으므로 W&B App에서 이미지, 오디오 등의 리치 미디어는 렌더링되지 않습니다.

W&B Artifacts는 CoreWeave Storage, Backblaze B2 Cloud Storage, MinIO를 비롯한 모든 Amazon S3 호환 인터페이스를 지원합니다. AWS_S3_ENDPOINT_URL 환경 변수가 S3 호환 서버를 가리키도록 설정하면(예: Backblaze B2의 경우 https://s3.us-west-001.backblazeb2.com) 아래 스크립트를 수정 없이 이러한 공급자에서 사용할 수 있습니다.

기본적으로 W&B는 객체 접두사를 추가할 때 객체 수를 10,000개로 제한합니다. 이 제한은 wandb.Artifact.add_reference()를 호출할 때 max_objects=를 지정하여 조정할 수 있습니다.

외부 클라우드 스토리지 버킷에서 아티팩트 다운로드하기

W&B는 참조 아티팩트를 다운로드할 때 아티팩트를 로깅할 때 기록된 메타데이터를 사용하여 기반 버킷에서 파일을 가져옵니다. 버킷에 객체 버전 관리가 활성화되어 있으면 W&B는 아티팩트를 로깅한 시점의 파일 상태에 해당하는 객체 버전을 가져옵니다. 아티팩트는 트레이닝 run 시점의 버킷 스냅샷 역할을 하므로, 버킷의 콘텐츠가 계속 바뀌더라도 특정 모델을 트레이닝하는 데 사용한 데이터의 정확한 버전을 언제든지 참조할 수 있습니다. 다음 코드 샘플은 참조 아티팩트를 다운로드하는 방법을 보여 줍니다. 아티팩트를 다운로드하는 API는 참조 아티팩트와 비참조 아티팩트 모두 동일합니다.

import wandb

with wandb.init(project="my-project") as run:
  artifact = run.use_artifact("mnist:latest", type="dataset")
  artifact_dir = artifact.download()

워크플로에서 파일을 덮어쓰는 경우, W&B는 저장소 버킷에서 ‘Object Versioning’을 활성화할 것을 권장합니다.버전 관리가 활성화되어 있으면 아티팩트를 로깅한 후에 파일을 덮어썼더라도, 아티팩트를 다운로드할 때 W&B가 항상 올바른 버전의 파일을 가져올 수 있습니다.사용 중인 환경에 맞는 객체 버전 관리 활성화 방법을 확인하세요: AWS, Google Cloud, Azure.

버킷에서 외부 파일 추가 및 다운로드

다음 코드 샘플은 데이터셋을 Amazon S3 버킷에 업로드하고 참조 아티팩트로 추적한 다음 다운로드합니다.

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 문서
Backblaze B2 Cloud Storage	Backblaze B2 Application Keys 문서
AWS	Boto3 문서
Google Cloud	Google Cloud 문서
Azure	Azure 문서

AWS의 경우 버킷이 설정된 사용자의 기본 리전에 있지 않다면 AWS_REGION 환경 변수를 버킷 리전으로 설정해야 합니다.

버킷의 CORS 설정에 따라 이미지, 오디오, 비디오, 포인트 클라우드 등의 리치 미디어가 App UI에서 렌더링되지 않을 수 있습니다. 버킷의 CORS 설정에서 app.wandb.ai를 허용 목록에 추가하면 W&B App에서 이러한 리치 미디어를 올바르게 렌더링할 수 있습니다.이미지, 오디오, 비디오, 포인트 클라우드 등의 리치 미디어가 App 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)

URL에 슬래시가 세 개 연속으로 있다는 점에 유의하세요. 첫 번째 부분은 파일 시스템 레퍼런스를 사용함을 나타내는 file:// 접두사입니다. 두 번째 부분은 파일 시스템의 루트 /입니다. 나머지 부분은 추적하려는 디렉터리 또는 파일의 경로입니다. 예를 들어, /mount에 마운트된 파일 시스템이 다음과 같은 구조로 되어 있다고 가정해 보겠습니다.

mount
|datasets/
  |-- mnist/
|models/
  |-- cnn/

datasets/mnist/ 디렉터리를 데이터셋 아티팩트로 추적하려는 경우를 예로 들어 보겠습니다. 다음 코드 스니펫을 사용하면 이 디렉터리를 추적할 수 있습니다.

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가 생성됩니다.

기본적으로 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()

W&B는 /mount/datasets/mnist의 내용을 artifacts/mnist:v0/ 디렉터리에 복사합니다.

Artifact.download()는 아티팩트를 재구성할 수 없으면 오류를 발생시킵니다. 예를 들어 아티팩트가 레퍼런스로 가리키는 파일을 덮어쓴 경우 아티팩트를 더 이상 재구성할 수 없으므로 Artifact.download()에서 오류가 발생합니다.

​외부 클라우드 스토리지 버킷의 아티팩트 추적하기

​외부 클라우드 스토리지 버킷에서 아티팩트 다운로드하기

​버킷에서 외부 파일 추가 및 다운로드

​클라우드 저장소 자격 증명

​파일 시스템에서 아티팩트 추적하기

​외부 파일 시스템에서 아티팩트 다운로드하기

외부 클라우드 스토리지 버킷의 아티팩트 추적하기

외부 클라우드 스토리지 버킷에서 아티팩트 다운로드하기

버킷에서 외부 파일 추가 및 다운로드

클라우드 저장소 자격 증명

파일 시스템에서 아티팩트 추적하기

외부 파일 시스템에서 아티팩트 다운로드하기