미디어 및 객체 로깅

Weights & Biases Python SDK로 미디어를 로깅하여 모델 입력과 출력을 검사하고 run, 모델, 데이터셋 간에 결과를 비교하세요. 지원되는 유형에는 이미지, 오디오, 비디오, 히스토그램, 3D 포인트 클라우드, 분자, HTML이 있습니다. API에 대한 자세한 내용은 데이터 유형 레퍼런스를 참조하세요. 예시는 모델 예측 보고서에서 확인하거나 비디오 워크스루를 시청하세요.

사전 요구 사항

일부 미디어 유형에는 추가 의존성이 필요합니다. 미디어 의존성을 포함하여 Weights & Biases SDK를 설치하려면 다음 명령을 실행하세요:

pip install wandb[media]

이미지

wandb.Image를 사용하여 NumPy 배열, PIL 이미지 또는 로컬 파일의 이미지를 로깅하세요. 이미지를 로깅하면 입력, 출력, 필터 가중치, 활성화 값을 살펴볼 수 있습니다.

학습 성능과 이미지 로딩 시간에 미치는 영향을 줄이려면 step당 50개 미만의 이미지를 로깅할 것을 CoreWeave는 권장합니다.

다음 탭에서는 다양한 입력 유형으로 이미지를 로깅하는 방법을 보여 줍니다.

배열
PIL 이미지
이미지 파일

torchvision의 make_grid를 사용할 때처럼 이미지를 직접 구성하는 경우에는 배열을 바로 전달하세요.

Weights & Biases는 Pillow를 사용하여 배열을 PNG 이미지로 변환합니다.

import wandb
import numpy as np

with wandb.init(project="image-log-example") as run:
    images = wandb.Image(image_array, caption="Top: Output, Bottom: Input")
    run.log({"examples": images})

NumPy 배열은 (height, width, channels) 형태로 사용하세요. Weights & Biases는 채널 수가 1, 3, 4이면 각각 그레이스케일, RGB, RGBA로 추론합니다. 이미지는 기본적으로 PNG 파일로 저장됩니다.값이 0–255 범위를 벗어나거나 모든 값이 0–1 범위 안에 있으면 픽셀 값이 0–255 범위로 정규화됩니다. 정규화를 끄려면 normalize=False를 전달하세요. 배열 변환을 더 세밀하게 제어하려면 PIL 이미지 탭에 나온 것처럼 PIL 이미지를 생성하세요.

PIL.Image를 생성하여 wandb.Image에 전달하세요.

from PIL import Image

image_array = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)

with wandb.init(project="pil-image-example") as run:
    # NumPy 배열로 PIL 이미지 생성
    image = Image.fromarray(image_array)

    # 필요한 경우 RGB로 변환 (선택 사항)
    if image.mode != "RGB":
        image = image.convert("RGB")

    # 이미지 로깅
    run.log({"example": wandb.Image(image, caption="My Image")})

기존 이미지 파일을 로깅하려면 파일 경로를 wandb.Image에 전달하세요.

with wandb.init(project="media-log-example") as run:
    run.log({"example": wandb.Image("myimage.jpg")})

학습 단계별로 이미지를 비교하려면 Weights & Biases 앱 UI에서 이미지 패널을 펼친 다음 step 슬라이더를 사용하세요. 이미지를 선택하면 전체 화면 뷰로 열리며, 여기서 마우스나 키보드 단축키로 확대/축소하고 이동할 수 있습니다. 여러 run, step 또는 인덱스의 이미지나 비디오를 하나의 뷰에서 비교하려면 비교 모드를 사용하세요.

이미지 오버레이

시맨틱 세그멘테이션 마스크를 로깅하면 Weights & Biases 앱 UI에서 마스크의 불투명도를 조절하고 step별 변화를 확인할 수 있습니다.

세그멘테이션 마스크
경계 상자

세그멘테이션 마스크나 경계 상자가 포함된 이미지를 로깅하면 Weights & Biases 앱 UI에서 모델 예측과 정답 데이터를 확인할 수 있습니다.

wandb.Image의 masks 인수에 딕셔너리를 전달하세요. 각 키는 predictions 또는 ground_truth처럼 마스크의 이름을 지정합니다. 각 값은 다음 필드로 구성된 딕셔너리입니다.

필드	설명
`mask_data`	각 픽셀의 정수 클래스 레이블을 담은 2D NumPy 배열입니다. `mask_data`와 `path` 중 하나를 제공하세요.
`path`	저장된 마스크 이미지의 경로입니다. `path`와 `mask_data` 중 하나를 제공하세요.
`class_labels`	정수 클래스 레이블을 읽기 쉬운 이름에 매핑하는 딕셔너리입니다(선택 사항).

