Go simd/archsimd 怎样区分可移植 API 与架构 API

Go 1.27 把实验性的 SIMD 能力拆成了两个观察角度：simd 面向可移植代码，simd/archsimd 面向具体架构的向量类型和操作。两者都需要在构建时设置 GOEXPERIMENT=simd，但它们解决的问题不同：前者隐藏向量宽度和硬件差异，后者直接让代码接触 Float32x4 这类架构类型。

官方地址：https://pkg.go.dev/simd

架构 API 文档：https://pkg.go.dev/simd/archsimd

如果同一份 Go 代码要覆盖 amd64、arm64 和 wasm，优先把业务或公共接口建立在 simd 上；只有确实需要某个架构独有的算子、寄存器宽度或指令能力时，才把 simd/archsimd 收进隔离的内部实现。archsimd 的类型不要直接泄漏到跨平台公共 API。

Go 1.27 的 SIMD 能力为什么分成两层

消息本身不复杂：Go 1.27 引入了可移植的实验性 simd 包，同时继续提供实验性的 simd/archsimd。难点在于，SIMD 不只是“把一个数字换成四个数字”。不同架构支持的指令、向量宽度和掩码表示都可能不同，直接把寄存器形状写进公共接口，就会把部署环境绑定到某一种硬件。

simd 因此只承诺一个跨架构的操作子集，使用 Float32s、Int8s 这类不暴露具体宽度的类型。它可能在有硬件支持时使用向量指令，也可能在纯 Go 中模拟；调用方关注的是运算语义，而不是当前机器到底是 128 位、256 位还是 512 位。

simd/archsimd 则更接近 intrinsics 层。它把具体形状直接写进类型名，例如 Float32x4 表示包含 4 个 float32 的 128 位向量。这个层级适合实现很窄的性能内核，但不能假定它天然可移植，也不能把它当成已经稳定的通用业务 API。

用 simd 表达不暴露硬件宽度的代码

当目标是“在多种架构上做同一类向量运算”，可移植 API 应该是第一选择。下面的示例只把输入加载成 simd.Float32s，再完成逐元素相加；代码没有写死一次能装几个 float32，也没有让调用者传入架构专属类型。

package vector

import "simd"

// AddPortable 只暴露可移植的 simd 类型，调用方不需要知道向量宽度。
func AddPortable(left, right []float32) simd.Float32s {
	// LoadFloat32s 要求输入切片足够长；长度契约由调用方或上层分块逻辑保证。
	x := simd.LoadFloat32s(left)
	y := simd.LoadFloat32s(right)

	// Add 表达逐元素加法，具体使用硬件还是模拟由 simd 层决定。
	return x.Add(y)
}

这段代码的价值不在于某个固定向量宽度，而在于接口稳定地表达“两个同形状向量相加”。如果输入长度可能不足，应在上层使用合适的分块策略或对应的部分加载 API；不要把越界或 panic 语义悄悄塞到公共接口的文档之外。

archsimd 什么时候值得直接使用

当算法必须调用某个只在特定架构上存在的算子，或者你需要明确控制某种向量形状时，archsimd 才有意义。例如，AMD64 上的内部内核可能明确使用 archsimd.Float32x4，并在架构文件中维护它的输入长度、CPU 特性和回退策略。

//go:build amd64 && goexperiment.simd

package vector

import "simd/archsimd"

// AddArch 只属于 amd64 的内部实现，不应出现在跨架构公共接口中。
func AddArch(left, right []float32) archsimd.Float32x4 {
	// Float32x4 固定装载 4 个 float32，切片不足时由 API 契约触发 panic。
	x := archsimd.LoadFloat32x4(left)
	y := archsimd.LoadFloat32x4(right)

	// 这里使用架构类型的 Add，具体指令和 CPU 特性由 archsimd 层决定。
	return x.Add(y)
}

