사례 연구: Transformer

이 Transformer 페이지는 Qwen3-0.6B를 구체적인 튜토리얼 사례로 삼아 이 모델의 멘탈 모델을 설명하고, 디코더 토큰 하나가 호스트에서 준비된 임베딩에서 출발해 패딩된 어휘 로짓에 이르는 과정을 따라갑니다. 각 경계는 이식 가능한 호스트 오라클과 재현 가능한 스케줄 산출물로 검사합니다. 이 예제를 응용할 때에는 호스트에서 준비된 이러한 경계를 유지하십시오.

이 모델은 28개 레이어로 구성된 디코더 전용 Transformer입니다. 각 레이어는 한 번에 토큰 하나에 대해 계속 갱신되는 은닉 벡터 하나를 변환합니다.

token id
   |
   v
[Embedding lookup]
   |
   v
+-----------------------------+
| Decoder layer × 28          |
| RMSNorm → Q/K/V projection  |
| QK-Norm → RoPE → Attention  |
| Output projection + residual|
| RMSNorm → SwiGLU MLP        |
| + residual                  |
+-----------------------------+
   |
   v
[Final RMSNorm] → [LM head] → logits

이 모델은 은닉 크기 1024, 쿼리 헤드 16개, 키/값 헤드 8개, 헤드 차원 128, 중간 크기 3072를 사용합니다. 그룹 쿼리 어텐션에서는 각 키/값 헤드를 두 개의 쿼리 헤드가 공유합니다. RoPE는 theta 1,000,000을 사용하며, 임베딩 가중치와 출력 가중치는 모델 설계상 묶여 있습니다.

RMSNorm, RoPE, 어텐션, KV 캐시, SwiGLU, 잔차, 출력 프로젝션에 관한 결정 사항은 이 사례 연구에 요약되어 있으며 로컬 transformer 예제에 구현되어 있습니다.

이 예제는 디코드 전용이며 단일 토큰만 처리합니다. 프리필, 샘플링, 디바이스 측 토큰 조회는 구현하지 않습니다. 실행 가능한 소스는 transformer 예제입니다. 이 사례 연구는 구현을 그대로 옮겨 싣는 대신 그 결정 사항을 설명하고 소스와 테스트를 안내합니다.

실행 가능한 디코더 흐름

로컬 furiosa-opt-examples/src/transformer/mod.rs는 다음 디바이스 실행을 제공합니다.

• embedding
• projection
• attention_forward_first
• attention_forward
• decoder
• final_layer

이 로컬 실행 맵은 이 사례 연구의 기준이 되는 실행 표면입니다. vISA와 API 계약은 레퍼런스 장에서 다룹니다.

워크로드 의미론

워크로드는 디코더 한 단계입니다:

host-prepared embedding → 28 decoder layers → final RMSNorm and LM head → logits [Wp]

현재 예제는 레이어 28개와 히든 크기 1024를 가진 Qwen3-0.6B를 다룹니다. 각 디코더 레이어에는 다음과 같은 경계가 있습니다:

1. projection: 입력 RMSNorm, Q/K/V 프로젝션, Q/K RMSNorm, RoPE, KV 캐시 쓰기입니다.
2. attention_forward_first 또는 attention_forward: 온라인 소프트맥스 어텐션 청크 하나입니다.
3. decoder: 출력 프로젝션, 잔차, 어텐션 후 RMSNorm, MLP, 잔차입니다.

final_layer는 최종 RMSNorm을 적용하고 패딩된 어휘 형태로 로짓을 계산합니다. 정확한 축 크기와 텐서 타입은 axes.rs에 정의되어 있습니다.

결정 추적

이 사례 연구는 이 책의 나머지 부분과 같은 순서를 따릅니다:

