Jetson 배포

Xisom Edge AI Box는 JetPack 4.5가 설치된 NVIDIA Jetson TX2에서 실행됩니다. 스택은 프런트엔드, 백엔드, Python 추론 서비스의 3개 서비스로 구성됩니다. Jetson에 특화된 부분은 추론 이미지입니다. 이 이미지는 JetPack이 제공하는 CUDA 라이브러리와 JetPack 4.5용 ONNX Runtime 휠로 빌드됩니다.

지원 프로필

프로필	장치 / JetPack	베이스 이미지	ONNX Runtime	실행 공급자
`jetson-gpu`	TX2, JetPack 4.5 (L4T r32.5)	`l4t-base:r32.5.0`	`onnxruntime-gpu 1.10.0` (cp36 휠)	CUDA, CPU 폴백

TX2에서는 TensorRT를 사용하지 않습니다. JetPack 4.5용 ONNX Runtime 빌드는 플랫폼이 제공하는 것보다 새로운 TensorRT가 필요하므로, 추론은 CUDA에서 실행됩니다.

시작 전에 알아두어야 할 이 프로필의 두 가지 결과:

ONNX opset 상한. ONNX Runtime 1.10은 opset 15까지 지원합니다. TX2용 모델은 --opset 15로 내보내세요. 번들은 이 때문에 opset-15 모델을 시드로 제공합니다.
고정된 Python 3.6 의존성 집합. JetPack 4.5는 Python 3.6에 고정되어 있으므로, jetson-gpu 이미지는 핀 고정된 이전 버전 의존성 집합을 사용합니다.

사전 요구사항 (Jetson 장치에서)

이미지는 Jetson에서 네이티브로 빌드합니다. QEMU를 사용해 L4T 이미지를 크로스 빌드하는 방식은 불안정하며 지원되지 않습니다.

docker version              # >= 20.10
docker compose version      # Compose v2 plugin required
sudo apt-get install -y zstd openssl
df -h ~                     # keep a few GB free (TX2 eMMC is small)
docker info | grep -i nvidia   # the NVIDIA container runtime must be wired in

Jetson Zoo에서 JetPack 4.5, Python 3.6용 ONNX Runtime GPU 휠을 선택하세요. PyPI의 일반 onnxruntime-gpu 휠은 Jetson에서 동작하지 않습니다. 시작 시 “missing library” 오류가 전형적인 증상입니다.

빌드 → 번들 → 설치

flowchart LR
  A["build-release-images.sh\n(build + tag 3 images)"] --> B["build-release-bundle.sh\n(docker save → dist/&lt;profile&gt;-&lt;version&gt;/)"]
  B --> C["install.sh on the target\n(load images → compose up → seed admin)"]
  A -. "build host: Jetson, internet once" .-> B
  C -. "target host: air-gapped OK" .-> C

이미지를 빌드합니다 (빌드용 Jetson에서, 최초 1회 인터넷 필요):

ORT_WHEEL_URL="https://<jetson-zoo-wheel-for-jetpack-4.5>.whl" \
  ./scripts/build-release-images.sh <version> --profile jetson-gpu

오프라인 번들을 패키징합니다:
Terminal window
```
./scripts/build-release-bundle.sh --profile jetson-gpu --version v<version>
```
출력 dist/jetson-gpu-v<version>/에는 무결성 매니페스트가 포함된 압축 이미지 아카이브, Tegra용 compose 파일, 시드 모델, 그리고 install.sh / update.sh / uninstall.sh 런북 스크립트가 들어 있습니다. 레이아웃은 오프라인 번들 설치에서 설명합니다.
대상 장치에 설치합니다 (번들 디렉터리를 USB/scp로 복사):
Terminal window
```
cd dist/jetson-gpu-v<version>
sudo ./install.sh                    # detects the Jetson and accepts the jetson-gpu bundle
# sudo ./install.sh --with-systemd   # optional: start on boot
```
설치 프로그램은 아카이브 체크섬을 검증하고, 이미지를 로드하며, 실행 스택을 /opt/aiboard에 배치하고, 고유한 JWT 시크릿과 관리자 비밀번호를 생성한 뒤, 스택을 시작하고 헬스를 기다립니다. 대시보드 URL과 관리자 비밀번호는 한 번만 출력됩니다. 즉시 저장하세요.
GPU 추론이 실제로 동작하는지 검증합니다:
Terminal window
```
docker ps --format '{{.Names}}  {{.Status}}'                              # inference and backend (healthy), frontend Up
docker inspect aiboard-inference-real --format '{{.HostConfig.Runtime}}'  # expect: nvidia
docker exec aiboard-inference-real grep -E "resolved to CPU only|STRICT_EP" /data/logs/inference.log  # expect: no output
```
스택은 /opt/aiboard에서 실행되며 /opt/aiboard/.env에서 설정을 읽습니다. 따라서 번들 디렉터리에서 docker compose 명령을 쓰지 말고 docker ps로 확인하세요. 그런 다음 대시보드에 로그인하여 Python 추론 카드의 실행 공급자가 **CPU (fallback)**이 아닌 CUDA로 표시되는지 확인하세요. 추론 콘솔은 오류만 출력하므로 공급자 관련 줄은 docker logs에 나타나지 않습니다. 위의 경고는 컨테이너 안의 /data/logs/inference.log에 기록됩니다. GPU가 예상되는데 CPU에서 실행될 때를 참조하세요.

