설치¶

torch-rbln은 사전 빌드된 휠로 설치하거나 소스에서 빌드할 수 있습니다. RBLN NPU에서 모델을 컴파일하고 실행하려면 RBLN 패키지 인덱스에서 rebel-compiler를 별도로 설치해야 합니다.

Python에서 평소처럼 import torch를 사용하면 torch-rbln을 사용할 수 있습니다. torch-rbln은 out-of-tree extension으로 자동 로드되므로 별도로 import할 필요가 없습니다.

1
2
3

import torch

x = torch.ones(4, dtype=torch.float16, device="rbln")

버전 이력은 릴리스 노트에서 확인할 수 있습니다.

버전 조합¶

torch-rbln은 특정 rebel-compiler 인터페이스와 특정 PyTorch CPU 휠을 기준으로 빌드됩니다. 세 패키지 모두 같은 SDK 릴리스의 버전으로 설치해야 합니다.

import torch를 실행하면 torch-rbln과 rebel-compiler의 ABI(Application Binary Interface) 호환성을 확인합니다. 서로 다른 릴리스의 패키지를 함께 사용하면 import 단계에서 RBLN ABI mismatch 메시지와 함께 실패합니다. 해결 방법은 문제 해결에 정리되어 있습니다.

빠른 시작¶

가상 환경을 만들고 패키지를 설치한 뒤 설치 상태를 확인합니다.

1
2
3

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

PyPI에서 torch-rbln과 의존성으로 지정된 torch CPU 휠을 함께 설치합니다.

1
2
3
4
5

$ pip install \
  --index-url https://download.pytorch.org/whl/cpu \
  torch==2.13.0+cpu
$ pip install \
  torch-rbln==0.12.0

RBLN 패키지 인덱스에서 rebel-compiler를 설치합니다. RBLN Portal 인증 정보가 필요합니다.

1
2
3

$ pip install \
  --extra-index-url https://pypi.rbln.ai/simple \
  rebel-compiler==0.12.0

설치 확인¶

먼저 환경 진단 보고서를 실행합니다. NPU가 필요하지 않으며 연산자를 실행하지도 않습니다.

1

python -m torch_rbln.diagnose

환경이 올바르게 설정되면 다음과 같은 출력이 나옵니다. 값은 시스템마다 다릅니다. torch-rbln package:와 rebel-compiler package:의 loaded from:이 활성화한 환경을 가리키고 rebel ABI handshake:가 verdict: OK로 끝나는지 확인합니다.

...
=== torch-rbln environment diagnostics ===

torch-rbln package:
  version: <TORCH_RBLN_VERSION>
  install_type: normal
  loaded from: /path/to/.venv/lib/python3.x/site-packages/torch_rbln
  installed at: /path/to/.venv/lib/python3.x/site-packages/torch_rbln
  lib_dir: /path/to/.venv/lib/python3.x/site-packages/torch_rbln/lib (exists: True)
  native .so in lib: libc10_rbln.so, ...

rebel-compiler package:
  version: <REBEL_COMPILER_VERSION>
  install_type: normal
  loaded from: /path/to/.venv/lib/python3.x/site-packages/rebel
  installed at: /path/to/.venv/lib/python3.x/site-packages/rebel

rebel ABI handshake:
  built against ABI: <N>
  librbln.so: /path/to/.venv/lib/python3.x/site-packages/tvm/librbln.so
  runtime accepts: <MIN>..<CURRENT> (min_supported..current)
  verdict: OK

Environment variables (affecting library search):
  LD_LIBRARY_PATH= (not set)
  PYTHONPATH= (not set)
...

보고서는 stderr로 출력되므로 텍스트를 읽어 확인합니다. 이 모듈은 torch의 네이티브 라이브러리나 RBLN 확장을 로드하지 않으므로 import torch 자체가 실패해도 보고서를 출력합니다.

이어서 fallback 로그를 켜고 디바이스에서 연산 하나를 실행합니다. 로그에 op ran on CPU 행이 없으면 해당 연산이 디바이스에서 실행되었으며 fallback이 감지되지 않았다는 뜻입니다. rbln 텐서를 직접 출력하면 호스트 측 포맷팅 연산자가 실행되어 이 포맷팅 연산자가 fallback 로그에 나타날 수 있습니다. 다음 명령은 이를 피하려고 출력 전에 .cpu()로 결과를 가져옵니다.

