Tenstorrent에서
모델을 실행하고
커널을 작성하다
PyTorch·GPU 경험이 있는 개발자가 Tenstorrent NPU를 처음부터 끝까지 익히도록 만든 한국어 가이드입니다. 설치부터 고수준 TT-NN, 저수준 TT-Metalium, 프론트엔드 TT-XLA, 커널 DSL TT-Lang, 그리고 모델 선택·vLLM 배포까지 — 공식 리포지터리와 문서의 실제 코드를 그대로 임베드하고, 개념 이해 → 예제 실행 → 직접 구축의 학습 경로로 엮었습니다.
TT-NN
PyTorch에 익숙하다면 여기서 시작하세요. ttnn.add, ttnn.matmul 같은 고수준 연산으로 텐서를 다루고 실제 모델을 추론합니다.
TT-Metalium
하드웨어를 직접 제어하고 싶다면 여기로. 서큘러 버퍼, 데이터 무브먼트 커널, FPU/SFPU 컴퓨트 커널을 C++로 작성합니다.
여기서 시작하세요 — PyTorch 개발자를 위한 학습 경로
이 페이지는 Python·PyTorch·GPU 경험이 있지만 Tenstorrent는 처음인 개발자를 위해 설계되었습니다. 아래 순서대로 따라가면 개념 이해 → 예제 실행 → 직접 포팅/커널 작성까지 도달합니다. 개념이 막히면 용어집·치트시트·FAQ를 참고하세요.
하드웨어와 프로그래밍 모델 이해하기
Tenstorrent의 AI 프로세서는 Tensix 코어들이 2차원 그리드 형태로 배열된 구조입니다. GPU처럼 하나의 거대한 SIMD 유닛이 아니라, 각각 독립적으로 프로그래밍 가능한 코어들이 NoC(Network-on-Chip)로 연결되어 있습니다. 각 Tensix 코어 안에는 5개의 RISC-V 코어가 들어 있고, 역할이 명확히 나뉩니다.
타일(Tile) — 32×32
하드웨어의 거의 모든 연산은 32×32 값으로 이루어진 타일 단위로 이루어집니다. bfloat16 기준 한 타일은 32×32×2 = 2048바이트입니다. 텐서를 디바이스에 올릴 때 TILE_LAYOUT으로 변환하고, 32의 배수가 아닌 크기는 자동으로 패딩됩니다.
L1(SRAM) vs DRAM
L1은 각 Tensix 코어 안에 있는 빠르고 작은 스크래치패드입니다(CPU의 L1 캐시와는 다릅니다). DRAM은 크지만 느립니다. 성능의 핵심은 데이터를 L1에 가깝게 유지하고 DRAM 왕복을 줄이는 것입니다.
서큘러 버퍼(Circular Buffer)
커널 사이의 통신 채널입니다. 리더 커널이 타일을 밀어넣고(push) 컴퓨트 커널이 꺼내(pop) 쓰는 FIFO 파이프입니다. Tensix 하나당 최대 32개까지 사용할 수 있으며, 더블 버퍼링으로 데이터 이동과 연산을 겹칩니다.
FPU vs SFPU
FPU(행렬 엔진)는 matmul·덧셈·리덕션 같은 무거운 연산을 담당하고, SFPU(벡터 엔진)는 exp·sqrt·sin·ReLU 같은 복잡한 원소별 함수를 담당합니다. 커널에서 어떤 엔진을 쓰느냐에 따라 API가 달라집니다.
또한 TT-Metalium의 최신 API는 단일 디바이스도 1×1 메시(Mesh)로 취급합니다. MeshDevice, MeshCommandQueue, MeshBuffer를 사용하면 코드를 바꾸지 않고도 1개에서 수백 개의 디바이스로 확장할 수 있습니다. 모든 연산(업/다운로드, 프로그램 실행)은 커맨드 큐(Command Queue)에 순서대로 쌓여 비동기로 실행됩니다.
TT-NN이 지원하는 데이터 타입
| 타입 | 비트 | 용도 | 트레이드오프 |
|---|---|---|---|
| float32 | 32 | 고정밀 부동소수점 | 정확도 높음, 메모리 많음 |
| bfloat16 | 16 | 신경망 표준 | 준수한 정확도, 메모리 2배 절약 |
| bfloat8_b | 8 | 추론, 대형 모델 | 메모리 4배 절약, 정확도 하락 |
| bfloat4_b | 4 | 초경량 추론 | 메모리 8배 절약, 최저 정확도 |
| uint16 / uint32 | 16 / 32 | 정수 연산 | 인덱싱·마스킹 등 |
FPU는 LoFi → HiFi2 → HiFi3 → HiFi4의 4단계 정밀도 모드를 제공합니다. LoFi는 가장 빠르고 부정확하며, HiFi4는 완전한 FP32 누산으로 가장 정확합니다. 예제들에서 MathFidelity::HiFi4가 자주 등장하는 이유입니다.
GPU/PyTorch에서 오셨나요? — 개념 대응표
이미 GPU와 PyTorch에 익숙하다면 Tenstorrent 개념을 익숙한 것에 대응시켜 이해하는 편이 빠릅니다. 가장 큰 차이는 암묵적 SIMT 스케줄링(GPU) 대신 명시적 데이터 이동 + 정적 코어 분배(Tenstorrent)라는 점입니다.
| GPU / PyTorch | Tenstorrent | 차이점 |
|---|---|---|
| CUDA core / SM | Tensix 코어 | 각 Tensix는 5개 RISC-V + FPU·SFPU. 워프 스케줄링이 아니라 명시적 데이터 이동으로 동작합니다. |
| warp / thread block | 코어 그리드 + 정적 분배 | 동적 스케줄링·오버서브스크립션 없음. 코어 수만큼만 병렬이며 작업을 직접 나눕니다. |
| VRAM (HBM/GDDR) | DRAM | 칩 외부 대용량 메모리 — 개념은 동일합니다. |
| shared memory / L1 | L1 (SRAM · 코어당) | 코어 내부 스크래치패드. 성능의 핵심은 데이터를 L1에 붙잡아 두는 것입니다. |
| tensor (row-major) | 타일 32×32 · TILE_LAYOUT | 하드웨어가 32×32 타일 단위로 연산. 올릴 때 타일 레이아웃으로 변환합니다. |
| fp16 / bf16 | bfloat16 · bfloat8_b · bfloat4_b | 블록 부동소수점으로 8·4비트까지 — 메모리·대역폭을 크게 절감합니다. |
| cuBLAS / cuDNN | TT-NN 연산 | ttnn.matmul·ttnn.conv2d 등 즉시 쓰는 고수준 연산. |
| CUDA 커널 작성 | TT-Metalium · TT-Lang | 리더·컴퓨트·라이터 커널 + 서큘러 버퍼로 명시적 파이프라인을 구성합니다. |
| CUDA Graph | Metal Trace | 연산 시퀀스를 녹화·재생해 호스트 오버헤드를 제거합니다. |
| NCCL (multi-GPU) | CCL + TT-Fabric (mesh) | all_gather·all_reduce로 멀티 디바이스 확장. |
| torch.compile / XLA | TT-XLA (PJRT) | 기존 JAX/PyTorch-XLA 그래프를 그대로 컴파일해 실행합니다. |
GPU에서는 스케줄러가 알아서 워프를 배분하지만, Tenstorrent에서는 어떤 코어가 어떤 타일을 언제 처리할지를 프로그래머(또는 TT-NN 같은 상위 계층)가 결정합니다. 그래서 "데이터 이동"과 "타일"이 이 페이지 전반의 핵심 주제입니다.
설치 & 환경 구성 — tt-installer
Tenstorrent 가속기를 처음 받으면 가장 먼저 드라이버·펌웨어·관리 도구를 포함한 소프트웨어 스택을 설치해야 합니다. 공식 tt-installer 스크립트는 이 과정을 한 줄 명령으로 자동화합니다.
이 절에서는 지원 OS와 BIOS 요구사항, 한 줄 설치 명령, 설치 마법사가 순서대로 묻는 것들, 가상환경 활성화, tt-smi·lspci를 이용한 검증, 장치 리셋, 그리고 장치가 안 잡힐 때의 문제 해결까지 공식 문서의 명령을 그대로 정리합니다.
스택 구성 요소
tt-kmd(커널 드라이버), tt-flash(펌웨어), tt-smi(관리·텔레메트리), HugePages, Python venv가 한 세트로 설치됩니다.
한 줄 프로비저닝
curl로 최신 install.sh를 받아 실행하면 전체 스택을 자동 설치합니다. 의존성은 curl과 jq뿐입니다.
검증과 리셋
tt-smi로 장치 인식을 확인하고, lspci -d 1e52로 PCIe 열거를, tt-smi -r로 오류 상태를 초기화합니다.
지원 환경
Ubuntu 22.04 LTS 권장. Ubuntu·Debian·Fedora 지원(신규 배포판은 실험적). BIOS의 PCIe AER은 OS First로 설정.
Tenstorrent 소프트웨어 스택은 여러 계층으로 구성됩니다. 커널 모드 드라이버(tt-kmd)가 PCIe로 연결된 가속기를 리눅스 커널에 노출하고, tt-flash가 보드 펌웨어를 갱신하며, tt-smi가 시스템 관리·텔레메트리를 담당합니다. 그 위에 TT-Metalium/TT-NN 개발 환경이 올라갑니다. 이 모든 구성 요소를 손으로 하나씩 설치하는 대신, 공식 편의 스크립트 tt-installer가 한 줄로 전체 스택을 프로비저닝합니다.
사전 준비 — OS · 하드웨어 · BIOS
권장 운영체제는 Ubuntu 22.04 LTS이며 Ubuntu·Debian·Fedora도 지원됩니다(더 최신 배포판은 실험적). 그 외에 인터넷 연결(패키지 다운로드), 관리자(sudo) 권한, 제품 매뉴얼에 따른 물리적 설치 완료가 필요합니다. 또한 BIOS에서 PCIe AER Reporting 항목을 OS First로 설정해야 합니다(TT-QuietBox 시스템은 자동 설정).
tt-installer는 curl과 jq 두 의존성만 필요합니다(일부 배포판은 기본 설치되어 있지 않음). 먼저 설치해 둡니다.
한 줄 설치 명령
아래 명령이 tt-installer의 최신 릴리스 스크립트를 내려받아 실행합니다. 이 스크립트는 패키지 설치, DKMS 커널 모듈 추가, HugePages 설정을 위해 슈퍼유저(sudo) 권한을 요구합니다.
curl로 받은 스크립트를 곧바로 파이프로 실행하는 방식은 편리하지만, 스크립트가 root 권한으로 커널 모듈을 추가하고 HugePages를 구성한다는 점에서 위험을 동반합니다. 내부 정책이 엄격하다면 install.sh를 먼저 파일로 내려받아 검토한 뒤 실행하세요.
설치 마법사가 순서대로 묻는 것
대화형 모드로 실행하면 스크립트는 다음을 차례로 진행합니다. (1) 진행 확인에 Y, (2) sudo 비밀번호 입력, (3) TT-Metalium Slim 컨테이너(tt-nn/tt-metalium 릴리스 빌드 포함) 설치 여부 — TT-NN/TT-Metalium 개발 시 Y, (4) 모델 데모 컨테이너(전체 tt-metal, 약 10GB) 설치 여부, (5) Python 패키지 위치 선택, (6) TT-KMD·TT-Flash·시스템 펌웨어·HugePages·TT-SMI 자동 설치, (7) 첫 설치 시 재부팅(필수).
(5) Python 설치 위치는 네 가지 중에서 고릅니다: active-venv(현재 활성 환경 사용), new-venv(기본값 — /home/$USER/.tenstorrent-venv 생성), system-python(비권장), pipx(격리 설치).
Python 가상환경 활성화
기본 설치는 ~/.tenstorrent-venv에 가상환경을 만듭니다. tt-smi 등 파이썬 도구를 쓰려면 이 venv를 활성화합니다.
설치 검증 — tt-smi & lspci
재부팅이 끝나면 tt-smi를 실행해 장치가 정상 인식되는지 확인합니다. 출력의 Device Information 섹션에 표시되는 장치 수가 실제 설치한 하드웨어 수와 일치해야 합니다. PCIe 수준의 열거는 lspci -d 1e52(1e52 = Tenstorrent 벤더 ID)로 확인합니다.
장치 리셋
장치가 오류 상태에 빠지거나 재실행 전 초기화가 필요하면 tt-smi -r로 리셋합니다(수 초 소요). 남아 있는 프로세스와 공유 메모리를 먼저 정리하면 더 확실합니다.
문제 해결 — 장치가 안 잡힐 때
"No Tenstorrent devices detected!"가 뜨는 경우, Blackhole 카드(p100/p150)라면 먼저 전원을 점검하세요: 부팅 시 팬 회전과 녹색 LED를 확인합니다. 전원이 정상인데도 안 잡히면 카드를 리셋하고, lspci -d 1e52 결과가 비어 있으면 PCIe 열거 자체가 실패한 것입니다(재장착·슬롯 변경을 검토).
설치가 끝나면 본격적인 개발로 넘어갑니다. TT-NN(02절~)으로 모델을 실행하거나, 배포가 목표라면 모델 선택 가이드와 vLLM 추론 서버로 이어집니다. 상태 모니터링은 tt-smi(스냅샷)와 tt-toplike(실시간)로 합니다.
TT-NN 소개 — 디바이스, 텐서, 레이아웃
가장 먼저 할 일은 디바이스를 여는 것입니다. TT-NN 텐서는 호스트(CPU)와 디바이스(Tenstorrent 하드웨어) 두 곳에 존재할 수 있고, ttnn.from_torch / ttnn.to_torch로 PyTorch와 자유롭게 오갑니다.
레이아웃: ROW_MAJOR vs TILE
TT-NN에는 두 가지 텐서 레이아웃이 있습니다. ROW_MAJOR_LAYOUT은 전통적인 행 우선 저장 방식이고, TILE_LAYOUT은 32×32 타일 기반 저장 방식입니다. 하드웨어는 타일 레이아웃에 최적화되어 있으므로, 고성능 연산은 대부분 타일 레이아웃을 요구합니다.
L1(SRAM) 직접 제어와 메모리 관리
TT-NN은 텐서를 느린 DRAM에 둘지 빠른 L1에 둘지 명시적으로 제어할 수 있습니다. 연산을 이어서 수행할 때는 중간 텐서를 ttnn.deallocate로 즉시 해제해 L1의 제한된 용량을 아끼는 것이 중요합니다.
TT-NN은 커널을 실행 시점에(JIT) 컴파일합니다. 따라서 첫 실행은 느리고(컴파일), 이후 실행은 캐시된 커널로 빠릅니다. 텐서의 shape·dtype·레이아웃이 바뀌면 새 컴파일이 트리거됩니다. 뒤의 어텐션 예제에서 "program cache" 덕분에 두 번째 반복이 빨라지는 것을 직접 확인할 수 있습니다.
Metal Trace & 멀티 디바이스
프로덕션 추론에서는 Metal Trace로 연산 시퀀스를 녹화·재생하여 Python 오버헤드를 제거하고, 메시 디바이스로 여러 칩에 텐서를 샤딩(sharding)해 모델·데이터 병렬화를 구현합니다.
TT-NN은 추론(inference)에 최적화되어 있으며 자동 미분(autograd)을 포함하지 않습니다. 학습이 필요하면 별도 프레임워크인 tt-train을 사용하세요.
텐서 더하기 — 첫 번째 디바이스 연산
여기서는 ttnn.full로 값이 채워진 32×32 텐서 두 개를 디바이스에서 직접 만들고, ttnn.add로 더합니다. 두 텐서 모두 TILE_LAYOUT이라는 점에 주목하세요 — 하드웨어 연산의 전제 조건입니다.
기본 텐서 연산 — 생성, 곱셈, 브로드캐스트
PyTorch 텐서를 ttnn.from_torch로 올리고, ttnn.zeros·ttnn.ones·ttnn.full로 디바이스에 직접 만들 수 있습니다. 연산은 ttnn.add, ttnn.mul, ttnn.matmul처럼 PyTorch와 거의 같은 이름을 씁니다.
행렬 곱셈 — 메모리 배치와 코어 그리드
@ 연산자, 레이아웃 변환, 그리고 L1 배치 + 코어 그리드 지정으로 성능을 끌어올리는 법을 봅니다.ttnn.rand로 디바이스에 큰 행렬을 만들고 파이썬 @ 연산자로 곱합니다. 결과는 타일 레이아웃이므로, 사람이 읽으려면 to_layout으로 ROW_MAJOR로 바꿉니다. 마지막에는 입력을 L1에 배치하고 core_grid로 8×8 = 64개 코어에 연산을 분배해 성능을 높입니다.
TT-NN은 고수준 API지만, core_grid·memory_config 같은 인자로 저수준 하드웨어 자원(어느 코어에서, 어느 메모리를 쓸지)을 제어할 수 있습니다. 이 아이디어를 밑바닥부터 직접 구현하는 것이 뒤의 TT-Metalium 행렬 곱 예제입니다.
Conv2D — 합성곱과 NHWC 레이아웃
conv2d는 PyTorch의 BCHW가 아니라 NHWC 레이아웃을 기대합니다. 입력을 permute·reshape하여 넘기는 패턴을 익힙니다.PyTorch의 이미지 텐서는 (batch, channel, height, width) 순서지만, TT-NN conv2d는 채널이 마지막인 NHWC를 원합니다. 그래서 ttnn.permute로 축을 바꾸고, 공간 차원을 평탄화한 뒤 ttnn.Conv2dConfig와 함께 호출합니다. 또한 open_device에 l1_small_size를 지정하는 점도 눈여겨보세요.
모델 학습 & 가중치 내보내기
.pt 가중치 파일은 이 PyTorch 스크립트로 먼저 CPU에서 학습해 만들어 둡니다.전체 흐름은 명확합니다 — 여기(PyTorch)에서 학습 → 저장, 다음 예제(TT-NN)에서 그 가중치를 로드 → Tenstorrent에서 추론. 먼저 MNIST용 3-레이어 MLP를 학습하고 W1..b3 텐서를 저장합니다.
CNN(CIFAR-10)도 동일한 패턴입니다. 표준 PyTorch로 학습한 뒤 state_dict 전체를 저장하면, CNN 추론 예제(08)가 이를 각각 TT-NN 텐서로 변환해 사용합니다.
TT-NN은 추론에 최적화된 프레임워크라 역전파(autograd)를 제공하지 않습니다. 따라서 "학습은 익숙한 PyTorch에서, 추론은 Tenstorrent에서"라는 분업이 자연스럽습니다. 디바이스 학습이 필요하면 별도 프레임워크 tt-train을 사용하세요. 가중치가 없으면 두 추론 예제는 랜덤 가중치로 폴백하므로(정확도는 낮음), 이 스크립트를 먼저 실행하는 것을 권장합니다.
MLP 추론 — MNIST 손글씨 분류
ttnn.linear + ttnn.relu로 구성해 실제 MNIST 이미지를 분류합니다. 첫 번째 end-to-end 모델입니다.각 레이어는 가중치 전치 → 편향 reshape → ttnn.linear → ReLU 패턴을 따릅니다. 마지막 레이어만 ReLU 없이 로짓을 출력하고, ttnn.to_torch로 내려 argmax로 예측 클래스를 얻습니다.
CNN 추론 — CIFAR-10 이미지 분류
핵심은 conv → ReLU → max_pool을 캡슐화한 conv_pool_stage 함수입니다. Conv2dConfig(activation=...)로 활성화를 합성곱에 융합하고, ttnn.max_pool2d로 다운샘플링합니다. 완전연결 단계에서는 다시 TILE_LAYOUT과 ttnn.linear를 사용합니다.
멀티헤드 어텐션 — Transformer의 심장
ttnn.transformer 융합 연산으로 최적화합니다.첫 번째 버전은 @(matmul), permute, softmax 같은 기본 연산을 조합해 어텐션을 직접 구성합니다. Q·K·V를 각각 투영하고, 스코어를 √d로 스케일링한 뒤 마스크를 더하고 softmax를 취합니다.
두 번째 버전은 TT-NN이 제공하는 융합 트랜스포머 연산을 사용합니다. QKV를 하나의 linear로 계산하고, split_query_key_value_and_split_heads·attention_softmax_·concatenate_heads로 여러 단계를 한 번에 처리합니다. ttnn.deallocate로 중간 텐서를 적극 해제하고, bfloat8_b로 matmul을 가속하는 점도 실전 최적화 포인트입니다.
튜토리얼은 두 구현을 각각 두 번 실행하며 시간을 측정합니다. 첫 반복은 커널 컴파일 때문에 느리지만, 두 번째 반복은 program cache 덕분에 훨씬 빠릅니다. 마지막에는 두 구현의 결과를 피어슨 상관계수(PCC ≥ 0.95)로 비교해, 최적화 버전(bfloat8_b)과 기본 버전(bfloat16)의 정밀도 차이를 허용 범위 안에서 검증합니다.
CLIP 제로샷 분류 — 실제 규모의 모델
CLIP은 이미지와 텍스트를 같은 임베딩 공간으로 인코딩한 뒤 코사인 유사도로 매칭합니다. 먼저 사전학습된 PyTorch 가중치를 TT-NN 텐서로 변환하고, 텍스트 인코더용 인과(causal) 마스크를 만듭니다.
모델의 반복 단위는 Residual Attention Block입니다. 앞서 배운 어텐션과 ttnn.layer_norm·ttnn.gelu를 잔차 연결로 엮습니다. 이 블록을 12개 쌓으면 하나의 Transformer 인코더가 됩니다.
비전 쪽은 이미지를 ttnn.conv2d로 패치 임베딩(32×32 패치 → 토큰)한 뒤 [CLS] 토큰과 위치 임베딩을 붙여 Transformer에 넣습니다. 마지막으로 이미지·텍스트 임베딩을 L2 정규화하고 스케일된 내적으로 유사도를 계산합니다.
linear·matmul·softmax·layer_norm·gelu·conv2d·embedding·permute·concat 등 앞서 배운 연산들이 하나의 실제 모델로 합쳐집니다. PyTorch의 CLIP과 달리 TT-NN은 아직 고급 인덱싱을 완전히 지원하지 않아, EOT 토큰 선택 같은 일부 단계는 잠시 호스트(torch)로 내려 처리하는 하이브리드 패턴을 씁니다.
모델 트레이싱 — 연산 그래프 시각화
ttnn.tracer는 실행되는 연산들을 포착해 계산 그래프로 그려줍니다. torch 연산과 TT-NN 연산이 어떻게 흐르는지, 모델 구조를 눈으로 확인할 때 유용합니다.사용법은 간단합니다. with trace(): 블록 안의 연산을 기록하고 visualize(결과)로 그래프를 렌더링합니다. 순수 torch 연산도, torch ↔ TT-NN 변환 흐름도 모두 추적됩니다.
동일한 방식으로 실제 모델 전체도 추적할 수 있습니다. 아래는 BERT 질의응답 추론을 통째로 trace()로 감싸 그래프화하는 예입니다.
트레이서가 연산의 논리적 그래프(무엇이 무엇으로 흐르는가)를 보여준다면, 다음 절의 TT-NN Visualizer는 여기에 메모리·성능 측정치를 더해 하드웨어 관점의 분석을 제공합니다. 트레이싱을 켜려면 enable_fast_runtime_mode를 꺼야 한다는 점이 공통입니다.
TT-NN Visualizer — 모델 프로파일링
- Operations — 모델의 모든 연산을 검색·필터하고 연산별 입출력 텐서와 메모리 배치를 확인
- Tensors — 각 텐서의 shape·dtype·레이아웃·샤딩·배치(L1/DRAM)와 연산 간 이동을 추적
- Buffers — 실행 중 사용된 모든 메모리 버퍼의 할당 위치·수명·재사용을 시각화
- Graph — 연산을 노드로, 텐서 흐름을 엣지로 표현한 모델 구조도
- Performance — 연산별 실행 시간·사용 코어 수·FLOPs·활용도, Matmul 최적화 힌트
워크플로는 두 단계입니다. 먼저 메모리 리포트를 pytest + 설정 파일로 생성하고, 성능 리포트를 tracy 프로파일러로 생성합니다.
두 리포트 디렉터리를 Visualizer에 업로드하면 모든 분석 탭이 활성화됩니다. 자세한 내용은 ttnn-visualizer 저장소를 참고하세요.
TT-XLA 개요 & 설치
TT-XLA는 XLA/StableHLO를 통해 컴파일되는 프레임워크(JAX와 PyTorch/XLA)가 Tenstorrent 하드웨어에서 실행되도록 해주는 PJRT 플러그인입니다. TT-NN이나 TT-Metalium처럼 전용 API로 새로 작성하는 대신, 기존 XLA 코드를 최소한의 변경으로 가속기에 올리고 싶을 때 쓰는 진입점입니다.
이 그룹은 개요·설치부터 JAX/PyTorch 예제, 혼합 정밀도, 코드 생성, 모델 실행까지를 개별 섹션으로 다룹니다.
PJRT 백엔드 통합
pjrt-plugin-tt로 JAX·PyTorch/XLA를 Tenstorrent에 연결합니다. StableHLO 그래프를 입력으로 받습니다.
tt-mlir 위에서 동작
프레임워크 → StableHLO → PJRT → tt-mlir → tt-metal → 디바이스. 단일·멀티 칩 모두 지원합니다.
JAX & PyTorch
JAX는 jit(backend="tt"), PyTorch는 model.compile(backend="tt")+xla_device(). 구형 TT-Torch를 대체합니다.
혼합 정밀도 · codegen
레이어별 가중치 dtype 오버라이드와, 컴파일 결과를 파이썬 코드로 내보내는 codegen을 지원합니다.
TT-XLA는 공식 표현으로 "a PJRT-based backend integration that enables JAX and PyTorch/XLA to run on Tenstorrent AI hardware"입니다. JAX/PyTorch가 모델을 StableHLO 그래프로 낮추면, TT-XLA의 PJRT 플러그인이 이를 tt-mlir 컴파일러로 넘기고, tt-metal 런타임을 거쳐 Wormhole·Blackhole에서 실행됩니다. 멀티 칩도 지원하며 과거 PyTorch용이던 TT-Torch를 대체합니다.
설치 — 휠 (권장)
모델을 실행만 하려면 미리 빌드된 휠을 설치합니다. 추가 인덱스에서 pjrt-plugin-tt를 설치한 뒤 tt-forge-install로 시스템 의존성을 채웁니다.
설치 — Docker & 소스
컨테이너로 실행하려면 슬림 이미지를, 소스 빌드 시에는 몇 가지 시스템 의존성을 설치합니다.
JAX 예제 — 선형 회귀
JAX 코드는 거의 그대로 둡니다. 핵심은 jit(..., backend="tt")로 컴파일 백엔드만 Tenstorrent로 지정하는 것입니다. 표준 vmap·grad·jit를 그대로 씁니다.
PyTorch 예제 — MNIST
PyTorch는 PyTorch/XLA를 통해 지원됩니다. 모델을 model.compile(backend="tt")로 컴파일하고 xm.xla_device()가 반환하는 디바이스로 옮기면 됩니다.
컴파일러 옵션 & eager 모드
컴파일 외에 세부 제어와 즉시 실행(eager)도 가능합니다. examples/pytorch/compiler_options.py(옵션), test_eager_mode.py(eager), export_ir_example.py(IR 내보내기)를 참고하세요.
혼합 정밀도 — 레이어별 dtype 오버라이드
전체를 균일하게 양자화하면 민감한 레이어에서 정확도가 떨어질 수 있습니다. TT-XLA는 텐서(가중치)별로 dtype을 지정할 수 있어, 대부분을 bfp_bf8/bfp_bf4로 낮추고 일부만 bf16으로 유지할 수 있습니다(현재 matmul·linear 가중치만 지원).
코드 생성 (codegen)
컴파일 결과를 독립 실행 가능한 파이썬 코드로 내보낼 수 있습니다. compiler_options에 backend와 export_path를 지정하면 디버깅·이식에 활용할 수 있습니다.
모델 실행 & 멀티칩 예제
저장소의 예제를 내려받아 곧바로 실행할 수 있습니다.
예제 저장소에는 실제 규모의 모델이 다수 포함됩니다: ResNet, Llama, Qwen3, Mistral, GPT-OSS-20B, OLMo3, Stable Diffusion(v1.4~XL). 또한 멀티칩(n300)의 데이터·텐서 병렬 추론과 CCL 연산, 직렬화 예제도 있습니다.
성능 개선, 모델 자동 탐색 테스트, op 퓨전/합성, PyTorch/XLA 소스 빌드, Explorer 시각화 도구 등은 공식 문서의 해당 페이지에서 다룹니다.
TT-Lang 개요 & 프로그래밍 모델
TT-Lang은 Tenstorrent 하드웨어용 고성능 커스텀 커널을 작성하기 위한 파이썬 임베디드 DSL입니다. 고수준 TT-NN 연산과 저수준 TT-Metalium 사이의 간극을 메워, 퓨전 커널을 표현하면서도 파이프라이닝·동기화를 원할 때만 세밀하게 제어할 수 있게 해줍니다(점진적 공개).
이 그룹은 프로그래밍 모델·설치부터 Elementwise·Matmul 튜토리얼, 완전한 커널 예제, 디버깅까지를 개별 섹션으로 다룹니다.
파이썬 임베디드 DSL
@ttl.operation 안에 @ttl.compute·@ttl.datamovement 커널을 모아 정의합니다. ttnn.Tensor를 그대로 인자로 받습니다.
TT-NN ↔ TT-Metalium
TT-NN은 퓨전이 어렵고 TT-Metalium은 저수준 부담이 큽니다. TT-Lang은 그 중간에서 컴파일러 보조 자원 관리를 제공합니다.
데이터플로 버퍼(DFB)
reserve()/push()로 생산, wait()/pop()으로 소비하는 L1 통신 파이프. 커널 사이 데이터를 동기화합니다.
노드 → 멀티디바이스
grid/node로 코어 그리드에 분배하고, ShardTensorToMesh·all_reduce로 여러 디바이스까지 확장합니다.
연산 함수는 @ttl.operation()로 감싼 파이썬 함수로, 그 안에 정의된 커널 함수들이 자동 수집·컴파일됩니다. 커널 함수는 @ttl.compute()(수학) 또는 @ttl.datamovement()(메모리 전송)로 표시합니다.
연산은 노드들로 이루어진 그리드 위에서 실행됩니다. ttl.grid_size(dims)는 그리드 크기를, ttl.node(dims)는 현재 노드 좌표를 돌려줍니다. 커널 사이 통신은 데이터플로 버퍼(DFB)로 하며, 생산자는 reserve()·push(), 소비자는 wait()·pop()을 씁니다. DFB에서 꺼낸 메모리 단위가 블록입니다.
설치 & 함수형 시뮬레이터
하드웨어가 있으면 PyPI로 설치합니다(Python 3.12 권장). 하드웨어 없이 로직만 검증하려면 시뮬레이터 전용 패키지를 씁니다.
함수형 시뮬레이터 & 검증
설치 후 예제를 시뮬레이터로 바로 실행해 동작을 확인합니다. 커널을 순수 파이썬으로 실행하므로 하드웨어 없이 로직을 검증할 수 있습니다.
튜토리얼 ① Elementwise (step 0 → 4)
공식 Elementwise 튜토리얼은 a*b + c*d 같은 원소별 연산을 5단계로 발전시킵니다. step 0은 TT-NN 기준선으로, 연산마다 따로 디스패치되어 중간 결과가 DRAM을 왕복합니다(메모리 병목).
step 1은 TT-Lang의 전체 모델을 도입합니다: @ttl.operation(grid=(1,1)) 아래 compute·reader·writer 세 커널이 동시에 돌고, L1의 DFB로 통신하며 하나의 퓨전 커널로 계산합니다.
step 2는 타일을 GRANULARITY×GRANULARITY 패치로 묶어 동기화 오버헤드를 줄이고, step 3은 grid=(4,4)로 여러 노드에 병렬화하며, step 4는 grid="full"로 그리드를 컴파일러가 정하게 하고 올림 나눗셈·경계 검사로 나눠떨어지지 않는 분배까지 처리합니다.
완전한 예제 — eltwise_add 커널
두 텐서를 타일 단위로 더하는 완전한 커널입니다(step 4 형태). @ttl.operation이 그리드 분배를, @ttl.compute가 덧셈을, 두 @ttl.datamovement가 입력 읽기·출력 쓰기를 담당합니다.
튜토리얼 ② Matmul (step 0 → 7)
Matmul 튜토리얼은 단일 노드에서 멀티디바이스까지 확장합니다. step 0은 TT-NN 기준선(relu(A@B + C)), step 1은 K 방향으로 누산하는 단일 타일 커널입니다.
step 2는 블록으로 묶어 활용도를 높이고, step 3~4는 M×N 출력을 코어 그리드에 분배합니다. 이후는 멀티디바이스입니다: step 5는 M 차원을 ShardTensorToMesh(dim=0)로 샤딩(K×N 복제, 통신 불필요), step 6은 K 차원 샤딩 후 호스트 합산, step 7은 ttnn.all_reduce로 TT-Fabric 위 온-디바이스 리덕션을 수행합니다.
에러 & 디버깅
examples/errors/에는 흔한 실수의 재현 예가 있습니다: 데드락(eltwise_add_deadlock.py), copy 잠금 오류(copy_lock_error.py), DFB 과다 경고(max_dfbs_warning.py). 동기화 순서가 어긋나면 데드락이 나므로 reserve/wait 짝을 맞추는 것이 중요합니다. 진단은 print-debugging·compiler-options·performance-tools 문서를 참고하세요.
여러 TT-NN 연산을 하나로 퓨전해 중간 텐서의 DRAM 왕복을 없애고 싶은데 TT-Metalium으로 밑바닥부터 짜기엔 부담이 클 때가 TT-Lang의 자리입니다. 간단한 커널은 최소한만 적고, 성능이 필요할 때만 파이프라이닝·동기화를 세밀하게 제어합니다.
모델 선택 가이드 — VRAM 계산기
모델을 서빙하기 전에 반드시 확인할 것은 "이 모델이 내 장치 메모리에 올라가는가"입니다. 파라미터가 많거나 컨텍스트가 길수록 요구 메모리가 커지고, 정밀도(양자화)를 낮추면 줄어듭니다. VRAM 계산기 (cv-learn.com)는 모델·정밀도·컨텍스트를 입력하면 필요한 메모리를 추정해 줍니다.
이 배포 그룹은 먼저 모델 선택(VRAM)을 다루고, 이어서 vLLM 추론 서버 배포로 넘어갑니다.
가중치 메모리
파라미터 수 × 정밀도 바이트. 고정 비용이며 정밀도로 2~8배까지 줄일 수 있습니다.
KV 캐시
컨텍스트 길이·배치에 선형 비례. 긴 컨텍스트에서는 가중치보다 큰 병목이 되기도 합니다.
정밀도 · 양자화
BF16 → bfloat8_b → bfloat4_b로 낮출수록 절감됩니다. Tenstorrent가 기본 지원합니다.
적합성 판단
가중치 + KV 캐시 + 오버헤드 합이 장치 메모리에 들어오는지로 모델을 고릅니다.
VRAM 계산기는 모델(또는 파라미터 수), 양자화/정밀도, 컨텍스트 길이(그리고 배치)를 입력받아 필요한 메모리를 가중치 + KV 캐시 + 오버헤드로 나누어 추정합니다. 다음 세 섹션에서 각 요소의 원리를 봅니다.
① 가중치 메모리 — 파라미터 × 정밀도
가중치가 차지하는 메모리는 파라미터 수 × 파라미터당 바이트로 결정되며, 컨텍스트와 무관한 고정 비용입니다. 정밀도를 낮추면(양자화) 선형으로 줄어듭니다.
② KV 캐시 — 컨텍스트가 길수록 폭증
생성 추론에서는 이전 토큰들의 key/value를 캐시합니다. 이 KV 캐시는 컨텍스트 길이·배치에 선형 비례하므로 2K에서 넉넉하던 모델이 32K에서는 메모리를 초과할 수 있습니다.
③ 정밀도로 메모리 줄이기 (양자화)
정밀도를 낮추는 것은 메모리를 줄이는 가장 효과적인 수단으로, 품질 저하를 최소화하며 2~4배까지 절감합니다. Tenstorrent는 bfloat16 → bfloat8_b → bfloat4_b를 기본 지원합니다(트레이드오프는 00절 데이터 타입 표 참고).
cv-learn VRAM 계산기에 모델·정밀도·컨텍스트를 입력하면 가중치·KV 캐시·오버헤드 합계를 보여줍니다. 이 값을 장치 메모리와 비교해 그대로 올릴지·정밀도를 낮출지·컨텍스트를 줄일지·더 작은 모델로 갈지 결정하세요.
실전 예 & Tenstorrent 하드웨어 매핑
실전 예 — 8B vs 70B
두 모델을 정밀도별로 대략 계산하면 어느 하드웨어에 맞는지 감이 옵니다(가중치만).
하드웨어 → 권장 모델
공식 tt-inference-server 문서의 하드웨어별 검증 조합입니다. 위 계산으로 용량을 가늠한 뒤 출발점으로 삼으세요.
모델을 골랐다면 이어지는 vLLM 서버 섹션에서 위 DEVICE·MODEL 값으로 서버를 띄웁니다.
vLLM 추론 서버 — 개요 & 메시 토폴로지
tt-inference-server란
vLLM과 tt-metal을 Tenstorrent에서 연결하는 배포 도구. Docker·모델 다운로드·서빙 설정을 자동화합니다.
단일 명령 배포
run.py에 --workflow server --docker-server를 주면 Docker 셋업과 서버 기동이 자동입니다.
JWT 인증
JWT_SECRET으로 서명한 토큰(pyjwt)을 Bearer 헤더로 전달해 API를 호출합니다.
OpenAI 호환
포트 8000에서 /v1/completions 등 OpenAI 표준 API를 제공합니다.
공식 문서는 tt-inference-server를 "Tenstorrent 하드웨어에서 추론을 서빙할 모델을 배포·테스트하는 가장 빠른 방법"으로 소개합니다. vLLM과 tt-metal을 연결해 Docker·가중치 다운로드·서빙을 자동화하고 OpenAI 호환 엔드포인트를 노출합니다.
루트 파티션 최소 360GB 여유, 비루트 Docker, 가중치 다운로드용 인터넷이 필요합니다. Wormhole 계열(QuietBox/LoudBox)은 배포 전 메시 토폴로지를 먼저 구성합니다.
(Wormhole 전용) 메시 토폴로지
모델 접근 & 하드웨어 선택
Llama 같은 게이트된 모델은 Hugging Face에서 접근 요청을 승인받고 토큰을 발급해 export 합니다.
시스템에 맞춰 DEVICE·MODEL을 지정합니다(MODEL 값에는 meta-llama/ 접두어를 붙이지 않습니다).
같은 배포 그룹의 VRAM 계산기 섹션에서 용량을 먼저 가늠하세요.
서버 실행 (run.py + Docker)
각 모델 구현은 미리 빌드된 릴리스 Docker 이미지에 매핑되므로 최신 버전 태그를 체크아웃합니다.
JWT_SECRET을 설정한 뒤 run.py로 서버를 기동합니다. 첫 실행은 가중치 다운로드에 30분 이상, 초기화에 70B는 약 40분·8B는 약 10분이 걸릴 수 있습니다.
상태 확인 & API 키 발급
서버가 준비되면 /health가 200을 반환합니다. API 키는 JWT_SECRET으로 서명한 JWT로, pyjwt로 만듭니다.
OpenAI 호환 API 호출
엔드포인트는 http://localhost:8000이며 /v1/completions 등 OpenAI 표준 경로를 제공합니다. 첫 요청은 워밍업으로 느립니다.
Python OpenAI 클라이언트
curl 대신 OpenAI 파이썬 클라이언트로 동일 엔드포인트를 호출할 수 있습니다. base_url만 바꾸면 됩니다.
확장 — 임베딩 모델 & 도구
LLM 외에 BGE-M3, Qwen3-Embedding, TinyLlama 같은 모델도 서빙할 수 있습니다. 저장소 examples/vllm/ 아래 각 모델 폴더의 service.sh(서버 기동)와 client.py(요청)를 참고하세요.
실시간 코어 활동·전력·메모리 트래픽은 tt-toplike로, 포인트-앤-클릭 배포·채팅 UI는 TT-Studio로 확인할 수 있습니다. 로컬 vLLM 엔드포인트는 Aider 같은 도구와도 연동됩니다.
용어집 — Tenstorrent 핵심 용어
치트시트 — 자주 쓰는 명령 & 연산
설치 · 검증 · 리셋
GPU/PyTorch ↔ TT-NN 코드 대응
| PyTorch (GPU) | TT-NN | 설명 |
|---|---|---|
x.cuda() | ttnn.from_torch(x, layout=ttnn.TILE_LAYOUT, device=dev) | 텐서를 디바이스로 |
x.cpu() | ttnn.to_torch(x) | 호스트로 복귀 |
a @ b | ttnn.matmul(a, b) 또는 a @ b | 행렬 곱 |
F.linear(x, w, b) | ttnn.linear(x, w, bias=b) | 선형 계층 |
F.relu(x) | ttnn.relu(x) | 활성화 |
F.softmax(x, -1) | ttnn.softmax(x, dim=-1) | 소프트맥스 |
nn.Conv2d | ttnn.conv2d(...) (NHWC) | 합성곱 — 입력은 NHWC |
torch.float16 | ttnn.bfloat16 / bfloat8_b | 정밀도 |
device="cuda:0" | ttnn.open_device(device_id=0) | 디바이스 열기 |
TT-NN 핵심 연산
| 연산 | 용도 | 비고 |
|---|---|---|
ttnn.from_torch / to_torch | torch ↔ TT-NN 변환 | dtype·layout·device 지정 |
ttnn.to_layout | TILE ↔ ROW_MAJOR | 고성능 연산은 TILE |
ttnn.matmul / linear | 행렬 곱 / 선형 | core_grid·memory_config로 튜닝 |
ttnn.add / mul / sub | 원소별 연산 | 브로드캐스트 지원 |
ttnn.deallocate | 중간 텐서 해제 | L1 절약에 필수 |
ttnn.transformer.* | 어텐션 융합 연산 | split_qkv, attention_softmax_ 등 |
ttnn.all_gather / all_reduce | 멀티 디바이스 통신 | 메시에서 사용 |
dtype 선택 가이드
TT-NN — PyTorch식으로 빠르게 모델 실행(대부분 여기서 시작). TT-Metalium — C++로 커널을 밑바닥부터. TT-XLA — 기존 JAX/PyTorch-XLA 코드를 그대로. TT-Lang — 퓨전 커널을 파이썬 DSL로(둘의 중간). 자세한 결정은 아래 FAQ를 참고하세요.
문제 해결 & FAQ
자주 겪는 오류
"No Tenstorrent devices detected!" — 장치가 안 잡혀요
lspci -d 1e52로 PCIe 열거를 먼저 확인하세요. 비어 있으면 전원(팬·LED)·재장착을 점검합니다. 열거는 되는데 안 잡히면 tt-smi -r로 리셋하고, 드라이버가 로드됐는지(tt-smi) 확인합니다.L1 메모리 부족 / Out of Memory
ttnn.deallocate()로 즉시 해제하고, 큰 텐서는 memory_config=ttnn.DRAM_MEMORY_CONFIG로 DRAM에 두세요. conv 등은 open_device(l1_small_size=8192)로 작업 공간을 확보합니다. L1은 코어당 1~1.5MB로 작습니다.레이아웃 / 포맷 관련 에러
TILE_LAYOUT을 요구합니다. ttnn.to_layout(x, ttnn.TILE_LAYOUT)로 변환하세요. conv2d 입력은 NHWC여야 하므로 ttnn.permute로 축을 바꿉니다. 32의 배수가 아닌 크기는 타일로 자동 패딩됩니다.첫 실행이 너무 느려요
정확도가 기대보다 낮아요
bfloat8_b/bfloat4_b는 메모리를 아끼는 대신 정확도가 떨어집니다. 행렬 곱은 MathFidelity::HiFi4로 올리고, 검증은 allclose 대신 PCC(피어슨 상관계수)로 하는 것이 관례입니다(예: > 0.97).vLLM 서버가 안 떠요 / 느려요
HF_TOKEN 승인을 확인하세요. Wormhole 시스템은 tt-topology -l mesh로 메시를 먼저 구성해야 합니다. 첫 기동은 가중치 다운로드+초기화로 수십 분 걸릴 수 있습니다.자주 묻는 질문
TT-NN, TT-Metalium, TT-XLA, TT-Lang 중 무엇을 써야 하나요?
내 PyTorch 모델을 어떻게 올리나요?
from_torch로 가중치를 올리고 ttnn.linear/conv2d/...로 forward를 구성(06~10절 참고). (2) TT-XLA로 그대로: model.compile(backend="tt")(21~26절). 학습은 PyTorch에서 하고 가중치만 내보내 추론하는 패턴이 일반적입니다.학습(training)도 되나요?
tt-train을 사용하거나, PyTorch에서 학습 후 가중치를 내보내 추론하세요(06절).어떤 모델이 내 하드웨어에 올라갈까요?
하드웨어 없이 공부할 수 있나요?
pip install tt-lang-sim 시뮬레이터로 하드웨어 없이 커널 로직을 실행해 볼 수 있습니다(28절).
