문제 해결¶

각 섹션은 증상이나 절차별로 표시되는 메시지, 원인, 해결 단계를 설명합니다. import 또는 라이브러리 오류가 발생하면 먼저 환경 보고서를 확인하는 것을 권장합니다. NPU 없이도 실행할 수 있습니다.

1

python -m torch_rbln.diagnose

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

보고서의 각 블록과 확인할 값은 설치 › 설치 확인에 설명되어 있습니다.

librbln.so / librbln_runtime.so를 찾을 수 없음¶

rebel-compiler와 함께 설치된 RBLN 런타임 라이브러리를 현재 Python 환경의 동적 로더가 찾지 못하는 경우입니다.

다음 순서로 해결합니다.

1. rebel-compiler가 설치된 환경을 활성화합니다. pip show rebel-compiler 또는 uv pip list | grep rebel로 확인할 수 있습니다.
2. 다른 스택에서 설정한 LD_LIBRARY_PATH 또는 PYTHONPATH가 라이브러리 검색 순서를 바꾸는지 확인합니다. 진단 보고서는 후보 경로를 검색 순서대로 나열하고 실제로 로드된 경로를 표시합니다. 다른 스택의 환경 변수가 설정되지 않은 새 셸이나 프로젝트 가상 환경만 사용하는 구성을 권장합니다.
3. 구성이 불확실하면 설치 문서에 따라 rebel-compiler와 torch-rbln을 다시 설치합니다.

torch-rbln과 librbln.so의 ABI 불일치¶

ABI(Application Binary Interface)는 torch-rbln과 librbln.so 사이의 바이너리 인터페이스를 정의합니다.

import torch는 autoload 진입점을 통해 torch-rbln을 로드하며 이때 로드한 librbln.so가 휠의 빌드 기준 인터페이스를 구현하는지 확인합니다. rebel-compiler는 구현한 인터페이스와 지원하는 가장 오래된 consumer contract를 두 숫자로 제공합니다. torch-rbln은 빌드에 사용한 인터페이스를 기록하며 이 값이 해당 범위 안에 있어야 합니다. 범위를 벗어나면 사용 중인 라이브러리와 양쪽 버전을 명시한 RBLN ABI mismatch 메시지와 함께 import가 실패합니다. 이 검사는 실행을 계속하다가 undefined symbol 크래시나 런타임 내부 손상이 발생하는 것을 방지합니다.

다음 순서로 해결합니다.

1. 같은 SDK 릴리스의 torch-rbln과 rebel-compiler를 설치합니다. 함께 배포되는 버전은 릴리스 노트, 설치 명령은 설치 › 버전 조합에서 확인할 수 있습니다.
2. python -m torch_rbln.diagnose를 실행합니다. 어떤 librbln.so가 로드되었는지, 휠의 빌드 기준 인터페이스, 런타임이 허용하는 범위, 최종 판정 결과를 확인할 수 있습니다.

이 검사가 도입되기 전의 런타임이거나 그런 런타임으로 빌드한 torch-rbln이면 비교할 값이 없습니다. 이 경우 import는 실패하는 대신 경고를 출력하고 계속 진행합니다.

버전이 맞는 휠을 아직 구할 수 없다면 TORCH_RBLN_SKIP_ABI_CHECK로 검사를 건너뛰어 버전이 맞지 않는 두 패키지를 함께 로드할 수 있습니다.

1

export TORCH_RBLN_SKIP_ABI_CHECK=1   # 1 / ON / TRUE / YES를 인식합니다

검사를 건너뛰어도 비호환성은 해소되지 않고 드러나지 않을 뿐입니다. 이 설정을 사용하기 전에 환경 변수 › ABI 검사를 먼저 읽어 보는 것을 권합니다.

undefined symbol로 인한 import 크래시¶

import torch가 rbln_ 또는 c10::rbln 심볼을 명시한 ImportError: ... undefined symbol: ... 메시지와 함께 중단되는 경우입니다.

