> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# W&B Models 시작하기

> 몇 줄의 코드만으로 실험을 추적하고, 메트릭을 로깅하고, 결과를 시각화하며 W&B Models를 시작해 보세요.

머신러닝 워크플로에서 W\&B를 언제, 어떻게 사용해 모델 아티팩트를 추적, 공유, 관리하는지 알아보세요. 이 페이지에서는 실험 로깅과 리포트 생성, 그리고 작업별로 적합한 W\&B API를 사용해 로깅된 데이터에 액세스하는 방법을 다룹니다.

이 튜토리얼에서는 다음을 사용합니다.

* [W\&B Python SDK](/ko/products/wandb/ref/python) (`wandb.sdk`): 트레이닝 중에 실험을 로깅하고 모니터링합니다.
* [W\&B Public API](/ko/products/wandb/ref/python/public-api) (`wandb.apis.public`): 로깅된 실험 데이터를 쿼리하고 분석합니다.
* [W\&B Reports and Workspaces API](/ko/products/wandb/ref/wandb_workspaces) (`wandb.wandb-workspaces`): 발견 사항을 요약한 리포트를 생성합니다.

<h2 id="sign-up-and-create-an-api-key">
  가입 및 API 키 생성
</h2>

W\&B에서 머신을 인증하려면 먼저 [forge.coreweave.com/settings](https://forge.coreweave.com/settings)에서 API 키를 생성해야 합니다. 생성한 API 키는 복사하여 안전한 곳에 보관하세요.

<h2 id="install-and-import-packages">
  패키지 설치 및 임포트
</h2>

W\&B 라이브러리와 이 워크스루에 필요한 기타 패키지를 설치하세요.

```python theme={"system"}
pip install wandb
```

W\&B Python SDK를 임포트하세요.

```python theme={"system"}
import wandb
```

다음 코드 블록에 팀의 entity를 지정하세요.

```python theme={"system"}
TEAM_ENTITY = "team_entity" # 사용할 팀 entity로 바꾸세요
PROJECT = "my-awesome-project"
```

<h2 id="train-a-model">
  모델 트레이닝하기
</h2>

다음 코드는 모델 트레이닝, 메트릭 로깅, 모델의 아티팩트 저장으로 이루어진 기본 머신러닝 워크플로를 시뮬레이션합니다.

트레이닝 중에 W\&B와 상호작용하려면 W\&B Python SDK(`wandb.sdk`)를 사용하세요. [`wandb.Run.log()`](/ko/products/wandb/ref/python/experiments/run#method-runlog)로 손실을 로깅한 다음, [`wandb.Artifact`](/ko/products/wandb/ref/python/experiments/artifact)로 트레이닝된 모델을 아티팩트로 저장하고, 마지막으로 [`Artifact.add_file`](/ko/products/wandb/ref/python/experiments/artifact#add_file)로 모델 파일을 추가합니다.

```python theme={"system"}
import random # 데이터 시뮬레이션용

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# 가중치와 노이즈 시뮬레이션
weights = random.random() # 가중치를 무작위로 초기화
noise = random.random() / 5  # 노이즈 시뮬레이션용 작은 무작위 노이즈

# 하이퍼파라미터 및 설정
config = {
    "epochs": 10,  # 트레이닝 에포크 수
    "learning_rate": 0.01,  # 옵티마이저 학습률
}

# 컨텍스트 관리자로 W&B run을 초기화하고 종료
with wandb.init(entity=TEAM_ENTITY, project=PROJECT, config=config) as run:    
    # 트레이닝 루프 시뮬레이션
    for epoch in range(config["epochs"]):
        xb = weights + noise  # 시뮬레이션한 입력 트레이닝 데이터
        yb = weights + noise * 2  # 시뮬레이션한 목표 출력(입력 노이즈의 두 배)
        
        y_pred = model(xb)  # 모델 예측
        loss = (yb - y_pred) ** 2  # 평균 제곱 오차(MSE) 손실

        print(f"epoch={epoch}, loss={loss}")
        # 에포크와 손실을 W&B에 로깅
        run.log({
            "epoch": epoch,
            "loss": loss,
        })

    # 모델 아티팩트의 고유 이름
    model_artifact_name = f"model-demo"  

    # 시뮬레이션한 모델 파일을 저장할 로컬 경로
    PATH = "model.txt" 

    # 모델을 로컬에 저장
    with open(PATH, "w") as f:
        f.write(str(weights)) # 모델 가중치를 파일에 저장

    # 아티팩트 객체 생성
    # 로컬에 저장한 모델을 아티팩트 객체에 추가
    artifact = wandb.Artifact(name=model_artifact_name, type="model", description="My trained model")
    artifact.add_file(local_path=PATH)
    artifact.save()
```

이전 코드 블록의 핵심 내용은 다음과 같습니다.

* 트레이닝 중에 메트릭을 로깅하려면 `wandb.Run.log()`를 사용하세요.
* 모델(데이터셋 등)을 W\&B 프로젝트에 아티팩트로 저장하려면 `wandb.Artifact`를 사용하세요.

모델을 트레이닝하고 아티팩트로 저장했으니 이제 W\&B의 레지스트리에 게시할 수 있습니다. [`wandb.Run.use_artifact()`](/ko/products/wandb/ref/python/experiments/run#method-runuse_artifact)를 사용하여 프로젝트에서 아티팩트를 가져오고 모델 레지스트리에 게시할 준비를 하세요. `wandb.Run.use_artifact()`의 주요 역할은 다음 두 가지입니다.

* 프로젝트에서 아티팩트 객체를 가져옵니다.
* 아티팩트를 run의 입력으로 표시하여 재현성과 추적성을 보장합니다. 자세한 내용은 [Lineage 맵 생성 및 보기](/ko/products/registry/lineage)를 참조하세요.

<h2 id="view-the-training-data-in-the-dashboard">
  대시보드에서 트레이닝 데이터 보기
</h2>

W\&B 대시보드로 이동하세요. **Projects** 탭을 선택하고 `my-awesome-project`(또는 위에서 프로젝트 이름으로 지정한 값)를 검색하세요. 검색된 프로젝트를 클릭하면 해당 프로젝트의 워크스페이스로 이동합니다.

여기에서 지금까지 실행한 모든 run의 세부 정보를 확인할 수 있습니다. 이 스크린샷에서는 코드를 여러 번 다시 실행해 여러 개의 run이 생성되었으며, 각 run에는 무작위로 생성된 이름이 부여되어 있습니다.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/quickstart_image.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=bd51b523b4bce2c7009d3877740b7a96" alt="run 이름, 메트릭, 상태 정보와 함께 여러 run이 table 뷰로 표시된 W&B 프로젝트 페이지" width="1152" height="653" data-path="products/wandb/_media/quickstart_image.png" />
</Frame>

<h2 id="publish-the-model-to-the-registry">
  모델을 레지스트리에 게시하기
</h2>

조직 내 다른 구성원과 모델을 공유하려면 `wandb.Run.link_artifact()`를 사용하여 모델을 [컬렉션](/ko/products/registry/create_collection)에 게시하세요. 다음 코드는 아티팩트를 [레지스트리](/ko/products/registry)에 연결하여 팀원들이 액세스할 수 있게 합니다.

```python theme={"system"}
# 아티팩트 이름으로 팀 프로젝트 내의 특정 아티팩트 버전을 지정합니다
artifact_name = f'{TEAM_ENTITY}/{PROJECT}/{model_artifact_name}:v0'
print("Artifact name: ", artifact_name)

REGISTRY_NAME = "DemoRegistry" # 레지스트리 이름
COLLECTION_NAME = "DemoModels"  # 레지스트리 내 컬렉션 이름

# 레지스트리 내 아티팩트의 대상 경로를 생성합니다
target_path = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
print("Target path: ", target_path)

with wandb.init(entity=TEAM_ENTITY, project=PROJECT) as run:
    model_artifact = run.use_artifact(artifact_or_name=artifact_name, type="model")
    run.link_artifact(artifact=model_artifact, target_path=target_path)
```

`wandb.Run.link_artifact()`를 실행하면 모델 아티팩트가 레지스트리의 `DemoModels` 컬렉션에 추가됩니다. 여기에서 버전 이력, [Lineage 맵](/ko/products/registry/lineage), 기타 [메타데이터](/ko/products/registry/registry_cards) 등의 세부 정보를 확인할 수 있습니다.

아티팩트를 레지스트리에 연결하는 방법에 대한 자세한 내용은 [레지스트리에 아티팩트 연결하기](/ko/products/registry/link_version)를 참조하세요.

<h2 id="retrieve-model-artifact-from-registry-for-inference">
  추론을 위해 레지스트리에서 모델 아티팩트 가져오기
</h2>

모델을 추론에 사용하려면 `wandb.Run.use_artifact()`로 레지스트리에 게시된 아티팩트를 가져오세요. 이 메서드는 아티팩트 객체를 반환하며, 이 객체에서 [`wandb.Artifact.download()`](/ko/products/wandb/ref/python/experiments/artifact#method-artifactdownload)를 호출하면 아티팩트를 로컬 파일로 다운로드할 수 있습니다.

```python theme={"system"}
REGISTRY_NAME = "DemoRegistry"  # 레지스트리 이름
COLLECTION_NAME = "DemoModels"  # 레지스트리 내 컬렉션 이름
VERSION = 0 # 가져올 아티팩트 버전

model_artifact_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{VERSION}"
print(f"Model artifact name: {model_artifact_name}")

with wandb.init(entity=TEAM_ENTITY, project=PROJECT) as run:
    registry_model = run.use_artifact(artifact_or_name=model_artifact_name)
    local_model_path = registry_model.download()
```

레지스트리에서 아티팩트를 가져오는 방법에 대한 자세한 내용은 [레지스트리에서 아티팩트 다운로드하기](/ko/products/registry/download_use_artifact)를 참조하세요.

사용하는 머신러닝 프레임워크에 따라 가중치를 로드하기 전에 모델 아키텍처를 다시 구성해야 할 수 있습니다. 구체적인 방법은 사용하는 프레임워크와 모델에 따라 다르므로 여기서는 다루지 않습니다.

<h2 id="share-your-findings-with-a-report">
  리포트로 발견 사항 공유하기
</h2>

<Note>
  W\&B Report and Workspace API는 공개 프리뷰 단계입니다.
</Note>

[리포트](/ko/products/wandb/reports)를 만들고 공유하여 작업 내용을 요약하세요. 리포트를 프로그래밍 방식으로 만들려면 [W\&B Report and Workspace API](/ko/products/wandb/ref/wandb_workspaces/reports)를 사용하세요.

먼저 W\&B Reports API를 설치하세요.

```bash theme={"system"}
pip install wandb wandb-workspaces -qqq
```

다음 코드 블록은 Markdown, 패널 그리드 등 여러 블록으로 구성된 리포트를 생성합니다. 블록을 더 추가하거나 기존 블록의 내용을 변경하여 리포트를 사용자 지정할 수 있습니다.

코드 블록을 실행하면 생성된 리포트의 URL 링크가 출력됩니다. 브라우저에서 이 링크를 열어 리포트를 확인하세요.

```python theme={"system"}
import wandb_workspaces.reports.v2 as wr

experiment_summary = """This is a summary of the experiment conducted to train a simple model using W&B."""
dataset_info = """The dataset used for training consists of synthetic data generated by a simple model."""
model_info = """The model is a simple linear regression model that predicts output based on input data with some noise."""

report = wr.Report(
    entity=TEAM_ENTITY,
    project=PROJECT,
    title="My Awesome Model Training Report",
    description=experiment_summary,
    blocks= [
        wr.TableOfContents(),
        wr.H2("Experiment Summary"),
        wr.MarkdownBlock(text=experiment_summary),
        wr.H2("Dataset Information"),
        wr.MarkdownBlock(text=dataset_info),
        wr.H2("Model Information"),
        wr.MarkdownBlock(text = model_info),
        wr.PanelGrid(
            panels=[
                wr.LinePlot(title="Train Loss", x="Step", y=["loss"], title_x="Step", title_y="Loss")
                ],
            ),  
    ]

)

# W&B에 리포트 저장
report.save()
```

프로그래밍 방식으로 리포트를 만드는 방법이나 W\&B App에서 대화형으로 리포트를 만드는 방법에 대한 자세한 내용은 W\&B Docs 개발자 가이드의 [리포트 만들기](/ko/products/wandb/reports/create-a-report)를 참조하세요.

<h2 id="query-the-registry">
  레지스트리 쿼리하기
</h2>

[W\&B Public APIs](/ko/products/wandb/ref/python/public-api)를 사용하면 W\&B의 과거 데이터를 쿼리, 분석, 관리할 수 있습니다. 이를 활용하면 아티팩트의 리니지를 추적하거나, 여러 버전을 비교하거나, 시간에 따른 모델 성능을 분석하는 데 유용합니다.

다음 코드 블록은 모델 레지스트리에서 특정 컬렉션에 속한 모든 아티팩트를 쿼리하는 방법을 보여줍니다. 이 코드는 컬렉션을 가져온 뒤 해당 버전을 순회하면서 각 아티팩트의 이름과 버전을 출력합니다.

```python theme={"system"}
import wandb

# wandb API 초기화
api = wandb.Api()

# 문자열 `model`을 포함하면서 
# `text-classification` 태그 또는 `latest` 별칭이 지정된 모든 아티팩트 버전 찾기
registry_filters = {
    "name": {"$regex": "model"}
}

# 논리 연산자 $or로 아티팩트 버전 필터링
version_filters = {
    "$or": [
        {"tag": "text-classification"},
        {"alias": "latest"}
    ]
}

# 필터 조건에 맞는 모든 아티팩트 버전을 iterable로 반환
artifacts = api.registries(filter=registry_filters).collections().versions(filter=version_filters)

# 찾은 각 아티팩트의 이름, 컬렉션, 별칭, 태그, created_at 날짜 출력
for art in artifacts:
    print(f"artifact name: {art.name}")
    print(f"collection artifact belongs to: { art.collection.name}")
    print(f"artifact aliases: {art.aliases}")
    print(f"tags attached to artifact: {art.tags}")
    print(f"artifact created at: {art.created_at}\n")
```

레지스트리를 쿼리하는 방법에 대한 자세한 내용은 [레지스트리 항목 쿼리](/ko/products/registry/search_registry#query-registry-items-with-mongodb-style-queries)를 참조하세요.


## Related topics

- [Weights & Biases 시작하기](/ko/products/wandb/get-started.md)