AI 튜토리얼

오픈 RTL LLM 추론 타일 APEX 구축 및 검증

APEX가 RTL로 트랜스포머 디코더 레이어를 구현하고, 어텐션 데이터패스 내부에서 KV 캐시를 압축하며, 실행 가능한 NumPy 모델을 기준으로 각 블록을 검증하는 방법을 알아보세요. 이 튜토리얼에서는 아키텍처, 로컬 설정, 검증 명령, 모델 평가, FPGA 데모와 측정 결과 및 예상 결과를 해석하는 실용적인 지침을 다룹니다.

2026년 8월 20일약 16분 소요

APEX의 기능

APEX는 검증을 최우선으로 하는 완전 개방형 LLM 추론 타일입니다. 어텐션, KV 캐시 압축, 온라인 소프트맥스, RMSNorm, 회전 위치 임베딩, SwiGLU, 잔차 연결, 행렬 연산을 포함한 트랜스포머 디코더 레이어 하나를 실제 RTL로 구현합니다.

이 프로젝트는 엣지 추론의 주요 병목을 해결하는 것을 목표로 합니다. 대화가 길어질수록 새 토큰마다 점점 커지는 키-값 캐시를 읽어야 합니다. APEX는 KV 코덱을 하드웨어 데이터 경로에 직접 배치합니다. 키와 값은 생성될 때 압축되고 압축된 형태로 저장되며, 어텐션이 이를 소비하는 동안 압축이 해제됩니다.

APEX는 완전한 가속기 칩이 아니라 하나의 추론 타일입니다. DRAM 컨트롤러, PCIe, 네트워크 온 칩은 저장소에서 명시한 범위에 포함되지 않습니다.

이 타일은 FPGA 하드웨어에서 Qwen2.5-0.5B를 사용해 시연되었습니다. Qwen2.5-7B 토큰은 소프트웨어로 검증된 골든 파이프라인을 통과했지만, README는 7B 모델이 실리콘에서 실행되었다고 주장하지 않습니다.

주요 기능

완전한 디코더 레이어 데이터 경로: RTL은 프로젝션, 어텐션, 정규화, RoPE, 피드포워드 연산, 잔차 연산, KV 캐시 처리를 포함합니다.
데이터 경로 내 KV 압축: 키에는 채널별 INT4 양자화를 사용하고, 값에는 토큰별 INT4 양자화를 사용하며, 처리하기 어려운 채널에는 fp16 아웃라이어 레인을 사용할 수 있습니다.
적응형 정밀도: TIP 유닛은 토큰 중요도를 추적하고 영역별로 KVQ8, KVQ4 또는 아웃라이어가 포함된 KVQ4를 선택합니다.
공유 행렬 엔진: INT8 시스톨릭 MXE는 디코더 레이어의 행렬 작업 전반에서 시분할 방식으로 사용됩니다.
온라인 소프트맥스: 점수는 컨텍스트 길이만큼의 점수 버퍼 없이 수치적으로 안정적인 소프트맥스 구현을 거쳐 스트리밍됩니다.
비트 단위 정확성 검증: RTL 결과는 불일치를 전혀 허용하지 않는 실행 가능한 NumPy 참조 모델과 비교됩니다.
뮤테이션 테스트된 테스트벤치: 의도적으로 삽입한 RTL 결함으로 테스트가 실패할 때만 검증을 의미 있는 것으로 간주합니다.
시뮬레이션-실리콘 재생: FPGA 레지스터 연산 프로그램은 Verilator 트윈에서도 실행되어 비트 단위 차이를 비교합니다.
명시적인 증거 라벨: 결과는 단일 성능 주장으로 섞지 않고 측정값 또는 예상값으로 분류됩니다.

아키텍처 이해하기

디코드 단계는 활성화 벡터에서 시작합니다. RMSNorm이 입력을 준비하고 MXE가 쿼리, 키, 값 프로젝션을 계산합니다. KVQ 엔진이 저장을 위해 키와 값을 압축하기 전에 RoPE가 쿼리와 키를 변환합니다.

