Neptune을 이용한 실험 추적#

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

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

주요 특징#

• 자동 로깅: 박스 손실, 분류 손실, mAP 등의 주요 학습 메트릭을 자동으로 기록합니다.
• 이미지 시각화: 학습 모자이크와 검증 예측을 Neptune 대시보드에서 직접 확인합니다.
• 모델 체크포인팅: 학습이 끝날 때 학습된 모델 가중치(best.pt)를 자동으로 업로드하고 버전 제어합니다.
• 하이퍼파라미터 추적: 모든 구성 파라미터를 기록하여 실험의 완전한 재현성을 보장합니다.
• 대화형 플롯: 혼동 행렬(confusion matrices)과 정밀도-재현율 곡선(precision-recall curves)을 시각화하여 모델 성능을 분석합니다.

설치#

Ultralytics에서 Neptune을 사용하려면 neptune 클라이언트 패키지와 ultralytics을 함께 설치해야 합니다.

# Install the required packages
pip install ultralytics neptune

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

설정#

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

자격 증명 가져오기#

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

환경 변수 설정#

자격 증명을 처리하는 가장 안전한 방법은 환경 변수를 사용하는 것입니다. Ultralytics Neptune 콜백은 YOLO project 인수를 읽으며 NEPTUNE_PROJECT을 사용하지 않는다는 점에 유의하세요. 학습 명령어에서 project=을 통해 전체 Neptune 슬러그(예: workspace/name)를 전달하세요. 그렇지 않으면 Neptune이 기본값인 "Ultralytics"를 그대로 사용하려고 시도하여 실행이 실패하게 됩니다.

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]:::start --> B{Neptune Callback}:::decide
    B -->|Log Scalars| C[Loss, mAP, LR]:::proc
    B -->|Log Images| D[Mosaics, Preds]:::proc
    B -->|Log Artifacts| E[Model Weights]:::proc
    B -->|Log Metadata| F[Hyperparameters]:::proc

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

    G --> H[Neptune Web Dashboard]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef extern fill:#607D8B,color:#fff

어떤 데이터가 기록됩니까?#

학습 명령을 실행하면 Neptune 통합이 실행 시 다음 데이터 구조를 자동으로 캡처합니다:

1. 구성/하이퍼파라미터: 모든 학습 인자(epochs, lr0, optimizer 등)가 구성 섹션 아래에 기록됩니다.
2. 구성/모델: 모델 아키텍처 및 정의.
3. 메트릭:
   • 학습: box_loss, cls_loss, dfl_loss, lr(학습률).
   • 메트릭: precision, recall, mAP50, mAP50-95.
4. 이미지:
   • Mosaic: 데이터 augmentation을 보여주는 학습 배치.
   • Validation: 검증 데이터에 대한 정답(Ground truth) 레이블 및 모델 예측.
   • Plots: 혼동 행렬(Confusion matrices), Precision-Recall 곡선.
5. 가중치: 최종 학습된 모델(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에서 모델 가중치는 어디에서 찾을 수 있습니까?#

Neptune 대시보드에서 Artifacts 또는 All Metadata 섹션으로 이동하세요. 배포용으로 다운로드할 수 있는 best.pt 파일이 포함된 weights 폴더를 찾을 수 있습니다.