콘텐츠로 이동

환경 변수

lccl은 환경 변수와 설정 파일 두 개에서 값을 읽습니다. 이 페이지에 없는 LCCL_* 변수는 개발용이라 설정해도 효과가 없거나 예고 없이 바뀝니다.

적용 시점 — 값을 언제 읽는지입니다. *라이브러리 로드*는 import lccl이나 라이브러리를 불러올 때, *프로세스 첫 사용*은 처음 읽은 값이 프로세스가 끝날 때까지 고정된다는 뜻입니다. 이미 읽은 뒤에 환경 변수를 바꿔도 반영되지 않습니다.


우선순위와 설정 파일

값은 아래 중 가장 먼저 정의된 곳에서 결정됩니다.

  1. 환경 변수
  2. ~/.lccl.conf
  3. /etc/lccl.conf
  4. 내장 기본값

설정 파일은 줄마다 NAME=VALUE 형식입니다. 다음을 알아 두십시오.

  • 처음 조회할 때 읽어 프로세스 환경으로 올립니다. 프로세스가 시작된 뒤의 파일 수정은 반영되지 않습니다.
  • 이미 설정된 환경 변수를 덮어쓰지 않습니다.
  • 주석을 지원하지 않고 값의 앞뒤 공백을 지우지 않습니다. 줄 끝의 공백이나 \r도 값에 들어갑니다.
  • ~는 $HOME이 아니라 실행 사용자의 홈 디렉터리(passwd 항목)입니다.
  • 정수 변수에 정수가 아닌 값을 쓰면 오류 없이 기본값으로 돌아갑니다. LCCL_DMABUF_POOL_SIZE_PER_CHANNEL은 예외로, 잘못된 값이면 LPU Direct RDMA를 쓰는 커뮤니케이터 생성이 실패합니다.
  • 파일의 모든 NAME=VALUE가 프로세스 환경 변수가 됩니다. LCCL_ 이외의 이름도 포함되고 자식 프로세스에 상속됩니다. 그래서 getenv로 직접 읽는 LCCL_SHM_PATH도 대개 파일 값을 보지만, HA_LOG_*처럼 라이브러리를 불러올 때 읽는 변수는 파일 값을 보지 못합니다. 이런 변수는 환경 변수로 지정하십시오.

Python 바인딩에는 LcclConfig가 없으므로 Python에서는 환경 변수와 설정 파일이 커뮤니케이터를 설정하는 유일한 길입니다.


토폴로지

변수 타입 기본값 적용 시점 설명
LCCL_PREDEFINED_SYSINFO 경로 없음 커뮤니케이터 생성 하드웨어 배치를 직접 탐색하지 않고 이 JSON 파일에서 읽습니다. 파일이 없거나 일반 파일이 아니면 경고하고 직접 탐색합니다(LCCL_TOPO_STRICT=1이면 실패). 형식은 토폴로지 파일
LCCL_TOPO_STRICT 0 | 1 0 커뮤니케이터 생성 1이면 토폴로지 파일이 없거나 일반 파일이 아닐 때와 파일에 schemaVersion이 없을 때 경고로 넘기지 않고 초기화를 실패시킵니다. 정수만 인정하므로 true나 yes는 켜지지 않습니다
LCCL_TOPO_DUMP_FILE 경로 없음 커뮤니케이터 생성 랭크 0이 직접 탐색한 토폴로지를 이 파일에 XML로 씁니다. 토폴로지 파일을 쓸 때는 쓰지 않습니다
LCCL_IGNORE_CPU_AFFINITY 설정 여부(값 무관) 설정 안 함 커뮤니케이터 생성 상속된 CPU 친화도를 무시하고 LPU에 가까운 CPU 집합을 씁니다. 토폴로지 파일을 쓸 때는 적용되지 않습니다
LCCL_HOSTID 문자열 호스트명 + boot id 커뮤니케이터 생성 어떤 랭크가 같은 서버에 있는지 판정하는 식별자를 덮어씁니다

LCCL_HOSTID는 컨테이너에서 중요합니다. 같은 식별자를 보고하는 랭크는 한 서버에 있는 것으로 취급되어 공유 메모리로 연결됩니다. 기본 식별자는 호스트명에 부팅마다 달라지는 boot id를 붙인 값입니다. 기본 네트워크의 컨테이너나 쿠버네티스 파드는 호스트명이 각자 달라 이미 서로 다른 서버로 분류됩니다. 하지만 호스트 네트워크(호스트 UTS)로 한 서버에 띄운 컨테이너들은 호스트명과 boot id가 같아 한 서버로 분류되는데, 공유 메모리는 두 랭크가 같은 /dev/shm을 볼 때만 쓸 수 있습니다. /dev/shm이 컨테이너마다 따로 있으면 LCCL이 컨테이너마다 서로 다른 서버로 취급해 네트워크 전송으로 연결합니다.

