W&B에서 Ultralytics Platform으로 Ultralytics YOLO 모델을 마이그레이션하는 방법

컴퓨터 비전 프로젝트에서 모델 학습은 워크플로의 한 부분일 뿐입니다. 실험 수가 늘어나면 모델 버전을 관리하고, 학습 지표를 추적하고, 결과를 비교하고, 학습된 모델을 실제 애플리케이션에 적용해야 합니다.

Weights & Biases (W&B)는 머신러닝에서 널리 사용되는 실험 추적 도구입니다. Ultralytics YOLO를 사용하는 경우 이미 W&B를 사용해 손실, mAP, 정밀도, 재현율 등의 학습 지표를 기록하고, 모델 가중치를 관리하고, 실험 성능을 시각화하고 있을 수 있습니다.

프로젝트가 실험 단계에서 배포 단계로 진행되면 한곳에서 모델을 관리하고, 성능을 평가하고, 내보내고, 배포하고자 할 수 있습니다.

Ultralytics Platform은 조건을 충족하는 Ultralytics YOLO 모델 체크포인트와 학습 기록을 W&B에서 직접 가져올 수 있습니다. 재학습할 필요가 없습니다. 모델을 가져오면 추론을 테스트하고, 모델을 내보내고, 배포할 수 있습니다.

이 가이드에서는 모델과 학습 기록을 준비하고, W&B 통합 기능을 통해 모델을 가져오고, 체크포인트를 수동으로 업로드하고, Ultralytics Platform에서 이후 학습 실행을 추적하는 방법을 설명합니다.

마이그레이션 전: 기존 모델과 학습 데이터 검토#

W&B에서 학습 실험은 일반적으로 실행(run)에 해당하며, 여러 실행을 하나의 프로젝트로 구성할 수 있습니다. 모델 가중치와 기타 학습 출력은 아티팩트로 저장하고 버전 관리할 수 있습니다.

Ultralytics YOLO 모델을 마이그레이션하기 전에 다음 항목을 확인하세요:

• 모델 가중치: 학습에서 성능이 가장 뛰어난 체크포인트를 저장하는 best.pt 등의 파일입니다.
• 학습 설정: 학습률, 에포크 수, 이미지 크기 등의 매개변수입니다.
• 학습 지표: 손실, mAP, 정밀도, 재현율 등의 지표입니다.
• 학습 기록: 실험 기록과 각 에포크에서 기록된 지표입니다.

Ultralytics Platform에서 가져올 수 있는 항목은 무엇인가요?#

공식 W&B 통합 기능을 통해 Ultralytics Platform은 조건을 충족하는 모델 아티팩트에 액세스하고 체크포인트에 저장된 정보를 읽을 수 있습니다.

마이그레이션되는 학습 기록의 범위는 원본 모델 파일과 W&B에 저장된 데이터에 따라 달라집니다. 체크포인트에 에포크별 학습 지표가 포함되어 있지 않으면 Ultralytics Platform은 W&B 실행 기록에서 학습 곡선을 가져오려고 시도합니다. 시작하기 전에 중요한 모델 파일과 실험 데이터를 백업하는 것이 좋습니다.

W&B 통합 기능을 통해 Ultralytics YOLO 모델 가져오기#

W&B 프로젝트에 Ultralytics YOLO 모델의 best.pt 체크포인트가 이미 있다면 Ultralytics Platform에 기본 제공되는 W&B 통합 기능을 사용할 수 있습니다. 브라우저에서 가져오기를 완료할 수 있으므로 각 모델을 직접 다운로드하고 다시 업로드할 필요가 없습니다.

1단계: Ultralytics Platform에 로그인#

Ultralytics Platform을 열어 로그인한 다음 모델을 가져올 워크스페이스로 전환합니다.

모델을 가져오려면 해당 워크스페이스에서 편집자 이상의 역할이 필요합니다. 가져온 모델은 워크스페이스의 스토리지 및 모델 한도에 포함됩니다. W&B 가져오기는 모든 요금제에서 사용할 수 있습니다.

