メインコンテンツへ移動
AIチュートリアル

オープンRTL LLM推論タイル「APEX」を構築・検証する

APEXがRTLでトランスフォーマーデコーダ層を実装し、アテンションデータパス内でKVキャッシュを圧縮し、実行可能なNumPyモデルと照合して各ブロックを検証する方法を解説します。本チュートリアルでは、アーキテクチャ、ローカル環境のセットアップ、検証コマンド、モデル評価、FPGAデモ、実測値と予測値を読み解くための実践的な指針を取り上げます。

約19分で読了
オープンRTL LLM推論タイル「APEX」を構築・検証する

APEXの概要

APEXは、検証を第一に設計した完全オープンなLLM推論タイルです。アテンション、KVキャッシュ圧縮、オンラインsoftmax、RMSNorm、回転位置埋め込み、SwiGLU、残差接続、行列演算を含む、トランスフォーマーデコーダーの1層を実際のRTLで実装しています。

このプロジェクトは、エッジ推論における主要なボトルネックを対象としています。会話が長くなるほど、新しいトークンは増大するキー・バリューキャッシュを読み取らなければなりません。APEXはKVコーデックをハードウェアデータパスに直接組み込みます。キーと値は生成時に圧縮され、圧縮形式で保存され、アテンション処理中に展開されます。

APEXは1つの推論タイルであり、完全なアクセラレータチップではありません。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は、デコーダー層内の行列ジョブ間で時分割多重化されます。
  • オンラインsoftmax: スコアは数値的に安定したsoftmax実装を通過するため、コンテキスト長に相当するサイズのスコアバッファは不要です。
  • ビット完全検証: RTLの結果は、実行可能なNumPyリファレンスモデルと比較され、不一致はゼロ件まで許容されます。
  • ミューテーションテスト済みテストベンチ: 意図的にRTLの欠陥を入れたときにテストが失敗して初めて、検証は有意義なものとみなされます。
  • シミュレーションからシリコンへのリプレイ: FPGAのレジスター操作プログラムはVerilatorツインでも実行され、ビット単位の差分比較が行われます。
  • 明示的な証拠ラベル: 結果は、単一の性能主張に混在させず、実測値または予測値として分類されます。

アーキテクチャを理解する

デコードステップはアクティベーションベクトルから始まります。RMSNormで入力を整え、MXEがクエリ、キー、値の射影を計算します。KVQエンジンがキーと値を圧縮して保存する前に、RoPEがクエリとキーを変換します。

アテンション処理では、キャッシュされた値が読み出しパスで展開されます。MXEがクエリとキーの積を計算し、ASUがオンラインsoftmaxを適用し、別のMXEジョブが確率とキャッシュされた値を組み合わせます。出力射影、残差加算、もう一段の正規化、SwiGLUフィードフォワードパスによって層が完成します。

主なRTLブロック

  • MXE: 層の行列演算に使用されるINT8シストリックGEMMエンジン。
  • KVQ: KVキャッシュの圧縮・展開エンジン。
  • ASU: オンラインsoftmax、RMSNorm、SiLU、SwiGLU。
  • RoPE: クエリとキーの回転位置埋め込み。
  • TIP: トークン重要度の追跡と精度ティアの決定。
  • SEQ: 制御・ステータスレジスタファイル、ジョブデコーダー、層ウォーカー。
  • SEAM: アクティベーションのフレーミング、境界量子化、スケール転送。
  • XBR: 不要なホスト往復を避ける、エンジン間のルーティング。
  • TOP: apex_topの構成レイヤーと統合ロジック。

詳細な設計、意思決定記録、モジュールの出典についてはARCHITECTURE.mdを参照してください。

ホストモードとウォークモード

APEXは2つの実行方式をサポートしています。ホストモードでは、ホストが各ハードウェアジョブを個別に構築して送信します。このモードは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

これはアテンションタイル向けに文書化されたエンドツーエンドのスモークターゲットです。ゴールデンモデルスイートの合格後、初期統合チェックとして使用します。

Layer-3検証を実行する

make -C verif/top l3

Layer-3ターゲットは、提供されたケース全体で、実際に構成されたタイルとゴールデンモデルを比較します。APEXでは、近似的な数値許容差ではなく、ビット単位で同一の結果が必要です。

Layer Walkerを検証する

make -C verif/seq_walker

このコマンドは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です。A2レシピと15.625 MHzのタイルクロックを使用します。

検証バッテリーを実行する

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

このスクリプトはFPGAインスタンスを起動し、イメージをロードし、文書化された検証バッテリーとwalkerチェーンを実行し、判定結果を表示して、インスタンスを終了します。

対話型プロンプトデモを開始する

bash scripts/fpga/f2/run_chat_demo.sh

対話型デモではwalkerパイプラインを使用します。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を参照してください。