콘텐츠로 이동

예제 실행하기

예제의 타겟은 **Bertha EVT0**입니다. tutorials/code 아래에서 내려받을 수 있는 각 Python 파일에는 커널, 호스트 설정, 검증 코드가 모두 들어 있습니다. 파일 하나를 내려받거나 해당 페이지의 전체 소스를 복사하면 되며, 함께 두어야 하는 다른 Python 파일은 필요 없습니다. 페이지에 표시되는 코드도 바로 이 파일에서 가져온 것입니다. 샘플을 import하면 커널만 정의되며, 디바이스 텐서 할당이나 커널 실행은 일어나지 않습니다. 실행은 if __name__ == "__main__" 아래에서 시작됩니다.

SDK 환경 활성화하기

먼저 legato, hart, torch_ha, PyTorch 2.10.0과 native 컴파일러/toolchain이 포함된 SDK Python 환경을 준비하십시오. 디바이스에서 실행하려면 드라이버를 갖춘 Bertha EVT0 하드웨어나 EVT0 Torch FSim 백엔드로 빌드한 런타임 중 하나가 추가로 필요합니다. (가상환경을 활성화한다고 해서 이 구성 요소들이 빌드되는 것은 아니므로, SDK를 아직 준비하지 않았다면 설치 안내를 참고하십시오. 리뷰 필요)

아래 블록의 처음 세 경로를 각각 SDK 체크아웃, 이 문서 저장소 체크아웃, 준비해 둔 SDK 가상환경 경로로 바꾸십시오. 이 블록을 Bash에서 실행한 다음, 이후의 명령은 같은 터미널에서 실행하십시오.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
SDK_ROOT=/path/to/hyperaccel-sdk
DOCS_ROOT=/path/to/ha-sdk-docs
SDK_VENV=/path/to/sdk-venv
source "$SDK_VENV/bin/activate"
cd "$SDK_ROOT/legato"

# SDK의 native toolchain을 사용하고, 각 예제 안에서 Torch 백엔드를 명시적으로 등록합니다.
export HA_TOOLCHAIN=1
export HART_TOOLCHAIN=1
export TORCH_DEVICE_BACKEND_AUTOLOAD=0
# 디렉터리를 바꾸어도 artifact와 시뮬레이터 로그를 같은 위치에 저장합니다.
export LEGATO_EXAMPLE_OUTPUT="$PWD/legato_example_output"

프론트엔드 전용 예제에는 Legato와 CPU PyTorch만 있으면 되고, 드라이버나 디바이스는 필요 없습니다. 컴파일 diagnostics 예제도 디바이스를 사용하지 않습니다. 이 예제는 CPU 입력으로 실제 컴파일러 검사를 실행하고, 예상한 에러를 잡아냅니다. 이 예제를 실행하려면 구성 요소별로 세분화된 diagnostic이 들어 있는 native 컴파일러가 필요합니다.

하드웨어에서 예제 실행하기

하드웨어에서 실행하려면 사용 중인 LPU 디바이스에 맞게 빌드한 SDK/런타임을 활성화하고 위의 환경 설정을 사용하십시오. 수치를 검증하는 예제를 실행하기 전에 시뮬레이터 선택을 명시적으로 해제하십시오.

아래와 같이 실행할 수 있습니다.

1
2
3
4
5
6
7
8
9
cd "$SDK_ROOT/legato"
unset HA_BACKEND

python "$DOCS_ROOT/docs/legato-language/tutorials/code/simple_matmul.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/static_multi_core.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/tensor_memory.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/attention.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/math_and_masking.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/broadcasting.py"

내려받은 예제를 실행하려면 전체 Python 소스를 원래 파일 이름 그대로 저장하십시오. SDK 환경을 활성화한 뒤 그 파일을 직접 실행하십시오. 예를 들어 아래 명령에서 디렉터리 부분을 simple_matmul.py가 있는 위치로 바꾸십시오.

1
2
3
cd /path/to/downloaded-examples
export HA_BACKEND=hw
python simple_matmul.py

하드웨어에서 실행할 때는 export HA_BACKEND=sim 대신 unset HA_BACKEND를 사용하십시오. 내려받은 파일 옆에 저장소의 Python helper를 함께 둘 필요는 없습니다.

예제가 검증하는 내용