어텐션 중에는 읽기 경로에서 캐시된 값의 압축이 해제됩니다. MXE는 쿼리-키 곱을 계산하고, ASU는 온라인 소프트맥스를 적용하며, 또 다른 MXE 작업은 확률과 캐시된 값을 결합합니다. 출력 프로젝션, 잔차 덧셈, 또 다른 정규화 단계, SwiGLU 피드포워드 경로가 레이어를 완성합니다.

주요 RTL 블록

MXE: 레이어의 행렬 연산에 사용되는 INT8 시스톨릭 GEMM 엔진입니다.
KVQ: KV 캐시 압축 및 압축 해제 엔진입니다.
ASU: 온라인 소프트맥스, RMSNorm, SiLU, SwiGLU를 담당합니다.
RoPE: 쿼리와 키를 위한 회전 위치 임베딩입니다.
TIP: 토큰 중요도 추적 및 정밀도 등급 결정을 담당합니다.
SEQ: 제어 및 상태 레지스터 파일, 작업 디코더, 레이어 워커입니다.
SEAM: 활성화 프레이밍, 경계 양자화, 스케일 전송을 담당합니다.
XBR: 불필요한 호스트 왕복 없이 엔진 간 라우팅을 수행합니다.
TOP: apex_top 구성 레이어 및 통합 로직입니다.

자세한 설계, 결정 레지스터, 모듈 출처는 ARCHITECTURE.md를 참조하세요.

호스트 모드와 워크 모드

APEX는 두 가지 실행 방식을 지원합니다. 호스트 모드에서는 호스트가 각 하드웨어 작업을 개별적으로 구성하고 제출합니다. 이 모드는 FPGA 실리콘에서 검증되었지만, 모든 작업마다 호스트 왕복이 발생합니다.

워크 모드에서는 호스트가 레이어를 한 번 시작합니다. 온타일 레이어 워커가 디스크립터를 가져오고, 엔진 실행 순서를 제어하며, 중간 텐서를 XBR 패브릭을 통해 라우팅하고, 양자화 스케일을 전달합니다. 워크된 레이어는 시뮬레이션에서 비트 단위로 정확합니다. README에 따르면 FPGA에서의 워크 어텐션은 아직 활발한 초기 구동 단계에 있습니다.

호스트 모드와 워크 모드를 동등한 성능 구성으로 간주해서는 안 됩니다. 호스트 모드는 정확성 확인과 초기 구동에 유용하며, 워커는 작업마다 발생하는 상당한 호스트 오버헤드를 제거하기 위한 것입니다.

설치 및 로컬 설정

사전 요구 사항

문서화된 로컬 검증 흐름을 위해 다음을 설치하세요:

Python 3.11
NumPy
Verilator 5.x
GNU Make
Icarus Verilog(선택 사항, 교차 확인용)

체크아웃한 APEX 저장소의 루트에서 명령을 실행하세요. 시작하기 전에 주요 도구가 준비되었는지 확인하세요:

python3 --version
verilator --version
make --version
python3 -c "import numpy; print(numpy.__version__)"

README는 패키지 설치 명령이나 고정된 Python 환경 명령을 제공하지 않습니다. 평가 또는 FPGA 워크플로에서 추가 종속성을 해결할 때는 저장소 자체의 파일과 하위 디렉터리 문서를 사용하세요.

먼저 증거 확인하기

긴 워크플로를 실행하기 전에 프로젝트의 증거와 제한 사항을 검토하세요:

STATUS.md에는 기계 생성 검증 횟수와 측정 결과가 포함되어 있습니다.
TRACEABILITY.md에는 알려진 공백이 기록되어 있으며, 주장을 뒷받침하는 증거로 연결합니다.
마스터 테이블에는 구현 및 초기 구동 상태가 추적됩니다.
결과 인덱스에서는 커밋된 증거를 캠페인별로 정리합니다.

