콘텐츠로 이동

7. 문제 해결

관측되는 증상으로 색인한 실패 목록입니다. 원인을 추론하기 전에, 로그에 찍힌 문자열이나 에러 코드를 그대로 이 페이지에서 검색하십시오.

각 항목은 증상 · 원인 · 조치 세 부분으로 되어 있습니다. 원인을 함께 적은 것은 여기 없는 변형을 만났을 때 스스로 판단할 근거가 되기 때문입니다.

Contents

Section Objective
시작하기 전에 지원을 요청하기 전에 수집할 것
시작 단계 첫 호출이나 새로 만든 스레드에서 실패
메모리 할당이 거부되거나 데이터가 어긋남
VMM KV 캐시 HW 페이지 초기화가 실패하거나 매핑 후 결과가 깨짐
실행 커널을 찾지 못하거나 실행이 실패
행(Hang) 호출이 반환하지 않음

여기 있는 대부분은 2장–5장에서 설명한 성질이 실제 증상으로 나타난 것입니다. 같은 증상이 반복된다면 해당 장을 다시 보는 편이 빠릅니다.

코드 정의는 에러 코드에, 실패를 분류하는 기준은 에러 처리에 있습니다.


시작하기 전에

지원 요청 시 아래를 함께 수집하십시오. 저희가 물어볼 대부분의 질문이 여기서 해결됩니다.

1
2
3
import hart

print("device count :", hart.get_device_count())
1
2
3
python -c "import hart, os; print(os.path.dirname(hart.__file__))"
lsmod | grep ha
ls -l /dev/ha*

시작 단계

첫 호출에서 HaDeviceNotAvailable

증상 — get_device_count()(C++: HaGetDeviceCount())나 첫 디바이스 호출이 HaDeviceNotAvailable로 실패합니다(Python: RuntimeError).

원인 — 프로세스에 보이는 디바이스가 없습니다. KMD가 로드되지 않았거나, 프로세스가 디바이스 노드에 접근할 수 없습니다.

조치

1
2
lsmod | grep ha          # ha.ko가 로드되어 있는가
ls -l /dev/ha*           # 노드가 있고 이 사용자가 열 수 있는가

모듈이 없으면 드라이버 문서를 참고하십시오. 노드는 있는데 사용자가 읽을 수 없다면 런타임 문제가 아니라 권한 문제입니다.

워커 스레드에서만 HaDeviceInvalidArgument

증상 — 메인 스레드에서 호출하면 되는 코드 경로가 스레드 풀 스레드에서 실패합니다.

원인 — 현재 디바이스는 스레드마다 따로 지정합니다. 워커 스레드가 set_device()(C++: HaSetDevice())를 호출한 적이 없습니다.

조치 — 런타임을 사용하는 모든 스레드의 시작 지점에서 hart.set_device(id)를 호출하십시오. 프레임워크나 스레드 풀이 만든 스레드도 포함됩니다. 멀티 디바이스 프로그래밍을 참고하십시오.

런타임을 다시 빌드했는데 반영되지 않음

증상 — runtime을 수정하고 다시 빌드했는데 torch_ha를 통해 실행하면 동작이 그대로입니다.

원인 — torch_ha가 런타임 공유 라이브러리 사본을 자체적으로 번들합니다. runtime만 다시 빌드하면 그 사본이 낡은 채로 남습니다.

조치 — runtime을 변경한 뒤에는 torch_ha도 다시 빌드하십시오.


메모리

디바이스 메모리가 남았는데 HaMemoryAllocationFailed

증상 — 전체 할당량이 디바이스 용량보다 훨씬 작은데도 할당이 실패합니다.

원인 — 대개 고갈이 아니라 단편화입니다. 해제된 블록은 런타임 풀에 남아 크기별로 재사용되므로, 다양한 크기의 할당이 오래 이어지면 충분히 큰 단일 블록이 남지 않을 수 있습니다.

조치 — 크고 오래 쓰는 버퍼는 요청마다가 아니라 시작 시 한 번 할당하십시오. 테스트 루프에 정말로 깨끗한 상태가 필요하면 반복 사이에 디바이스를 리셋하되, 리셋이 핸들을 무효화하므로 모든 포인터와 스트림을 먼저 버리십시오.

HaMemoryAlignmentError 또는 레이아웃 거부

증상 — build_device_tensor_layout()(C++: HaBuildDeviceTensorLayout())이나 mem_cpy_nd()(C++: HaMemCpyNd())가 정렬 또는 잘못된 인자 코드로 실패합니다.

원인 — 레이아웃이 DRAM 정렬 제약을 위반했습니다. 인터리브 종류는 채널당 chunk가 DRAM 워드 크기(Bertha Cloud 64 B, Bertha Edge 32 B)의 정수배여야 합니다. SinglePassInterleaved는 더 엄격합니다. MPUTensor와 KV 캐시 종류는 head_dim이 channels_per_token * elements_per_word로 나누어떨어져야 합니다.

조치 — 사용 중인 HaTensorKind의 제약을 메모리 모델에서 확인하십시오. 하드웨어 요구사항이므로 런타임은 조용히 패딩하지 않고 거부합니다.

HaMemCpyNd()에서 HaMemoryInvalidArgument

원인 — 거의 항상 두 레이아웃의 rank나 shape 불일치입니다. 이 API는 브로드캐스트하지 않습니다.

조치 — 호출 전에 한쪽을 다시 뷰로 만들어 rank와 shape을 맞추십시오. stride 단위가 바이트가 아니라 원소인지도 확인하십시오. 이 실수는 에러가 아니라 잘못된 데이터를 만듭니다.

