Legato로 PyTorch 모델 컴파일하기¶
이 페이지는 torch.compile(..., backend="legato")로 Legato를 PyTorch 모델과 연동하는 방법을 설명합니다.
사용자 정의 Legato primitive를 등록하는 방법과,
그래프가 전부 컴파일 가능할 때와 일부만 컴파일 가능할 때 백엔드가 어떻게 동작하는지를 다룹니다.
이 방식 대신, 직접 작성한 Legato 커널에 디바이스 텐서를 넘겨 바로 호출하려면
PyTorch 연동을 참고하십시오.
준비 사항¶
legato, torch_legato, PyTorch 2.10.0이 있는 SDK 환경을 사용하십시오.
별도 패키지인 torch_legato가 "legato" TorchDynamo 백엔드를 제공합니다.
legato만 설치해서는 이 백엔드가 등록되지 않습니다.
LPU에서 실행하려면 hart, torch_ha와 대상에 맞는 디바이스·런타임 설정도 필요합니다.
PyTorch 연동을 참고하십시오.
아래 컴파일 전용 예제는 CPU 입력과 legato.session.launch=False를 사용합니다.
Primitive 함수 작성하기¶
resolver(연산의 인자를 받아 사용할 primitive를 골라 주는 함수)는
PyTorch 연산을 구현하는 @legato.primitive(...)의 JitFunction을 반환합니다.
연산의 인자는 primitive의 파라미터가 되고, primitive는 연산의 결과를 반환합니다.
언어 문법은 데코레이터와 세션을 참고하십시오.
현재 프론트엔드는 입력 load를 삽입하고 token 행을 여러 코어에 나눕니다. primitive 시그니처는 **load 이후의 레이아웃, 코어별 tile 용량, placement**와 맞아야 합니다. 고정 shape의 단일 코어 primitive를 core-split resolver 대신 그대로 쓸 수는 없습니다. 새 resolver를 구현할 때는 백엔드의 primitive builder를 재사용하거나 조정하십시오.
기본 matmul resolver는 BF16을 지원하며,
"mpu_dram" 또는 "transposed_mpu_dram"에서 "mpu_weight"로 load한
복제 RHS를 기대합니다. 이 resolver는 row-major SRAM RHS를 지원하지 않습니다.
호스트 레이아웃 이름은 종류 선택과
Bertha 레이아웃을 참고하십시오.
Resolver 등록하기¶
legato.registry.register(op=...)에는 호환되는 primitive를 직접 넘기거나,
현재 입력 메타데이터에서 primitive를 선택하는 resolver를 넘길 수 있습니다.
아래 예제는 현재 matmul builder에 위임해 레이아웃과 core-split 검사를 유지합니다.
custom resolver는 자신이 지원하는 입력에 맞는 다른 primitive를 선택할 수 있습니다.
기본 resolver 라이브러리를 먼저 불러온 뒤 override를 등록하십시오. 레지스트리는 마지막 등록을 사용하므로, 첫 사용 시의 자동 검색이 앞서 등록한 override를 덮어쓸 수 있습니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
Resolver 동작과 fallback¶
Legato는 이제 노드가 컴파일 경로에 남을 수 있는지 판단하기 전에 resolver 결과를 먼저 확인합니다.
- resolver가 있고 primitive
JitFunction을 반환하면 노드는 컴파일 가능한 상태로 남습니다. - resolver가 없으면 노드는 extern fallback(컴파일하지 않고 eager로 실행) 후보가 될 수 있습니다.
- resolver가 현재의 dtype/shape 조합에서
AssertionError를 발생시키는 경우에도 노드는 extern fallback 후보가 될 수 있습니다. - resolver가 유효하지 않은 객체를 반환하거나 예상치 못한 예외를 발생시키면, Legato는 조용히 fallback으로 넘기지 않고 그대로 에러로 처리합니다.
즉 혼합 실행이 켜져 있으면, resolver가 없다고 해서 이제는 컴파일이 항상 곧바로 실패하지는 않습니다.
지원되지 않는 call_function 노드는 eager extern 실행으로 넘기고,
컴파일 가능한 영역은 그대로 Legato로 lowering할 수 있습니다.
컴파일러에 함수 노출하기¶
모듈을 import하지 않으면 Legato는 primitive 함수를 인식하지 못합니다. primitive 함수를 구현해 둔 모듈을 import하는 방법은 세 가지입니다.
-
모듈을 직접 import합니다.
1 2
# model.py import my.lib -
load_library함수를 씁니다.1 2 3 4
# model.py import legato.registry legato.registry.load_library("my.lib") -
entrypoint를 씁니다.
pyproject.toml에torch_legato_libraryentrypoint를 추가하십시오.1 2 3 4 5
[project] # 프로젝트 설정... [project.entry-points.torch_legato_library] my_lib = "my.lib"
모델 컴파일하기¶
torch.compile에 backend="legato"를 지정하면 모델을 컴파일할 수 있습니다.
shape이 정적인 모델에는 dynamic=False를 넘기고,
동적 차원을 허용하려면 동적 shape 입력을 참고하십시오.
torch.nn.Module 사용¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | |
함수 사용¶
1 2 3 4 5 6 7 8 9 10 11 12 | |
실행 모델¶
모든 그래프는 LegatoGraphWrapper를 거치며, 이 wrapper는 다음과 같은 통일된 실행 모델을 제공합니다.
call_function노드를 컴파일 노드(Legato primitive)와 extern 노드(eager fallback)로 분류합니다.- 연속된 컴파일 노드를 segment(구간)로 묶습니다.
- 각 segment를 Legato 커널로 컴파일합니다.
- 지원되지 않는 노드는 extern 호출로 처리하여 eager로 실행합니다.
- 컴파일 경로와 extern 경로를 함께 조율하는 callable 하나를 반환합니다.
전부 컴파일 가능한 그래프(모든 노드가 Legato primitive로 lowering됨)에서는 wrapper가 segment 하나를 만듭니다. 혼합 그래프(일부 노드에 eager fallback이 필요함)에서는 여러 컴파일 segment와 extern 호출이 번갈아 이어지도록 구성합니다.
따라서 실제로는 사용자 정의 연산이나 지원되지 않는 ATen 연산이 들어 있는 모델도, 해당 노드를 eager로 실행할 수 있기만 하면 곧바로 실패하지 않습니다.
Note
현재의 혼합 실행 지원은 의도적으로 보수적입니다.
segment 경계의 값은 텐서류(tensor-like) 값이어야 하며, 구현은 call_function fallback에 초점을 맞추고 있습니다.
디바이스 없이 컴파일하기¶
이 완전한 예제는 CPU 입력으로 기본 add 경로를 바이너리까지 lowering합니다.
launch=False는 바이너리를 실행하지 않고 컴파일러만 실행합니다.
반환된 출력 버퍼에는 계산 결과가 없으므로, 수치 정확성이 아니라 artifact를 검사합니다.
디바이스 실행에는 초기화한 LPU 텐서와 스트림 동기화가 필요합니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | |
옵션¶
legato.device¶
타입: str
컴파일할 타겟 디바이스의 이름입니다. 필수 옵션입니다.
예:
1 2 3 4 5 6 | |
legato.session.output_type / legato.session.output_path¶
타입: legato.OutputType / str
컴파일러 artifact와 그 저장 위치를 선택합니다.
각각 legato.session(...)의 output_type, output_path 인자에 대응합니다
(컴파일러 세션 참고).
둘 다 기본값은 None입니다.
torch.compile이 적용된 코드 안에서는 legato.session(...)을 열 수 없으므로,
백엔드가 내부에서 세션을 열고 그 인자를 이 옵션들에서 읽어 옵니다.
예:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
동적 shape 입력¶
컴파일된 변형마다 유한한 버퍼 용량이 필요합니다. 용량을 정하는 방법은 두 가지입니다.
torch._dynamo.mark_dynamic(tensor, dim, min=1, max=N)으로 상한을 지정합니다. 프론트엔드는 Dynamo의ShapeEnv에서 상한을 읽습니다.max를 지정하지 않습니다. 현재 프론트엔드는 이런 차원을 size bucket(입력 크기를 묶어 정한 버퍼 용량)으로 처리합니다.dynamic=True나 자동 동적 shape 재컴파일로 생긴 차원도 포함합니다. bucket 조합의 첫 호출은 변형을 컴파일하고, 같은 bucket의 다음 호출은 이를 재사용합니다.
기본 bucket 규칙은 고정된 최댓값 없이 커집니다.
크기가 무한한 텐서를 컴파일한다는 의미는 아닙니다.
용량을 직접 정하려면 legato.size_buckets에 양의 정수를 엄격한 오름차순으로 나열한
비어 있지 않은 리스트를 지정하십시오.
입력이 명시한 가장 큰 bucket보다 크면 ValueError가 발생합니다.
이 옵션은 명시적 max가 없는 차원에 적용됩니다.
각 컴파일 용량에는 백엔드 레이아웃과 메모리 제약이 계속 적용됩니다.
아래 예제는 프론트엔드 dry_run=True를 사용해
바이너리를 컴파일하거나 실행하지 않고 CPU 값을 검사합니다.
상한을 지정하는 차원에는 SDK의 PyTorch 2.10에 맞게 min과 max를 함께 넘기십시오.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
max가 없는 차원은 bucket 리스트를 지정해 선택되는 용량과 상한을 예측할 수 있습니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
legato.session.launch¶
타입: bool, 기본값 True.
False이면 선택한 artifact까지 컴파일하지만 커널을 제출하지 않습니다.
백엔드 컴파일을 건너뛰는 프론트엔드 dry_run과는 별개의 옵션입니다.
컴파일 전용 호출의 출력 버퍼를 계산 결과로 해석하지 마십시오.
코어 분배 옵션¶
| 옵션 | 기본값 | 의미 |
|---|---|---|
legato.frontend.core_num |
32 |
참여 코어 수. 1부터 32까지이며 초기화한 디바이스와 맞아야 합니다. |
legato.frontend.token_dim |
-2 |
부호를 유지하는 token 축 인덱스. [tokens, heads, head_dim]처럼 선두 token 축에는 0을 사용합니다. |
legato.frontend.dump_before_pass¶
타입: bool
패스를 반복할 때마다 torch FX 그래프를 출력합니다. 디버깅 전용입니다.
legato.frontend.dump_ir¶
타입: bool
모델의 IR(중간 표현) 코드를 출력합니다. 디버깅과 테스트 전용입니다.
legato.frontend.dump_legato¶
타입: bool
합성된 Legato 함수 또는 생성된 혼합 wrapper 소스를 출력합니다. 디버깅과 테스트 전용입니다.
legato.frontend.dry_run¶
타입: bool
프론트엔드 검증 동작은 그대로 두고 백엔드 실행만 건너뜁니다. 디버깅과 테스트 전용입니다.
- 전부 컴파일 가능한 그래프에서는 dry-run 모드에서도 변환된 프론트엔드 경로를 그대로 실행하되,
백엔드 코드를 컴파일하는 대신
gm.forward를 반환합니다. - 혼합 그래프에서는 dry-run 모드에서도 segment 분할 계획과 서브그래프 추출 검증은 그대로 실행하지만,
segment를 조합하거나 컴파일하지는 않습니다. 그런 다음
gm.forward를 반환합니다.
따라서 dry-run 모드는 백엔드 코드 생성이나 런타임 실행 없이 프론트엔드 동작을 검증하려 할 때 유용합니다.