골든 모델 테스트 실행

실행 가능한 NumPy 참조 모델과 고정 벡터부터 시작합니다.

make -C golden test

이 명령은 골든 모델을 실행하며, 고정된 압축 산정 게이트도 포함합니다. APEX는 명목상 INT4 페이로드만 보고하는 것이 아니라 태그, 스케일, 패딩 및 이상치 저장 공간까지 포함하므로 압축 산정이 중요합니다.

RTL 파이프라인 검증

전체 어텐션 타일 스모크 테스트 실행

make -C verif/top/smoke smoke

이는 어텐션 타일을 위한 문서화된 엔드투엔드 스모크 대상입니다. 골든 모델 제품군을 통과한 후 초기 통합 검사로 사용하십시오.

레이어 3 검증 실행

make -C verif/top l3

레이어 3 대상은 제공된 사례 전반에서 실제로 구성된 타일을 골든 모델과 비교합니다. APEX에는 근사 수치 허용 오차가 아니라 비트 단위로 동일한 결과가 필요합니다.

레이어 워커 검증

make -C verif/seq_walker

이 명령은 워커 제품군과 변이 게이트를 실행합니다. 변이 테스트는 동작을 의도적으로 깨뜨린 뒤 검증 환경이 결함을 감지하는지 확인합니다. 살아남은 변이는 성공적인 설계 결과가 아니라 검증 취약성을 의미합니다.

성능 모델 확인

다음 명령으로 분석 모델의 보정 검사를 실행합니다.

python3 perf/apex_perf_model.py --check

성능 모델은 실리콘에서 측정한 성능이 아니라 명시적으로 예측된 성능입니다. 모델의 가정과 보정 기준점은 PERF_MODEL.md에 문서화되어 있습니다.

7B급 읽기 속도 및 에너지 수치의 예측값은 네이티브 W4 가중치 경로, 하드웨어 레이어 워킹, 광폭 LPDDR 통합 등 아직 구축되지 않았거나 불완전한 시스템 구성 요소에 좌우됩니다. 이를 달성된 하드웨어 결과로 제시해서는 안 됩니다.

모델에서 KV 압축 평가

저장소에는 검증된 KV 코덱의 모델 정확도 행렬이 포함되어 있습니다. 0.5B 및 1.5B 행렬은 다음 명령으로 실행합니다.

bash eval/kv_eval/run_matrix.sh

7B 행렬은 다음 명령으로 실행합니다.

bash eval/kv_eval/run_matrix_7b.sh

이 명령을 실행하기 전에 커밋된 결과 파일 옆에 있는 평가 README를 확인하십시오. 공개된 평가는 전체 10,042개 문서로 구성된 HellaSwag 검증 세트를 사용합니다. README에는 소형 모델에서 거의 손실이 없는 동작, 7B에서 KVQ8의 전체 세트 기준 감지 가능한 영향 없음, 7B에서 KVQ4의 측정된 작은 비용이 보고되어 있습니다.

관련 증거는 헤드투헤드 결과와 7B 평가 결과에서 확인할 수 있습니다.

골든 파이프라인에서 모델 실행

프로젝트에서는 run_tinynpu.py --prompt를 사용한 프롬프트 실행을 문서화합니다. 이 명령은 고정소수점 골든 파이프라인을 통해 Qwen 토큰을 탐욕적으로 스트리밍하며, 재생을 위한 하드웨어 형태의 작업을 생성할 수 있습니다.

run_tinynpu.py --prompt

README의 최상위 지침에는 완전한 모델 설정이나 모든 명령줄 인수가 제공되어 있지 않으므로, 정확한 범위, 산출물 및 재현 세부 정보는 7B 토큰 산출물 문서를 따르십시오. 이 7B 흐름은 소프트웨어로 검증된 것이며 FPGA 타일에서 7B를 실행했다는 주장이 아님을 기억하십시오.

