Skip to main content
W&B Python SDK를 사용하면 W&B run에서 아티팩트를 생성할 수 있습니다. 아티팩트에는 파일, 디렉터리, URI, 병렬 run의 파일을 추가할 수 있습니다. 아티팩트에 파일을 추가한 후에는 W&B 서버 또는 자체 비공개 서버에 아티팩트를 저장하세요. 각 아티팩트는 하나의 run과 연결됩니다. Amazon S3에 저장된 파일 등 외부 파일을 추적하는 방법은 외부 파일 추적 페이지를 참조하세요.

아티팩트 구성하기

다음 세 단계에 따라 W&B 아티팩트를 구성하세요.
  1. wandb.Artifact()로 아티팩트 Python 객체 생성하기
  2. 아티팩트에 파일 하나 이상 추가하기
  3. W&B 서버에 아티팩트 저장하기

wandb.Artifact()로 아티팩트 Python 객체 생성하기

wandb.Artifact() 클래스를 초기화하여 아티팩트 객체를 생성하세요. 다음 매개변수를 지정하세요.
  • Name: 아티팩트의 이름입니다. 이름은 고유하고, 내용을 잘 나타내며, 기억하기 쉬워야 합니다.
  • Type: 아티팩트의 유형입니다. 유형은 단순하고 내용을 잘 나타내야 하며, 머신러닝 파이프라인의 한 단계에 대응해야 합니다. 일반적인 아티팩트 유형으로는 'dataset', 'model' 등이 있습니다.
W&B는 사용자가 지정한 “name”과 “type”을 사용하여 W&B App에 방향성 비순환 그래프(DAG)를 생성합니다. 자세한 내용은 아티팩트 그래프 탐색 및 순회를 참조하세요.
다음 코드 스니펫을 복사하여 붙여 넣고 아티팩트 객체를 생성하세요. "artifact-name" 및 "artifact-type" 자리 표시자는 실제 값으로 바꾸세요.
아티팩트는 유형이 다르더라도 같은 이름을 사용할 수 없습니다. 예를 들어, 유형이 dataset인 cats 아티팩트를 만든 후에는 유형이 model인 cats 아티팩트를 또 만들 수 없습니다.
아티팩트 객체를 초기화할 때 설명, 메타데이터, 다이제스트 알고리즘 등의 매개변수를 선택적으로 지정할 수 있습니다. 예를 들어, 다음 코드 스니펫은 이름, 유형, 설명, 메타데이터, 다이제스트 알고리즘을 지정하여 아티팩트 객체를 생성합니다.
기본 다이제스트 알고리즘은 여전히 MD5입니다. W&B Python SDK 0.29.0 이상에서는 digest_algorithm="XXH128"을 설정하면 새 아티팩트에 더 빠른 해싱을 적용할 수 있습니다. MD5를 사용하는 기존 아티팩트 컬렉션은 계속 MD5를 사용합니다. 0.29.0 이전 버전의 SDK에서는 Artifact.verify()로 XXH128 항목이 포함된 아티팩트를 검증할 수 없습니다.
사용 가능한 속성과 매개변수에 대한 자세한 내용은 Python SDK 레퍼런스 가이드의 wandb.Artifact 클래스 정의를 참조하세요.

아티팩트에 하나 이상의 파일 추가하기

아티팩트 객체에 파일, 디렉터리, 외부 URI 참조(예: Amazon S3) 등을 추가할 수 있습니다. 단일 파일을 추가하려면 아티팩트 객체의 Artifact.add_file() 메서드를 사용하세요.
디렉터리를 추가하려면 Artifact.add_dir() 메서드를 사용하세요.
아티팩트에 다양한 유형의 파일을 추가하는 방법에 대한 자세한 내용은 다음 섹션인 아티팩트에 파일 추가하기를 참조하세요.

아티팩트를 W&B 서버에 저장하기

아티팩트를 W&B 서버에 저장하세요. 아티팩트를 저장하려면 run 객체의 wandb.Run.log_artifact() 메서드를 사용하세요.
wandb.Run.log_artifact()와 Artifact.save() 중 무엇을 사용해야 하나요?
  • 새 아티팩트를 생성하고 특정 run과 연결하려면 wandb.Run.log_artifact()를 사용하세요.
  • 새 run을 생성하지 않고 기존 아티팩트를 업데이트하려면 Artifact.save()를 사용하세요.
