Xây dựng và xác minh APEX, một tile suy luận LLM RTL mở

APEX làm gì

APEX là một tile suy luận LLM hoàn toàn mở, ưu tiên xác minh. Nó triển khai một lớp decoder transformer bằng RTL thực, bao gồm attention, nén KV-cache, softmax trực tuyến, RMSNorm, embedding vị trí xoay, SwiGLU, kết nối residual và các phép toán ma trận.

Dự án nhắm đến một nút thắt lớn trong suy luận biên: khi cuộc hội thoại dài hơn, mỗi token mới phải đọc một KV-cache ngày càng lớn. APEX đặt bộ mã hóa KV trực tiếp trong đường dữ liệu phần cứng. Key và value được nén khi tạo ra, lưu trữ dưới dạng nén và giải nén khi attention sử dụng chúng.

APEX là một tile suy luận, không phải một chip tăng tốc hoàn chỉnh. Bộ điều khiển DRAM, PCIe và mạng trên chip nằm ngoài phạm vi được nêu của repository.

Tile đã được trình diễn với Qwen2.5-0.5B trên phần cứng FPGA. Các token Qwen2.5-7B đã đi qua pipeline chuẩn được xác minh bằng phần mềm, nhưng README không tuyên bố rằng mô hình 7B đã chạy trên silicon.

Tính năng chính

• Đường dữ liệu lớp decoder hoàn chỉnh: RTL bao quát phép chiếu, attention, chuẩn hóa, RoPE, tính toán feed-forward, phép toán residual và xử lý KV-cache.
• Nén KV ngay trong đường dữ liệu: Key sử dụng lượng tử hóa INT4 theo từng kênh, value sử dụng lượng tử hóa INT4 theo từng token; các kênh khó có thể dùng lane ngoại lệ fp16.
• Độ chính xác thích ứng: Khối TIP theo dõi mức độ quan trọng của token và chọn KVQ8, KVQ4 hoặc KVQ4 kèm ngoại lệ theo từng vùng.
• Engine ma trận dùng chung: MXE tâm sai INT8 được phân chia theo thời gian cho các tác vụ ma trận trong một lớp decoder.
• Softmax trực tuyến: Các điểm số chạy qua triển khai softmax ổn định về số học mà không cần bộ đệm điểm số có kích thước theo độ dài ngữ cảnh.
• Xác minh chính xác từng bit: Kết quả RTL được so sánh với các mô hình tham chiếu NumPy có thể thực thi, không cho phép bất kỳ sai khác nào.
• Testbench kiểm thử đột biến: Việc xác minh chỉ được xem là có ý nghĩa khi các lỗi RTL được cố ý đưa vào khiến kiểm thử thất bại.
• Phát lại từ mô phỏng đến silicon: Các chương trình thao tác thanh ghi FPGA cũng chạy trên bản sao Verilator để so sánh sai khác từng bit.
• Nhãn bằng chứng rõ ràng: Kết quả được phân loại là đo được hoặc dự phóng, thay vì trộn thành một tuyên bố hiệu năng duy nhất.

Tìm hiểu kiến trúc

Một bước giải mã bắt đầu với vector activation. RMSNorm chuẩn bị đầu vào, còn MXE tính các phép chiếu query, key và value. RoPE biến đổi query và key trước khi engine KVQ nén key và value để lưu trữ.

Trong attention, các value được lưu trong cache được giải nén trên đường đọc. MXE tính tích query-key, ASU áp dụng softmax trực tuyến, và một tác vụ MXE khác kết hợp xác suất với các value được lưu trong cache. Phép chiếu đầu ra, phép cộng residual, một giai đoạn chuẩn hóa khác và đường dẫn feed-forward SwiGLU hoàn tất lớp này.

Các khối RTL chính

• MXE: Engine GEMM tâm sai INT8 dùng cho các phép toán ma trận của lớp.
• KVQ: Engine nén và giải nén KV-cache.
• ASU: Softmax trực tuyến, RMSNorm, SiLU và SwiGLU.
• RoPE: Embedding vị trí xoay cho query và key.
• TIP: Theo dõi mức độ quan trọng của token và quyết định tầng độ chính xác.
• SEQ: Tập thanh ghi điều khiển và trạng thái, bộ giải mã tác vụ và bộ duyệt lớp.
• SEAM: Định khung activation, lượng tử hóa ranh giới và truyền scale.
• XBR: Định tuyến giữa các engine mà không cần các lượt quay về host không cần thiết.
• TOP: Lớp kết hợp apex_top và logic tích hợp.

Đọc ARCHITECTURE.md để xem thiết kế chi tiết, sổ đăng ký quyết định và nguồn gốc các module.

Chế độ host và chế độ walked