비동기 복사 후 데이터가 잘못됨

증상 — 결과가 간헐적으로 틀리며, 부하가 높을수록 자주 발생합니다.

원인 — 복사가 끝나기 전에 호스트 버퍼를 수정하거나 읽었습니다. mem_cpy_async()(C++: HaMemCpyAsync())가 반환했다고 복사가 끝난 것은 아닙니다.

조치 — 호스트 버퍼를 건드리기 전에 스트림을 동기화하거나 이벤트를 기록해 기다리십시오. 이 부류의 버그는 부하에 의존적이어서 수백 번 통과하다 한 번 실패할 수 있습니다. 테스트가 통과했다는 것이 동기화가 올바르다는 증거가 되지 않습니다.


VMM

HaVmmInitBlocks()가 HaMemoryAllocationFailed를 반환

증상 — 풀 할당은 성공했는데 HaVmmInitBlocks()가 HaMemoryAllocationFailed로 실패합니다.

원인 — pool_bytes가 요청 1개의 KEY+VALUE 페이지(최대 토큰 수 = max_num_blocks_per_row × block_size 기준)보다 작습니다. 런타임은 풀 크기에서 최대 HW 페이지 수를 역산하는데, 요청 하나도 담을 수 없는 풀은 설정 오류로 보고 거부합니다.

조치 — 풀을 키우거나 max_num_blocks_per_row × block_size(요청당 최대 토큰 수)를 줄이십시오. 풀은 K와 V 절반씩을 모두 담아야 합니다. pool_base가 4 KiB 정렬이 아니면 HaMemoryInvalidArgument가 반환되므로, 풀을 alignment=4096으로 할당하고 segments[0].pa_start를 넘기십시오.

매핑을 바꾼 뒤 커널 결과가 깨짐

증상 — 스텝마다 요청 페이지를 매핑·언매핑하는 서빙 루프에서 어텐션 결과가 간헐적으로 틀리며, 배치가 클수록 자주 발생합니다.

원인 — 이전 스텝의 커널이 아직 실행 중일 때 매핑을 바꿨습니다. 매핑·언매핑은 실행 중인 커널을 기다리지 않으므로, 실행 중인 커널이 바뀐 변환을 읽습니다. 요청 페이지가 매핑된 채로 HaVmmFreePool()을 호출해 물리 메모리가 다른 할당에 재사용된 경우에도 같은 증상이 나타납니다.

조치 — 매핑을 바꾸기 전에 이전 스텝의 스트림을 동기화하거나 이벤트로 완료를 확인하십시오. 풀은 모든 요청을 언매핑한 뒤에만 해제하십시오. 자세한 규칙은 메모리 모델: 규칙에 있습니다.


실행

HaKernelNotFound

원인 — 커널 바이너리 경로가 해석되지 않습니다.

조치 — 프로세스의 작업 디렉토리 기준으로 경로가 존재하는지 확인하십시오. 커널 메타데이터는 디바이스별로 캐싱되므로, 디바이스 0에서 성공적으로 로드된 커널도 디바이스 1에서 처음 쓸 때 다시 로드됩니다.

HaKernelExecutionFailed

원인 — 커널이 실행되어 실패했거나 디바이스가 폴트를 냈습니다. 이 코드만으로는 어느 쪽인지 알 수 없습니다.

조치 — 실행을 그 자리에서 재시도하지 마십시오. 이 에러 이후의 디바이스 상태는 보장되지 않습니다. 같은 입력으로 재현되는지 확인한 뒤, 커널 바이너리와 입력을 함께 보고하십시오.

첫 실행만 유독 느림

원인 — 결함이 아닙니다. 커널 바이너리는 디바이스별로 첫 실행 시 로드되어 캐싱됩니다.

조치 — 측정 전에 워밍업하십시오. 실행 모델의 바이너리 로딩 및 캐싱 메커니즘을 참고하십시오.


행(Hang)

HaStreamSynchronize()에서 멈춤

원인 — 스트림의 작업이 완료될 수 없습니다. 흔한 경우는 기록된 적 없는 이벤트를 기다리는 스트림 간 의존성과, 종료하지 않는 커널입니다.

조치

  1. stream_synchronize()(C++: HaStreamSynchronize())를 stream_query()(C++: HaStreamQuery()) 폴링으로 바꿔 정말 멈춘 것인지 느린 것인지 확인하십시오.
  2. 모든 stream_wait_event()(C++: HaStreamWaitEvent())에 대응하는 event_record()(C++: HaEventRecord())가 있는지 확인하십시오. 기다리기만 하고 기록되지 않은 이벤트는 대기 스트림을 영원히 막습니다.
  3. 로그를 파일로 남기도록 설정하고(에러 처리) 로그를 수집하십시오.

같은 디바이스에서 두 스레드가 데드락

원인 — HA_STREAM_DEFAULT가 스레드 간에 직렬화된다는 가정이 자주 원인입니다. 그렇지 않습니다. 기본 스트림은 스레드별입니다.

조치 — 명시적 스트림을 공유하거나 이벤트로 순서를 지정하십시오. 스트림과 이벤트를 참고하십시오.


지원 요청

위 항목으로 해결되지 않으면 아래를 첨부해 HyperAccel 지원팀에 문의하십시오.

  1. 시작하기 전에의 진단 정보
  2. 런타임 로그(에러 처리: 로깅)
  3. 최소 재현 코드