다음 코드 스니펫은 지금까지 설명한 내용을 종합하여 데이터셋 아티팩트를 생성하고, 아티팩트에 파일을 추가한 뒤, 아티팩트를 W&B에 저장하는 방법을 보여 줍니다.
이름과 유형이 같은 아티팩트를 로깅할 때마다 W&B는 해당 아티팩트의 새 버전을 생성합니다. 자세한 내용은 새 아티팩트 버전 생성을 참조하세요.
W&B는 업로드 성능을 높이기 위해 wandb.Run.log_artifact() 호출을 비동기적으로 수행합니다. 따라서 루프에서 아티팩트를 로깅하면 예상치 못한 동작이 발생할 수 있습니다. 예를 들면 다음과 같습니다.
아티팩트가 로깅되는 순서는 보장되지 않으므로, 아티팩트 버전 v0의 메타데이터에 있는 index 값이 0이 아닐 수도 있습니다.

아티팩트에 파일 추가

다음 섹션에서는 다양한 유형의 객체를 아티팩트에 추가하는 방법을 설명합니다. 예시에서는 다음과 같은 구조의 디렉터리가 있다고 가정합니다.

단일 파일 추가

wandb.Artifact.add_file()을 사용하면 로컬 파일 하나를 아티팩트에 추가할 수 있습니다. 파일의 로컬 경로를 local_path 매개변수에 지정하세요.
예를 들어, 로컬 작업 디렉터리에 'hello.txt'라는 파일이 있다고 가정해 보겠습니다.
이제 아티팩트에는 다음 내용이 포함됩니다.
필요한 경우 name 매개변수에 다른 이름을 전달하면 아티팩트 객체 안에서 파일 이름을 변경할 수 있습니다. 앞의 예시를 이어서 보면 다음과 같습니다.
아티팩트는 다음과 같이 저장됩니다.
다음 표는 API 호출에 따라 아티팩트 콘텐츠가 어떻게 달라지는지 보여줍니다.

여러 파일 추가

wandb.Artifact.add_dir() 메서드를 사용하면 로컬 디렉터리에 있는 여러 파일을 아티팩트에 추가할 수 있습니다. local_path 매개변수에 디렉터리의 로컬 경로를 지정하세요.
다음 표는 API 호출에 따라 아티팩트 내용이 어떻게 달라지는지 보여줍니다.

URI 참조 추가

URI의 스킴을 W&B 라이브러리가 지원하면 아티팩트는 재현성을 위해 체크섬 및 기타 정보를 추적합니다. wandb.Artifact.add_reference() 메서드를 사용하여 아티팩트에 외부 URI 참조를 추가하세요. 'uri' 문자열은 사용할 URI로 바꾸세요. 필요하면 name 매개변수에 아티팩트 내에서 사용할 경로를 전달할 수도 있습니다.
아티팩트는 다음 URI 스킴을 지원합니다.
  • http(s)://: HTTP로 액세스할 수 있는 파일의 경로입니다. HTTP 서버가 ETag 및 Content-Length 응답 헤더를 지원하면 아티팩트는 etag 형식의 체크섬과 크기 메타데이터를 추적합니다.
  • s3://: S3에 있는 객체 또는 객체 접두사의 경로입니다. 아티팩트는 참조된 객체의 체크섬과 버전 관리 정보(버킷에 객체 버전 관리가 활성화된 경우)를 추적합니다. 객체 접두사를 지정하면 해당 접두사 아래의 객체가 최대 10,000개까지 포함됩니다.
  • gs://: GCS에 있는 객체 또는 객체 접두사의 경로입니다. 아티팩트는 참조된 객체의 체크섬과 버전 관리 정보(버킷에 객체 버전 관리가 활성화된 경우)를 추적합니다. 객체 접두사를 지정하면 해당 접두사 아래의 객체가 최대 10,000개까지 포함됩니다.
다음 표는 API 호출에 따라 아티팩트 내용이 어떻게 달라지는지 보여줍니다.

병렬 run에서 아티팩트에 파일 추가하기

대규모 데이터셋이나 분산 트레이닝에서는 여러 병렬 run이 하나의 아티팩트에 함께 기여해야 할 수 있습니다.

로깅된 아티팩트 및 기타 메타데이터의 경로 찾기

다음 코드 스니펫은 W&B Public API를 사용하여 run에 포함된 파일 목록을 이름 및 URL과 함께 조회하는 방법을 보여줍니다. <entity/project/run-id> 플레이스홀더를 실제 값으로 바꾸세요.
사용 가능한 속성과 메서드에 대한 자세한 내용은 File 클래스를 참조하세요.
마지막 수정일 2026년 9월 30일