공개 노트

Jetson에서 오픈소스 VLM(Cosmos Reason 2B) 배포 핵심 정리

2026-02-27Views 208약 6분

Summary

이 노트는 아래 출처를 AI 도구 클립을 활용하여 재구성한 것입니다. 상세한 정보는 원문 방문을 권장합니다.

원문 출처: https://huggingface.co/blog/nvidia/cosmos-on-jetson

핵심 요약

Jetson 보드에서 NVIDIA Cosmos Reason 2B 비전-언어 모델을 vLLM으로 띄우고, Live VLM WebUI로 웹캠 기반 실시간 분석 환경을 만드는 과정이다.
Thor/AGX Orin/Orin Super Nano 별로 GPU 메모리 한계가 달라서, 같은 모델을 서로 다른 파라미터로 서빙하는 전략이 핵심이다.

VLM과 Jetson을 엣지 서비스로 보는 관점

Vision-Language Model은 이미지를 보고 말을 이해하고 답할 수 있는 멀티모달 LLM이다.
이 튜토리얼의 대상인 Cosmos Reason 2B는 여기에 "chain-of-thought 스타일 추론"까지 제공해, 단순 캡션을 넘어 상황 설명과 이유 설명까지 가능하다.

Jetson 라인업(AGX Thor, AGX Orin, Orin Super Nano)은 GPU가 들어간 엣지 디바이스로, 로봇·물류·리테일 카메라처럼 "현장에서 바로 판단해야 하는" 물리 공간 AI에 적합하다.
핵심은 클라우드 대신 디바이스 위에서 VLM을 직접 돌려, 지연과 네트워크 의존성을 줄이고 데이터를 로컬에 유지하는 것이다.

필요한 하드웨어·소프트웨어 전제 조건

지원 대상은 Jetson AGX Thor, AGX Orin(32/64GB), Orin Super Nano로 제한된다.
모두 NVMe SSD가 필수인데, 모델 FP8 가중치 약 5GB와 vLLM 컨테이너 약 8GB, 그리고 런타임 여유 공간을 고려하면 최소 20GB 이상을 잡는 것이 안전하다.

Thor는 JetPack 7(L4T r38.x), Orin 계열은 JetPack 6(L4T r36.x)를 요구해, OS 버전이 맞지 않으면 그대로 막힌다.
또한 모델과 컨테이너 이미지를 받기 위해 무료 NVIDIA NGC 계정과 API 키가 필요하다는 점도 초기에 준비해야 한다.

전체 워크플로 한눈에 보기

이 튜토리얼의 워크플로는 네 단계로 요약된다.
첫째, NGC CLI를 설치하고 Cosmos Reason 2B FP8 모델 체크포인트를 다운로드한다.
둘째, Jetson 종류에 맞는 vLLM Docker 이미지를 가져온다.
셋째, 모델 디렉터리를 컨테이너에 볼륨 마운트한 뒤 vLLM으로 HTTP 서버를 띄운다.
넷째, Live VLM WebUI를 설치하고 vLLM API에 붙여, 웹 브라우저에서 웹캠 영상을 실시간 분석한다.

스타트업 입장에서 보면 "모델·서빙·UI" 세 블록을 조립해, 빠르게 엣지 VLM 프로토타입을 만드는 구조다.

NGC CLI로 모델 받기: 조직 내 재현 가능한 스텝 만들기

먼저 Jetson에 작업용 디렉터리를 만들고, ARM64용 NGC CLI를 내려받아 PATH에 추가한다.
CLI 설정에서 API 키만 입력하면 이후 팀원 누구나 동일 명령어로 모델을 받을 수 있으므로, 사내 위키에 그대로 명령어를 적어두는 것이 좋다.

핵심 명령은 다음과 같다.

ngc registry model download-version \
  "nim/nvidia/cosmos-reason2-2b:1208-fp8-static-kv8"

이 명령으로 cosmos-reason2-2b_v1208-fp8-static-kv8/ 디렉터리가 생성되며, 이 경로를 vLLM에 그대로 넘겨 사용한다.
클라우드에서 받던 Hugging Face 모델과 달리, Jetson에 직접 저장된 NGC 아티팩트를 쓰는 형태라고 보면 된다.

Jetson별 vLLM 컨테이너 전략과 메모리 감각

Jetson마다 가져와야 하는 컨테이너 이미지와 설정값이 미묘하게 다르다.
Thor는 nvcr.io/nvidia/vllm:26.01-py3, Orin 계열은 ghcr.io/nvidia-ai-iot/vllm:r36.4-tegra-aarch64-cu126-22.04 이미지를 사용한다.

Thor와 AGX Orin은 FP8 2B 모델을 max-model-len 8192, gpu-memory-utilization 0.8로 여유 있게 돌릴 수 있고, 따라서 여러 문장·여러 턴의 대화를 자연스럽게 처리할 수 있다.
반면 Orin Super Nano는 메모리가 크게 제한되어 있어, 컨텍스트 길이·동시 시퀀스·멀티모달 입력 개수까지 적극적으로 줄여야 한다.

Orin Super Nano용 vLLM 설정 예시는 다음과 같다.