수치를 검증하는 각 예제의 소스에는 아래 단계가 주석과 함께 그대로 드러나 있습니다.

  1. LPU Torch 백엔드를 등록하고, 시뮬레이터를 선택했다면 FSim을 설정한 뒤 디바이스 0을 선택합니다.
  2. CPU 입력을 준비하고, 필요한 물리 레이아웃의 디바이스 텐서를 할당한 뒤 연속된 데이터를 복사합니다.
  3. 바이너리 출력을 지정한 legato.session 안에서 컴파일하고 실행합니다.
  4. 스트림을 동기화(synchronization)해서, 비동기 디바이스 에러가 있으면 예제가 실패하도록 합니다.
  5. 결과를 CPU로 복사하고, 값이 유한한지 검사한 뒤 모든 출력 원소를 CPU 기준값과 비교합니다.

padding을 사용하는 예제에서는 물리 backing 텐서와 그 논리 view도 보여 줍니다. 컴파일 전용 케이스와 프론트엔드 전용 케이스는 launch=False를 명시적으로 지정하며, 디바이스 초기화와 동기화를 생략합니다.

스크립트 수행하는 검증
simple_matmul.py 바이너리 + FSim 값, 모든 출력 원소
static_multi_core.py 바이너리 + FSim 값, 32개 코어 전부
tensor_memory.py 동적 할당은 바이너리 컴파일만, 부분 복사는 FSim 값과 그대로 보존된 행
attention.py 바이너리 + FSim 값, 용량보다 짧은 런타임 prefix
math_and_masking.py 바이너리 + FSim 값, mask 적용 후의 maximum을 직접 넘겨주는 경우
broadcasting.py 바이너리 + FSim 값, add/conv/dwconv/pool/LayerNorm/RMSNorm
channel_multi_core.py rank별 ELF 바이너리 두 개와 코어별 텐서 채널 binding 네 개, launch 없음
weight_quant_matmul.py converter 바이트 수 + 바이너리 컴파일, FSim 수치 검증 없음
static_evaluation.py, tensor_fill_frontend.py 프론트엔드 MLIR만, launch 없음
compile_diagnostics.py 실제 컴파일 실패 세 가지(소스 label, headline/사유 코드, 정렬 및 전송 정보), launch 없음

프론트엔드 컴파일이 성공하는 것, 바이너리가 생성되는 것, 디바이스에서 올바른 값이 나오는 것은 각각 별개의 검사입니다. FP8 양자화의 시뮬레이터 제약과 standalone fill/reduction의 제약은 각각 해당 예제/API 페이지에 그대로 적혀 있습니다. 하드웨어에서도 결과가 일치하는지(hardware parity)는 이번 문서 업데이트에서 측정하지 않았습니다. 아키텍처 매뉴얼은 실리콘이 가진 기능을 설명하는 문서이지, 컴파일러가 무엇을 지원하는지 나타낸 표가 아닙니다.

문서 예제 검사

SDK 환경에서 아래 명령을 사용해, 내려받을 수 있는 Python 예제를 검사하고 튜토리얼 notebook을 실행하십시오.

SDK 개발 의존성을 설치한 환경에서 각 테스트 파일을 따로 실행하십시오.

1
2
3
4
5
6
7
cd "$SDK_ROOT/legato"
export HA_BACKEND=sim

# 내려받을 수 있는 Python 예제를 검사합니다.
python -m pytest -c pyproject.toml src/tests/documentation_examples/test_examples.py
# 실제 Jupyter 커널에서 튜토리얼 notebook을 실행합니다.
python -m pytest -c pyproject.toml src/tests/documentation_examples/test_tutorials.py

두 테스트 파일을 한꺼번에 실행할 수도 있습니다.

1
2
cd "$SDK_ROOT/legato"
HA_BACKEND=sim python -m pytest -c pyproject.toml src/tests/documentation_examples

수치 검사는 스트림을 동기화한 뒤 모든 출력 원소를 CPU 기준값과 비교합니다. 컴파일 전용 검사는 launch 없이 바이너리가 비어 있지 않은지 확인하고, 프론트엔드 전용 검사는 생성된 MLIR을 살펴봅니다. notebook 검사는 현재 활성화된 SDK Python 인터프리터를 사용하는 실제 Jupyter 커널에서 모든 코드 셀을 실행합니다.

FSim이나 Jupyter를 띄우지 않고 문법/API만 빠르게 점검하려면 다음 명령을 실행하십시오.

1
2
cd "$SDK_ROOT/legato"
python Documentation/verify_examples.py --api

대화형으로 쓰려면 Jupyter에서 SDK Python 환경을 선택하고 Documentation/tutorial에 있는 notebook의 모든 셀을 실행하십시오. notebook을 대화형으로 쓸 때도 같은 assertion이 실행됩니다. notebook 출력은 커밋하지 않습니다.

문서 사이트를 빌드하려면 문서 의존성이 설치된 환경에서 다음 명령을 실행하십시오.

1
2
cd "$SDK_ROOT"
python -m mkdocs build --strict --config-file legato/Documentation/mkdocs.yml