이미지 하나에 여러 마스크를 로깅하려면 마스크마다 별도의 딕셔너리를 제공하세요.

mask_data = np.array([[1, 2, 2, ..., 2, 2, 1], ...])

class_labels = {1: "tree", 2: "car", 3: "road"}

mask_img = wandb.Image(
    image,
    masks={
        "predictions": {"mask_data": mask_data, "class_labels": class_labels},
        "ground_truth": {
            # ...
        },
        # ...
    },
)

각 키의 세그멘테이션 마스크는 step마다(즉, wandb.Run.log()를 호출할 때마다) 정의됩니다.

여러 step에서 동일한 마스크 키에 서로 다른 값을 제공하면 해당 키의 가장 최근 값만 이미지에 적용됩니다.
여러 step에서 서로 다른 마스크 키를 제공하면 표시 여부 컨트롤에는 모든 키가 나타나지만, 이미지에는 선택한 step에서 정의된 마스크만 적용됩니다. 해당 step에서 정의되지 않은 마스크는 켜거나 꺼도 이미지가 변경되지 않습니다.

전체 예제는 세그멘테이션 마스크 보고서와 예시 노트북을 참조하세요.

경계 상자가 포함된 이미지를 로깅한 다음, 필터와 표시 여부 컨트롤을 사용하여 Weights & Biases 앱 UI에서 상자 그룹을 살펴보세요.

wandb.Image의 boxes 인수에 딕셔너리를 전달하세요. 각 키는 predictions나 ground_truth와 같은 그룹 이름입니다. 각 값에는 다음 필드가 포함됩니다.

필드	설명
`box_data`	바운딩 박스마다 하나씩 포함된 딕셔너리 목록입니다.
`class_labels`	클래스 ID를 읽기 쉬운 이름에 매핑하는 딕셔너리로, 선택 사항입니다. 생략하면 Weights & Biases가 `class_0`, `class_1`과 같은 이름을 생성합니다.

box_data의 각 딕셔너리는 상자 하나를 정의합니다.

필드	설명
`position`	상자의 위치와 크기입니다. `minX`, `maxX`, `minY`, `maxY` 또는 `middle`, `width`, `height` 중 하나를 사용하세요. `middle`에는 `[x, y]` 좌표를 지정하세요. 상자마다 서로 다른 형식을 사용할 수 있습니다.
`class_id`	`class_labels`의 항목에 대응하는 정수 클래스 ID입니다.
`scores`	점수 이름을 숫자 값에 매핑하는 딕셔너리입니다. 이 점수로 Weights & Biases 앱 UI에서 상자를 필터링할 수 있습니다.
`domain`	좌표 단위입니다. 픽셀 좌표를 사용하려면 `"pixel"`로 설정하세요. 기본적으로 좌표는 이미지 크기에 대한 0~1 사이의 비율입니다.
`box_caption`	상자에 표시할 텍스트로, 선택 사항입니다.

이 예제는 상대 좌표를 사용하는 상자 하나와 픽셀 좌표를 사용하는 상자 하나를 로깅합니다.

import wandb

class_id_to_label = {
    1: "car",
    2: "road",
    3: "building"
}

img = wandb.Image(
    image,
    boxes={
        "predictions": {
            "box_data": [
                {
                    # 기본 도메인(상대 좌표/비율)으로 표현한 박스
                    "position": {"minX": 0.1, "maxX": 0.2, "minY": 0.3, "maxY": 0.4},
                    "class_id": 2,
                    "box_caption": class_id_to_label[2],
                    "scores": {"acc": 0.1, "loss": 1.2},
                    # 픽셀 도메인으로 표현한 또 다른 박스
                    # (설명을 위한 예시일 뿐이며, 실제로는 대개 모든 박스가
                    # 같은 도메인/형식을 사용합니다)
                    "position": {"middle": [150, 20], "width": 68, "height": 112},
                    "domain": "pixel",
                    "class_id": 3,
                    "box_caption": "a building",
                    "scores": {"acc": 0.5, "loss": 0.7},
                    # ...
                    # 필요한 만큼 박스를 로깅하세요
                }
            ],
            "class_labels": class_id_to_label,
        },
        # 의미 있는 박스 그룹마다 고유한 키 이름을 지정해 로깅하세요
        "ground_truth": {
            # ...
        },
    },
)