vllm serve /models/cosmos-reason2-2b \
  --host 0.0.0.0 \
  --port 8000 \
  --trust-remote-code \
  --enforce-eager \
  --max-model-len 256 \
  --max-num-batched-tokens 256 \
  --gpu-memory-utilization 0.65 \
  --max-num-seqs 1 \
  --enable-chunked-prefill \
  --limit-mm-per-prompt '{"image":1,"video":1}' \
  --mm-processor-kwargs '{"num_frames":2,"max_pixels":150528}'

여기서 중요한 건 "성능 최적화"보다 "절대 안 죽고 돌아가는 것"에 초점을 맞췄다는 점이다.
메모리가 더 필요하면 max-model-len, gpu-memory-utilization, max-num-seqs를 내려가는 방향으로 조정하면 된다.

vLLM 서버를 제품처럼 다루기: 헬스 체크와 간단 테스트

컨테이너를 띄운 뒤 vLLM이 제대로 살아 있는지 확인하기 위해 HTTP 헬스 체크를 사용한다.
다음 명령으로 모델 리스트를 확인할 수 있다.

curl http://localhost:8000/v1/models

이후 간단한 채팅 API 콜로 실제 추론이 동작하는지 테스트한다.

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/models/cosmos-reason2-2b",
    "messages": [
      {"role": "user", "content": "What capabilities do you have?"}
    ],
    "max_tokens": 128
  }' | python3 -m json.tool

실제 서비스로 발전시킬 계획이라면, 이 두 가지를 CI 혹은 배포 스크립트의 자동 검증 단계로 넣어두면 "모델이 안 떠서 현장에서 디바이스만 켜놓고 멍때리는 상황"을 피할 수 있다.

Live VLM WebUI로 "바로 보여줄 수 있는 데모" 만들기

Live VLM WebUI는 vLLM 서버에 붙는 웹 UI로, 브라우저에서 카메라를 선택하고 바로 스트리밍하면서 모델 답변을 볼 수 있게 해준다.
설치는 Python(uv 기반 가상환경)으로 하거나 Docker로 할 수 있어, 개발자 환경과 데모 환경을 분리하기에도 좋다.

WebUI를 실행한 뒤 브라우저에서 https://localhost:8090에 접속해, API Base URL을 http://localhost:8000/v1로 설정하고 모델을 선택하면 된다.
카메라를 선택해 Start를 누르면, 실시간 영상이 Cosmos Reason 2B로 넘어가고 오른쪽 패널에 모델 설명과 추론 결과가 출력된다.

엣지 AI를 투자자·고객에게 보여줄 때 "현장에서 물체를 집어 들면 바로 설명하는" 데모를 몇 분 안에 구성할 수 있다는 점이 큰 장점이다.

Orin 계열에서는 WebUI 설정에서 Max Tokens를 100~150, Frame Processing Interval을 60 이상으로 두는 것이 좋다.
이렇게 하면 각 응답은 짧지만 빨리 끝나고, 프레임 간 간격을 넓혀 디바이스 과부하를 줄일 수 있다.

현장에서 자주 만날 문제와 빠른 우회 전략

CUDA out-of-memory 에러는 가장 흔한 장애다.
이 경우 캐시 메모리 삭제(sudo sysctl -w vm.drop_caches=3), gpu-memory-utilization 값 감소, max-model-len 축소, 그리고 불필요한 GPU 프로세스 종료라는 4단계로 순차적으로 대응하면 대부분 해결된다.

WebUI에서 모델이 안 보이면 먼저 curl /v1/models로 vLLM이 살아 있는지 확인하고, WebUI의 Base URL이 https가 아닌 http로 되어 있는지 체크해야 한다.
vLLM과 WebUI가 서로 다른 컨테이너에 있다면 localhost 대신 Jetson의 IP를 명시해야 하는 것도 흔한 함정이다.

또한 Jetson에서 curl이 기본 설치가 안 되어 있는 경우가 있어, apt-get install curl로 먼저 설치해야 curl 기반 테스트를 진행할 수 있다.
도커 권한 문제로 컨테이너가 안 올라가는 상황도 많으니, Jetson 공식 문서의 Docker 설정 가이드를 한 번 따라가면서 그룹 권한을 정리해두는 것이 좋다.

인사이트

이 튜토리얼의 핵심 가치는 "Jetson 위에서 VLM을 product-ready 형태의 HTTP 서비스로 띄우는 구체적인 레시피"에 있다.
스타트업 관점에서는 Jetson 하드웨어 하나만 있으면, 클라우드 의존 없이 멀티모달 LLM 기반 기능을 실제 환경에서 검증하고 바로 데모까지 만들 수 있다.

실행 전략을 정리하면 다음과 같다.
먼저 자신이 쓸 Jetson 모델을 확정하고, 그 보드의 메모리 한계에 맞게 vLLM 설정을 보수적으로 시작한다.
이후 WebUI로 데모를 확보한 뒤, 제품 요구사항에 맞춰 컨텍스트 길이·응답 길이·프레임 간격 등 파라미터를 조금씩 올려가며 "성능과 안정성의 균형점"을 찾는 식으로 튜닝한다.

결국 Cosmos Reason 2B + vLLM + Live VLM WebUI 조합은 "엣지 물리 AI PoC 팩"이라고 보면 된다.
아이디어가 있다면, Jetson 하나 올려놓고 오늘 바로 카메라 앞에서 실험을 시작할 수 있다.

출처 및 참고 : Deploying Open Source Vision Language Models (VLM) on Jetson