AWS F2 데모 실행

요구 사항 및 비용

FPGA 데모를 실행하려면 us-west-2의 f2.6xlarge 인스턴스에 액세스할 수 있는 AWS CLI 자격 증명이 필요합니다. README에서는 전체 실행에 약 30분과 약 2달러가 소요될 것으로 예상합니다.

문서화된 참조 FPGA 이미지는 agfi-030a812cd224b409d입니다. 이 이미지는 15.625 MHz 타일 클록을 사용하는 A2 레시피를 사용합니다.

검증 배터리 실행

bash scripts/fpga/f2/run_walked_demo.sh agfi-030a812cd224b409d

이 스크립트는 FPGA 인스턴스를 부팅하고 이미지를 로드한 뒤, 문서화된 검증 배터리와 워크 체인을 실행하고 판정 결과를 출력한 다음 인스턴스를 종료합니다.

대화형 프롬프트 데모 시작

bash scripts/fpga/f2/run_chat_demo.sh

대화형 데모는 워크 파이프라인을 사용합니다. README에는 The capital of France is가 예시 프롬프트로 제시되어 있으며, 채점된 응답은 Paris.으로 보고되어 있습니다.

DDR 이미지는 mlx-community/Qwen2.5-0.5B-Instruct-4bit에서 파생됩니다. 팀 스테이징 산출물은 스크립트에 구성되어 있습니다. 외부 사용자는 다음 명령으로 가중치 이미지를 생성해야 합니다.

python3 scripts/fpga/f2/make_weight_image.py

팀의 스테이징 버킷에 액세스할 수 있다고 가정하지 말고, 생성된 이미지를 사용자가 관리하는 버킷에 맞게 구성하십시오.

하드웨어 결과를 올바르게 해석하기

저장소에는 62.5 MHz의 A0 이미지에서 초당 0.56토큰, 15.625 MHz의 A2 참조 이미지에서 초당 0.25토큰이라는 측정 처리량이 보고되어 있습니다. 또한 호스트 구동 기준선인 초당 0.004토큰에서 측정된 향상 과정도 보고합니다.

이 수치는 특정 FPGA 이미지, 클록 및 실행 경로를 나타냅니다. 인용하기 전에 FIRST_WALKED_TOKENS.md를 확인하고, 관련 구성과 측정 라벨을 그대로 유지하십시오.

고급 팁

골든 모델을 기준 판정기로 사용

RTL 블록을 변경할 때는 먼저 실행 가능한 사양을 업데이트하거나 검증하고, 저장소의 요구 사항에 따라 벡터를 재생성하거나 확인한 다음 RTL 출력을 비트 단위로 비교하세요. 프로젝트에 문서화된 산술 계약에서 명시적으로 요구하지 않는 한 허용 오차 기반 검사를 도입하지 마세요.

변이 커버리지 유지

APEX 방법론에서는 회귀 테스트 통과만으로 충분하지 않습니다. 테스트벤치, 스코어보드, 시퀀서 또는 산술 블록을 변경한 후에는 관련 변이 검증 게이트를 실행하세요. 의도적으로 오류를 넣은 구현이 통과한다면 원래의 정상 결과를 신뢰하기 전에 검증을 강화하세요.

환경 간 동일한 작업 재실행

APEX 작업은 셰이프, 라우팅 및 양자화 계약을 포함하는 자체 설명형 작업 디스크립터를 사용합니다. 불일치를 진단할 때는 디스크립터, 스케일 및 레지스터 연산을 보존하세요. Verilator F2 트윈과 하드웨어에서 동일한 플라이트를 재실행하는 것이 RTL 결함과 합성 또는 툴체인 결함을 구분하는 가장 좋은 방법입니다.

텐서 데이터와 함께 스케일 추적