ABI 검사는 이 오류를 방지하기 위한 기능입니다. TORCH_RBLN_SKIP_ABI_CHECK로 검사를 건너뛰었거나 검사가 도입되기 전의 런타임을 사용하거나 다른 설치 경로의 librbln.so가 LD_LIBRARY_PATH를 통해 먼저 매핑되면 발생합니다.

1. TORCH_RBLN_SKIP_ABI_CHECK와 LD_LIBRARY_PATH 설정을 해제한 뒤 python -m torch_rbln.diagnose를 실행합니다. 어떤 librbln.so가 로드된 것으로 표시되는지 확인합니다.
2. 같은 릴리스의 torch-rbln과 rebel-compiler를 설치합니다.

보이는 NPU가 없음¶

torch.rbln.device_count()가 0을 반환하거나 torch.rbln.is_available()이 False를 반환하거나 디바이스 열거를 언급하는 런타임 오류로 디바이스 할당에 실패하는 경우입니다.

두 조회 함수는 예외를 발생시키지 않습니다. 런타임이 없거나 NPU가 보이지 않거나 디바이스 매핑 설정이 잘못되면 각각 0과 False를 반환합니다. 설정이 잘못된 경우에는 경고도 출력하며 torch.rbln.current_device(), torch.rbln.set_device() 또는 첫 할당에서 전체 오류가 발생합니다.

1. 드라이버가 카드를 인식하는지 확인합니다. rbln-smi는 호스트의 모든 NPU를 나열합니다. 표가 비어 있으면 RBLN Driver 설치 가이드에 따라 드라이버를 설치합니다.
2. RBLN_VISIBLE_DEVICES를 확인합니다(RBLN_DEVICES는 더 이상 권장하지 않는 별칭입니다). 호스트의 범위를 벗어난 ID를 지정하면 프로세스에 보이는 디바이스가 없어집니다.
3. RBLN_NPUS_PER_DEVICE와 RBLN_DEVICE_MAP을 확인합니다. 그룹 크기가 1, 2, 4, 8, 16, 32 이외의 값이거나 ID가 중복되거나 보이는 NPU 범위를 벗어나면 설정 오류입니다. torch.rbln.device_summary()로 매핑 계획을 출력합니다.
4. 컨테이너에서는 RBLN Container Toolkit을 통해 디바이스 노드가 전달되는지 확인합니다.

물리 NPU 사용 중¶

디바이스를 처음 사용할 때 다음 형태의 메시지와 함께 RuntimeError가 발생하는 경우입니다.

rbln_register_device_id failed for rbln:0 on physical NPU(s) [0] (rc=<N>); the device(s) may be in use by another process or hold stale allocations. Free the device(s) or adjust RBLN_DEVICES.

런타임이 디바이스 매핑에 지정된 NPU 중 하나를 확보하지 못한 상태입니다. 공유 호스트에서는 다른 프로세스가 카드를 점유하고 있을 수 있으며 크래시 이후에는 프로세스가 할당을 해제하지 못한 상태일 수 있습니다. 여러 논리 디바이스를 등록하던 중 발생하면 메시지 끝에 이 프로세스가 이미 확보한 디바이스 목록이 표시됩니다. 해당 디바이스는 프로세스가 종료될 때까지 확보된 상태로 유지됩니다.

1. rbln-smi의 프로세스 표에서 NPU별 PID와 할당 메모리를 확인합니다. 점유한 프로세스가 끝날 때까지 기다리거나 종료합니다.
2. RBLN_VISIBLE_DEVICES로 사용 가능한 NPU를 지정하거나 RBLN_NPUS_PER_DEVICE 또는 RBLN_DEVICE_MAP의 그룹 크기를 줄입니다.
3. 카드를 점유한 프로세스가 없는데도 오류가 지속되면 rbln-smi 출력을 포함해 보고해 주시기 바랍니다(문제 보고).

디바이스 메모리 부족¶

메모리를 할당하거나 텐서의 첫 디바이스 연산을 실행할 때 다음 메시지 중 하나와 함께 RuntimeError가 발생하는 경우입니다.