with wandb.init(project="my_project") as run:
    run.log({"driving_scene": img})

대화형 예시는 경계 상자 보고서를 참조하세요.

Tables의 이미지 오버레이

Weights & Biases Table에 이미지 오버레이를 표시하려면 마스크 또는 경계 상자가 포함된 wandb.Image 객체를 각 행에 추가하세요.

세그멘테이션 마스크
바운딩 박스

이 예제는 table의 각 행마다 세그멘테이션 마스크가 포함된 이미지를 하나씩 로깅합니다.

table = wandb.Table(columns=["ID", "Image"])

for id, img, label in zip(ids, images, labels):
    mask_img = wandb.Image(
        img,
        masks={
            "prediction": {
                "mask_data": label,
                "class_labels": class_labels
                }
            # ...
        },
    )

    table.add_data(id, mask_img)

with wandb.init(project="my_project") as run:
    run.log({"Table": table})

이 예제는 table의 각 행마다 경계 상자가 포함된 이미지를 하나씩 로깅합니다.

table = wandb.Table(columns=["ID", "Image"])

for id, img, boxes in zip(ids, images, boxes_set):
    box_img = wandb.Image(
        img,
        boxes={
            "prediction": {
                "box_data": [
                    {
                        "position": {
                            "minX": box["minX"],
                            "minY": box["minY"],
                            "maxX": box["maxX"],
                            "maxY": box["maxY"],
                        },
                        "class_id": box["class_id"],
                        "box_caption": box["caption"],
                        "domain": "pixel",
                    }
                    for box in boxes
                ],
                "class_labels": class_labels,
            }
        },
    )

히스토그램

wandb.Histogram을 사용하여 모델 기울기와 같은 숫자 분포를 로깅하세요. Weights & Biases 앱 UI에서 x축은 학습 단계, y축은 메트릭 값을 나타내고, 색상은 각 구간에 속한 개수를 나타냅니다.

기본 히스토그램 로깅
유연한 히스토그램 로깅

목록, 배열, 텐서 등의 숫자 시퀀스를 wandb.Histogram에 전달하세요. Weights & Biases는 배열과 텐서를 평탄화한 다음 numpy.histogram()을 사용하여 히스토그램을 계산합니다.히스토그램은 기본적으로 64개의 구간을 사용합니다. 구간 수를 사용자 지정하려면 num_bins를 최대 512까지의 값으로 설정하세요.

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(grads)})

히스토그램 계산 방식을 직접 제어하려면 np.histogram()을 호출한 뒤 반환된 튜플을 np_histogram에 전달하세요.

import numpy as np

np_hist_grads = np.histogram(grads, density=True, range=(0.0, 1.0))

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(np_hist_grads)})

필요한 경우 density=True를 설정하면 구간 값을 개수 대신 확률 밀도로 나타낼 수 있습니다.

3D 시각화

wandb.Object3D를 사용하여 3D 포인트 클라우드와 경계 상자가 포함된 lidar 장면을 로깅하세요. 점 좌표와 선택적으로 색상 또는 범주 레이블이 포함된 NumPy 배열을 제공하세요. 포인트 클라우드는 Weights & Biases 앱 UI에서 대화형으로 조작할 수 있습니다. 드래그하여 뷰를 회전하거나, 확대/축소하여 세부 사항을 살펴보거나, Control 키를 누른 채 마우스로 장면 안을 이동할 수 있습니다. 다음 보고서는 3D 경계 상자가 포함된 Lyft 데이터셋의 장면을 보여줍니다.

Weights & Biases 앱 UI는 포인트 클라우드당 최대 300,000개의 데이터 포인트를 표시합니다.

NumPy 배열 형식

다음 배열 형식 중 하나를 사용하세요. 여기서 n은 포인트 수입니다.

형태	포인트 형식	설명
`(n, 3)`	`[x, y, z]`	포인트 좌표입니다.
`(n, 4)`	`[x, y, z, category]`	좌표와 1~14 범위의 범주(예: 세그멘테이션 클래스)입니다.
`(n, 6)`	`[x, y, z, r, g, b]`	좌표와 0~255 범위의 빨강, 초록, 파랑 값입니다.

Python 객체

wandb.Object3D.from_point_cloud()를 사용하여 데이터 포인트, 경계 상자, 벡터로 구성된 장면을 만드세요.

import wandb
import numpy as np

points = np.array([
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255],
])

boxes = [{
    "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1],
    ],
    "color": [0, 0, 255],
    "label": "example region",
    "score": 0.6,
}]

