콘텐츠로 이동

Python API

1
import lccl

의미는 C++ API와 동일하며, 다른 부분만 C++ API와의 차이에 정리했습니다.

먼저 알아 둘 것

  • import lccl은 같은 Python 환경에 설치된 hart를 찾아 씁니다. hart를 PYTHONPATH 등으로 다른 디렉터리에 두었다면 import hart를 먼저 하십시오.
  • 독립 lccl 패키지는 LPU용 하드웨어 빌드(+hw)로 배포됩니다. torch_ha에도 LCCL이 들어 있어 torch.distributed로 쓸 수 있습니다. 지원 매트릭스를 보십시오.
  • 한 프로세스에서 lccl과 torch_ha를 함께 쓰려면 같은 릴리즈의 hart, lccl, torch_ha를 설치하십시오. lccl과 torch_ha가 같은 이름의 라이브러리(libha_lccl.so)를 따로 싣고 있어 먼저 불러온 쪽을 함께 씁니다.

커뮤니케이터

함수 시그니처 비고
get_unique_id () -> LcclUniqueId 한 랭크에서만 호출하고 결과를 대역 외로 배포. 이 프로세스는 모든 랭크가 접속할 때까지 살아 있어야 함
comm_init_rank (nranks: int, comm_id: LcclUniqueId, myrank: int) -> LcclComm nranks개 랭크가 모두 참여할 때까지 블로킹. 먼저 hart.set_device()
comm_init_all (ndev: int, devlist: list[int]) -> list[LcclComm] 단일 프로세스, 단일 노드. 호출 전에 스레드에 디바이스를 바인딩해야 함. devlist는 list이고 길이가 ndev와 같으며 중복이나 범위 밖 값이 없어야 함. 예외가 나면 그 프로세스에서는 lccl을 더 쓰지 말고 새 프로세스에서 다시 시작
comm_destroy (comm: LcclComm) -> None 자원을 해제. 가비지 컬렉터가 대신 하지 않으므로 반드시 호출
bootstrap_is_root_alive () -> int 이 프로세스가 만든 고유 ID에 랭크들이 아직 접속하는 중인지(1이면 기다리는 중). 프로세스 전체에서 값 하나이며, 모든 랭크가 접속하면 0이 됨

그룹

함수 시그니처 비고
group_start () -> None 중첩 가능. 깊이는 스레드별
group_end () -> None 가장 바깥 구간이 닫힐 때 실행

집합 연산

함수 시그니처
all_reduce (send_buff, recv_buff, count: int, datatype: LcclDataType, op: LcclRedOp, comm: LcclComm, stream: int = 0) -> None
reduce (send_buff, recv_buff, count, datatype, op, root: int, comm) -> None
reduce_scatter (send_buff, recv_buff, recv_count, datatype, op, comm) -> None
broadcast (send_buff, recv_buff, count, datatype, root: int, comm) -> None
all_gather (send_buff, recv_buff, send_count, datatype, comm) -> None
gather (send_buff, recv_buff, count, datatype, root: int, comm) -> None
scatter (send_buff, recv_buff, count, datatype, root: int, comm) -> None
all_to_all (send_buff, recv_buff, count, datatype, comm) -> None

수신 버퍼 크기는 연산마다 다릅니다. 집합 연산을 보십시오. LPU에서 실행되는 연산은 지원 매트릭스에 있습니다.

버퍼 인자

send_buff와 recv_buff는 hart.mem_alloc()이 돌려준 디바이스 주소(정수)를 받습니다. __index__로 정수가 되는 객체(NumPy·PyTorch 정수 스칼라)도 똑같이 처리합니다. 크기를 검사하지 않고 count를 믿습니다. bool은 거부합니다.

루트가 아닌 랭크에서 쓰지 않는 버퍼에도 값을 줘야 합니다. None은 안 되고 정수 0을 주십시오.

점대점

함수 시그니처 비고
send (send_buff, count, datatype, peer: int, comm) -> None 대응하는 recv와 그룹 안에서 짝지을 것
recv (recv_buff, count, datatype, peer: int, comm) -> None

두 랭크가 서로 교환하려면 양쪽에서 같은 그룹 안에 둘 다 두어야 교착되지 않습니다. 점대점을 보십시오.

1
2
3
4
5
6
lccl.group_start()
try:
    lccl.send(send_buf, count, dt, peer, comm)
    lccl.recv(recv_buf, count, dt, peer, comm)
finally:
    lccl.group_end()

타입

LcclComm

커뮤니케이터를 설명하는 읽기 전용 속성입니다. 진단에 유용합니다.

속성 의미
rank, n_ranks 이 랭크의 인덱스와 커뮤니케이터 크기
ha_dev 이 커뮤니케이터가 구동하는 디바이스
bus_id 그 디바이스의 버스 식별자
node, n_nodes 이 서버의 인덱스와 서버 수
local_rank, local_ranks 서버 안의 랭크 인덱스와 이 서버의 랭크 수
n_channels 이 커뮤니케이터가 만든 채널 수