rbln_malloc_lazy failed (rbln:0, <BYTES> bytes); the device may be out of memory or hold stale allocations
rbln_malloc_eager failed (rbln:0, <BYTES> bytes); the device may be out of memory or hold stale allocations

해당 논리 디바이스의 메모리가 소진된 상태입니다. 할당이 지연되므로 메모리를 예약한 torch.empty 호출보다 텐서의 데이터를 실제 디바이스 메모리에 배치하는 첫 디바이스 연산에서 실패하는 경우가 많습니다. 오류가 발생한 줄과 메모리를 할당한 줄이 다를 수 있습니다.

1. 실패하는 단계 전에 torch.rbln.memory_reserved()와 torch.rbln.memory_allocated()를 확인합니다. 두 값의 차이가 크다면 캐시된 메모리가 많다는 뜻이며 torch.rbln.empty_cache()로 이 메모리를 런타임에 반환할 수 있습니다.
2. 컴파일된 프로그램은 자체 디바이스 버퍼를 유지합니다. 입력 shape가 자주 바뀌면 버퍼 수도 늘어나며 torch._dynamo.reset()으로 해제할 수 있습니다. 관련 내용은 재컴파일 한도 초과에서 다룹니다.
3. torch.inference_mode()에서 추론을 실행하면 불필요한 메모리 사용을 줄일 수 있습니다.
4. 다른 프로세스가 카드를 공유하면 해당 프로세스의 할당량도 포함됩니다. rbln-smi의 Memory(used/total) 열에서 전체 사용량을 확인합니다.

코어 덤프 파일 수집¶

RBLN PyTorch 실행 중 프로세스가 크래시하면 생성된 코어 덤프 파일을 문제 보고에 나열된 정보와 함께 client_support@rebellions.ai로 보내 주시기 바랍니다.

1. ulimit 제한을 해제합니다.

   $ ulimit -c unlimited
   

2. 제한이 해제되었는지 확인합니다.

   $ ulimit -c
   unlimited
   

3. 문제가 발생한 스크립트를 다시 실행합니다. 크래시가 발생하면 /var/crash 아래에 코어 덤프 파일이 생성됩니다.

   $ ls /var/crash
   -rw-r----- 1 rebel1    root   779026 Jul  2 17:50 /var/crash/_usr_bin_python3.10.2029.crash
   -rw-r----- 1 rebel2    root 94849351 Jun 25 18:27 /var/crash/_usr_bin_python3.10.2035.crash
   

CPU fallback 로그¶

RBLN PyTorch가 PyTorch 연산자나 특정 dtype을 지원하지 않으면 실행을 계속할 수 있도록 해당 연산을 CPU에서 수행합니다. 이 동작은 모델 호환성을 높이지만 해당 연산은 NPU 가속의 이점을 얻지 못하므로 최적화할 때 이런 연산을 파악하는 것이 도움이 됩니다.

RBLN PyTorch의 기본 로그 레벨은 WARNING이므로 CPU fallback 메시지는 표시되지 않습니다. CPU fallback 연산은 INFO 레벨에서 기록됩니다. CPU에서 실행되는 연산자를 확인하려면 TORCH_RBLN_LOG_LEVEL을 INFO로 설정합니다. 각 레벨은 환경 변수 › 로깅과 진단에 설명되어 있습니다.

$ export TORCH_RBLN_LOG_LEVEL=INFO

기본 설정으로 되돌리려면 다음 명령을 실행합니다.

$ export TORCH_RBLN_LOG_LEVEL=WARNING

이 설정으로 eager mode에서 모델을 실행하면 디바이스 커널이 없는 연산자나 Python dispatch 계층이 CPU로 보내는 연산자가 RBLN NPU 대신 CPU에서 실행될 때 로그를 출력합니다. 로그에는 연산자 이름과, 추적 가능한 경우 소스 코드 위치가 포함됩니다. pre-dispatch 검사(dtype, 모든 입력이 scalar인지 여부, NaN/Inf)에서 결정한 fallback은 로그를 출력하지 않습니다. 이 경우 torch.rbln.explain()이 why: 사유와 함께 보고합니다.