채널과 버퍼

변수 타입 기본값 적용 시점 설명
LCCL_MIN_NCHANNELS 정수 미설정(0) 커뮤니케이터 생성 채널 수의 하한. LPU에서 랭크가 2개 이상이면 1보다 큰 값은 경고와 함께 무시됩니다
LCCL_MAX_NCHANNELS 정수 1 커뮤니케이터 생성 채널 수의 상한. 1보다 작으면 경고와 함께 무시하고 기본값을 씁니다. LPU에서 랭크가 2개 이상이면 1보다 큰 값은 경고와 함께 무시됩니다
LCCL_MIN_CHANNELS 정수 1 커뮤니케이터 생성 LcclConfig의 min_num_chnl을 덮어씁니다
LCCL_MAX_CHANNELS 정수 8 커뮤니케이터 생성 LcclConfig의 max_num_chnl을 덮어씁니다
LCCL_BUFFSIZE 바이트 4 MiB(4194304) 커뮤니케이터 생성 Simple 프로토콜이 쓰는 전송 버퍼의 크기. 64의 배수여야 하고 기본값보다 키울 수는 없습니다(줄이기만 가능). 이 두 조건을 어기면 경고하고 기본값을 씁니다. LPU에서 랭크가 2개 이상이면 4096의 배수여야 하며, 어기면 모든 집합 연산과 LcclSend/LcclRecv가 kLcclNotSupported를 반환합니다. 모든 랭크가 같은 값이어야 합니다
LCCL_CHUNK_SIZE 바이트 0(미설정) 연산 제출 점대점 전송(LcclSend/LcclRecv, LcclAllToAll)의 청크 크기. 집합 연산에는 적용되지 않습니다. 지정할 때는 512의 배수이면서 LCCL_BUFFSIZE의 ⅛(기본 512 KiB) 이하인 값을 모든 랭크에 같게 지정하십시오. 그 밖의 값을 주면 점대점 전송이 kLcclKernelInvalidArgs로 실패할 수 있고, 이 실패 뒤에는 그 커뮤니케이터를 쓸 수 없습니다

LPU에서 랭크가 2개 이상인 커뮤니케이터는 이 변수들과 관계없이 채널 1개를 씁니다. 1보다 큰 값을 주면 communicator of N ranks on hw uses 1 channel 경고를 남깁니다.

알고리즘과 프로토콜

변수 타입 기본값 적용 시점 설명
LCCL_PROTO 이름 목록 Simple 커뮤니케이터 생성 허용할 프로토콜. LL, Simple을 쉼표로 나열하고, 앞에 ^를 붙이면 나열한 것을 제외합니다. 대소문자를 구분하지 않습니다. 빈 값은 미설정으로 봅니다. 알 수 없는 이름은 오류 없이 무시됩니다
LCCL_ALGO 이름 목록 Ring 커뮤니케이터 생성 허용할 알고리즘. Ring뿐이라 바꿀 일이 없습니다. 형식은 LCCL_PROTO와 같습니다

지정할 때 조심하십시오. 허용 목록이 비면(이름을 잘못 썼거나, LL 커널이 없는 LPU에서 LCCL_PROTO=LL만 지정한 경우) 모든 집합 연산이 kLcclEnqueueNoAlgo로 실패합니다. NCCL의 tree나 LL128 같은 값은 이 라이브러리에 없습니다. 근거와 범위는 지원 매트릭스를 보십시오.

전송 계층

P2P와 공유 메모리

변수 타입 기본값 적용 시점 설명
LCCL_P2P_DISABLE 0 | 1 0 커뮤니케이터 생성 1이면 P2P 전송을 쓰지 않습니다
LCCL_P2P_LEVEL LOC | PIX | PXB | PHB | SYS 자동 커뮤니케이터 생성 P2P를 허용할 최대 인터커넥트 거리. 예전 방식의 숫자(0~)도 받습니다. 자동일 때는 Intel·Zhaoxin x86과 ARM 호스트에서 PXB, 그 밖에는 SYS입니다
LCCL_IGNORE_DISABLED_P2P 0 | 1 0 커뮤니케이터 생성 드라이버가 P2P를 허용하지 않는 LPU 쌍마다 남기는 INFO 메시지(P2P is disabled between connected LPUs)를 숨깁니다. 이 변수와 관계없이 그 쌍의 P2P는 꺼집니다
LCCL_SHM_PATH 경로 /dev/shm 통신 연결을 만들 때 공유 메모리 파일을 만드는 디렉터리. 한 서버의 모든 랭크가 같은 값이어야 합니다