n_nodes는 랭크가 몇 대의 서버에 퍼졌다고 LCCL이 판단했는지를, n_channels는 실제로 만들어진 채널 수를 보여 줍니다. 릴리즈 빌드에서는 INFO 로그로 이 정보를 얻을 수 없으니 이 속성으로 확인하십시오. 환경 변수를 보십시오.

LcclUniqueId

구성 의미
LcclUniqueId() 빈 핸들. get_unique_id()가 채워서 돌려주는 것을 쓰십시오
LcclUniqueId(data: bytes) internal 값으로 핸들을 재구성합니다. 정확히 128바이트여야 하며 아니면 ValueError
internal 읽기 전용. 원시 128바이트 핸들, bytes

다른 랭크에 배포하는 것이 bytes(unique_id.internal)이고, 수신측에서 LcclUniqueId(data)로 되살립니다. 핸들 객체 자체는 pickle할 수 없습니다.

LcclDataType

LcclInt8 / LcclChar, LcclUint8, LcclInt32 / LcclInt, LcclUint32, LcclInt64, LcclUint64, LcclFloat16 / LcclHalf, LcclFloat32 / LcclFloat, LcclFloat64 / LcclDouble, LcclBfloat16.

짝지어진 이름들은 값이 같은 별칭이며 NCCL 열거형과 일치합니다.

LcclRedOp

LcclSum, LcclProd, LcclMax, LcclMin, LcclAvg.

열거형이 구현보다 넓습니다

LcclMax, LcclMin은 어떤 연산에도 커널이 없어 RuntimeError(kLcclNotSupported)를 발생시킵니다. LcclProd와 LcclAvg는 all_reduce와 reduce에서만 동작합니다. 지원 매트릭스를 보십시오.


C++ API와의 차이

C++ Python
실패 보고 LcclResult 반환 RuntimeError. 메시지는 <함수 이름> failed: <메시지>
잘못된 고유 ID 길이 — ValueError
버퍼 void * 디바이스 포인터 정수(디바이스 주소)
스트림 대부분 HaStream_t를 받음 all_reduce만 stream 키워드(정수 핸들, 기본 0). 나머지는 기본 스트림
커뮤니케이터 조회 LcclCommCount(), LcclCommUserRank(), LcclCommHaDevice() LcclComm의 속성
LcclCommInitRankConfig, LcclCommFinalize, LcclCommAbort 있음 노출되지 않음
LcclCommGetAsyncError 있음 노출되지 않음
LcclCommRegister, LcclCommDeregister 있음 노출되지 않음
LcclConfig 있음 없음. 환경 변수와 설정 파일이 유일한 설정 경로
LcclResult 값 열거형 노출되지 않음. 예외 메시지에 문장으로만 담김
문자열 헬퍼 LcclGetErrorToString() 등 노출되지 않음
GIL — 블로킹 호출이 GIL을 놓지 않음

Python에서는 비동기 에러를 확인할 수 없습니다

LcclCommGetAsyncError()에 Python 바인딩이 없습니다. 논블로킹 모드(LCCL_BLOCKING=0)를 쓰면 kLcclInProgress를 반환하는 호출이 예외로 바뀌므로 Python에서는 기본 블로킹 모드만 쓰십시오. kLcclKernelAborted가 반환됐을 때의 원인 코드도 읽을 수 없습니다. 배포에서 이것이 중요하다면 C++에서 라이브러리를 구동하십시오.

GIL을 놓지 않으므로 스레드로 랭크를 나누면 교착됩니다

집합 연산과 comm_init_rank는 상대 랭크를 기다리며 블로킹되는데, 그동안 GIL을 놓지 않아 같은 프로세스의 다른 Python 스레드가 멈춥니다. 한 프로세스 안에서 스레드마다 랭크를 맡기면 교착됩니다. 랭크마다 프로세스를 따로 두십시오.

디바이스 선택

커뮤니케이터는 생성 시점에 호출 스레드에 바인딩된 디바이스에 묶입니다. 생성 전에 설정하십시오. 빠뜨리면 LcclCommInitRank failed: Communicator unknown or unclassified error입니다.

1
2
3
import hart
hart.set_device(rank_local_device)
comm = lccl.comm_init_rank(nranks, unique_id, rank)

현재 디바이스는 스레드 로컬입니다. hart를 보십시오. 커뮤니케이터를 만든 스레드가 아닌 스레드에서 연산이나 comm_destroy()를 부를 때는 그 스레드에서도 먼저 hart.set_device()로 같은 디바이스를 고르십시오. 런타임을 초기화한 프로세스를 fork하면 자식이 안전하지 않으므로 랭크 프로세스는 spawn으로 띄우십시오.