[2026-03-27 00:00:00.000][I] `aten::pow` op ran on CPU instead of RBLN
/transformers/models/llama/modeling_llama.py:72: UserWarning: TRACE
  variance = hidden_states.pow(2).mean(-1, keepdim=True)

자주 발생하는 원인을 빈도순으로 정리했습니다.

로그 대신 구조화된 보고서를 보려면 해당 구간을 torch.rbln.explain()으로 감쌉니다. dispatch/cpu_fallback 블록은 pre-dispatch 검사에서 CPU로 보낸 각 연산자의 횟수와 why: 사유를 표시합니다. with_stack=True이면 호출 위치도 표시합니다. 디바이스 커널이 없거나 CPU에 고정된 연산자는 이 블록에 집계되지 않고 로그에만 나타납니다. 튜토리얼에서 확인할 수 있습니다. 미등록 연산자를 오류로 처리하려면 프로세스를 시작하기 전에 TORCH_RBLN_DISABLE_FALLBACK=unsupported_op를 설정해야 합니다. dtype, scalar, NaN/Inf fallback은 pre-dispatch 검사에 해당하므로 이 변수의 적용 대상이 아닙니다. 환경 변수에서 확인할 수 있습니다.

재컴파일 한도 초과¶

Dynamo 캐시 한도에 도달했다는 경고가 표시되거나 빠르던 구간이 느려지거나 프로세스에서 torch._dynamo.exc.FailOnRecompileLimitHit가 발생하는 경우입니다.

Eager 실행은 Dynamo를 통해 각 연산자를 shape와 dtype별로 컴파일합니다. RBLN PyTorch는 프레임별 캐시 한도를 64로 높이고 한도를 넘으면 Dynamo가 오류를 발생시키도록 설정합니다. 입력 shape가 자주 바뀌는 문제를 감지해 재컴파일이 끝없이 반복되는 것을 방지하기 위해서입니다. 한도에 도달하면 compile wrapper가 Dynamo를 초기화하고 호출을 한 번 재시도합니다. 다시 한도에 도달하면 해당 호출을 CPU에서 실행하며 TORCH_RBLN_DISABLE_FALLBACK에 compile_error가 포함되어 있으면 예외를 발생시킵니다. 다른 Dynamo backend와 마찬가지로 TORCH_LOGS=recompiles는 각 재컴파일의 원인을 출력합니다. RBLN PyTorch는 torch._dynamo.config.specialize_float = True도 설정하므로 호출마다 Python float 인자가 바뀌면 새 프로그램을 생성합니다.

1. TORCH_LOGS=recompiles로 입력 shape가 자주 바뀌는 원인을 찾습니다. 대표적인 원인은 padding 없이 늘어나는 sequence 길이, 데이터에 따라 달라지는 shape, 호출마다 바뀌는 Python float입니다.
2. 입력에 padding을 적용하거나 bucket으로 묶어 고정된 shape 집합을 사용합니다.
3. 필요한 shape의 종류가 실제로 64개를 넘는다면 첫 디바이스 연산 전에 한도를 높입니다.

1
2
3

import torch

torch._dynamo.config.cache_size_limit = 256

느린 첫 호출¶

연산자, 모델 또는 torch.compile 그래프의 첫 실행에는 수초에서 수분이 걸리지만, 이후 호출은 빠른 경우입니다.

멈춘 상태가 아니라 컴파일 중인 것입니다. Eager mode에서 새로운 연산자 shape와 dtype을 처음 사용하거나 torch.compile에서 새 그래프를 처음 사용하면 RBLN Compiler가 이를 컴파일하고 캐시합니다. 확인하려면 첫 호출과 이후 호출을 각각 torch.rbln.explain_steady()로 감쌉니다. 안정 상태 구간에서는 dispatch/recompile 신호가 사라집니다. 첫 호출 시간을 줄이려면 컴파일된 프로그램을 재사용하도록 입력 shape를 고정하고 요청 사이에도 프로세스를 유지합니다. 실행 방식 › 그래프 실행과 입력 shape에서 컴파일, 재실행, 새 shape 처리의 측정 시간을 확인할 수 있습니다.