P2P는 같은 프로세스 안의 랭크끼리만 쓸 수 있습니다. 랭크마다 프로세스를 따로 쓰는 일반적인 구성(torchrun, multiprocessing)에서는 P2P 전송이 선택되지 않고 공유 메모리로 넘어갑니다. LCCL_P2P_DISABLE과 LCCL_P2P_LEVEL은 P2P를 쓰지 않는 이 구성에서도 통신 경로를 정하는 데 영향을 줄 수 있으므로, 바꿨다면 결과를 확인하십시오.

공유 메모리는 LCCL_SHM_PATH 아래 lccl-XXXXXX 파일로 만들어집니다. 같은 서버의 랭크를 서로 다른 프로세스로 실행하면 랭크 사이 통신에 이 공유 메모리를 쓰고, 서버당 필요한 용량은 그 서버의 랭크 수의 제곱에 비례해 늘어납니다. 기본 LCCL_BUFFSIZE에서 랭크 2개는 약 22 MiB, 4개는 약 80 MiB, 8개는 약 300 MiB가 필요합니다. 컨테이너의 기본 /dev/shm(64 MiB)에는 랭크 3개까지만 들어가므로, 그보다 많으면 --shm-size를 늘리거나 더 큰 파일시스템으로 LCCL_SHM_PATH를 돌리십시오. 공간이나 권한이 모자라면 kLcclMemShmMapFail이 납니다.

네트워크

변수 타입 기본값 적용 시점 설명
LCCL_SOCKET_IFNAME 이름 목록 자동 프로세스 첫 사용 부트스트랩과 소켓·ibverbs 연결에 쓸 네트워크 인터페이스. eth(접두사), =eth0(정확히 일치), ^docker,lo(제외). 지정하면 자동 선택으로 돌아가지 않습니다
LCCL_SOCKET_FAMILY AF_INET | AF_INET6 자동 프로세스 첫 사용 후보 인터페이스를 IPv4 또는 IPv6 주소를 가진 것으로 거릅니다. 서버에 없는 종류를 지정하면 매칭되는 인터페이스가 없어 kLcclBootstrapNoNetIf가 납니다. 다른 값은 무시됩니다
LCCL_NET IB | Socket 자동 커뮤니케이터 생성 네트워크 백엔드를 고정합니다. 대소문자를 구분하지 않습니다. 해당 백엔드를 쓸 수 없으면 kLcclInvalidArgument로 실패합니다

LCCL_SOCKET_IFNAME을 지정하지 않으면 ib*, docker와 lo가 아닌 것, docker*, lo 순으로 처음 매칭되는 인터페이스를 고릅니다. 루프백은 마지막 수단입니다. 지정한 이름에 매칭되는 인터페이스가 없으면 경고를 남기고 인터페이스를 찾지 못한 것으로 처리하며(kLcclBootstrapNoNetIf), 다른 인터페이스로 대신하지 않습니다. 이 선택은 프로세스에서 한 번 하고 고정됩니다.

네트워크 백엔드는 ibverbs(IB)를 먼저 시도하고, 쓸 수 없으면 소켓(Socket)을 씁니다. 런타임에 libibverbs가 없거나 RDMA 장치가 없으면 조용히 소켓으로 넘어갑니다.

ibverbs(InfiniBand, RoCE)

NCCL에서 가져온 변수들로, 같은 이름의 NCCL_IB_*와 같은 의미입니다. 프로세스에서 처음 읽을 때 값이 고정됩니다. 확인한 구성은 지원 매트릭스를 보십시오.

