跳到主要内容
AI教程

构建并验证开放式 RTL LLM 推理 Tile：APEX

了解 APEX 如何用 RTL 实现 Transformer 解码器层、在注意力数据通路中压缩 KV 缓存，并依据可执行 NumPy 模型验证各模块。

AI我搜编辑部阅读约 13 分钟
APEX 开放式 RTL LLM 推理 Tile

APEX 的功能

APEX 是一款完全开放、验证优先的 LLM 推理 Tile。它使用真实 RTL 实现一个 Transformer 解码器层，包括注意力、KV 缓存压缩、在线 softmax、RMSNorm、旋转位置嵌入、SwiGLU、残差连接和矩阵运算。

该项目针对边缘推理中的一个主要瓶颈：随着对话增长，每生成一个新 token，都必须读取越来越大的键值缓存。APEX 将 KV 编解码器直接置于硬件数据通路中。键和值在生成时被压缩，以压缩形式存储，并在注意力机制使用它们时进行解压缩。

APEX 是一个推理 Tile，而不是完整的加速器芯片。DRAM 控制器、PCIe 和片上网络不在该代码仓库声明的范围内。

该 Tile 已在 FPGA 硬件上使用 Qwen2.5-0.5B 完成演示。Qwen2.5-7B token 已通过软件验证的黄金流水线，但 README 并未声称 7B 模型已在硅片上运行。

主要特性

  • 完整的解码器层数据通路：RTL 涵盖投影、注意力、归一化、RoPE、前馈计算、残差运算和 KV 缓存处理。
  • 数据通路内 KV 压缩：键采用逐通道 INT4 量化，值采用逐 token INT4 量化，而难以量化的通道可以使用 fp16 离群值通道。
  • 自适应精度：TIP 单元跟踪 token 重要性，并按区域选择 KVQ8、KVQ4 或带离群值的 KVQ4。
  • 共享矩阵引擎：INT8 脉动阵列 MXE 以时分复用方式处理解码器层中的各项矩阵任务。
  • 在线 softmax：分数以流式方式通过数值稳定的 softmax 实现，无需使用大小与上下文长度相同的分数缓冲区。
  • 逐位精确验证：将 RTL 结果与可执行 NumPy 参考模型进行比较，不允许出现任何不匹配。
  • 经过变异测试的测试平台：只有在故意引入 RTL 缺陷会导致测试失败时，验证才被视为有效。
  • 从仿真到硅片的重放：FPGA 寄存器操作程序也会在 Verilator 孪生模型中运行，以进行逐位差分比较。
  • 明确的证据标签：结果被归类为实测或预测，而不是混合成单一的性能声明。

了解架构

解码步骤从一个激活向量开始。RMSNorm 对输入进行预处理，MXE 计算查询、键和值的投影。RoPE 对查询和键进行变换，然后 KVQ 引擎压缩键和值以供存储。

在注意力计算期间，缓存的值会在读取路径中解压缩。MXE 计算查询与键的乘积，ASU 应用在线 softmax，另一个 MXE 任务将概率与缓存值相结合。输出投影、残差相加、另一个归一化阶段以及 SwiGLU 前馈路径共同完成该层。

主要 RTL 模块

  • MXE：用于层内矩阵运算的 INT8 脉动阵列 GEMM 引擎。
  • KVQ：KV 缓存压缩和解压缩引擎。
  • ASU：在线 softmax、RMSNorm、SiLU 和 SwiGLU。
  • RoPE：用于查询和键的旋转位置嵌入。
  • TIP：token 重要性跟踪与精度层级决策。
  • SEQ：控制与状态寄存器文件、任务解码器和层遍历器。
  • SEAM：激活数据成帧、边界量化和尺度传输。
  • XBR：在引擎之间进行路由，无需不必要的主机往返。
  • TOP：apex_top 组合层和集成逻辑。

有关详细设计、决策记录和模块来源，请阅读 ARCHITECTURE.md。

主机模式与遍历模式

APEX 支持两种执行方式。在主机模式下，主机单独构建并提交每个硬件任务。该模式已在 FPGA 硅片上得到验证，但每个任务都会产生一次主机往返。

在遍历模式下，主机只需启动一次层执行。Tile 上的层遍历器获取描述符、对引擎进行排序、通过 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 流水线

运行完整的注意力 Tile 冒烟测试

make -C verif/top/smoke smoke

这是文档中为注意力 Tile 提供的端到端冒烟测试目标。黄金模型测试套件通过后，可将其用作初始集成检查。

运行第 3 层验证

make -C verif/top l3

第 3 层目标会在所提供的测试用例中，将真实的组合 Tile 与黄金模型进行比较。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 报告称，较小模型的表现接近无损；KVQ8 在 7B 完整数据集上没有可检测到的影响；KVQ4 在 7B 上则有小幅实测代价。

相关证据可参见正面对比结果和7B 评估结果。

通过黄金流水线运行模型