메모리 통계¶

rbln에 텐서를 생성한 직후 torch.rbln.memory_allocated()와 torch.rbln.memory_stats()가 예상보다 낮은 값을 반환하거나 큰 텐서를 할당한 뒤에도 0을 반환하는 경우입니다.

디바이스 메모리 할당은 지연되므로 예상된 동작입니다. 디바이스 연산이 텐서 데이터를 실제 디바이스 메모리에 배치한 후에야 통계에 반영되며 메모리 API는 디바이스 메모리만 보고합니다. Dynamo에 캐시된 컴파일된 프로그램도 디바이스 메모리를 유지합니다. 자세한 설명과 권장 측정 방법은 실행 방식 › 메모리 통계와 캐싱 할당기에서 확인할 수 있습니다.

CPU 실행과 다른 결과¶

같은 스크립트를 실행해도 rbln의 출력이 CPU 출력과 다르거나 greedy decoding에서 다른 토큰을 선택하는 경우입니다.

CPU의 float16 실행 결과와 원소별로 일치할 것으로 기대해서는 안 됩니다. 디바이스의 16비트 연산은 런타임 자체 계산 형식을 사용하며 이 형식의 가수 비트 수는 IEEE float16보다 적습니다. 자세한 내용은 실행 방식 › 정밀도와 dtype에서 확인할 수 있습니다.

1. CPU에서 float32로 기준 출력을 다시 계산하고 완전 일치 대신 허용 오차를 적용해 비교합니다(torch.testing.assert_close).
2. 디버깅 중에는 TORCH_RBLN_DEPLOY를 설정하지 않습니다. NaN 또는 Inf가 포함된 입력이 CPU로 전달되고 fallback 로그에 나타나도록 하기 위해서입니다.
3. TORCH_RBLN_LOG_LEVEL=INFO로 실행합니다. Fallback한 연산자는 호스트에서 계산하므로 fallback하면 사라지는 차이는 잘못된 결과가 아니라 디바이스 정밀도에 따른 차이입니다.
4. 차이가 크거나 sequence 길이에 따라 커지면 양쪽 출력과 모델 실행에 사용한 dtype을 포함해 보고해 주시기 바랍니다(문제 보고).

문제 보고¶

버그나 예상과 다른 동작은 다음 채널로 알려 주시기 바랍니다. 보고에 확인 목록의 정보를 포함하면 추가 문의 없이 재현할 수 있습니다.

확인 목록:

1. 환경 보고서인 python -m torch_rbln.diagnose 출력. torch-rbln, rebel-compiler 버전과 ABI 판정 결과가 포함됩니다.
2. rbln-smi에서 확인한 드라이버 버전과 설치에 사용한 릴리스 노트의 SDK 릴리스.
3. 입력 shape와 dtype을 고정한 최소 재현 스크립트, 환경 변수(TORCH_RBLN_*, RBLN_*)를 포함한 정확한 명령줄.
4. TORCH_RBLN_LOG_LEVEL=INFO의 전체 로그. 성능 문제라면 torch.rbln.explain() 보고서도 포함해 주시기 바랍니다.
5. 크래시라면 코어 덤프 파일 수집에 따라 수집한 코어 덤프.
6. 결과가 잘못되었다면 CPU에서 float32로 계산한 기준 출력, 실제 출력, 모델 실행에 사용한 dtype.

관련 문서¶

• 설치 › 설치 확인 - 설치 또는 업그레이드 후 실행할 검사
• 환경 변수 - 앞에서 언급한 모든 변수
• 실행 방식 - 앞의 증상과 관련된 dtype 정책, 지연 메모리 할당, fallback 규칙