2단계: W&B 통합 기능 열기#

Ultralytics Platform에서 Settings → Integrations → Weights & Biases로 이동합니다. 여기에서 기존 Ultralytics YOLO 모델을 W&B에서 가져올 수 있습니다.

3단계: W&B 계정 연결#

W&B 인증 페이지에서 API 키를 가져옵니다. Ultralytics Platform으로 돌아와 키를 붙여 넣고 Connect를 클릭합니다.

연결되면 Ultralytics Platform에 키로 액세스할 수 있는 W&B 프로젝트가 표시됩니다. 여기에는 본인의 프로젝트와 팀 프로젝트, 그리고 가져올 수 있는 모델이 포함됩니다. 마이그레이션하려는 프로젝트를 읽을 권한이 API 키에 있는지 확인하세요.

보안 참고: API 키는 민감한 자격 증명입니다. 공개 코드 저장소에 커밋하거나 다른 사람과 공유하지 마세요.

워크스페이스 소유자가 W&B API 키로 연결하면 Ultralytics Platform은 해당 키를 암호화하여 저장하고 이후 해당 워크스페이스에서 가져올 때 재사용하므로 키를 다시 입력할 필요가 없습니다. 저장된 키를 추가, 교체 또는 제거할 수 있는 사람은 소유자뿐입니다. 다른 워크스페이스 구성원이 입력한 키는 해당 가져오기에만 사용됩니다.

4단계: 가져올 프로젝트 선택#

연결하면 API 키로 액세스할 수 있고 모델 아티팩트가 포함된 W&B 프로젝트가 목록에 표시됩니다. 모델 세부 정보가 로드될 때까지 기다린 다음 마이그레이션할 프로젝트를 선택합니다.

Ultralytics Platform은 프로젝트 단위로 가져옵니다. 선택한 각 프로젝트에서 조건을 충족하는 모든 모델을 가져오려고 시도합니다. 다음 조건을 충족하는 모델을 가져올 수 있습니다:

1. 해당 W&B 실행에 best.pt 체크포인트가 포함된 모델 아티팩트가 있습니다.
2. 해당 작업 유형은 Ultralytics Platform에서 지원됩니다.
3. 해당 체크포인트의 크기는 모델 업로드 한도인 1 GB 이내입니다.

조건을 충족하는 모델이 없는 프로젝트는 선택할 수 없습니다.

5단계: 가져오기 시작#

프로젝트를 선택한 후 Import N을 클릭합니다. 여기서 N은 선택한 프로젝트 수입니다. Ultralytics Platform은 조건을 충족하는 모델을 가져오기 시작하고 백그라운드 업로드 추적기에서 진행 상황을 표시합니다.

업로드가 완료될 때까지 브라우저 탭을 열어 두세요. 업로드가 진행되는 동안 Ultralytics Platform 내에서 계속 이동할 수 있습니다.

6단계: 가져온 모델 검토#

가져오기가 완료되면 해당 프로젝트를 열고 모델을 선택해 세부 정보를 확인합니다. 각 W&B 프로젝트는 같은 이름의 Ultralytics Platform 프로젝트로 가져오며, 해당 프로젝트가 아직 없는 경우 새로 생성됩니다.

가져온 각 모델에서 아키텍처, 작업 유형, 클래스 이름, 학습 설정, 학습 지표 등 사용 가능한 정보를 확인할 수 있습니다. 원본 체크포인트에 에포크별 결과가 포함되어 있지 않은 경우 Ultralytics Platform은 W&B 실행 기록에서 결과를 가져오려고도 시도합니다.

이제 기존 Ultralytics YOLO 모델을 Ultralytics Platform에서 관리하고, 테스트하고, 사용할 수 있습니다.

대안: 기존 모델 가중치를 수동으로 업로드#

모델이 로컬에 저장되어 있다면 Ultralytics Platform에 직접 업로드할 수 있습니다.