scene = wandb.Object3D.from_point_cloud(
    points=points,
    boxes=boxes,
    vectors=[{"start": [0, 0, 0], "end": [0.1, 0.2, 0.5], "color": [255, 0, 0]}],
    point_cloud_type="lidar/beta",
)

with wandb.init() as run:
    run.log({"my_first_point_cloud": scene})

Weights & Biases 앱 UI에서 포인트 클라우드 내부를 이동하려면 Control 키를 누른 상태에서 마우스를 움직이세요.

포인트 클라우드 파일

JSON 파일에서 포인트 클라우드 데이터를 불러오려면 wandb.Object3D.from_file()을 사용하세요.

run.log({"my_cloud_from_file": wandb.Object3D.from_file(
     "./my_point_cloud.pts.json"
)})

다음 JSON은 포인트 클라우드 데이터의 형식을 보여줍니다.

{
  "points": [
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255]
  ],
  "boxes": [
    {
      "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]
      ],
      "color": [0, 0, 255],
      "label": "example region",
      "score": 0.6
    }
  ],
  "type": "lidar/beta"
}

NumPy 배열

지원되는 배열 형식의 데이터는 모두 wandb.Object3D.from_numpy()로 사용할 수 있습니다:

# 좌표만 포함
xyz_points = np.array([[0.4, 1, 1.3], [1, 1, 1], [1.2, 1, 1.2]])

# 좌표와 범주 레이블 포함
category_points = np.array([[0.4, 1, 1.3, 1], [1, 1, 1, 1], [1.2, 1, 1.2, 12]])

# 좌표와 RGB 색상 포함
rgb_points = np.array([
    [0.4, 1, 1.3, 255, 0, 0],
    [1, 1, 1, 0, 255, 0],
    [1.2, 1, 1.2, 0, 0, 255],
])

with wandb.init() as run:
    run.log({
        "xyz_point_cloud": wandb.Object3D.from_numpy(xyz_points),
        "category_point_cloud": wandb.Object3D.from_numpy(category_points),
        "rgb_point_cloud": wandb.Object3D.from_numpy(rgb_points),
    })

분자

wandb.Molecule을 사용하여 분자 데이터를 로깅하고 Weights & Biases 앱 UI에서 3D 구조를 확인하세요.

run.log({"protein": wandb.Molecule("6lu7.pdb")})

지원되는 파일 유형은 pdb, pqr, mmcif, mcif, cif, sdf, sd, gro, mol2, mmtf입니다. SMILES 문자열, RDKit mol 파일, rdkit.Chem.rdchem.Mol 객체도 로깅할 수 있습니다. 이 예시를 실행하려면 RDKit이 필요합니다.

from rdkit import Chem

resveratrol = rdkit.Chem.MolFromSmiles("Oc1ccc(cc1)C=Cc1cc(O)cc(c1)O")

with wandb.init() as run:
    run.log(
        {
            "resveratrol": wandb.Molecule.from_rdkit(resveratrol),
            "green fluorescent protein": wandb.Molecule.from_rdkit("2b3p.mol"),
            "acetaminophen": wandb.Molecule.from_smiles("CC(=O)Nc1ccc(O)cc1"),
        }
    )

대화형 예시는 AlphaFold 워크스페이스를 참조하세요.

분자의 2D 뷰

wandb.Image 데이터 유형과 rdkit을 사용하여 분자의 2D 뷰를 로깅할 수 있습니다:

from rdkit import Chem
from rdkit.Chem import AllChem, Draw

molecule = Chem.MolFromSmiles("CC(=O)O")
AllChem.Compute2DCoords(molecule)
pil_image = Draw.MolToImage(molecule, size=(300, 300))

with wandb.init() as run:
    run.log({"acetic_acid": wandb.Image(pil_image)})

기타 미디어

Weights & Biases는 다양한 기타 미디어 유형의 로깅도 지원합니다.

오디오

오디오 데이터를 로깅하려면 wandb.Audio를 사용하세요. sample_rate에는 녹음된 오디오의 샘플링 레이트를 헤르츠(Hz) 단위로 지정하세요.

with wandb.init() as run:
    run.log({"whale songs": wandb.Audio(np_array, caption="OooOoo", sample_rate=32)})

step당 최대 100개의 오디오 클립을 로깅할 수 있습니다. 자세한 내용은 audio-file을 참조하세요.

비디오

비디오 파일을 로깅하려면 wandb.Video를 사용하세요:

with wandb.init() as run:
    run.log({"video": wandb.Video("myvideo.mp4")})

