简介

gemmkit 是一个纯 Rust 编写的 GEMM 工作区，用于计算通用矩阵乘法 C <- alpha*A*B + beta*C。核心 crate 可以处理带步长的视图或裸指针。它会在运行时选择当前机器上最快的指令集。在固定的输入和配置下，它保证每次运行的结果都可复现。核心之外还有 3 个零拷贝适配器，分别对接 ndarray、nalgebra 和 faer。此外还有一个安装时自动调优器，用来为实际部署的机器校准引擎。

这本书是整个工作区的叙述式文档。docs.rs 上的 API 参考仍然是函数签名和条目级细节的权威来源。本书负责把各个部分放在上下文里讲清楚：设计思路、取舍，以及那些参考页面无法深入展开的 API 细节。

本书内容

gemmkit 使用指南覆盖核心 crate。它从第一次矩阵乘法讲起，一直讲到大多数用户用不到的部分：

• 矩阵视图与内存布局
• 可选的元素类型（f16/bf16、i8、复数）
• 并行执行
• 预打包操作数
• 融合 epilogue
• 批量 GEMM
• 小形状与 GEMV
• 指令集固定
• 调优旋钮
• no_std 与 WebAssembly 构建
• unchecked 裸指针层

适配器指南展示如何用 ndarray、nalgebra、faer 的原生类型直接驱动引擎，全程零拷贝。每个适配器都有自己的章节，包含一篇快速上手和一篇进阶用法。进阶用法覆盖完整的 API 面：融合运算、整数与复数 GEMM、批量运算、预打包，全部使用宿主库自己的类型。

gemmkit-tune 指南讲解自动调优器。它说明如何在部署机器上运行自动调优器、生成的配置文件里有什么，以及背后的扫描过程是怎么工作的。

架构说明逐层拆解引擎内部。它说明一次调用如何从公共 API 一路走到微内核，以及指令集和元素类型如何在不用宏的前提下保持可插拔。它还说明分块参数如何从缓存层级推导出来，以及整个引擎是如何被测试的。它是仓库里那份紧凑的 ARCHITECTURE.md 的详细版和易读版，适合从头到尾通读。

阅读建议

如果你只是想在应用里用上快速的矩阵乘法，从快速上手开始。按需求往后读使用指南即可。

如果你的矩阵本来就存在 ndarray、nalgebra 或 faer 里，直接跳到对应适配器的章节。需要理解底层概念时，再回头查使用指南。适配器转发到同一个引擎，语义完全一致。

如果你好奇引擎内部是怎么工作的，或者打算参与开发，架构说明就是为你准备的路线。它假设你大致翻过使用指南，但不假设你了解 BLIS。它解释的是设计决策本身，而不只是代码。

约定与资源

代码示例基于 Rust edition 2024，工作区 MSRV 为 1.89。需要开启可选 Cargo feature 的示例会在出现处注明。像 gemmkit/src/driver.rs 这样的仓库路径均相对于仓库根目录。

相关资源包括：API 参考、CHANGELOG，以及 crates.io 上的各个 crate：gemmkit、gemmkit-ndarray、gemmkit-nalgebra、gemmkit-faer、gemmkit-tune。

This book is also available in English.