1. 워크로드 의미론: 토큰 하나와 점점 커지는 KV 캐시가 데이터 이동을 결정합니다.
2. 엄격한 제약 조건: 모든 커널에는 타입이 지정된 공개 경계가 있습니다. 어휘 출력은 Wp를 사용하고, 모델 어휘는 W입니다.
3. 커널 경계: Rust 모듈은 embedding, projection, attention_forward_first, attention_forward, decoder, final_layer를 별도의 디바이스 진입점으로 노출합니다.
4. 매핑과 이동: 소스는 호스트에서 준비한 텐서를 HBM과 DM을 거쳐 이동시키며, 각 엔진이 요구하는 표현을 사용합니다. 이러한 계약은 텐서 매핑과 텐서 이동을 참고하십시오.
5. 엔진 선택: 프로젝션과 LM 헤드 축약에는 Contraction Engine을 사용합니다. RMSNorm과 요소별 단계에는 Vector Engine을 사용합니다. 전송에는 DMA 경로와 Fetch/Commit 경로를 사용합니다. 해당 계약은 텐서 계산을 참고하십시오.
6. 검증: 호스트 오라클 테스트로 값을 확인하고, 덤프된 스케줄에 정적 실행 계획을 기록합니다. 스케줄링과 튜닝을 참고하십시오.

따라서 이 사례 연구는 여러 선택이 어떻게 조합되는지 보여 줍니다. 개별 엔진 API를 새로 정의하지는 않습니다.

호스트에서 준비한 임베딩

embedding 진입점은 호스트가 준비한 HBM 복사입니다. 이 진입점은 HbmTensor<bf16, ..., m![H]>를 받아 to_hbm_view로 그 뷰를 출력 HBM 텐서에 복사합니다. 이는 토큰 ID로 수행하는 디바이스 조회가 아니며, 그렇게 설명해서는 안 됩니다.

현재 소스는 이 단계를 ops::embedding으로 구현합니다. 스모크 테스트는 test_embedding입니다.

디코더 단계

projection은 하나의 은닉 벡터, 프로젝션 및 RMSNorm 가중치, 위치에 따라 달라지는 cos 및 sin 벡터, 그리고 변경 가능한 K/V 캐시를 받습니다. 이 함수는 Q를 HBM에 쓰고 캐시를 갱신합니다. 첫 번째 어텐션 청크는 attention_forward_first를 사용합니다. 이후 청크는 attention_forward를 사용하여 온라인 리덕션 상태를 이어 갑니다.

decoder는 어텐션 출력과 그 리덕션 상태를 소비하고, 잔차 스트림을 HBM에 다시 쓰며, 출력 프로젝션, 잔차 경로, RMSNorm, MLP, 최종 잔차 경로를 적용합니다. 필요한 입력과 출력은 함수 시그니처가 정의합니다. 구현 세부 사항은 furiosa-opt-examples/src/transformer/mod.rs에 있습니다.

경계 테스트 test_decoder_step_wires_kernel_boundaries는 호스트가 준비한 입력을 0 가중치로 프로젝션, 하나의 어텐션 청크, 디코더에 차례로 통과시킵니다. 이 테스트의 스칼라 오라클 테스트는 프로젝션, 청크 단위 어텐션, 디코더 연산을 각각 따로 검증합니다.

최종 레이어와 패딩된 로짓

final_layer는 잔차 스트림을 받아 RMSNorm을 적용하고, 모델 어휘 가중치 뷰를 패딩된 출력 표현으로 재구성한 뒤, 로짓을 m![Wp]에 씁니다. 소스는 별도의 lm_head_weight를 받습니다. 이 예제는 임베딩 가중치 공유(tied embedding)를 주장하지 않습니다.

결정적 테스트 test_final_layer_matches_scalar_reference는 유효한 W개의 로짓을 호스트의 RMSNorm 및 내적 오라클과 비교합니다. 패딩은 텐서의 필수 형태와 저장 동작의 일부입니다. 패딩된 항목의 해석은 호출자의 몫입니다.

검증과 검사

저장소의 일반 명령으로 Transformer 테스트 대상을 실행하십시오:

cargo furiosa-opt test --test transformer_tests

이 테스트는 시드가 고정된 작은 픽스처를 사용하며, 지원되는 각 경계를 호스트 수식과 비교합니다. 모델 파일이나 샘플링 루프는 필요하지 않습니다. 선택한 디바이스 진입점을 --dump-schedule과 함께 컴파일하여 스케줄 데이터를 생성하십시오. Schedule Viewer로 결과를 검사하고 스케줄링과 튜닝의 비교 절차를 따르십시오.

변경은 규율 있게 진행하십시오. 먼저 오라클을 확립하고, 기준 스케줄을 기록하고, 매핑, 이동, 엔진, 형태 선택 중 하나만 변경한 뒤, 같은 산출물을 비교하십시오. 오라클이나 소스 순서로부터 처리량을 추론하지 마십시오.