1

TORCH_RBLN_LOG_LEVEL=INFO python -c "import torch; a = torch.ones(64, dtype=torch.float16, device='rbln'); c = a + a; print(c.device, c.cpu()[:3])"

rbln:0 tensor([2., 2., 2.], dtype=torch.float16)

첫 호출은 연산자를 컴파일하므로 같은 프로세스의 이후 호출보다 눈에 띄게 오래 걸립니다. 이는 정상이며 매 프로세스에서 다시 컴파일하므로 매 실행마다 첫 호출은 느릴 수 있습니다. 텐서가 정상적으로 출력되고 op ran on CPU 행이 없다면 설치 확인이 끝났습니다. 만약 실패했다면 다음을 확인합니다.

• RuntimeError: Cannot find libraries: ['librbln.so', 'librbln_runtime.so'] 또는 FileNotFoundError: Could not find librbln.so: 현재 환경에 rebel-compiler가 없거나 다른 스택의 LD_LIBRARY_PATH가 해당 라이브러리보다 우선하도록 설정되어 있습니다. 해결 방법은 문제 해결에 정리되어 있습니다.
• RBLN ABI mismatch: ...: torch-rbln과 rebel-compiler가 서로 다른 릴리스입니다. 같은 릴리스의 두 패키지를 다시 설치해야 합니다. 자세한 내용은 문제 해결에서 확인할 수 있습니다.
• torch.rbln.device_count()가 0을 반환: 현재 프로세스에서 볼 수 있는 NPU가 없습니다. rbln-smi, RBLN_VISIBLE_DEVICES 설정, 컨테이너 디바이스 패스스루를 확인합니다. 이 경우는 문제 해결에서 자세히 다룹니다.

필요하다면 디바이스 토폴로지를 출력해 각 논리 디바이스에 어떤 물리 NPU가 포함되는지 확인할 수 있습니다.

1

python -c "import torch; torch.rbln.device_summary()"

[RBLN] Device Topology Initialized:
+----------------+------------------+---------------------+
| Logical Device | Physical NPU IDs | Status              |
+----------------+------------------+---------------------+
| rbln:0         | [ 0 ]            | Active              |
+----------------+------------------+---------------------+

Docker¶

설치 가이드의 설치 매트릭스에는 지원하는 OS와 Python 버전별 SDK 컨테이너 이미지 및 docker pull 명령이 있습니다. 이미지에 rebel-compiler가 포함되어 있으므로 컨테이너 안에서 앞의 pip 명령으로 torch-rbln을 추가합니다. RBLN Container Toolkit으로 NPU 디바이스 노드를 컨테이너에 연결합니다.

업그레이드¶

빠른 시작의 명령은 정확한 버전을 지정합니다. 새 릴리스의 명령을 실행하면 세 패키지가 함께 교체됩니다. 업그레이드 후 설치 확인을 다시 진행하는 것을 권장합니다.

제거¶

1

pip uninstall -y torch-rbln

rebel-compiler와 torch는 별도 패키지입니다. 같은 환경의 다른 패키지에서 사용하지 않을 때만 제거해야 합니다.

소스 빌드(고급)¶

저장소: torch-rbln

machine pypi.rbln.ai
login <your-rbln-portal-id>
password <your-rbln-portal-password>

1
2
3
4

git clone https://github.com/RBLN-SW/torch-rbln.git
cd torch-rbln
uv venv .venv && source .venv/bin/activate
uv pip install -U pip

1

./tools/dev-setup.sh pypi

❌ Cannot reach any rbln pypi index (no permission or network error).

1
2

uv sync --no-install-project
uv pip install -e . --no-build-isolation

다음 단계¶

• 튜토리얼: 실행 및 디버깅 - 첫 연산과 모듈 실행, fallback 로그, explain().
• 실행 방식 - 모델을 포팅하기 전에 알아야 할 device="rbln"의 동작.
• 환경 변수 - 여러 NPU를 사용하는 호스트의 디바이스 매핑과 로깅.