APEX hỗ trợ hai phương thức thực thi. Ở chế độ host, host tạo và gửi từng tác vụ phần cứng riêng lẻ. Chế độ này đã được chứng minh trên silicon FPGA, nhưng mỗi tác vụ đều phát sinh một lượt quay về host.

Ở chế độ walked, host khởi động một lớp duy nhất. Bộ duyệt lớp trên tile sẽ lấy các descriptor, điều phối các engine, định tuyến tensor trung gian qua fabric XBR và truyền các scale lượng tử hóa. Lớp walked chính xác từng bit trong mô phỏng. README cho biết attention walked trên FPGA vẫn đang được tích cực bring-up.

Không nên xem chế độ host và chế độ walked là các cấu hình hiệu năng tương đương. Chế độ host hữu ích cho việc kiểm tra tính đúng đắn và bring-up, còn bộ walker được thiết kế để loại bỏ phần lớn chi phí host cho mỗi tác vụ.

Cài đặt và thiết lập cục bộ

Điều kiện tiên quyết

Để thực hiện quy trình xác minh cục bộ được tài liệu hóa, hãy cài đặt:

• Python 3.11
• NumPy
• Verilator 5.x
• GNU Make
• Icarus Verilog, tùy chọn, để đối chiếu

Chạy các lệnh từ thư mục gốc của repository APEX đã checkout. Xác nhận các công cụ chính trước khi bắt đầu:

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

README không cung cấp lệnh cài đặt package hoặc lệnh tạo môi trường Python được ghim phiên bản. Hãy sử dụng các file riêng của repository và tài liệu trong các thư mục con khi xử lý các dependency bổ sung cho quy trình đánh giá hoặc FPGA.

Kiểm tra bằng chứng trước

Trước khi chạy một quy trình dài, hãy xem xét các bằng chứng và giới hạn của dự án:

• STATUS.md chứa số liệu xác minh do máy tạo và các kết quả đo được.
• TRACEABILITY.md ghi lại các khoảng trống đã biết và liên kết các nhận định với bằng chứng hỗ trợ.
• Bảng tổng hợp theo dõi trạng thái triển khai và khởi động.
• Mục lục kết quả sắp xếp bằng chứng đã cam kết theo từng chiến dịch.

Chạy các bài kiểm thử mô hình chuẩn

Bắt đầu với các mô hình tham chiếu NumPy có thể thực thi và các vector cố định:

make -C golden test

Lệnh này kiểm tra các mô hình chuẩn và bao gồm cổng kiểm soát hạch toán nén đã được cố định. Hạch toán nén rất quan trọng vì APEX bao gồm thẻ, hệ số tỷ lệ, phần đệm và dữ liệu lưu trữ ngoại lệ, thay vì chỉ báo cáo payload INT4 danh nghĩa.

Xác minh pipeline RTL

Chạy kiểm thử smoke toàn bộ attention tile

make -C verif/top/smoke smoke

Đây là mục tiêu smoke đầu-cuối được tài liệu hóa cho attention tile. Hãy dùng mục tiêu này làm bước kiểm tra tích hợp ban đầu sau khi bộ kiểm thử mô hình chuẩn đã chạy thành công.

Chạy xác minh Layer-3

make -C verif/top l3

Mục tiêu Layer-3 so sánh tile được ghép thực tế với mô hình chuẩn trên các trường hợp được cung cấp. APEX yêu cầu kết quả giống hệt từng bit thay vì dung sai số gần đúng.

Xác minh bộ duyệt layer

make -C verif/seq_walker

Lệnh này chạy bộ kiểm thử walker và các cổng kiểm soát đột biến. Kiểm thử đột biến cố ý phá vỡ hành vi rồi kiểm tra xem môi trường xác minh có phát hiện lỗi hay không. Một mutant tồn tại cho thấy điểm yếu trong xác minh, không phải kết quả thiết kế thành công.

Kiểm tra mô hình hiệu năng

Chạy các kiểm tra hiệu chuẩn của mô hình phân tích bằng lệnh:

python3 perf/apex_perf_model.py --check

Mô hình hiệu năng là dự phóng, không phải hiệu năng silicon đo được. Các giả định và mốc hiệu chuẩn của mô hình được ghi lại trong PERF_MODEL.md.

Các con số dự phóng về tốc độ đọc và năng lượng cho lớp 7B phụ thuộc vào những thành phần hệ thống chưa được xây dựng hoặc chưa hoàn thiện, bao gồm đường dẫn trọng số W4 gốc, cơ chế duyệt layer bằng phần cứng và tích hợp LPDDR băng rộng. Không nên trình bày chúng như kết quả phần cứng đã đạt được.

Đánh giá nén KV trên các mô hình

Kho lưu trữ bao gồm các ma trận độ chính xác mô hình cho codec KV đã được xác minh. Chạy ma trận 0.5B và 1.5B bằng lệnh:

bash eval/kv_eval/run_matrix.sh

Chạy ma trận 7B bằng lệnh:

bash eval/kv_eval/run_matrix_7b.sh

Hãy đọc các README đánh giá nằm cạnh các tệp kết quả đã cam kết trước khi chạy các lệnh này. Bản đánh giá đã công bố sử dụng toàn bộ tập xác thực HellaSwag gồm 10,042 tài liệu. README báo cáo hành vi gần như không suy giảm đối với các mô hình nhỏ hơn, không phát hiện ảnh hưởng trên toàn bộ tập đối với KVQ8 ở 7B và một tổn phí nhỏ được đo đối với KVQ4 ở 7B.

Bằng chứng liên quan có tại kết quả đối đầu và kết quả đánh giá 7B.

Chạy một mô hình qua pipeline chuẩn

Dự án hướng dẫn thực thi prompt bằng run_tinynpu.py --prompt. Lệnh này truyền các token Qwen tham lam qua pipeline chuẩn dấu phẩy động cố định và có thể tạo các job có hình dạng phần cứng để phát lại.

run_tinynpu.py --prompt

README không cung cấp thiết lập mô hình đầy đủ hoặc mọi đối số dòng lệnh trong hướng dẫn cấp cao nhất, vì vậy hãy làm theo tài liệu artifact token 7B để biết chính xác phạm vi, artifact và chi tiết tái hiện. Lưu ý rằng luồng 7B này được xác minh bằng phần mềm; đây không phải tuyên bố rằng tile FPGA thực thi 7B.

Chạy bản trình diễn AWS F2

Yêu cầu và chi phí

Bản trình diễn FPGA yêu cầu thông tin xác thực AWS CLI có quyền truy cập vào một instance f2.6xlarge trong us-west-2. README ước tính một lần chạy đầy đủ mất khoảng 30 phút và tốn khoảng hai đô la Mỹ.

Ảnh FPGA tham chiếu được tài liệu hóa là agfi-030a812cd224b409d. Ảnh này sử dụng công thức A2 với xung nhịp tile 15.625 MHz.

Chạy bộ kiểm tra xác minh

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

Script khởi động instance FPGA, nạp ảnh, chạy bộ kiểm tra xác minh và các chuỗi walked được tài liệu hóa, in kết luận rồi chấm dứt instance.

Bắt đầu bản trình diễn prompt tương tác

bash scripts/fpga/f2/run_chat_demo.sh

Bản trình diễn tương tác sử dụng pipeline walked. README đưa ra The capital of France is làm prompt ví dụ và báo cáo phản hồi được chấm điểm là Paris..

Các ảnh DDR được tạo từ mlx-community/Qwen2.5-0.5B-Instruct-4bit. Các artifact staging của nhóm được cấu hình trong các script. Người dùng bên ngoài nên tạo ảnh trọng số bằng:

python3 scripts/fpga/f2/make_weight_image.py

Hãy cấu hình ảnh kết quả cho một bucket do bạn kiểm soát, thay vì giả định có quyền truy cập vào bucket staging của nhóm.

Diễn giải đúng kết quả phần cứng

Kho lưu trữ báo cáo thông lượng đo được là 0.56 token mỗi giây trên ảnh A0 ở 62.5 MHz và 0.25 token mỗi giây trên ảnh tham chiếu A2 ở 15.625 MHz. Kho cũng báo cáo mức cải thiện đo được từ đường cơ sở do máy chủ điều khiển ở 0.004 token mỗi giây.

Các con số này mô tả những ảnh FPGA, xung nhịp và đường dẫn thực thi cụ thể. Hãy kiểm tra FIRST_WALKED_TOKENS.md trước khi trích dẫn, đồng thời giữ lại cấu hình và nhãn đo tương ứng.

Mẹo nâng cao

Dùng mô hình chuẩn làm trọng tài

Khi thay đổi một khối RTL, trước tiên hãy cập nhật hoặc xác thực đặc tả thực thi, tạo lại hoặc xác nhận các vector theo yêu cầu của kho mã, rồi so sánh đầu ra RTL theo từng bit. Tránh đưa vào các phép kiểm tra dựa trên dung sai, trừ khi hợp đồng số học được tài liệu hóa của dự án yêu cầu rõ ràng.

Duy trì Độ bao phủ Đột biến

Một hồi quy vượt qua là chưa đủ theo phương pháp APEX. Hãy chạy các cổng đột biến liên quan sau khi thay đổi testbench, scoreboard, sequencer hoặc khối số học. Nếu một triển khai bị cố ý làm hỏng vẫn vượt qua, hãy tăng cường xác minh trước khi tin tưởng kết quả xanh ban đầu.

Phát lại Cùng một Tác vụ trên các Môi trường

