4. 加速实现与基准实现的接口对齐

在数值加速项目中，我们常常把注意力集中在算法替换上：把 O(n²) 的循环换成向量化实现，把标量计算换成 SIMD，把 CPU 路径换成 GPU 内核。然而，当加速版本与基准版本的结果出现偏差时，真正的原因往往不在算法本身，而在接口层——数据在内存中的排布方式不同、调用时的参数顺序或单位不一致、边界条件的处理策略有差异、异常路径的返回约定不统一。这些非算法性差异会伪装成精度问题，让排查方向严重跑偏。本节的核心任务，就是在加速实现与基准实现之间建立一套严格的接口对齐规范，把"算法差异"和"接口差异"彻底分离。

一、数据布局：同一份数值，两种内存语义

数据布局是最容易被忽视、也最容易制造"假精度问题"的环节。以矩阵乘法为例，基准实现通常采用行主序（row-major）连续存储，而某些加速库（如 BLAS 接口）默认列主序（column-major）。如果加速侧直接把行主序缓冲区传给列主序接口，数值本身没有错，但参与运算的元素位置全部错位，结果自然面目全非。这类错误在单元测试中表现为"误差巨大且无规律"，很容易被误判为算法精度不足。

对齐数据布局需要明确三件事：存储顺序（行主序/列主序）、步长与对齐（leading dimension、是否要求 16/32 字节对齐）、数据类型与精度（float32/float64、是否允许混合精度累加）。实践中推荐的做法是：在基准实现与加速实现之间定义一个中立的数据描述结构，由适配层负责转换，而不是让两侧各自假设对方的布局。例如：

struct TensorDesc {
    void*  data;          // 起始地址
    int    rows, cols;    // 逻辑维度
    int    ld;            // leading dimension（行主序=cols，列主序=rows）
    Layout layout;        // ROW_MAJOR / COL_MAJOR
    DType  dtype;         // F32 / F64
    bool   aligned16;     // 是否满足 16 字节对齐
};

适配层在调用加速内核前，依据 TensorDesc 判断是否需要转置或拷贝；若布局一致则零拷贝直通，若不一致则显式转换并记录一次转换开销。这样，布局差异被隔离在适配层，算法对比时两侧看到的都是同一语义的数据。

二、调用约定：参数顺序、单位与生命周期

调用约定的不一致同样隐蔽。常见问题包括：参数顺序颠倒（如 (m, n, k) 与 (k, n, m)）、角度与弧度混用、长度单位从"元素个数"变成"字节数"、以及缓冲区所有权与生命周期约定不同（调用方分配还是被调方分配、是否需要显式释放）。这些问题不会在编译期报错，却会在运行时产生系统性偏差或内存错误。

对齐策略是建立一份接口契约表，逐项固定每个参数的名称、类型、单位、取值范围和所有权。对于加速实现，尤其要标注"与基准实现的差异点"，并在适配层做显式换算。例如基准实现的角度参数以弧度传入，而加速内核以角度传入，则适配层必须执行 rad * 180.0 / PI，且该换算只在一处发生，避免多处重复导致二次换算。

三、参数语义：边界、容差与累加顺序

参数语义的对齐不止于类型和单位，还包括边界行为与数值约定。例如：当输入维度为 0 时，基准实现返回空结果还是抛出异常？当输入包含 NaN/Inf 时，加速内核是传播还是截断？归约运算的累加顺序是否一致——这一点尤其关键，因为浮点加法不满足结合律，不同的累加顺序（串行累加 vs 树形归约 vs 分块累加）会产生不同的舍入误差，属于"合法的算法性差异"，必须在对比时用容差而非逐位相等来判定。

因此，接口对齐需要同时定义对比判据：对确定性逐元素运算，可采用相对误差 |a-b| / max(|a|,|b|,eps) 不超过 1e-6（float32）或 1e-12（float64）；对归约类运算，应放宽到与累加顺序相关的理论误差界，并在文档中说明该差异属于算法性而非接口性。把判据写进契约，才能让"精度一致性校验"有明确的通过标准。

四、异常处理：统一错误码与降级路径

异常处理的不一致会污染结果对比。基准实现可能通过返回错误码报告失败，加速实现可能直接抛出异常或返回 NaN；若适配层不统一，失败路径会被误读为"数值异常"。对齐做法是：在适配层定义统一的错误枚举，把两侧的失败信号映射到同一套错误码，并规定降级策略——当加速路径因对齐、尺寸或硬件能力不满足而无法执行时，是回退到基准实现，还是返回明确错误。回退路径必须被记录，否则"加速版结果正确"可能只是因为悄悄走了基准路径。

五、落地检查：把对齐变成可执行的清单

接口对齐不是一次性文档工作，而应固化为可执行的检查项。建议在每次加速实现接入时，按以下顺序核对：先确认数据布局描述（存储顺序、ld、对齐、dtype）两侧一致或已由适配层转换；再核对参数的单位、顺序与所有权；然后验证边界输入（空、单元素、含 NaN/Inf）的行为是否被统一映射；最后确认异常路径与降级路径均有记录。完成这些之后，再运行精度对比，此时若仍出现超容差偏差，才可以有把握地归因于算法本身。

一个实用的验证方法是构造"接口探针"用例：选取小尺寸、可手算的输入（如 2×3 矩阵乘 3×2 矩阵），分别走基准路径和加速路径，逐元素打印中间结果。若布局错位，探针会立刻暴露元素位置互换；若单位错误，探针会显示固定倍数偏差；若累加顺序不同，探针会显示末位舍入差异。探针用例的规模小、可解释性强，是区分接口问题与算法问题的最快手段。

综上，接口对齐的本质是把加速实现与基准实现放在同一语义坐标系下比较。数据布局统一了"数值在哪里"，调用约定统一了"参数怎么传"，参数语义统一了"边界与容差怎么算"，异常处理统一了"失败怎么报"。四者对齐之后，剩余的差异才是真正值得研究的算法性差异，精度一致性校验也才具备可信的判据基础。