변수 기본값 설명
LCCL_IB_DISABLE 0 1이면 ibverbs를 쓰지 않고 소켓을 씁니다
LCCL_IB_HCA 전부 사용할 장치와 포트를 쉼표로 나열합니다(mlx5_0:1,mlx5_1). 앞에 =이면 정확히 일치, ^이면 제외합니다. 연결 양 끝의 포트 종류(InfiniBand, RoCE)가 다르면 커뮤니케이터 생성이 실패하므로, 두 종류가 함께 있으면 모든 서버에서 같은 종류만 고르십시오
LCCL_IB_GID_INDEX -1(자동) RoCE에서 쓸 GID 인덱스
LCCL_IB_ROCE_VERSION_NUM 2 자동 선택 때 선호하는 RoCE 버전
LCCL_IB_ADDR_FAMILY AF_INET 자동 GID 선택 때 선호하는 주소 패밀리(AF_INET/AF_INET6). IPv6 주소만 있는 RoCE 네트워크에서는 AF_INET6으로 지정하십시오
LCCL_IB_ADDR_RANGE 미설정 자동 GID 선택 때 선호하는 주소 범위(예: 10.0.0.0/16). LCCL_IB_ADDR_FAMILY와 같은 패밀리의 주소로 지정하십시오
LCCL_IB_TIMEOUT 20 QP 전송 타임아웃 지수
LCCL_IB_RETRY_CNT 7 QP 재시도 횟수
LCCL_IB_SL, LCCL_IB_TC, LCCL_IB_FIFO_TC -1(미설정) service level, traffic class, 제어 FIFO의 traffic class
LCCL_IB_QPS_PER_CONNECTION 1 연결당 QP 수. 모든 랭크가 같은 값이어야 하며, 다르면 커뮤니케이터 생성이 실패합니다
LCCL_IB_SPLIT_DATA_ON_QPS 0 1이면 데이터를 QP에 나눠 보냅니다

그 밖의 튜닝 변수는 기본값과 함께 적습니다. 필요하지 않다면 건드리지 마십시오: LCCL_IB_PKEY(0), LCCL_IB_USE_INLINE(0), LCCL_IB_PCI_RELAXED_ORDERING(2, 자동), LCCL_IB_ADAPTIVE_ROUTING(-2, 미설정), LCCL_IB_AR_THRESHOLD(8192), LCCL_IB_MERGE_VFS(1), LCCL_IB_ECE_ENABLE(1), LCCL_IB_ROUTABLE_FLID_GID_INDEX(1), LCCL_IB_MQP_RETRY_ALL(0), LCCL_IB_MQP_RETRY_CNT(34), LCCL_IB_MQP_RETRY_SLEEP_MSEC(100).

아래 변수는 LPU Direct RDMA를 조절합니다. 쓰이는 조건은 다중 노드 실행을 보십시오.

변수 기본값 설명
LCCL_NET_RDMA_LEVEL PXB LPU Direct RDMA를 쓸 LPU와 RNIC 사이 PCIe 경로의 최대 거리. LOC, PIX, PXB, PHB, SYS 중 하나이고, LOC이면 쓰지 않습니다
LCCL_NET_RDMA_READ 미설정 0이면 송신 쪽에서 LPU Direct RDMA를 쓰지 않습니다
LCCL_GDR_FLUSH_DISABLE 0 0이 아니면 수신 쪽에서 LPU Direct RDMA를 쓰지 않습니다
LCCL_NET_FORCE_FLUSH 1 0이면 수신 쪽에서 LPU Direct RDMA를 쓰지 않습니다. NCCL의 NCCL_NET_FORCE_FLUSH=0과 뜻이 다르므로 그 설정을 옮겨 오지 마십시오
LCCL_DMABUF_POOL_SIZE_PER_CHANNEL 64 MiB(67108864) LPU Direct RDMA에 쓰는 버퍼의 DRAM 채널당 크기(바이트). 4096의 배수이고 64 MiB 이하인 양수여야 하며, 어기면 기본값으로 돌아가지 않고 LPU Direct RDMA를 쓸 때 커뮤니케이터 생성이 kLcclInvalidArgument로 실패합니다

프로세스가 한 LPU에서 LPU Direct RDMA 연결을 처음 만들 때 그 LPU에 (LCCL_DMABUF_POOL_SIZE_PER_CHANNEL + 64 MiB) × DRAM 채널 수의 LPU 메모리(기본값이면 1 GiB)를 할당해 프로세스가 끝날 때까지 유지하고, 연결마다 여기서 LCCL_BUFFSIZE만큼 씁니다. 이 메모리를 할당하지 못하거나 남은 자리가 없어 커뮤니케이터 생성이 kLcclMemDeviceAllocFail로 실패하면, 쓰지 않는 커뮤니케이터를 파괴하거나 LCCL_NET_RDMA_LEVEL=LOC로 LPU Direct RDMA를 끄십시오.

실행

