Mục tiêu
Bài này dựng môi trường runtime cho Jetson AGX Orin 64GB. Theo tài liệu cuRobo mới nhất, môi trường được khuyến nghị là Ubuntu Linux, GPU NVIDIA đời Turing trở lên, Python từ 3.10 đến 3.13 chưa vượt ngưỡng validation, driver hỗ trợ CUDA 12+, và cài bằng uv. Trên Jetson, driver/CUDA đi theo JetPack, nên bước quan trọng nhất là khóa JetPack trước khi cài PyTorch và cuRobo.
Ma trận version nên ghi vào lab notebook
Trước khi cài bất kỳ package nào, tạo một file deploy-matrix.md hoặc deploy-matrix.yaml. Đây là thứ giúp bạn debug sau 2 tuần khi planner bỗng chậm hoặc import CUDA lỗi.
target: jetson-agx-orin-64gb
l4t: "R36.x"
jetpack: "6.x"
cuda_runtime: "12.x"
python: "3.11"
torch: "aarch64 wheel matching JetPack"
curobo: "git sha or release tag"
install_mode: "uv pip install .[cu12] if torch already exists"
storage: "NVMe for repo, venv, torch cache, uv cache"
power_mode: "MAXN for benchmarking, production mode documented separately"
Không trộn ba nguồn PyTorch: wheel NVIDIA Jetson, PyPI x86_64, và container NGC khác JetPack. Nếu bạn dùng base image l4t-pytorch, để image quyết định PyTorch rồi cài cuRobo bằng extra không kéo torch (.[cu12]). Nếu bạn cài bare-metal, kiểm tra wheel PyTorch aarch64 trước, rồi mới chạy cuRobo tests.
1. Kiểm tra Jetson trước khi cài
sudo nvpmodel -q
tegrastats
nvcc --version
python3 --version
df -h /
Nếu rootfs nằm trên eMMC, nên chuyển workspace và cache sang NVMe. cuRobo kéo PyTorch, Warp và build/cache CUDA kernels; eMMC nhỏ làm build chậm và dễ hết dung lượng.
mkdir -p /mnt/nvme/robotics/{src,venvs,cache}
export UV_CACHE_DIR=/mnt/nvme/robotics/cache/uv
export TORCH_HOME=/mnt/nvme/robotics/cache/torch
2. Clone và tạo venv
cd /mnt/nvme/robotics/src
git clone https://github.com/NVlabs/curobo
cd curobo
uv venv --python 3.11
source .venv/bin/activate
python -V
Tài liệu chính thức dùng:
uv pip install .[cu12-torch]
Nếu Jetson của bạn đã có PyTorch wheel đúng JetPack/CUDA, dùng biến thể không kéo PyTorch:
uv pip install .[cu12]
Trên Jetson, đây là lựa chọn thường an toàn hơn vì PyTorch wheel cho aarch64 phải khớp JetPack. Không ép wheel x86_64 từ PyPI vào Jetson.
3. Smoke test tối thiểu
python - <<'PY'
import torch
import curobo
print("torch", torch.__version__)
print("cuda", torch.version.cuda)
print("cuda available", torch.cuda.is_available())
print("device", torch.cuda.get_device_name(0))
print("curobo", curobo.__version__)
PY
Sau đó chạy test package nếu thời gian cho phép:
pytest --pyargs curobo.tests
Nếu test đầy đủ quá lâu, chạy ít nhất các example getting-started không yêu cầu robot thật trước khi nối ROS 2.
4. Container hóa để không mất môi trường
Một layout đơn giản:
FROM nvcr.io/nvidia/l4t-pytorch:r36.4.0-pth2.4-py3
RUN apt-get update && apt-get install -y git curl build-essential && rm -rf /var/lib/apt/lists/*
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
WORKDIR /opt/curobo
COPY . /opt/curobo
RUN uv venv --python 3.11 /opt/curobo/.venv
RUN . /opt/curobo/.venv/bin/activate && uv pip install .[cu12]
Không dùng Dockerfile này như chân lý tuyệt đối; hãy đổi base image theo JetPack thực tế. Điều cần giữ là: base L4T đúng, PyTorch đúng, rồi mới cài cuRobo.
5. Lỗi thường gặp
| Triệu chứng | Nguyên nhân hay gặp | Cách xử lý |
|---|---|---|
torch.cuda.is_available() == False |
Wheel PyTorch sai JetPack/CUDA | Cài lại PyTorch aarch64 đúng bản |
| Build quá lâu rồi hết disk | Cache nằm trên eMMC | Chuyển UV_CACHE_DIR, TORCH_HOME, workspace sang NVMe |
| Import được nhưng example crash | ABI mismatch CUDA/Warp/PyTorch | Pin image và cài lại trong venv sạch |
| Planner lần đầu rất chậm | CUDA graph/kernel warmup | Gọi warmup() trong startup, không trong vòng điều khiển |
6. Smoke test có giá trị hơn import curobo
Sau import, chạy ba lớp test nhỏ:
# 1) GPU tensor path
python - <<'PY'
import torch
x = torch.randn(1024, 1024, device="cuda")
print((x @ x).mean().item())
PY
# 2) cuRobo package tests, nếu đủ thời gian
pytest --pyargs curobo.tests -q
# 3) một example không cần robot thật
python -m curobo.examples.getting_started.forward_kinematics --help
Nếu test package quá lâu trên Jetson, vẫn nên chạy ít nhất một example FK/IK sau khi build robot model ở bài 3. Mục tiêu không phải "test hết thư viện", mà là chứng minh đúng pipeline CUDA/PyTorch/Warp trên chính target runtime.
7. Checklist trước bài tiếp theo
python -c "import curobo"chạy được.torch.cuda.is_available()trả vềTrue.nvidia-smikhông có trên Jetson là bình thường; dùngtegrastats.- Repo và venv nằm trên NVMe.
- Có log exact version của JetPack, Python, PyTorch, CUDA và cuRobo commit.
Kết luận
Phần khó của cuRobo trên Jetson không phải cú pháp cài đặt, mà là khóa ma trận version. Khi môi trường đã reproducible, bạn mới nên build robot model. Bài tiếp theo sẽ xử lý URDF, mesh, collision spheres và self-collision matrix cho robot arm.