Ultralytics YOLO 모델을 객체 감지용으로 학습한 후 출력 디렉터리는 일반적으로 다음과 같습니다:

runs/
└── detect/
    └── train/
        └── weights/
            ├── best.pt
            └── last.pt

best.pt 파일에는 학습에서 성능이 가장 뛰어난 체크포인트가 포함되어 있으며, 추론 및 배포에 가장 많이 사용됩니다.

Ultralytics Platform에서 대상 프로젝트를 엽니다. .pt 파일을 프로젝트 페이지나 모델 사이드바로 끌어다 놓거나 Upload models를 클릭하고 로컬 파일을 선택합니다. 업로드가 완료되면 Ultralytics Platform이 작업, 아키텍처, 클래스 이름 등의 지원되는 모델 메타데이터를 자동으로 읽습니다.

업로드 전에 모델이 올바르게 로드되는지 확인하려면 Ultralytics Python 패키지로 간단한 예측을 실행할 수 있습니다:

from ultralytics import YOLO

# 로컬 모델 로드
model = YOLO("best.pt")

# 추론 실행
results = model.predict(
    source="test.jpg",
    conf=0.25,
)

print(results)

예제 경로를 모델 가중치와 테스트 이미지의 경로로 바꾸세요.

수동 업로드로는 원본 체크포인트에 저장되지 않은 학습 기록을 복원할 수 없습니다.

기존 모델을 가져온 후에는 이후 Ultralytics YOLO 학습 실행을 Ultralytics Platform으로 바로 전송할 수도 있습니다.

Ultralytics Platform에서 새 학습 실행 추적#

다음 예제에서는 Ultralytics YOLO26을 사용하여 개인 컴퓨터에서 모델을 학습하는 동시에 학습 지표를 Ultralytics Platform으로 스트리밍하는 방법을 보여줍니다.

1단계: Ultralytics 설치 또는 업데이트#

pip install -U ultralytics

로컬 학습 지표를 Ultralytics Platform으로 스트리밍하려면 다음이 필요합니다:

• Python 3.11 이상
• ultralytics 8.4.120 이상

W&B로 실험을 추적해 왔으며 이후 실행 결과를 Ultralytics Platform에만 보고하려면 W&B 로깅을 끌 수 있습니다:

yolo settings wandb=False

이렇게 해도 W&B에 이미 저장된 실험 데이터는 삭제되지 않습니다.

2단계: Ultralytics Platform API 키 설정#

Ultralytics Platform에서 Settings → API Keys로 이동합니다. 워크스페이스 소유자는 학습용 키를 만들 수 있습니다. Add Key를 클릭하고 Ultralytics를 선택한 다음 이름을 입력하고 Create Key를 클릭합니다.

Linux 또는 macOS에서 환경 변수로 설정합니다:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOUR_API_KEY을 본인의 키로 바꾸고 공개 코드 저장소에는 포함하지 마세요.

3단계: YOLO26 학습#

이 예제에서는 COCO8 샘플 데이터셋으로 YOLO26n을 학습합니다:

yolo train \
  model=yolo26n.pt \
  data=coco8.yaml \
  epochs=5 \
  project=your-username/my-project \
  name=experiment-1

각 인수의 기능은 다음과 같습니다:

• model: 학습할 모델입니다.
• data: 데이터셋 설정입니다.
• epochs: 학습 에포크 수입니다.
• project: Ultralytics Platform의 대상 프로젝트이며, username/project 형식입니다.
• name: 이 실험의 이름입니다.

your-username/my-project을 워크스페이스 사용자 이름과 프로젝트 이름으로 바꾸세요.

Python API로도 동일한 작업을 수행할 수 있습니다:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

model.train(
    data="coco8.yaml",
    epochs=5,
    project="your-username/my-project",
    name="experiment-1",
)

학습이 시작되면 지원되는 지표가 Ultralytics Platform으로 실시간 스트리밍됩니다.

