W&B Python SDK를 사용하여 W&B Runs으로부터 Artifacts를 생성할 수 있습니다. 파일, 디렉토리, URI 및 병렬 run의 파일을 Artifacts에 추가할 수 있습니다. Artifacts에 파일을 추가한 후에는 해당 Artifacts를 W&B 서버 또는 사용자 지정 프라이빗 서버에 저장하세요. 각 Artifacts는 run과 연결됩니다.
Amazon S3에 저장된 파일과 같은 외부 파일을 트래킹하는 방법은 외부 파일 트래킹 페이지를 참조하세요.
Artifacts 생성 방법
W&B Artifacts를 생성하는 과정은 세 단계로 이루어집니다:
1. wandb.Artifact()로 Artifacts 파이썬 오브젝트 만들기
wandb.Artifact() 클래스를 초기화하여 Artifacts 오브젝트를 생성합니다. 다음 파라미터를 지정하세요:
- Name: Artifacts의 이름을 지정합니다. 이름은 고유하고 설명적이며 기억하기 쉬워야 합니다. Artifacts 이름은 W&B 앱 UI에서 Artifacts를 식별할 때와 해당 Artifacts를 사용하려 할 때 모두 사용됩니다.
- Type: 유형(Type)을 입력합니다. 유형은 단순하고 설명적이어야 하며 기계학습 파이프라인의 단일 단계에 대응해야 합니다. 일반적인 Artifacts 유형으로는
'dataset' 또는 'model'이 있습니다.
W&B는 사용자가 제공한 “이름(name)“과 “유형(type)“을 사용하여 유향 비순환 그래프(DAG)를 생성합니다. W&B 앱에서 Artifacts의 계보를 확인할 수 있습니다. 자세한 내용은 Artifacts 그래프 탐색 및 트래버스 가이드를 참조하세요. Artifacts는 유형(types) 파라미터가 다르더라도 동일한 이름을 가질 수 없습니다. 즉, 유형이 dataset인 cats라는 이름의 Artifacts를 생성하고, 유형이 model인 동일한 이름의 Artifacts를 또 생성할 수 없습니다.
wandb.Artifact 클래스 정의를 참조하세요.
다음 코드 조각을 복사하여 붙여넣어 Artifacts 오브젝트를 생성하세요. <name>과 <type> 플레이스홀더를 실제 값으로 바꾸어 사용하세요:
import wandb
# Artifacts 오브젝트 생성
artifact = wandb.Artifact(name="<name>", type="<type>")
2. Artifacts에 하나 이상의 파일 추가하기
파일, 디렉토리, 외부 URI 참조(예: Amazon S3) 등을 Artifacts 오브젝트에 추가합니다.
단일 파일을 추가하려면 Artifacts 오브젝트의 Artifact.add_file() 메소드를 사용하세요:
artifact.add_file(local_path="path/to/file.txt", name="<name>")
Artifact.add_dir() 메소드를 사용하세요:
artifact.add_dir(local_path="path/to/directory", name="<name>")
3. Artifacts를 W&B 서버에 저장하기
마지막으로, Artifacts를 W&B 서버에 저장합니다. Artifacts를 저장하려면 run 오브젝트의 wandb.Run.log_artifact() 메소드를 사용하세요.
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
import wandb
artifact = wandb.Artifact(name="<name>", type="<type>")
artifact.add_file(local_path="path/to/file.txt", name="<name>")
artifact.add_dir(local_path="path/to/directory", name="<name>")
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
Artifact.save() 또는 wandb.Run.log_artifact()를 사용하는 경우
- 새로운 run을 생성하지 않고 기존 Artifacts를 업데이트하려면
Artifact.save()를 사용하세요.
- 새로운 Artifacts를 생성하고 특정 run과 연결하려면
wandb.Run.log_artifact()를 사용하세요.
log_artifact 호출은 성능 효율적인 업로드를 위해 비동기식으로 수행됩니다. 이로 인해 루프 내에서 Artifacts를 로깅할 때 예상치 못한 행동이 발생할 수 있습니다. 예를 들어:for i in range(10):
a = wandb.Artifact(
"race",
type="dataset",
metadata={
"index": i,
},
)
# ... artifact a에 파일 추가 ...
run.log_artifact(a)
Artifacts에 파일 추가하기
다음 섹션에서는 다양한 파일 유형 및 병렬 run으로부터 Artifacts를 구성하는 방법을 설명합니다.
다음 예제에서는 여러 파일과 디렉토리 구조를 가진 프로젝트 디렉토리가 있다고 가정합니다:
project-directory
|-- images
| |-- cat.png
| +-- dog.png
|-- checkpoints
| +-- model.h5
+-- model.h5
단일 파일 추가
다음 코드 조각은 단일 로컬 파일을 Artifacts에 추가하는 방법을 보여줍니다:
# 단일 파일 추가
artifact.add_file(local_path="path/file.format")
'file.txt'라는 파일이 있다고 가정해 보겠습니다.
artifact.add_file("path/file.txt") # `file.txt'로 추가됨
name 파라미터를 통해 Artifacts 내에서의 원하는 경로를 전달할 수 있습니다.
artifact.add_file(local_path="path/file.format", name="new/path/file.format")
| API 호출 | 결과 Artifacts |
|---|
artifact.add_file('model.h5') | model.h5 |
artifact.add_file('checkpoints/model.h5') | model.h5 |
artifact.add_file('model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
여러 파일 추가
다음 코드 조각은 로컬 디렉토리 전체를 Artifacts에 추가하는 방법을 보여줍니다:
# 디렉토리를 재귀적으로 추가
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| API 호출 | 결과 Artifacts |
|---|
artifact.add_dir('images') | cat.png
dog.png
|
artifact.add_dir('images', name='images') | images/cat.png
images/dog.png
|
artifact.new_file('hello.txt') | hello.txt |
URI 참조 추가
URI가 W&B 라이브러리가 처리할 수 있는 스키마를 가지고 있다면, Artifacts는 재현성을 위해 체크섬 및 기타 정보를 추적합니다.
add_reference 메소드를 사용하여 Artifacts에 외부 URI 참조를 추가합니다. 'uri' 문자열을 실제 URI로 바꾸세요. 선택적으로 name 파라미터로 Artifacts 내에서의 원하는 경로를 전달할 수 있습니다.
# URI 참조 추가
artifact.add_reference(uri="uri", name="optional-name")
http(s)://: HTTP를 통해 엑세스 가능한 파일 경로입니다. HTTP 서버가 ETag 및 Content-Length 응답 헤더를 지원하는 경우, Artifacts는 etag 형식의 체크섬과 크기 메타데이터를 추적합니다.s3://: S3의 오브젝트 또는 오브젝트 프리픽스 경로입니다. Artifacts는 참조된 오브젝트에 대한 체크섬과 버전 관리 정보(버킷에 오브젝트 버전 관리가 활성화된 경우)를 추적합니다. 오브젝트 프리픽스는 프리픽스 아래의 오브젝트를 포함하도록 확장되며, 최대 10,000개의 오브젝트까지 가능합니다.gs://: GCS의 오브젝트 또는 오브젝트 프리픽스 경로입니다. Artifacts는 참조된 오브젝트에 대한 체크섬과 버전 관리 정보(버킷에 오브젝트 버전 관리가 활성화된 경우)를 추적합니다. 오브젝트 프리픽스는 프리픽스 아래의 오브젝트를 포함하도록 확장되며, 최대 10,000개의 오브젝트까지 가능합니다.
이어지는 API 호출은 다음과 같은 Artifacts를 생성합니다:
| API 호출 | 결과 Artifacts 내용 |
|---|
artifact.add_reference('s3://my-bucket/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/checkpoints/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
artifact.add_reference('s3://my-bucket/images') | cat.png
dog.png
|
artifact.add_reference('s3://my-bucket/images', name='images') | images/cat.png
images/dog.png
|
병렬 run에서 Artifacts에 파일 추가하기
대규모 데이터셋이나 분산 트레이닝의 경우, 여러 병렬 run이 단일 Artifacts에 기여해야 할 수 있습니다.
import wandb
import time
# 데모 목적으로 run을 병렬로 실행하기 위해 ray를 사용합니다.
# 사용자는 원하는 방식으로 병렬 run을 오케스트레이션할 수 있습니다.
import ray
ray.init()
artifact_type = "dataset"
artifact_name = "parallel-artifact"
table_name = "distributed_table"
parts_path = "parts"
num_parallel = 5
# 병렬 작성자(writer)의 각 배치는 고유한 그룹 이름을 가져야 합니다.
group_name = "writer-group-{}".format(round(time.time()))
@ray.remote
def train(i):
"""
작성자(writer) 작업. 각 작성자는 Artifacts에 하나의 이미지를 추가합니다.
"""
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(name=artifact_name, type=artifact_type)
# wandb table에 데이터 추가. 이 예시에서는 예제 데이터를 사용합니다.
table = wandb.Table(columns=["a", "b", "c"], data=[[i, i * 2, 2**i]])
# Artifacts 내의 폴더에 table 추가
artifact.add(table, "{}/table_{}".format(parts_path, i))
# Artifacts를 upsert하면 데이터를 생성하거나 Artifacts에 추가합니다.
run.upsert_artifact(artifact)
# run을 병렬로 실행
result_ids = [train.remote(i) for i in range(num_parallel)]
# 모든 작성자가 완료될 때까지 대기하여 Artifacts를 마무리하기 전에
# 파일이 모두 추가되었는지 확인합니다.
ray.get(result_ids)
# 모든 작성자가 끝나면 Artifacts를 마무리하여 준비 상태로 표시합니다.
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(artifact_name, type=artifact_type)
# 테이블 폴더를 가리키는 "PartitionTable"을 생성하고 Artifacts에 추가합니다.
artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)
# finish_artifact는 Artifacts를 확정하며, 이후 이 버전에 대한 "upserts"를 허용하지 않습니다.
run.finish_artifact(artifact)
로깅된 Artifacts 및 기타 메타데이터 경로 찾기
다음 코드 조각은 W&B Public API를 사용하여 이름과 URL을 포함한 run의 파일 목록을 표시하는 방법을 보여줍니다. <entity/project/run-id> 플레이스홀더를 실제 값으로 바꾸세요:
from wandb.apis.public.files import Files
from wandb.apis.public.api import Api
# 예시 run 오브젝트
run = Api().run("<entity/project/run-id>")
# run의 파일을 반복하기 위해 Files 오브젝트 생성
files = Files(api.client, run)
# 파일 반복 작업
for file in files:
print(f"File Name: {file.name}")
print(f"File URL: {file.url}")
print(f"Path to file in the bucket: {file.direct_url}")
