263 lines
14 KiB
Markdown
263 lines
14 KiB
Markdown
# 张量模块
|
||
|
||
**脚本入口：** `eve.TF()`
|
||
|
||
执行 eager 张量运算，或用 Func 构图、编译并重复运行。编译管线采用类似
|
||
AITemplate 的静态编译思路：按图生成专用 GPU kernel、融合元素级算子链、静态
|
||
内存规划复用缓冲区、对 matmul 做自动调优。
|
||
|
||
## 基本用法
|
||
|
||
```squirrel
|
||
local tf = eve.TF();
|
||
local a = tf.ones2(2, 3);
|
||
local b = tf.fill2(2, 3, 2.0);
|
||
local c = tf.add(a, b);
|
||
print(c.get2(0, 0) + "\n");
|
||
```
|
||
|
||
```squirrel
|
||
// 编译一个可复用的“游戏 AI”策略网络：x @ W1 + b -> relu -> @ W2 -> softmax
|
||
local fn = tf.func();
|
||
local x = fn.input1(4);
|
||
local h = tf.matmul(tf.reshape2(x, 1, 4), W1); // W1 等 eager 张量会被捕获为常量
|
||
h = tf.add(h, b1);
|
||
h = tf.relu(h);
|
||
h = tf.matmul(h, W2);
|
||
h = tf.softmax(h, 1);
|
||
fn.setOutput(h);
|
||
local compiled = fn.compile(); // 融合 + 生成专用 kernel + 内存规划
|
||
local out = compiled.run1(state); // 每帧只做 feed + dispatch + 读回
|
||
```
|
||
|
||
## 对象关系与调用时机
|
||
|
||
`TF` 创建 eager Tensor 或 Func；Func 中的 Tensor 是 symbolic；`compile()` 返回
|
||
CompiledFunction；run 接收 eager feed 并返回 eager 输出。shape 与 dtype 必须匹配。
|
||
|
||
## AITemplate 风格编译管线
|
||
|
||
`compile()` 不再按“固定算子 + opcode”解释执行，而是：
|
||
|
||
1. **图优化**（`Optimizer`）：DCE、常量折叠、元素级链融合、matmul/conv 的
|
||
bias + 激活后置融合、按生命周期做静态内存规划（不重叠的中间结果复用同一块
|
||
显存）。
|
||
2. **专用 kernel 代码生成**（`KernelGen`）：每个融合组生成一份形状全部烘焙为
|
||
常量的 GLSL；softmax/layernorm 使用两遍 kernel；SDPA 使用共享内存的融合
|
||
attention；matmul 提供 naive 与 16x16 tiled 两种模板。
|
||
3. **进程内 GLSL→SPIR-V 编译**：Windows 上链接 Vulkan SDK 的 shaderc
|
||
（glslang + SPIRV-Tools）静态库，不依赖外部 glslc.exe；找不到 shaderc 时回退
|
||
到调用 glslc。
|
||
4. **matmul 自动调优**：编译时对 naive / tiled 两种变体各计时 5 次，选择更快者。
|
||
5. **整图单次提交**（`GpuBackend` + `gpgpu::Sequence`）：一次 `run()` 把
|
||
placeholder 上传、所有融合组的 kernel dispatch、输出回读录制进同一个
|
||
command buffer，`submit()` 一次完成——而不是每个 kernel 各提交等待一次。
|
||
对 transformer 这类几十个 kernel 的推理图，可省掉几十次 GPU 提交往返。
|
||
|
||
当没有 Vulkan 设备或图无法降级到 GPU 时，`compile()` 自动回退到 CPU 参考解释器，
|
||
`getDevice()` 返回 `"gpu"` 或 `"cpu"`。
|
||
|
||
## 目标导向指南
|
||
|
||
### 游戏离线 AI（策略/行为模型）
|
||
|
||
用 `func()` 构图一次、每帧 `run`：`matmul` → `add`/`addScalar`（bias）→
|
||
`relu`/`gelu`/`silu` → `softmax` 得到动作概率，再用 `argmax` 取动作、用
|
||
`embedding` 查表。rank 3 的 `matmul` 支持批处理多个智能体。
|
||
|
||
### 常用 GPGPU 计算
|
||
|
||
广播二元运算（`[N,C] + [C]` 等）、`sumAxis/meanAxis/minAxis/maxAxis`、
|
||
`where`、`clamp` 都既支持 eager 也支持构图编译；大张量全量归约
|
||
（`reduceSum` 等）在超过 16384 元素时自动走 GPU reduction。
|
||
|
||
### 游戏中运行离线语音模型
|
||
|
||
语音模型常用算子都已内置：`conv1d`（特征提取）、`layernorm`/`rmsnorm`、
|
||
`gelu`/`silu`、`sdpa`/`sdpaMasked`（融合 attention，自带 softmax 与 mask）、
|
||
`embedding`、`slice`/`concat`/`permute`。`cast(x, "int32")` 得到索引张量供
|
||
`embedding` 使用。SDPA 限制 S ≤ 2048、D ≤ 512，超出自动回退 CPU。
|
||
|
||
### 快速计算地形地貌
|
||
|
||
`conv2d`/`maxpool2d`/`avgpool2d` 用于平滑、侵蚀、降采样；`resize2d`（最近邻 /
|
||
双线性）用于高度图放大；`where` + 比较组合实现掩膜；`randomUniform*` 提供种子化
|
||
噪声。这些都能构图后在 GPU 上批量处理整块地形。
|
||
|
||
### 大规模模拟
|
||
|
||
把模拟状态组织成批张量，用广播运算一次推进整批：`mulScalar`（时间步长）、
|
||
`add`/`sub`（状态更新）、`clamp`（边界）、`reduceSum`（统计）。把每帧固定形状
|
||
的更新写成 Func 编译一次，避免脚本侧逐元素循环。
|
||
|
||
### 跑一个真实的 mini LLM（TinyStories-gpt2-3M）
|
||
|
||
用预训练权重实测整个推理管线：`calum/tinystories-gpt2-3M`（8 层、d=64、16 头、
|
||
GPT-2 BPE 词表 50257，TinyStories 语料训练）。测试 [test/tensor_llm.cpp]
|
||
(../../../test/tensor_llm.cpp) 用 TF 算子逐层搭出完整 GPT-2 图：
|
||
`embedding`（token + 位置）→ 8 × { `layernormWB` → 多头 `sdpaMasked`（因果 mask）
|
||
→ 残差 → MLP(`gelu`) → 残差 } → `layernormWB` → `matmul(lm_head)` → `argmax`
|
||
贪婪采样。验证结果：
|
||
|
||
- 与 numpy 参考实现逐位置对比 softmax 概率：最大差 3e-7，top-1 一致 16/16；
|
||
- 编译路径（`func()` + `compile()`）与 eager 完全一致（logit 差 0），device 为
|
||
cpu 或 gpu（有 Vulkan 窗口时）；
|
||
- 贪婪生成与 numpy 参考 24/24 token 一致，CPU eager 约 100 ms/token。
|
||
|
||
示例输出（prompt：*Once upon a time, there was a little*）：
|
||
|
||
> Once upon a time, there was a little girl named Lily. She loved to play with
|
||
> her toys and make things. One day, she found a big box in...
|
||
|
||
资产（约 47 MB）已 gitignore，按以下步骤重建：
|
||
|
||
```bash
|
||
# 1) 从 https://huggingface.co/calum/tinystories-gpt2-3M 下载 4 个文件到
|
||
# test/assets/mini_llm/：pytorch_model.bin / config.json / vocab.json / merges.txt
|
||
# （文件名带 tinystories_ 前缀）
|
||
# 2) 导出引擎权重包 + token 表 + numpy 参考输出：
|
||
python scripts/export_tiny_gpt2.py
|
||
# 3) 运行测试：
|
||
build/test/unit_test.exe --testcase="tensor.llm.*"
|
||
```
|
||
|
||
### 权重量化（fp16 / fp8 / fp4 / int8 / int4）
|
||
|
||
推理管线内置权重-only 量化：把 eager 权重打包成紧凑 dtype，构图时捕获为量化
|
||
Const，CPU 解释器与 GPU kernel 都在使用点反量化，激活保持 fp32。
|
||
|
||
```squirrel
|
||
local wq = tf.quantizeWeight(W, "int8", 64); // 每 64 个元素一个 block scale
|
||
local wq = tf.quantizeWeight(W, "fp16"); // fp16 为纯 half 存储，无 scale
|
||
```
|
||
|
||
格式与布局（`Tensor.get(i)` 直接返回反量化后的值，`isQuantized()` 可查询）：
|
||
|
||
- `fp16`：IEEE half，2 字节/元素，无 scale；
|
||
- `fp8`：e4m3（1 字节）+ per-group block scale；
|
||
- `fp4`：e2m1（2 元素/字节）+ per-group block scale；
|
||
- `int8` / `int4`：对称量化 + per-group block scale（int4 两元素/字节）。
|
||
|
||
支持量化的使用点：matmul 的权重输入（B）、embedding 表、lm_head（transpose 后）。
|
||
GPU 侧在生成的 GLSL kernel 内联反量化（naive matmul 与 embedding），不落回
|
||
fp32 缓冲；LN 的 scale/bias 与线性 bias 建议保持 fp32（测试默认如此）。
|
||
|
||
TinyStories 模型全矩阵量化（group=64）实测（top-1 贪婪一致率 vs fp32，16 个
|
||
预测位；权重体积 vs fp32 27.6 MB）：
|
||
|
||
| dtype | 概率最大差 | top-1 | 体积 |
|
||
|-------|-----------|-------|------|
|
||
| fp16 | 0.0004 | 16/16 | 13.2 MB |
|
||
| int8 | 0.0103 | 16/16 | 7.0 MB |
|
||
| fp8 | 0.0716 | 15/16 | 6.6 MB |
|
||
| int4 | 0.1767 | 16/16 | 3.7 MB |
|
||
| fp4 | 0.3961 | 16/16 | 3.3 MB |
|
||
|
||
fp8/fp4 的 block scale 取 `maxAbs / 格式最大幅值`（e4m3=240、e2m1=6），让归一化
|
||
值铺满整个格式动态范围——若只归一化到 [0,1]，e2m1 会浪费 2/3/4/6 等电平，误差
|
||
会大一个数量级（早期版本的 0.94 就是这样来的）。
|
||
量化正确性由 `tensor.quant.*` 与 `tensor.llm.quantizedDtypes` 测试覆盖（含
|
||
GPU 编译路径），资产缺失时自动跳过。
|
||
|
||
## C++ 原生 ONNX 导入与量化 GPU 推理
|
||
|
||
`tensor/OnnxModel.h` 直接导入 ONNX，保留 int8/uint8 权重、仿射 scale/zero-point
|
||
及精确 int32/int64 数据。`run()` 执行 CPU 参考路径；`runGpu()` 接收
|
||
`createOnnxGpuCompute()` 返回的引擎 Gpgpu 适配器，在 Vulkan 设备线程上同步执行。
|
||
GPU 负责量化矩阵乘、卷积、LSTM 投影、浮点神经网络计算；形状、索引、控制流、
|
||
LSTM 门控仍由 CPU 处理；动态量化在 GPU 上计算，只回读少量校验标量。
|
||
GPU 错误明确返回，不会自动改用 CPU 重试。
|
||
|
||
已用原版 Kokoro v1.1 INT8 模型跑通中文语音整图，包括 Loop/If/Sequence。
|
||
接口使用 owning Result，输出不依赖模型生命周期，随机激励可指定种子。
|
||
当前 ONNX GPU 执行已使用驻留缓冲区和批量 Sequence 提交；连续 GPU 节点之间不回读，
|
||
仅在 CPU 数据依赖边界下载。应在推理循环外创建并保留 `createOnnxGpuCompute()`
|
||
返回的 GPU 会话，跨调用复用管线、权重和缓冲区池；Graphics 销毁前自动清理，
|
||
失效会话明确拒绝执行。实测同进程第二次合成约 2.60 秒，仍需优化 LSTM CPU 门控等开销。文字前处理、Squirrel
|
||
绑定及 dialogue 播放接入不在此示例范围内。
|
||
|
||
完整构建命令、模型资源、数值契约、限制和可重复语音测试见
|
||
[原生 ONNX 示例](../../../examples/tensor/onnx/README.md)。
|
||
|
||
## 常见问题
|
||
|
||
- 对 symbolic Tensor 调用 `get()`。
|
||
- matmul 内维度不一致；rank 3 批处理要求 batch 相同。
|
||
- 每帧重新 func/compile，而不是复用 CompiledFunction。
|
||
- GPU 编译需要已创建 Vulkan 窗口（`gpgpu.isAvailable()` 为真）；否则回退 CPU。
|
||
- `argmax`/`cast("int32")` 得到 int32 dtype 张量，脚本读取仍返回 float。
|
||
|
||
## API 快查
|
||
|
||
下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 `Tensor`、
|
||
`Func`、`CompiledFunction`）的方法也列在这里。
|
||
|
||
### TF（`tf.` 方法）
|
||
|
||
- `abs()`、`add()`、`addScalar()`、`arange()`、`argmax()`
|
||
- `avgpool2d()`、`cast()`、`clamp()`、`concat2()`、`concat3()`、`concat4()`
|
||
- `constantScalar()`、`conv1d()`、`conv1dBias()`、`conv2d()`、`conv2dBias()`
|
||
- `cos()`、`div()`、`divScalar()`、`embedding()`、`exp()`、`eye()`
|
||
- `fill1()`、`fill2()`、`fill3()`、`fill4()`、`flatten()`、`func()`
|
||
- `gelu()`、`getRandomSeed()`、`layernorm()`、`layernormWB()`、`linspace()`
|
||
- `log()`、`logSoftmax()`、`matmul()`、`maxAxis()`、`maximumScalar()`
|
||
- `maxpool2d()`、`meanAxis()`、`minAxis()`、`minimumScalar()`
|
||
- `mulScalar()`、`multiply()`、`neg()`、`ones1()`、`ones2()`、`ones3()`
|
||
- `ones4()`、`ones5()`、`ones6()`、`permute2()`、`permute3()`、`permute4()`
|
||
- `permute5()`、`permute6()`、`powScalar()`、`rand1()`、`rand2()`、`rand3()`
|
||
- `quantizeWeight()`、`rand4()`、`randn1()`、`randn2()`、`randn3()`、`randn4()`、`randomNormal1()`
|
||
- `randomNormal2()`、`randomNormal3()`、`randomNormal4()`、`randomUniform1()`
|
||
- `randomUniform2()`、`randomUniform3()`、`randomUniform4()`
|
||
- `reduceMax()`、`reduceMean()`、`reduceMin()`、`reduceSum()`、`relu()`
|
||
- `reshape1()`、`reshape2()`、`reshape3()`、`reshape4()`、`reshape5()`
|
||
- `reshape6()`、`resize2d()`、`rmsnorm()`、`rmsnormW()`、`sdpa()`
|
||
- `sdpaMasked()`、`setRandomSeed()`、`sigmoid()`、`silu()`、`sin()`
|
||
- `slice()`、`softmax()`、`sqrt()`、`sub()`、`subScalar()`、`sumAxis()`
|
||
- `tanh()`、`transpose()`、`where()`、`zeros1()`、`zeros2()`、`zeros3()`
|
||
- `zeros4()`、`zeros5()`、`zeros6()`
|
||
|
||
量化相关：`quantizeWeight(t, "fp16"/"fp8"/"fp4"/"int8"/"int4", group)`；
|
||
`t.isQuantized()`；量化张量的 `get(i)` 返回反量化值。
|
||
|
||
### Tensor（`tf.*` 返回对象的 `t.` 方法）
|
||
|
||
- `abs()`、`add()`、`addInPlace()`、`addScalar()`、`addScalarInPlace()`
|
||
- `clone()`、`copyFrom()`、`cos()`、`div()`、`divScalar()`、`dot()`
|
||
- `exp()`、`fill()`、`flatten()`、`gelu()`、`get()`、`get1()`、`get2()`
|
||
- `get3()`、`get4()`、`get5()`、`get6()`、`getDevice()`、`getDim()`
|
||
- `getDim0()`、`getDim1()`、`getDim2()`、`getDim3()`、`getDim4()`、`getDim5()`
|
||
- `getDtype()`、`getRank()`、`getSize()`、`isEager()`、`isSymbolic()`、`log()`
|
||
- `matmul()`、`maximumScalar()`、`minimumScalar()`、`mulScalar()`
|
||
- `mulScalarInPlace()`、`multiply()`、`multiplyInPlace()`、`neg()`
|
||
- `powScalar()`、`reduceMax()`、`reduceMean()`、`reduceMin()`、`reduceSum()`
|
||
- `relu()`、`reluInPlace()`、`reshape1()`、`reshape2()`、`reshape3()`
|
||
- `reshape4()`、`reshape5()`、`reshape6()`、`set()`、`set1()`、`set2()`
|
||
- `set3()`、`set4()`、`set5()`、`set6()`、`sigmoid()`、`silu()`、`sin()`
|
||
- `sqrt()`、`sub()`、`subScalar()`、`tanh()`、`transpose()`
|
||
|
||
### Func（`tf.func()` 返回对象的 `fn.` 方法）
|
||
|
||
- `compile()`、`input1()`、`input2()`、`input3()`、`input4()`、`input5()`
|
||
- `input6()`、`setOutput()`
|
||
|
||
### CompiledFunction（`fn.compile()` 返回对象的 `c.` 方法）
|
||
|
||
- `getDevice()`、`getPlaceholderCount()`、`run0()`、`run1()`、`run2()`
|
||
- `run3()`、`run4()`、`run5()`、`run6()`
|
||
|
||
## 使用要点
|
||
|
||
- 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
|
||
- 带 `update(dt)` 的系统应在 `eve_update` 调用；绘制方法应在 `eve_render` 调用。
|
||
- 参数约束、默认值和返回类型以对应模块头文件及 `addFunc` 绑定为准；本文 API 快查与当前源码同步生成。
|
||
- 张量支持 rank 1–6，dtype 为 float32 / int32；二元运算支持广播。
|
||
- 原生 ONNX GPU 会话使用有界 shader 编译队列，`createOnnxGpuCompute(compilerWorkers)`
|
||
可选 1–8 个 CPU 编译线程（默认 4）；同源码去重，编译器上下文和管线缓存均复用。
|
||
Vulkan 管线创建与提交仍在设备线程，`runGpu` 保持同步返回；并发数应按目标构建实测选择。
|
||
- GPU 路径：`compile()` 需要已初始化的 Vulkan Graphics（先创建窗口）。Windows
|
||
上 GLSL→SPIR-V 由链接进引擎的 shaderc 静态库完成，不需要安装 glslc。
|
||
|
||
**源码：** [`src/modules/tensor/`](../../../src/modules/tensor/)（含
|
||
`Optimizer` 图优化/融合、`KernelGen` 专用 kernel 生成、`GpuBackend` GPU 运行时）
|
||
**相关测试：** 在 [`test/`](../../../test/) 中搜索 `tensor`。
|