Tegra 특유의 동작

번들의 compose 파일에는 TX2에 필요한 설정이 들어 있습니다:

runtime: nvidia 및 추론 컨테이너 내부의 root — Tegra에서 GPU 장치 접근을 위해 필요합니다.
/sys 마운트 — GPU 부하와 온도는 Tegra sysfs에서 가져옵니다(Jetson에는 nvidia-smi가 없습니다). 대시보드의 GPU 패널에 공급됩니다.
OPENBLAS_CORETYPE 핀 — Tegra 코어에서 OpenBLAS 잘못된 명령어(illegal-instruction) 크래시를 방지합니다.
필드별 N/A 메트릭 — Jetson이 보고할 수 없는 대시보드 헬스 필드는 가짜 0 대신 N/A로 표시됩니다.

추론 서비스는 CUDA 실행 공급자를 사용합니다. CUDA를 시작할 수 없으면 CPU로 폴백하고 경고를 기록하며, 대시보드에 **CPU (fallback)**이 표시됩니다. 폴백 대신 박스가 시작을 거부하도록 하려면 GPU가 예상되는데 CPU에서 실행될 때를 참조하세요.

Jetson 라인의 버전 관리

Jetson 릴리스는 Git 태그가 아니라 VERSION 파일로 버전이 매겨집니다. 대시보드의 About 패널은 설치된 번들의 릴리스 버전을 보여줍니다. 예상과 다르면 번들의 images/manifest.txt와 비교하세요. 버전 및 업데이트를 참조하세요.

문제가 발생하면

증상	해결
`unknown shorthand flag: 'f' in -f`	Compose v2 플러그인 누락 — `sudo apt-get install -y docker-compose-plugin`
빌드 중 `Cannot autolaunch D-Bus`	헤드리스 크리덴셜 헬퍼 문제 — 빌드 스크립트가 자동으로 격리합니다. 임시 `docker` 명령에는 비어 있는 `DOCKER_CONFIG` 디렉터리를 사용하세요
GPU 컨테이너: `no CUDA-capable device`	호스트에 NVIDIA container runtime이 없거나, compose에 `runtime: nvidia`가 없습니다(번들 compose에는 이미 설정되어 있습니다)
추론이 missing-library 오류로 종료됨	잘못된 ONNX Runtime 휠 — Jetson Zoo에서 JetPack 4.5용 휠을 선택해 재빌드하세요
`install.sh`: “does not match this bundle”	이 머신은 Jetson이 아닙니다. `jetson-gpu` 번들을 TX2로 복사해 그곳에서 설치하세요
업로드 시 모델 검증 실패	opset > 15로 내보낸 모델 — ONNX Runtime 1.10을 위해 `--opset 15`로 다시 내보내세요

다음 단계

오프라인 번들 설치 전체 에어갭 설치 및 업데이트 런북.

하드웨어 설정 실행 공급자 모드와 네트워크 사전 요구사항.

modelctl로 모델 준비하기 TX2에 맞는 opset으로 ONNX 모델을 내보냅니다.

GPU / CUDA 오류 GPU 가시성과 CUDA 실패를 문제 해결합니다.