더 간단하게 설정하려면 Ultralytics Platform 학습 대화상자에서 Local Training 탭을 열고 생성된 명령을 복사하세요. 해당 명령에는 API 키가 이미 포함되어 있습니다.

4단계: 학습 결과 확인#

모델의 Train 탭을 열어 학습 중 기록된 다음 항목을 확인합니다:

• 학습 및 검증 손실
• 정밀도, 재현율, mAP 등의 모델 지표
• 시간 경과에 따른 학습률
• 사용 가능한 경우 검증 플롯
• 콘솔 로그
• GPU, CPU 및 메모리 사용량을 포함한 시스템 리소스

이 기록을 사용하여 학습을 분석하고 구성 및 모델 크기별 성능을 비교할 수 있습니다.

마이그레이션 후 수행할 수 있는 작업#

모델을 Ultralytics Platform으로 가져오면 모델을 테스트, 내보내기, 비교 및 배포할 수 있습니다.

브라우저에서 모델 테스트하기#

모델 페이지에서 Predict 탭을 열고 이미지를 업로드하면 모델의 예측 결과를 바로 확인할 수 있습니다.

다양한 형식으로 모델 내보내기#

Ultralytics Platform에서는 다양한 배포 형식으로 모델을 내보낼 수 있으며, 여기에는 ONNX, TensorRT, CoreML이 포함됩니다. 모델의 작업과 배포 대상 하드웨어에 따라 형식을 선택하세요.

프로젝트 내에서 실험 비교하기#

프로젝트 페이지에서 바로 실험을 비교할 수 있습니다. W&B 개념이 Ultralytics Platform에서 어떻게 대응되는지 확인해 보세요.

같은 W&B 프로젝트에서 가져온 모델은 동일한 Ultralytics Platform 프로젝트에 저장되므로, 가져오기가 완료되면 사용 가능한 학습 결과를 비교할 수 있습니다.

차트 비교#

왼쪽의 모델 목록에서 비교할 모델을 선택하세요. 오른쪽 패널에는 해당 모델의 곡선이 겹쳐 표시되고 Metrics, Loss, Learning Rate와 같은 카테고리별로 그룹화됩니다. 작업과 사용 가능한 데이터에 따라 mAP50-95, 정밀도, 재현율, 개별 학습 및 검증 손실이 표시됩니다. 곡선 위에 마우스를 올리면 정확한 값을 확인할 수 있고, 범례를 사용하여 모델을 표시하거나 숨길 수 있으며, 클릭한 채로 드래그하면 특정 영역을 확대할 수 있습니다.

테이블 비교#

Table 보기로 전환하여 선택한 모델의 학습 매개변수와 최종 지표를 나란히 비교하세요. Diff를 켜면 모델 간 값이 다른 열만 표시되므로, 결과에 영향을 미쳤을 수 있는 하이퍼파라미터를 더 쉽게 찾을 수 있습니다.

컴퓨터 비전 프로젝트를 계속 개발하세요#

Ultralytics Platform은 데이터셋 관리, 어노테이션, 클라우드 GPU 학습, 모델 관리 및 모델 배포도 지원하므로, 프로젝트가 성장함에 따라 더 많은 워크플로를 한곳에서 관리할 수 있습니다.

W&B 실험을 Ultralytics Platform으로 가져오기#

내장된 W&B 통합을 사용하면 지원 대상인 Ultralytics YOLO 체크포인트와 사용 가능한 학습 기록을 재학습 없이 Ultralytics Platform으로 가져올 수 있습니다. 로컬에 저장된 체크포인트는 수동으로 업로드할 수 있습니다.

그런 다음 한곳에서 새로운 학습 실행을 추적하고, 모델 성능을 비교하고, 추론을 실행하고, 모델을 내보내고 배포할 수 있습니다.

Ultralytics Platform 사용해 보기

관련 문서#

• Ultralytics Platform W&B 통합 가이드
• Ultralytics Platform 빠른 시작 가이드
• Ultralytics Platform 학습 가이드
• Ultralytics YOLO W&B 통합 가이드