Các hoạt động APEX sử dụng bộ mô tả tác vụ tự mô tả, bao gồm các hình dạng, định tuyến và hợp đồng lượng tử hóa. Giữ nguyên bộ mô tả, hệ số tỷ lệ và các thao tác thanh ghi khi chẩn đoán sai lệch. Phát lại cùng một chuyến chạy trên bản sao F2 Verilator và trên phần cứng là cách ưu tiên để phân biệt lỗi RTL với lỗi tổng hợp hoặc lỗi chuỗi công cụ.

Theo dõi Hệ số Tỷ lệ cùng Dữ liệu Tensor

Các hệ số tỷ lệ lượng tử hóa là một phần của hợp đồng phần cứng, không phải siêu dữ liệu không đáng kể. Khi tạo hoặc kiểm tra tác vụ, hãy giữ lại thông tin tỷ lệ đi qua các điểm giao tiếp. Một tensor không có hệ số tỷ lệ tương ứng không thể tái tạo phép toán dấu phẩy cố định dự kiến.

Phân biệt Payload Codec với Tổng Dung lượng Lưu trữ

Không tính độ nén chỉ từ các payload INT4. Hãy bao gồm các ngân hàng hệ số tỷ lệ, thẻ, phần đệm, siêu dữ liệu độ chính xác và các lane ngoại lệ. Sử dụng cổng kiểm kê chuẩn của kho mã và STATUS.md làm cơ sở có thẩm quyền cho các tỷ lệ được công bố.

Tách biệt Kích thước Mô hình và Tuyên bố Thực thi

• Qwen2.5-0.5B: Được minh chứng thông qua pipeline dựa trên FPGA do dự án mô tả.
• Qwen2.5-7B: Được thực thi thông qua pipeline chuẩn vàng đã được xác minh bằng phần mềm.
• Các dự phóng kiến trúc cấp 7B: Các dự phóng phân tích cho một hệ thống lớn hơn xoay quanh tile, không phải hiệu năng đo được từ triển khai FPGA hiện tại.

Nghiên cứu Truyền Trọng số trước khi Mở rộng Walker

Trọng số mô hình không thể nằm hoàn toàn trên tile. Thiết kế IB-FUEL truyền các bản ghi trọng số theo từng tác vụ từ DDR vào FIFO trên tile, trong khi đường W4 vận chuyển các nhóm bốn bit và giải đóng gói chúng cho bộ máy ma trận INT8. Hãy xem xét IB_FUEL.md và W4_DATAPATH.md trước khi sửa đổi việc lập lịch hoặc hành vi của bộ nạp.

Sử dụng Hiệu quả Bố cục Kho mã

• rtl/ chứa phần triển khai phần cứng.
• golden/ chứa các mô hình tham chiếu NumPy chính xác theo từng bit.
• verif/ chứa testbench, assertion, scoreboard, cổng đột biến và bản sao mô phỏng F2.
• eval/ chứa các công cụ đánh giá độ chính xác mô hình cho codec.
• perf/ chứa mô hình hiệu năng phân tích dự phóng.
• scripts/fpga/ chứa các script xây dựng, tạo image, nạp DDR, chạy chuyến và vòng lặp token.
• docs/results/ chứa bằng chứng chiến dịch đã được commit.

Hạn chế Hiện tại và Lộ trình

Lộ trình hiện tại ưu tiên xác thực attention tuần tự trên FPGA, đóng timing nhanh hơn, truyền trọng số liên tục, hỗ trợ W4 đầu cuối, bổ sung công việc đo tốc độ token và chuẩn bị signoff Sky130. Trạng thái trực tiếp được duy trì trong bảng tổng thể.

Tránh giả định rằng các hạng mục trong lộ trình đã hoàn tất. Cụ thể, README xác định việc khởi động phần cứng attention tuần tự đầy đủ và một số phụ thuộc liên quan đến băng thông vẫn đang được thực hiện.

Kết luận

APEX vừa là một triển khai RTL của tile bộ giải mã transformer, vừa là một nghiên cứu điển hình về xác minh phần cứng dựa trên bằng chứng. Đặc điểm nổi bật nhất của nó là codec bộ nhớ đệm KV tích hợp, lưu trữ key và value ở dạng nén trong khi vẫn là một phần của datapath attention đã được xác minh.

Hãy bắt đầu với các kiểm thử chuẩn vàng, sau đó chạy xác minh tile và walker, kiểm tra bằng chứng đã đo, và chỉ chuyển sang các quy trình mô hình hoặc FPGA khi có đủ các tạo tác bổ sung tương ứng. Giữ riêng các kết quả FPGA đã đo với các dự phóng phân tích, đồng thời sử dụng các tài liệu truy xuất nguồn gốc của dự án mỗi khi trình bày một tuyên bố.

APEX được phát hành theo Apache License 2.0. Xem LICENSE để biết các điều khoản và thông báo áp dụng.