Link to this sectionNeptune을 이용한 실험 추적#

Neptune은 MLOps를 위한 메타데이터 저장소로, 많은 실험을 수행하는 팀을 위해 구축되었습니다. 모델 구축 메타데이터를 기록, 저장, 표시, 구성, 비교 및 쿼리할 수 있는 중앙 관리 공간을 제공합니다.

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

Link to this section주요 특징#

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

Link to this section설치#

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

Link to this section설정#

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

Link to this section자격 증명 가져오기#

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

Link to this section환경 변수 설정#

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

Link to this section사용법#

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

Link to this section학습 예시#

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")

Link to this section통합 이해하기#

다음 다이어그램은 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

Link to this section어떤 데이터가 기록됩니까?#

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

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

Link to this section고급 사용법#

Link to this section실행 구성하기#

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

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

Link to this section사용자 지정 로깅#

자동 로깅 외에 추가적인 사용자 지정 메트릭을 기록해야 하는 경우 Neptune 실행 인스턴스에 액세스할 수 있습니다. Ultralytics 통합이 내부적으로 실행 수명 주기를 관리하므로, 특정 실행 객체에 액세스하려면 트레이너 로직을 수정하거나 사용자 지정 콜백을 생성해야 한다는 점에 유의하십시오.

Link to this sectionFAQ#

Link to this sectionNeptune 로깅을 어떻게 비활성화합니까?#

neptune을 설치했지만 특정 세션 또는 전역적으로 로깅을 비활성화하려면 YOLO 설정을 수정할 수 있습니다.

# Disable Neptune integration
yolo settings neptune=False

Link to this section이미지가 업로드되지 않습니다. 무엇이 문제입니까?#

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

Link to this section특정 Neptune 실행 ID로 기록할 수 있습니까?#

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

Link to this sectionNeptune에서 모델 가중치는 어디에서 찾을 수 있습니까?#

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.