Ultralytics YOLO의 Luxonis OAK 배포#

Luxonis OAK 카메라는 Luxonis 도구를 사용해 변환한 후 Ultralytics YOLO 모델을 온디바이스에서 실행합니다. 이는 수동 배포 워크플로이며, Luxonis는 Ultralytics의 기본 model.export(format="...") 대상이 아닙니다.

이 가이드에서는 RVC2 및 RVC4 장치를 다룹니다. 카메라 플랫폼에 맞게 변환하세요. RVC2와 RVC4 아티팩트는 서로 호환되지 않습니다. 지원되는 모델 계열과 작업은 다를 수 있으므로 변환 전에 Luxonis Tools 지원 매트릭스를 확인하세요.

.pt과 같이 지원되는 YOLO 체크포인트 또는 자체 학습된 모델인 yolo26n.pt에서 시작하세요. 변환된 NN Archive에는 모델과 런타임 메타데이터가 패키징됩니다.

Luxonis Hub를 사용한 클라우드 변환#

1. Luxonis Hub에 로그인하고 빠른 변환을 엽니다.
2. YOLO를 선택하고 RVC2 또는 RVC4를 선택한 다음 .pt 체크포인트를 업로드합니다.
3. 입력 형태와 변환 매개변수를 설정한 다음 변환을 제출합니다.
4. 완료되면 아래 추론 예제에 사용할 변환된 모델의 식별자를 복사하거나 NN Archive를 다운로드합니다.

자동 변환이나 사용자 지정 RVC4 보정 데이터를 사용하려면 HubAI SDK를 사용하세요. Python 3.10 이상 환경에서 설치 안내를 따르세요. 상세 변환에서는 레지스트리 관리와 사전 정의된 보정 데이터셋을 제공합니다.

Tools 및 ModelConverter를 사용한 로컬 변환#

Python 3.10 이상과 Docker를 사용하세요. 종속성 제약 조건을 포함한 업스트림 설정 안내에 따라 Luxonis Tools를 설치합니다. Tools는 Luxonis 파싱에 맞게 YOLO 출력을 준비합니다. 일반적인 ONNX 내보내기로 이 단계를 대체할 수 없습니다.

# Export the checkpoint to an ONNX NN Archive
tools yolo26n.pt --imgsz "640 640" --output-dir output

# Install the target-platform converter
pip install modelconv==0.6.0

Tools는 yolo26n.tar.xz을 output/ 아래의 타임스탬프가 지정된 디렉터리에 씁니다. 아래 예제 경로를 해당 파일의 경로로 바꾸세요. RVC4 INT8 변환의 경우 calibration_images/에 대표적인 배포 이미지를 채우세요. 보정 데이터 요구 사항을 참조하세요.

modelconverter convert rvc4 --path output/yolo26n_20260807_104858/yolo26n.tar.xz \
  calibration.path calibration_images/

RVC2의 경우 rvc4 대신 rvc2을 사용하세요. RVC2의 FP16 변환에는 보정 이미지가 필요하지 않습니다. 추론에는 중간 ONNX Archive가 아니라 ModelConverter 출력 디렉터리에 생성된 컴파일된 NN Archive를 사용하세요. 출력 경로와 플랫폼별 옵션은 ModelConverter를 참조하세요.

OAK 카메라에서 추론 실행#

호환되는 OAK 카메라를 연결하고 Python 환경에 DepthAI를 설치합니다.

pip install depthai==3.9.0

비공개 Hub 모델의 경우 스크립트를 실행하기 전에 DEPTHAI_HUB_API_KEY에 Luxonis Hub API 키를 설정하세요. your-model-identifier를 Hub에서 가져온 식별자로 바꾸거나, 로컬에서 컴파일한 NN Archive를 사용할 수 있습니다.

import depthai as dai

model = "your-model-identifier"
# 또는 변환된 로컬 아티팩트를 사용하세요.
# model = dai.NNArchive("path/to/model.rvc4.tar.xz")

visualizer = dai.RemoteConnection()

with dai.Pipeline() as pipeline:
    camera = pipeline.create(dai.node.Camera).build()
    detection = pipeline.create(dai.node.DetectionNetwork).build(camera, model)

    visualizer.addTopic("rgb", detection.passthrough, group="RGB")
    visualizer.addTopic("detections", detection.out, group="RGB")

    pipeline.start()
    visualizer.registerPipeline(pipeline)

    while pipeline.isRunning():
        if visualizer.waitKey(1) == ord("q"):
            pipeline.stop()

RGB 스트림과 감지 결과를 보려면 http://localhost:8082을 엽니다. DetectionNetwork은 호환되는 인스턴스 분할 및 포즈 모델도 지원합니다. 시맨틱 분할 및 분류를 비롯한 다른 작업은 작업별 추론 안내를 따르세요.

스테레오 깊이 파이프라인은 공간 감지 예제를 참조하세요. 벤치마킹 가이드를 사용해 대상 카메라에서 모델을 측정하세요. 처리량은 모델, 입력 크기, 정밀도 및 파이프라인 구성에 따라 달라집니다.

자주 묻는 질문#