W&B Python SDK를 사용해 W&B Runs에서 artifact를 생성할 수 있습니다. 파일, 디렉터리, URI, 병렬 run의 파일을 artifact에 추가할 수 있습니다. artifact에 파일을 추가한 후에는 해당 artifact를 W&B Server 또는 직접 관리하는 프라이빗 서버에 저장하세요. 각 artifact는 하나의 run과 연결됩니다.
Amazon S3에 저장된 파일과 같은 외부 파일을 추적하는 방법에 대한 자세한 내용은 외부 파일 추적 페이지를 참조하세요.
W&B Artifact를 다음 세 단계로 생성합니다:
wandb.Artifact()로 artifact Python 객체 생성- artifact에 하나 이상의 파일 추가
- artifact를 W&B 서버에 저장
1. wandb.Artifact()로 artifact Python 객체 생성하기
wandb.Artifact() 클래스를 초기화하세요. 다음 매개변수를 지정합니다.
- Name: artifact의 이름입니다. 이름은 고유하고, 설명적이며, 기억하기 쉬워야 합니다.
- Type: artifact의 유형입니다. 유형은 단순하고 설명적이어야 하며, 머신 러닝 파이프라인의 단일 step에 해당해야 합니다. 일반적인 artifact 유형으로는
'dataset' 또는 'model'이 있습니다.
Artifacts는 유형과 관계없이 같은 이름을 가질 수 없습니다. 즉, dataset 유형의 cats라는 artifact와 같은 이름의 model 유형 artifact를 따로 만들 수는 없습니다.
wandb.Artifact 클래스 정의를 참조하세요.
다음 코드 스니펫을 복사해 artifact 객체를 만드세요. <name> 및 <type> 플레이스홀더를 원하는 값으로 바꾸세요:
import wandb
# artifact 객체 생성
artifact = wandb.Artifact(name="<name>", type="<type>")
2. artifact에 파일을 하나 더 추가합니다
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. artifact를 W&B 서버에 저장하기
wandb.Run.log_artifact() 방법을 사용하세요.
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
wandb.Run.log_artifact()와 Artifact.save()의 사용 시점
wandb.Run.log_artifact()는 새 artifact를 생성하고 이를 특정 run에 연결할 때 사용합니다.Artifact.save()는 새 run을 생성하지 않고 기존 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)
W&B는 업로드 성능을 높이기 위해 wandb.Run.log_artifact() 호출을 비동기적으로 수행합니다. 이로 인해 루프에서 artifact를 로깅할 때 예상치 못한 동작이 발생할 수 있습니다. 예를 들면 다음과 같습니다.with wandb.init() as run:
for i in range(10):
a = wandb.Artifact(name = "race",
type="dataset",
metadata={
"index": i,
},
)
# ... artifact a에 파일 추가 ...
run.log_artifact(a)
root-directory
| - hello.txt
| - images/
| -- | cat.png
| -- | dog.png
| - checkpoints/
| -- | model.h5
| - models/
| -- | model.h5
wandb.Artifact.add_file()을 사용합니다. 파일의 로컬 경로를 local_path 매개변수로 지정합니다:
import wandb
# artifact 객체 초기화
artifact = wandb.Artifact(name="<name>", type="<type>")
# 단일 파일 추가
artifact.add_file(local_path="path/file.format")
'hello.txt'라는 파일이 있다고 가정해 보겠습니다.
artifact.add_file("hello.txt")
name Parameter에 다른 이름을 전달해 artifact 객체 자체에서 파일 이름을 바꿀 수 있습니다. 이전 예제를 이어서 보면 다음과 같습니다:
artifact.add_file(
local_path="hello.txt",
name="new/path/hello_world.txt"
)
| API 호출 | 생성되는 artifact |
|---|
artifact.new_file('hello.txt') | hello.txt |
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 |
wandb.Artifact.add_dir() 메서드를 사용하세요. local_path 매개변수로 디렉터리의 로컬 경로를 지정하세요.
import wandb
# artifact 객체 초기화
artifact = wandb.Artifact(name="<name>", type="<type>")
# artifact에 로컬 디렉토리 추가
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| API Call | Resulting artifact |
|---|
artifact.add_dir('images') | cat.png
dog.png
|
artifact.add_dir('images', name='images') | images/cat.png
images/dog.png
|
wandb.Artifact.add_reference() 방법으로 artifact에 외부 URI reference를 추가합니다. 'uri' 문자열을 사용자의 URI로 바꾸세요. 필요에 따라 name Parameter에 artifact 내에서 사용할 원하는 경로를 전달할 수도 있습니다.
# URI 레퍼런스 추가
artifact.add_reference(uri="uri", name="optional-name")
http(s)://: HTTP를 통해 액세스할 수 있는 파일 경로입니다. HTTP 서버가 ETag 및 Content-Length 응답 헤더를 지원하는 경우, artifact는 ETag 형식의 체크섬과 크기 메타데이터를 추적합니다.s3://: S3의 객체 또는 객체 접두사 경로입니다. artifact는 참조된 객체의 체크섬과 버전 관리 정보(버킷에서 객체 버전 관리가 활성화된 경우)를 추적합니다. 객체 접두사는 해당 접두사 아래의 객체를 포함하도록 확장되며, 최대 10,000개 객체까지 포함됩니다.gs://: GCS의 객체 또는 객체 접두사 경로입니다. artifact는 참조된 객체의 체크섬과 버전 관리 정보(버킷에서 객체 버전 관리가 활성화된 경우)를 추적합니다. 객체 접두사는 해당 접두사 아래의 객체를 포함하도록 확장되며, 최대 10,000개 객체까지 포함됩니다.
다음 표는 서로 다른 API 호출에 따라 생성되는 artifact 콘텐츠가 어떻게 달라지는지 보여줍니다:
| API 호출 | 생성되는 artifact 콘텐츠 |
|---|
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
|
import wandb
import time
# 이 예제는 데모 목적으로 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 작업입니다. 각 writer는 artifact에 이미지 하나를 추가합니다.
"""
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]])
# artifact 내 폴더에 table을 추가합니다.
artifact.add(table, "{}/table_{}".format(parts_path, i))
# artifact를 upsert하면 artifact에 데이터를 생성하거나 추가합니다.
run.upsert_artifact(artifact)
# run을 병렬로 실행합니다.
result_ids = [train.remote(i) for i in range(num_parallel)]
# artifact를 완료하기 전에 모든 writer의 파일이
# 추가되었는지 확인하기 위해 join합니다.
ray.get(result_ids)
# 모든 writer가 완료되면 artifact를 완료하여
# 준비 상태로 표시합니다.
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(artifact_name, type=artifact_type)
# table 폴더를 가리키는 "PartitionTable"을 생성하고
# artifact에 추가합니다.
artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)
# finish_artifact는 artifact를 확정하여 이 버전에 대한
# 이후 "upsert"를 허용하지 않습니다.
run.finish_artifact(artifact)
<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}")
print(f"파일 URL: {file.url}")
print(f"bucket 내 파일 경로: {file.direct_url}")