项目记录了使用 run_tinynpu.py --prompt 执行提示词的方法。该命令通过定点黄金流水线流式传输贪心解码的 Qwen token，并可生成具有硬件格式的任务以供重放。

run_tinynpu.py --prompt

README 的顶层说明未提供完整的模型设置或全部命令行参数，因此请按照7B token 工件文档了解确切范围、工件和复现细节。请记住，此 7B 流程经过软件验证，并不表示 7B 模型已在 FPGA Tile 上执行。

运行 AWS F2 演示

要求和成本

FPGA 演示需要 AWS CLI 凭证，并且该凭证必须有权访问 us-west-2 区域中的 f2.6xlarge 实例。README 估计完整运行大约需要 30 分钟，成本约为 2 美元。

文档指定的参考 FPGA 镜像为 agfi-030a812cd224b409d。它使用 A2 配置，Tile 时钟频率为 15.625 MHz。

运行验证测试组

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 个 token；在频率为 15.625 MHz 的 A2 参考镜像上，实测吞吐量为每秒 0.25 个 token。它还报告了相较于主机驱动基线每秒 0.004 个 token 的实测提升过程。

这些数据描述的是特定 FPGA 镜像、时钟频率和执行路径。引用前请查看 FIRST_WALKED_TOKENS.md，并保留相关配置和“实测”标签。

高级技巧

将黄金模型作为裁决依据

修改 RTL 模块时，应先更新或验证可执行规范，根据代码仓库要求重新生成或确认测试向量，并逐位比较 RTL 输出。除非项目记录的算术约定明确要求，否则应避免引入基于容差的检查。

保持变异测试覆盖率

按照 APEX 方法，仅仅让回归测试通过还不够。修改测试平台、记分板、定序器或算术模块后，请运行相关变异关卡。如果故意破坏的实现仍能通过测试，应先加强验证，再相信原本通过的结果。

在不同环境中重放同一任务

APEX 操作使用自描述任务描述符，其中包含形状、路由和量化约定。诊断不匹配时，请保留描述符、尺度和寄存器操作。首选方法是在 Verilator F2 孪生模型和硬件上重放同一任务，以区分 RTL 缺陷与综合或工具链缺陷。

让尺度与张量数据一同传递

量化尺度是硬件约定的一部分，而不是无关紧要的元数据。创建或检查任务时，请保留经由接口传输的尺度信息。缺少对应尺度的张量无法复现预期的定点运算。

区分编解码器有效载荷与总存储量

不要只根据 INT4 有效载荷计算压缩率。还应计入尺度库、标签、填充、精度元数据和离群值通道。发布压缩率时，应以代码仓库的黄金核算关卡和 STATUS.md 为权威依据。

区分模型规模与执行声明

  • Qwen2.5-0.5B：已通过项目所述的 FPGA 支持流水线完成演示。
  • Qwen2.5-7B：已通过软件验证的黄金流水线运行。
  • 7B 级架构预测：针对围绕该 Tile 构建的更大型系统所做的分析预测，并非当前 FPGA 实现的实测性能。

扩展遍历器前先研究权重流式传输

模型权重无法全部放入 Tile。IB-FUEL 设计将逐任务权重记录从 DDR 流式传输到 Tile 上的 FIFO，而 W4 路径则传输四位分组，并将其解包供 INT8 矩阵引擎使用。修改调度或供数器行为之前，请查看 IB_FUEL.md 和 W4_DATAPATH.md。

高效使用代码仓库目录结构

  • rtl/ 包含硬件实现。
  • golden/ 包含逐位精确的 NumPy 参考模型。
  • verif/ 包含测试平台、断言、记分板、变异关卡和 F2 仿真孪生模型。
  • eval/ 包含编解码器的模型准确率评估工具。
  • perf/ 包含预测性分析性能模型。
  • scripts/fpga/ 包含构建、镜像、DDR 加载、任务和 token 循环脚本。
  • docs/results/ 包含已提交的测试活动证据。

当前限制与路线图

当前路线图优先推进 FPGA 上的遍历式注意力验证、更快的时序收敛、持续权重流式传输、端到端 W4 支持、更多 token 速率实测工作，以及 Sky130 签核准备。最新状态维护在主表中。

不要假定路线图项目已经完成。特别是，README 将完整的遍历式注意力硬件初始调试和多个带宽相关依赖项列为进行中的工作。

总结

APEX 既是 Transformer 解码器 Tile 的 RTL 实现，也是证据驱动型硬件验证的案例研究。其最具特色的功能是集成式 KV 缓存编解码器，它以压缩形式存储键和值，同时仍是已验证注意力数据通路的一部分。

首先运行黄金测试，然后进行 Tile 和遍历器验证并检查实测证据；只有在额外工件可用时，才继续开展模型或 FPGA 工作流程。请将 FPGA 实测结果与分析预测分开，并在陈述任何声明时参考项目的可追溯性文档。

APEX 根据 Apache License 2.0 发布。有关适用条款和声明，请参阅 LICENSE。