비디오 프레임으로 구성된 NumPy 배열을 로깅하려면 다음과 같이 출력 형식과 프레임 속도를 지정하세요.

with wandb.init() as run:
    run.log({"video": wandb.Video(video_array, fps=4, format="gif")})

단일 비디오에는 (frames, channels, height, width) 형태를, 배치에는 (batch, frames, channels, height, width) 형태를 사용하세요. NumPy 배열을 인코딩하려면 FFmpeg와 MoviePy가 필요합니다. 지원되는 형식은 "gif", "mp4", "webm", "ogg"입니다. 배열이나 메모리 내 스트림을 전달할 때는 format을 지정하세요. 원시 프레임을 인코딩할 때 기본 프레임 속도는 초당 4프레임입니다. 파일 경로를 제공하면 Weights & Biases는 파일이 존재하는지, 지원되는 형식인지 확인합니다. BytesIO 객체를 제공하면 Weights & Biases는 지정된 형식을 확장자로 사용하는 임시 파일을 생성합니다. 비디오를 보고 재생하려면 프로젝트 Workspace, run 워크스페이스 또는 보고서에서 미디어 패널을 여세요. 비교 모드를 사용하면 여러 run 또는 step의 비디오를 비교할 수 있습니다.

텍스트

wandb.Table을 사용하면 예측, 레이블 또는 기타 값과 함께 텍스트를 표시할 수 있습니다. table을 생성할 때 열 이름을 지정하세요. 기본적으로 열 머리글은 ["Input", "Output", "Expected"]입니다. 최적의 UI 성능을 보장하기 위해 기본 최대 행 수는 10,000으로 설정되어 있습니다. 하지만 wandb.Table.MAX_ROWS = {DESIRED_MAX}를 사용하여 최댓값을 명시적으로 재정의할 수 있습니다.

columns = ["Text", "Predicted Sentiment", "True Sentiment"]
data = [["I love my phone", "1", "1"], ["My phone is terrible", "0", "-1"]]

with wandb.init(project="my_project") as run:
    table = wandb.Table(data=data, columns=columns)
    run.log({"examples": table})

또는 wandb.Table.add_data()를 사용하여 행을 추가할 수도 있습니다.

table = wandb.Table(columns=columns)
table.add_data("I love my phone", "positive", "positive")
table.add_data("My phone stopped working", "negative", "negative")
run.log({"text_examples": table})

pandas DataFrame으로 table을 만들려면 DataFrame을 dataframe에 전달하세요.

table = wandb.Table(dataframe=my_dataframe)
with wandb.init() as run:
    run.log({"examples": table})

자세한 사용 정보는 string을 참조하세요.

HTML

wandb.Html을 사용하면 run 페이지의 패널에 맞춤형 HTML을 표시할 수 있습니다. HTML 파일 또는 문자열을 전달하세요:

with wandb.init() as run:
    run.log({"custom_string": wandb.Html('<a href="https://mysite">Link</a>')})
    
    with open("some.html") as f:
        run.log({"custom_file": wandb.Html(f)})

기본적으로 Weights & Biases는 HTML에 스타일을 추가합니다. 이 동작을 비활성화하려면 inject=False를 전달하세요. 이 동작을 끄려면 다음과 같이 inject=False를 전달하세요.

with wandb.init() as run:
    with open("some.html") as html_file:
        run.log({"custom_file": wandb.Html(html_file, inject=False)})

자세한 사용 방법은 html-file를 참조하세요.

Weights & Biases

가이드

인테그레이션

레퍼런스

지원

미디어 및 객체 로깅

사전 요구 사항

이미지

이미지 오버레이

Tables의 이미지 오버레이

히스토그램

3D 시각화

NumPy 배열 형식

Python 객체

포인트 클라우드 파일

NumPy 배열

분자

분자의 2D 뷰

기타 미디어

오디오

비디오

텍스트

HTML

​사전 요구 사항

​이미지

​이미지 오버레이

​Tables의 이미지 오버레이

​히스토그램

​3D 시각화

​NumPy 배열 형식

​Python 객체

​포인트 클라우드 파일

​NumPy 배열

​분자

​분자의 2D 뷰

​기타 미디어

​오디오

​비디오

​텍스트

​HTML

사전 요구 사항

이미지

이미지 오버레이

Tables의 이미지 오버레이

히스토그램

3D 시각화

NumPy 배열 형식

Python 객체

포인트 클라우드 파일

NumPy 배열

분자

분자의 2D 뷰

기타 미디어

오디오

비디오

텍스트

HTML