Neptune을 이용한 실험 추적

Neptune은 많은 실험을 수행하는 팀을 위해 구축된 MLOps용 메타데이터 저장소입니다. 모델 구축과 관련된 모든 메타데이터를 기록, 저장, 표시, 구성, 비교 및 쿼리할 수 있는 단일 공간을 제공합니다.

Ultralytics YOLO26은 Neptune과 통합되어 실험 추적을 간소화합니다. 이 통합을 통해 사용자 지정 로깅 코드를 작성하지 않고도 훈련 지표를 자동으로 기록하고, 모델 예측을 시각화하며, 모델 아티팩트를 저장할 수 있습니다.

주요 특징

• 자동 로깅: 박스 손실(box loss), 분류 손실(classification loss) 및 mAP와 같은 주요 훈련 지표를 자동으로 기록합니다.
• 이미지 시각화: 훈련 모자이크와 검증 예측 결과를 Neptune 대시보드에서 직접 확인하십시오.
• 모델 체크포인팅: 훈련 종료 시 훈련된 모델 가중치(best.pt)를 자동으로 업로드하고 버전 관리합니다.
• 하이퍼파라미터 추적: 실험의 완전한 재현성을 보장하기 위해 모든 구성 파라미터를 기록합니다.
• 대화형 플롯: 혼동 행렬(confusion matrices) 및 정밀도-재현율 곡선(precision-recall curves)을 시각화하여 모델 성능을 분석합니다.

설치

To use Neptune with Ultralytics, you will need to install the neptune client package along with ultralytics.

# Install the required packages
pip install ultralytics neptune

# Enable Neptune integration in Ultralytics settings
yolo settings neptune=True

구성(Configuration)

훈련을 시작하기 전에 로컬 환경을 Neptune 프로젝트에 연결해야 합니다. Neptune 대시보드에서 API Token과 Project Name이 필요합니다.

자격 증명 가져오기

1. Neptune.ai에 로그인하십시오.
2. 새 프로젝트를 생성하거나 기존 프로젝트를 선택하십시오.
3. 사용자 메뉴로 이동하여 API Token을 가져오십시오.

환경 변수 설정

The securest way to handle credentials is via environment variables. Note that the Ultralytics Neptune callback reads the YOLO project argument and does not use NEPTUNE_PROJECT. Pass the full Neptune slug (e.g., workspace/name) via project= in your training command; otherwise Neptune will try to use the literal default "Ultralytics" and the run will fail.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

사용법

구성이 완료되면 YOLO26 모델 훈련을 시작할 수 있습니다. Neptune 통합은 neptune 패키지가 설치되어 있고 설정에서 통합이 활성화되어 있으면 자동으로 작동합니다.

학습 예제

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")

# Train the model
# Pass the Neptune project slug as the 'project' argument (workspace/name)
results = model.train(data="coco8.yaml", epochs=10, project="my-workspace/my-project", name="experiment-1")

통합 방식 이해하기

다음 다이어그램은 Ultralytics 훈련 파이프라인이 Neptune과 상호 작용하여 다양한 아티팩트와 지표를 기록하는 방법을 보여줍니다.

graph LR
    A[YOLO Training Loop] --> B{Neptune Callback}
    B -->|Log Scalars| C[Loss, mAP, LR]
    B -->|Log Images| D[Mosaics, Preds]
    B -->|Log Artifacts| E[Model Weights]
    B -->|Log Metadata| F[Hyperparameters]

    C --> G[Neptune Server]
    D --> G
    E --> G
    F --> G

    G --> H[Neptune Web Dashboard]

무엇이 기록되나요?

훈련 명령을 실행하면 Neptune 통합이 실행 과정에서 다음 데이터 구조를 자동으로 캡처합니다:

1. Configuration/Hyperparameters: 모든 훈련 인수(epochs, lr0, optimizer 등)가 Configuration 섹션 아래에 기록됩니다.
2. Configuration/Model: 모델 아키텍처 및 정의.
3. Metrics:
   • Train: box_loss, cls_loss, dfl_loss, lr (학습률).
   • Metrics: precision, recall, mAP50, mAP50-95.
4. Images:
   • Mosaic: 데이터 증강을 보여주는 훈련 배치.
   • Validation: 검증 데이터에 대한 정답 라벨 및 모델 예측.
   • Plots: 혼동 행렬, 정밀도-재현율 곡선.
5. Weights: 최종 훈련된 모델(best.pt)이 Neptune 실행의 weights 폴더에 업로드됩니다.

고급 사용법

실행 구성하기

표준 Ultralytics project 및 name 인수를 사용하여 Neptune에서 실행을 구성할 수 있습니다.

• project: Neptune 프로젝트 슬러그 workspace/name이어야 합니다. 이것이 콜백이 neptune.init_run에 전달하는 값입니다.
• name: 특정 실행에 대한 식별자 역할을 합니다.

사용자 지정 로깅

자동 로깅과 함께 추가적인 사용자 지정 지표를 기록해야 하는 경우 Neptune 실행 인스턴스에 액세스할 수 있습니다. Ultralytics 통합은 실행 수명 주기를 내부적으로 관리하므로, 특정 실행 객체에 액세스하려면 트레이너 로직을 수정하거나 사용자 지정 콜백을 만들어야 합니다.

FAQ

Neptune 로깅을 비활성화하려면 어떻게 하나요?

neptune을 설치했지만 특정 세션이나 전체적으로 로깅을 비활성화하려면 YOLO 설정을 수정하십시오.

# Disable Neptune integration
yolo settings neptune=False

이미지가 업로드되지 않습니다. 무엇이 문제인가요?

네트워크가 Neptune 서버와의 연결을 허용하는지 확인하십시오. 또한 이미지 로깅은 일반적으로 특정 간격(예: 에포크 종료 또는 훈련 종료)에 발생합니다. Ctrl+C를 사용하여 훈련을 조기에 중단하면 혼동 행렬이나 최상의 모델 가중치와 같은 최종 아티팩트가 업로드되지 않을 수 있습니다.

특정 Neptune 실행 ID에 기록할 수 있나요?

현재 통합 방식은 각 훈련 세션마다 새로운 실행을 자동으로 생성합니다. 기존 실행에 대한 로깅을 재개하려면 일반적으로 Python 코드에서 Neptune 초기화를 수동으로 처리해야 하며, 이는 자동 통합의 범위를 벗어납니다. 그러나 Ultralytics는 로컬에서 훈련 재개를 지원하며, 이 경우 재개된 에포크를 추적하기 위해 Neptune에 새로운 실행이 생성됩니다.

Neptune에서 모델 가중치는 어디에서 찾을 수 있나요?

In your Neptune dashboard, navigate to the Artifacts or All Metadata section. You will find a weights folder containing your best.pt file, which you can download for deployment.