注意这个函数的边界有三层：文件构建条件绑定了架构和实验开关，参数长度绑定了 Float32x4 的宽度，返回值又把架构类型暴露给了上层。实际工程里通常会把它包在内部适配层里，再向业务层返回普通切片、可移植的 simd 类型或业务结果。

两类 API 的差异可以这样对照

这张表的核心不是说 simd 一定更快，而是先把“可移植性”和“能力上限”分开判断。可移植层可能需要等待更多通用操作进入 API；架构层能提供更细的控制，却把测试矩阵和发布风险一起带进来。

理解 ToArch 与 FromArch 的转换边界

两层 API 并不是互相隔绝的。可移植向量提供 ToArch() any，可以取得当前硬件对应的架构值；simd 也提供如 Float32sFromArch 的泛型转换入口，把匹配的 archsimd.Float32x4 转回可移植类型。但官方文档特别强调，调用方需要按目标架构构建并做正确的类型断言，错误的对应关系可能导致 panic。

//go:build amd64 && goexperiment.simd

package vector

import (
	"simd"
	"simd/archsimd"
)

// AddThroughArch 只展示受控转换，不把 archsimd 类型继续向外传播。
func AddThroughArch(left, right []float32) simd.Float32s {
	// 先在可移植层加载，保持上层调用方不感知具体寄存器形状。
	x := simd.LoadFloat32s(left)
	y := simd.LoadFloat32s(right)

	// 只有架构适配层才做类型断言，类型必须与当前架构和向量宽度对应。
	ax := x.ToArch().(archsimd.Float32x4)
	ay := y.ToArch().(archsimd.Float32x4)
	archResult := ax.Add(ay)

	// 转回可移植类型后，外层仍可沿用 simd 的结果语义。
	return simd.Float32sFromArch(archResult)
}

这个示例还有一个现实限制：它把 Float32x4 写死了，因此并不能原样覆盖所有架构和向量宽度。真正的适配层要按官方支持范围拆分文件，并为不可用的架构准备普通 Go 或 simd 路径。转换函数的存在，解决的是边界表达问题，不是自动生成跨架构实现。

采用前先把实验性风险写进工程边界

Go 官方把这两套 API 都定位为实验性能力。把它们用于局部探索、性能内核或可替换的内部模块比较合适；如果直接把 archsimd.Float32x4 放进公共包的导出函数，后续架构扩展、API 调整和测试环境变化都会变成调用方的负担。

• 把 GOEXPERIMENT=simd 写进构建说明，并确认 CI 与本地工具链一致。
• 把 simd/archsimd 的导入限制在带构建约束的内部文件，公共接口优先使用普通 Go 类型或 simd 类型。
• 对输入长度、向量宽度和 CPU 特性分别写清契约，不要用“支持 SIMD”代替实际边界。
• 准备没有目标指令时的回退路径；不要把单台机器上的硬件结果当作所有部署环境的结论。
• 把实验性 API 的升级成本放进版本计划，尤其是类型名称、支持架构和操作子集可能变化的地方。

常见问题

simd 会不会总是比普通 Go 代码快？

不能这样推断。它可能使用硬件指令，也可能采用纯 Go 模拟；实际收益还取决于数据规模、内存访问、分块方式和算子是否落在支持的子集内。应以目标工作负载的独立基准为准。

archsimd 能不能直接放进公共 SDK？

通常不建议。它的类型和操作带有架构与实验性约束，公共 SDK 一旦导出这些类型，就会把调用方绑定到更窄的构建环境。更稳妥的做法是把它留在内部适配层。

ToArch 是不是可以在任意架构上断言成 Float32x4？

不是。返回值对应当前硬件和实际向量类型，断言必须与构建目标和官方支持的类型匹配。错误断言可能 panic，不能把 any 当成通用转换器。

只想写跨平台向量加法，应该从哪一层开始？

先从 simd 开始。只有通用 API 无法表达明确需求，且你愿意承担构建约束、回退实现和实验性 API 的维护成本时，再把特定算子下沉到 archsimd。