양자화 스케일은 부수적인 메타데이터가 아니라 하드웨어 계약의 일부입니다. 작업을 생성하거나 검사할 때 경계를 통과하는 스케일 정보를 보존하세요. 해당 스케일이 없는 텐서는 의도한 고정소수점 연산을 재현할 수 없습니다.

코덱 페이로드와 전체 저장 공간 구분

INT4 페이로드만으로 압축률을 계산하지 마세요. 스케일 뱅크, 태그, 패딩, 정밀도 메타데이터 및 이상치 레인을 포함하세요. 게시되는 비율의 권위 있는 근거로 저장소의 골든 회계 게이트와 STATUS.md를 사용하세요.

모델 크기와 실행 주장 분리

Qwen2.5-0.5B: 프로젝트에서 설명하는 FPGA 기반 파이프라인을 통해 시연되었습니다.
Qwen2.5-7B: 소프트웨어로 검증된 골든 파이프라인을 통해 실행되었습니다.
7B급 아키텍처 프로젝션: 타일을 중심으로 한 더 큰 시스템에 대한 분석적 프로젝션이며, 현재 FPGA 구현에서 측정한 성능이 아닙니다.

워커를 확장하기 전에 가중치 스트리밍 검토

모델 가중치는 타일에 모두 들어가지 않습니다. IB-FUEL 설계는 작업별 가중치 레코드를 DDR에서 온타일 FIFO로 스트리밍하며, W4 경로는 4비트 그룹을 전송하고 이를 언팩하여 INT8 행렬 엔진에 공급합니다. 스케줄링 또는 피더 동작을 수정하기 전에 IB_FUEL.md 및 W4_DATAPATH.md를 검토하세요.

저장소 레이아웃을 효율적으로 사용

rtl/에는 하드웨어 구현이 들어 있습니다.
golden/에는 비트 단위로 일치하는 NumPy 참조 모델이 들어 있습니다.
verif/에는 테스트벤치, 어서션, 스코어보드, 변이 게이트 및 F2 시뮬레이션 트윈이 들어 있습니다.
eval/에는 코덱의 모델 정확도 평가 도구가 들어 있습니다.
perf/에는 분석적으로 추정한 성능 모델이 들어 있습니다.
scripts/fpga/에는 빌드, 이미지, DDR 로딩, 플라이트 및 토큰 루프 스크립트가 들어 있습니다.
docs/results/에는 커밋된 캠페인 증거가 들어 있습니다.

현재 제한 사항 및 로드맵

현재 로드맵은 FPGA에서의 워크드 어텐션 검증, 더 빠른 타이밍 클로저, 지속적인 가중치 스트리밍, 엔드투엔드 W4 지원, 추가적인 토큰 레이트 측정 작업 및 Sky130 사인오프 준비를 우선시합니다. 최신 상태는 마스터 테이블에서 관리됩니다.

로드맵 항목이 완료되었다고 가정하지 마세요. 특히 README는 전체 워크드 어텐션 하드웨어 초기 구동과 여러 대역폭 관련 종속 항목이 진행 중인 작업임을 명시합니다.

결론

APEX는 트랜스포머 디코더 타일의 RTL 구현인 동시에 증거 기반 하드웨어 검증의 사례 연구입니다. 가장 두드러진 특징은 키와 값을 압축된 형태로 저장하면서도 검증된 어텐션 데이터패스의 일부로 유지하는 통합 KV 캐시 코덱입니다.

골든 테스트부터 시작한 다음 타일 및 워커 검증을 실행하고 측정된 증거를 점검하세요. 추가 아티팩트가 준비된 경우에만 모델 또는 FPGA 워크플로로 진행하세요. 측정된 FPGA 결과와 분석적 프로젝션을 분리하고, 주장을 제시할 때는 프로젝트의 추적성 문서를 사용하세요.

APEX는 Apache License 2.0에 따라 배포됩니다. 적용되는 조건과 고지는 LICENSE를 참조하세요.