변수 타입 기본값 적용 시점 설명
LCCL_BLOCKING 0 | 1 1 커뮤니케이터 생성 0이면 커뮤니케이터 생성, LcclCommFinalize, 연결이 필요한 그룹의 제출이 kLcclInProgress로 먼저 돌아올 수 있고, 완료는 LcclCommGetAsyncError로 확인합니다. LcclCommDestroy와 LcclCommAbort는 그룹 밖에서는 호출 안에서 끝납니다. 0과 1 외의 값은 무시되며, 설정하면 LcclConfig의 blocking을 덮어씁니다
LCCL_KERNEL_TIMEOUT_MS 밀리초 5000 커널 실행 커널 하나가 끝나길 기다리는 최대 시간. LPU에서는 장치 커널 실행 한 번마다 적용되고, 호출 스레드의 기본 스트림에 먼저 큐잉된 작업을 기다린 시간과 다른 랭크가 연산에 늦게 들어온 시간도 들어갑니다. 넘으면 커뮤니케이터를 중단시키고 kLcclKernelSpinTimeout을 반환합니다. 0 이하이면 워치독을 끕니다
LCCL_DEVICE_LOOP_LAUNCH_BYTES 바이트 256 MiB(268435456) 연산 호출 LPU에서 LcclAllReduce, LcclReduceScatter, LcclSend/LcclRecv(LcclAllToAll 포함)의 장치 커널 실행 한 번이 처리하는 최대 바이트 수. 이보다 큰 호출은 여러 번 나눠 실행합니다. 실행 한 번이 LCCL_KERNEL_TIMEOUT_MS 안에 끝나도록 정한 값입니다. 다른 연산은 나누지 않습니다
LCCL_LOCAL_REGISTER 0 | 1 1 등록 호출 0이면 LcclCommRegister가 아무것도 하지 않고 성공을 반환합니다. 번들된 네트워크 백엔드에서는 1이어도 등록이 효과를 갖지 않습니다
HA_TOOLCHAIN 0 | 1 설정 안 함 커널 실행 런타임과 공유하는 변수이며, LPU에서는 1(Legato)로 설정하십시오. 설정하지 않으면 경고를 한 번 남기고 1로 동작하며, 0이면 점대점 연산과 랭크가 2개 이상인 커뮤니케이터의 집합 연산이 실패합니다

LCCL_BLOCKING=0은 LcclCommGetAsyncError로 완료를 확인해야 하는 모드입니다. Python에는 비동기 오류를 조회하는 함수가 없으므로 Python에서는 0으로 바꾸지 마십시오.

LCCL_KERNEL_TIMEOUT_MS는 집합 연산이 서로 다른 인자로 호출되었거나 상대 랭크가 오지 않을 때 영원히 기다리지 않게 하는 안전장치입니다. 시간이 지나면 중단된 커뮤니케이터는 복구되지 않으므로 파괴하고 다시 만들어야 합니다. 느린 환경에서 정상 연산이 끊긴다면 이 값을 늘리십시오. LPU에서는 1~9999 안에서 정하십시오. 그 밖의 값이면 경고를 남기고, 멈춘 커널이 드라이버의 12초 한도에 걸려 카드를 리셋해야 할 수 있습니다.

진단

변수 타입 기본값 적용 시점 설명
HA_LOG_LEVEL 0~6 2(Info). 릴리즈 빌드는 3(Warn) 라이브러리 로드 로그 레벨. 릴리즈 빌드는 Warn 미만을 Warn으로 올려 처리하도록 되어 있어 보통 낮춰도 적용되지 않습니다
HA_LOG_OUTPUT_MODE 0 | 1 0(콘솔) 프로세스 첫 사용 1이면 로그를 HA_LOG_PATH 파일에 씁니다
HA_LOG_PATH 경로 ha_runtime.log 라이브러리 로드 로그 파일 경로. HA_LOG_OUTPUT_MODE=1일 때 적용됩니다

HA_LOG_*는 런타임과 공유하는 변수입니다. 자세한 값과 릴리즈 빌드의 제약은 런타임 환경 변수의 로깅을 보십시오. 릴리즈 빌드에서는 INFO 이하 로그가 나오지 않으므로, 문제 해결의 진단 절차는 INFO 로그 없이도 따라갈 수 있게 썼습니다.


환경 변수로 제어하지 않는 것

설정 지정 방법
현재 디바이스 커뮤니케이터를 만들기 전에 호출 스레드에서 HaSetDevice()(Python은 hart.set_device())
로그를 코드에서 지정 halogger.set_level() / set_file(), C++은 진단의 환경 변수. 런타임은 처음 호출될 때 HA_LOG_* 환경 변수에 따라 로그 설정을 다시 정하므로 halogger 함수는 hart.set_device() 다음에 호출하십시오

NCCL_* 변수는 읽지 않습니다

설정해도 아무 효과가 없고 경고도 나오지 않습니다. 대응 변수는 대부분 접두사만 LCCL_로 바뀌어 있습니다.


함께 보기