npm - @kernaut/kernaut-resources - Versions diffs - 0.1.17-beta.1 → 0.1.18 - Mend

@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1678) hide show

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/techniques/discrete-memory-access/README.md DELETED Viewed

@@ -1,258 +0,0 @@
----
-id: skill-ascend-discrete-memory-access
-title: "Discrete Memory Access Optimization"
-type: skill
-vendor: ascend
-tags:
-- triton-ascend
-- discrete-memory-access
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- triton-ascend
-techniques:
-- discrete-memory-access
-symptoms:
-- random index gather
-- scatter add by indices
-- non-contiguous memory access
-- scattered global memory access
-- low memory bandwidth utilization
-- data dependent indexing
-- gather rows by index vector
-- interpolate gather neighbor by computed index
-- 随机索引gather
-- 离散访存
-- 非连续访存
-- 带宽利用率低
-aliases:
-- memory coalescing
-- coalesced access
-- scattered load
-- discrete access
-- gather
-- scatter
----
-# 离散访存优化模式
-## 概述
-在 Triton NPU kernel 中，当线程通过非连续或不可预测的索引向量访问全局内存时，会导致访存效率低下，显著降低带宽利用率。先将整块数据读取到share memory，再取非连续或不可预测的索引可以显著提升计算效率。
-## 触发条件
-**当代码中存在以下场景时，应考虑应用此优化**：
-1. **存在访存语句**：使用了`tl.load`/ `tl.store`读写了全局内存
-2. **访存的索引为随机向量/矩阵**：当且仅当访存地址序列无法被静态解析为连续/步长/分块连续模式时，判定为随机访存，注意如果读取单个索引标量并不会引起离散访存，关于随机性的判定如下：
-```
-┌─────────────────┬─────────────────────────────────────┬──────────────┐
-│ 索引来源类型     │ 示例代码                              │ 随机性判定   │
-├─────────────────┼─────────────────────────────────────┼──────────────┤
-│ 程序ID线性变换   │ pid * BLOCK + arange                 │ 确定性连续   │
-│                 │ tl.program_id(0) * 256 + tl.arange   │             │
-├─────────────────┼─────────────────────────────────────┼──────────────┤
-│ 循环变量线性     │ for i in range(N): ptr + i * stride  │ 确定性步长   │
-│                 │                                      │             │
-├─────────────────┼─────────────────────────────────────┼──────────────┤
-│ 内存加载值/      │ idx = tl.load(indices_ptr + offset)  │ ⚠️ 潜在随机 │
-│ kernel入参      │ val = tl.load(data_ptr + idx)        │ 需检查来源   │
-└─────────────────┴─────────────────────────────────────┴──────────────┘
-```
-## 实验性优化方法
-下面的优化方法仅能在特定软件配套版本下成功生效，如果尝试后发生报错请跳转到##基于普通接口的优化方法
-### 随机读优化方法
-随机读可以尝试使用`gather_out_to_ub`接口替换，该接口功能为：根据索引张量（index）从全局内存（Global Memory, GM）的源张量（src）采集数据到统一缓冲区（Unified Buffer, UB） 中。该函数输入：
-| 参数名             | 类型                        | 是否必填 | 说明                                   |
-| --------------- | ------------------------- | ---- | ------------------------------------ |
-| src             | tl.tensor（指针类型）           | 是    | 全局内存（GM）中的源张量指针，数据将从此张量中采集           |
-| index           | tl.tensor                 | 是    | UB 中的索引，表示待采集的原始索引集合                 |
-| index\_boundary | int64                     | 是    | 索引值的上边界，超过该边界的索引视为越界                 |
-| dim             | int32                     | 是    | 采集操作沿源张量的维度，需满足0 ≤ dim < index.rank  |
-| src\_stride     | Tuple\[int64]             | 是    | 源张量各维度的步长（stride）                    |
-| end\_offset     | Tuple\[int32]             | 是    | 索引张量的每个维度的结束偏移量                      |
-| start\_offset   | Tuple\[int32]             | 是    | 索引张量的每个维度的起始偏移量                      |
-| other           | Optional\[numbers.Number] | 否    | 索引越界时的兜底填充值（标量），默认值为None（需确保越界时显式指定） |
-输出：
-* 类型：tensor
-* 形状：形状与 index 一致
-* 数据类型：与源张量相同
-* 内存位置：统一缓冲区（UB）
-支持dtype：fp16	fp32 bf16
-Shape 支持：仅支持 1~5维 tensor
-特殊限制说明：
-* 维度一致性：src 与index的秩（rank）必须相同。
-* 数据类型限制：src 仅支持 float16、bfloat16、float32 三种浮点类型；index 必须为整数类型张量。
-* 索引张量约束：index 的秩需在 1~5 之间；dim 需为有效维度（0 ≤ dim < index_tile.rank）。
-* 维度尺寸约束：对于非采集维度（i ≠ dim），原始索引张量的尺寸index_shape[i]不得超过源张量对应维度尺寸src.shape[i]。
-* 兜底值约束：other 必须为标量（非张量），若存在越界场景则必须显式指定。
-下面是该接口替换tl.load的使用例：
-#### 原始代码（随机访存）
-```python
-index = tl.load(index_ptr + y0_local*2 + x1_local, mask) # idx是一个完全无法预测的随机向量
-val = tl.load(src_ptr + index, mask=mask)  # 直接从global中离散访问取数
-```
-#### 优化后代码（整块访存+访存）
-```python
-	# Load index tile to UB
-	index = tl.load(index_ptr + y0_local*2 + x1_local, mask)
-	# Call gather_out_to_ub: gather values from src along dim=0
-	val = gather_out_to_ub(
-		src=src_ptr,
-		index=index,
-		index_boundary=4,
-		dim=0,
-		src_stride=(2, 1),
-		end_offset=(2, 2),
-		start_offset=(0, 0)
-	)
-```
-### 随机写优化方法
-随机写可以尝试使用`scatter_ub_to_out`接口替换，该接口功能为：将统一缓冲区（Unified Buffer, UB） 中的数值张量（value）根据索引张量（index）沿目标张量的指定维度（dim），分散存储到全局内存（Global Memory, GM）的目标张量（ptr）中。该函数输入：
-| 参数名             | 类型              | 是否必填 | 说明                                   |
-| --------------- | --------------- | ---- | ------------------------------------ |
-| ptr             | tl.tensor（指针类型） | 是    | 全局内存（GM）中的目标张量指针，数据将分散写入此张量中         |
-| value           | tl.tensor       | 是    | UB 中的值，表示待分散写入目标张量的数值集合              |
-| index           | tl.tensor       | 是    | UB 中的索引，表示待分散操作的原始索引集合               |
-| index\_boundary | int64           | 是    | 索引值的上边界，用于索引边界检查，确保分散操作的索引有效性        |
-| dim             | int32           | 是    | 分散操作沿目标张量的维度，需满足0 ≤ dim < index.rank |
-| dst\_stride     | Tuple\[int64]   | 是    | 目标张量各维度的步长（stride）                   |
-| end\_offset     | Tuple\[int32]   | 是    | 索引张量的每个维度的结束偏移量                      |
-| start\_offset   | Tuple\[int32]   | 是    | 索引张量的每个维度的起始偏移量                      |
-返回值：无返回值
-支持dtype：fp16	fp32 bf16
-Shape 支持：仅支持 1~5维 tensor
-特殊限制说明：
-* 维度一致性：ptr、value 与index的秩（rank）必须相同。
-* 数据类型限制：ptr 仅支持 float16、bfloat16、float32 三种浮点类型；index 必须为整数类型张量。
-* 索引张量约束：index 的秩需在 1~5 之间；dim 需为有效维度（0 ≤ dim < index.rank）。
-* 维度尺寸约束：对于非分散维度（i ≠ dim），索引分片的尺寸index.size[i]不得超过目标张量对应维度尺寸ptr.size[i]。
-下面是该接口替换tl.store的使用例：
-#### 原始代码（随机访存）
-```python
-index = tl.load(index_ptr + y0_local*2 + x1_local, mask) # offset是一个完全无法预测的随机标量
-tl.store(dst_ptr + index, value)  # 直接从global中离散访问取数
-```
-#### 优化后代码（整块访存+访存）
-```python
-	index = tl.load(index_ptr + y0_local*2 + x1_local, mask)
-	scatter_ub_to_out(
-		ptr=dst_ptr,
-		value=value,
-		index=index,
-		index_boundary=4,
-		dim=0,
-		dst_stride=(2, 1),
-		end_offset=(2, 2),
-		start_offset=(0, 0)
-	)
-```
-### 关键点
-1. **识别无法预测的随机值**：溯源访存命令的索引计算过程，找到是否有随机值风险
-2. **替换优化**：将 `tl.load`的替换为`gather_out_to_ub`，将`tl.store`的替换为`scatter_ub_to_out`
-## 基于普通接口的优化方法
-### 原始代码（随机访存）
-```python
-offset = tl.load(offset_ptr) # offset是一个完全无法预测的随机标量
-idx = tl.load(idx_ptr + rn * stride_idx) # idx是一个完全无法预测的随机向量
-val = tl.load(x_ptr + offset + idx * stride_x, mask=mask)  # 直接从global中离散访问取数
-```
-### 优化后代码（整块访存+访存）
-```python
-offset = tl.load(offset_ptr) # offset是一个完全无法预测的随机标量
-idx = tl.load(idx_ptr + rn * stride_idx) # idx是一个完全无法预测的随机值向量
-rm = tl.arange(0, M) # rm包含了所有的值，M为x张量的总长度
-x_shared = tl.load(x_ptr + offset_ptr + rm * stride_x) # 将x对应偏移的所有数据从global搬至share
-val = tl.gather(x_shared.to(tl.float16), idx, 0).to(tl.int32)  # 再从share中select目标值，注意数据类型的切换
-```
-### 关键点
-1. **识别无法预测的随机值**：溯源`tl.load`的输入索引计算过程，找到是否有无法预测的随机值，例如被`tl.load`读进来的值
-2. **自动优化**：将 `tl.load`的输入指针中的随机值剔除，改为读取一大块内存（注意不能超过share memory限制），然后使用`tl.gather`输入随机值，得到最终需要取的值
-3. **注意gather的数据类型**：`tl.gather`不支持`int类型`，最好将输入强转成`tl.float16`再执行`tl.gather`,最后再转回原有的数据类型。如果提示精度报错，可以尝试强转成`tl.float32`。
-### 模式 2：循环内通过随机索引访问小查找表
-**问题代码（极易误判）**：
-```python
-for x in range(tl.cdiv(topk_numel, BLOCK_SIZE)):
-    mask = offsets < (topk_numel - x * BLOCK_SIZE)
-    expert_ids = tl.load(topk_ids_ptrs, mask=mask, other=-1)
-    if HAS_EXPERT_MAP:
-        # 错误：expert_ids 来自 tl.load，是运行时随机值
-        # expert_map + expert_ids 产生随机全局内存访问，每次循环迭代都可能跨步
-        expert_map_ptrs = expert_map + expert_ids
-        expert_ids = tl.load(expert_map_ptrs, mask=mask, other=-1)
-    ...
-```
-**优化后代码**：
-```python
-# 循环外一次性将 expert_map（小查找表）加载到 UB
-expert_map_data = tl.load(expert_map + tl.arange(0, num_experts)).to(tl.float32)
-for x in range(cntx):
-    mask = offsets < (topk_numel - x * BLOCK_SIZE)
-    e_ids = tl.load(topk_ids_ptr + x * BLOCK_SIZE + offsets, mask=mask, other=0)
-    # 对 UB 中的局部 buffer 使用 gather，替代全局离散加载
-    expert_ids = tl.gather(expert_map_data, e_ids, 0)
-    ...
-```
-**关键差异**：
-- 原始版本：每次循环迭代执行 `tl.load(expert_map + expert_ids)`，索引 `expert_ids` 随机，导致全局离散访存
-- 优化版本：循环外一次 `tl.load` 将 expert_map 整体搬到 UB，循环内用 `tl.gather` 从 UB 局部查找
-**识别要点**：当代码出现 `tl.load(small_table + tl.load(random_indices))` 这种"双层加载-索引"模式时，几乎总是可以通过"预加载 + gather"优化。
-## 性能收益
-先将整块数据读取到share memory，再取非连续或不可预测的索引可在 NPU 上获得显著的性能提升。
-## 风险提示
-| 风险 | 说明 | 缓解措施 |
-|------|------|----------|
-| 精度下降 | `tl.gather`输入强转成`tl.float16`可能会丢失精度 | 尝试将`tl.gather`输入强转成`tl.float32`或者放弃优化 |

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/techniques/dynamic-quant/README.md DELETED Viewed

@@ -1,334 +0,0 @@
----
-id: skill-ascend-dynamic-quant
-title: "AscendC DynamicQuant Operator Specification"
-type: skill
-vendor: ascend
-tags:
-- ascendc
-- quantization
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- ascendc
-kernel_types:
-- quantization
-techniques:
-- fine-grained-quantization
-symptoms:
-- per token quantization compute scale then quantize
-- dynamic quant int8
-- quantize with runtime scale
-- 动态量化
-- per-token量化
-aliases:
-- dynamic quant
-- per token quant
----
-# AscendC 量化算子 (DynamicQuant 类) 知识库
-> **本文档仅供参考，不作为绝对约束。** 内容基于一次具体硬件 (Atlas A2 / CANN 8.5.0) 与 CANN 版本下的实测与文档整理；不同 SoC、CANN 版本、kernel 设计场景下接口能力与精度行为可能不同。开发时以官方 API 文档与实测结果为准。
-适用于将每行/每 token 维度的动态量化（per-token / per-row dynamic quant）落到 AscendC 的开发者。覆盖 Cast 接口能力、舍入语义、典型数据流约束、验证标准。
----
-## 1. 算子语义
-per-token dynamic quant 的核心步骤（每个 token / 每行独立）：
-```
-row_max_abs = max(|x|)
-scale       = max(row_max_abs / 127.0, 1e-10)        # fp32
-quantized   = round(x / scale).clamp(-128, 127)      # 输出 int8
-```
-输出两个张量：
-| 输出 | dtype | 形状 | 备注 |
-|---|---|---|---|
-| `quantized` | int8 | 同输入 | 每行独立 round + clamp |
-| `scale` | fp32 | 输入除最后一维 | 每行一个标量 |
-`torch_npu.npu_dynamic_quant(x)` 是这一类算子的标杆参考，内部走 NPU 硬件 quant 单元，不通过标准 AscendC vector API 直接暴露。
----
-## 2. Cast 接口能力（Atlas A2，CANN 8.5.0）
-### 2.1 fp32 → 整数
-| 目的类型 | 支持的 RoundMode |
-|---|---|
-| `int32_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-| `int64_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-| `int16_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-| `int8_t`  | **不支持直接 fp32 → int8 cast，必须走 fp16 中转** |
-### 2.2 fp32 → 浮点
-| 目的类型 | 支持的 RoundMode |
-|---|---|
-| `half` | NONE / ODD（NONE 在有损时 = RINT） |
-| `bfloat16_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-### 2.3 half / bfloat16_t → 整数
-| 源 → 目的 | 支持的 RoundMode |
-|---|---|
-| `half` → `int32_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-| `half` → `int16_t` | RINT |
-| `half` → `int8_t`  | FLOOR / CEIL / ROUND / TRUNC / NONE |
-| `bfloat16_t` → `int32_t` | RINT / FLOOR / CEIL / ROUND / TRUNC |
-### 2.4 不存在的常用 Cast 重载
-| Cast 形式 | 状态 |
-|---|---|
-| `Cast<int8_t, int32_t>` | 不存在（编译失败） |
-| `Cast<int8_t, fp32>` | 不存在 |
-| `Cast<int16_t, int32_t>` | 不存在 |
-需要这些路径时，应组合可用 cast（fp16 中转、int16 中转 + host 端 `.to(int8)` 窄化）。
-### 2.5 RoundMode 语义（`enum class RoundMode`）
-| Mode | 含义 |
-|---|---|
-| `CAST_NONE = 0` | 有精度损失时 = `CAST_RINT`；无损失时不舍入 |
-| `CAST_RINT` | 四舍六入五成双（IEEE round-half-to-even / banker's） |
-| `CAST_FLOOR` | 向 -∞ 舍入 |
-| `CAST_CEIL` | 向 +∞ 舍入 |
-| `CAST_ROUND` | 四舍五入（远离零） |
-| `CAST_TRUNC` | 向零舍入 |
-| `CAST_ODD` | Von Neumann，最近邻奇数舍入 |
----
-## 3. 量化路径选择
-落地 fp32 → int8 时，两条等价但精度特征不同的路径：
-### 路径 A：fp32 → fp16 → int8
-```cpp
-AscendC::Cast(yFp16, yFp32, AscendC::RoundMode::CAST_NONE, count);  // fp16 lossy → 自动 RINT
-AscendC::Cast(yI8,   yFp16, AscendC::RoundMode::CAST_NONE, count);  // half→int8 → RINT
-```
-特点：
-- fp16 的 ulp 在 `|x|≈100` 时约为 0.0625，会把接近整数 .5 的 fp32 值吸到可表示的 fp16 半步上，进而影响最终 int8 的舍入结果
-- 与硬件融合 quant 单元的内部行为更接近
-### 路径 B：fp32 → int16 → host narrow
-```cpp
-AscendC::Cast(yI16, yFp32, AscendC::RoundMode::CAST_RINT, count);  // 直接 banker's 入整
-```
-host 端：`y_int16.to(torch.int8)`（int16 中 [-128,127] 的低字节即 int8）。
-特点：
-- 中间精度全程保持 fp32，避免 fp16 ulp 干扰
-- int16 GM 占用是 int8 的 2×，最大算子 (8192×16384) 约 256 MB 中间张量
----
-## 4. 数值精度要点
-### 4.1 `Div` 与 `Muls` 不等价
-`x / scale`（向量 `Div(y, x, scaleVec)`）和 `x * (1.0f/scale)`（标量 `Muls(y, x, invScale)`）在 fp32 ulp 上有 1–2 位漂移，可能让正好处在整数 .5 边界的元素倒向另一侧。需要严格匹配 reference 的除法语义时，使用 `Div`（`scaleVec` 由 `Duplicate` 填充）。
-### 4.2 标量写 GM 必须走 UB + DataCopyPad
-```cpp
-// 推荐
-AscendC::LocalTensor<float> scaleLocal;
-scaleOutQueue_.AllocTensor<float>(scaleLocal);
-AscendC::Duplicate(scaleLocal, scale, 8);  // pad 到 32 B 满足 DataCopyPad 对齐
-scaleOutQueue_.EnQue(scaleLocal);
-scaleOutQueue_.DeQue<float>(scaleLocal);
-StoreUbToGm(scaleGM_[rowIdx], scaleLocal, 1);
-scaleOutQueue_.FreeTensor(scaleLocal);
-```
-`GlobalTensor::SetValue(idx, val)` 是直写指令，与 vector pipeline 不在同一通道，host 读回时不保证已落盘；用 UB + `DataCopyPad`（即 `StoreUbToGm`）走标准 EnQue/DeQue 才能正确同步。
-### 4.3 输入 dtype 转 fp32 是无损的
-`bf16 → fp32` 和 `fp16 → fp32` 均无损（fp32 的 mantissa/exponent 范围严格覆盖两者），用 `Cast<fp32, dataType, CAST_NONE>` 即可。
-### 4.4 reduce 用 fp32 累加
-`max(|x|)` 应在 fp32 域内用 `Abs` + `ReduceMax<float>` 完成；用输入 dtype 直接 reduce 会丢失 1 ulp 精度，导致 `scale = max/127` 与参考偏差。
----
-## 5. TQue 与 Cast 接口的常见约束
-### 5.1 `TQue<..., 0>`（depth=0）的 DeQue 形式
-```cpp
-AscendC::TQue<AscendC::TPosition::VECOUT, 0> outQ;
-AscendC::LocalTensor<int16_t> outLocal;
-outQ.AllocTensor<int16_t>(outLocal);   // 引用形式：可
-outQ.DeQue<int16_t>(outLocal);         // 引用形式：可
-auto x = outQ.DeQue<int16_t>();        // 返回值形式：编译失败（depth=0 时 static_assert）
-```
-depth=0 + 返回值 DeQue 触发 `static_assert((depth != 0), "must use DeQue<LocalTensor&> api ...")`。两种解法：把 depth 改为 ≥1，或全部使用引用形式。
-### 5.2 Cast 起始地址 32 B 对齐
-`Cast` 的 `dst` / `src` 起始地址必须 32 B 对齐。`AllocTensor` 默认满足；`Get<T>()` 自 `TBuf` 取出的 LocalTensor 同样从 buffer 起始位置对齐。
-### 5.3 `DataCopyPad` 写不足 32 B 的元素
-写 1 个 fp32（4 B）回 GM 时仍需走 `DataCopyPad`，UB 一侧用 `Duplicate(buf, val, 8)` 填到 32 B 后传 `count = 1`：
-```cpp
-AscendC::DataCopyExtParams params{1, sizeof(float), 0, 0, 0};
-AscendC::DataCopyPad(scaleGM_[rowIdx], scaleLocal, params);
-```
----
-## 6. 验证标准
-`utils/verification_ascendc.py` 对比 reference 与 candidate 输出：
-| 输出 dtype | 判定方式 |
-|---|---|
-| 浮点 (fp16 / bf16 / fp32) | MERE / MARE 阈值（threshold 取自 `PRECISION_THRESHOLDS`） |
-| int8 / int16 | **元素级 max abs diff ≤ 1**（`INT_LSB_TOLERANCE`） |
-| int32 / int64 / bool | `torch.equal` 严格按位 |
-```python
-INT_LSB_TOLERANCE = {
-    torch.int8:  1,
-    torch.int16: 1,
-}
-```
-判定逻辑：
-```python
-diff = (rhs.to(torch.int32) - lhs.to(torch.int32)).abs()
-max_abs = diff.max().item()
-if max_abs <= tol:
-    return True
-```
-容忍度是张量内的最大值，**不是平均值**：哪怕只有一个元素差 2，整张张量判 fail。
-浮点阈值：
-| dtype | MERE threshold | MARE threshold |
-|---|---|---|
-| float16 | 9.77e-4 | 9.77e-3 |
-| bfloat16 | 7.81e-3 | 7.81e-2 |
-| float32 | 1.22e-4 | 1.22e-3 |
-scale 输出（fp32）走 MERE/MARE，量化输出（int8）走 ±1 LSB。
----
-## 7. 输入与 Tiling
-### 7.1 输入 shape 处理
-per-token 量化对最后一维做 reduce + scale。任意维度输入可以 host 端 reshape 成 2D `[M, N]`：
-```python
-x_2d = x.reshape(-1, x.shape[-1]).contiguous()
-y_2d, scale_1d = _ext.run_op(x_2d)
-y     = y_2d.reshape(x.shape)
-scale = scale_1d.reshape(x.shape[:-1])
-```
-### 7.2 N 较大时的 split-D
-UB 容量下整行可能装不下 fp32 工作 buffer。N 拆为 `kBlockN`（典型 4096）后，每行内 reduce 与 quant 各做一遍 chunk 循环：reduce 阶段累计 chunk-max；quant 阶段用已确定的 scale 做整行划分。
-### 7.3 Block / Core 划分
-每核处理 `blockM` 行（典型 16）；AIV 子块 = `blockM / GetSubBlockNum()`；usedCoreNum = `min(20, ceil(M / blockM))`。
----
-## 8. Pybind 与 Host 接口
-### 8.1 Tiling struct
-```cpp
-struct DynamicQuantTiling {
-    int32_t M, N;
-    int32_t blockM;
-    int32_t usedCoreNum;
-    int32_t tasksPerCore;
-    int32_t pad0;  // 32 B 对齐
-};
-```
-### 8.2 Launch dispatch
-```cpp
-LaunchFn launch = nullptr;
-if (x.scalar_type() == at::kHalf)         launch = dynamic_quant_do_fp16;
-else if (x.scalar_type() == at::kBFloat16) launch = dynamic_quant_do_bf16;
-else TORCH_CHECK(false, "unsupported dtype");
-```
-### 8.3 输出张量分配
-| 路径 | y 输出 dtype |
-|---|---|
-| 路径 A（fp16 中转） | `at::kChar`（int8）直接出 |
-| 路径 B（int16 + host narrow） | `at::kShort`（int16） |
-scale 一律 `at::kFloat`。
----
-## 9. KERNEL_TYPE 与 vec_num
-| vec_num | KERNEL_TYPE 宏 | 每 block 组成 |
-|---|---|---|
-| 1 | `KERNEL_TYPE_MIX_AIC_1_1` | 1 AIC + 1 AIV |
-| 2 | `KERNEL_TYPE_MIX_AIC_1_2` | 1 AIC + 2 AIV |
-per-token quant 的 reduce + 单值 scale 写出场景，`KERNEL_TYPE_MIX_AIC_1_2` 即可（计算全在 AIV）。
----
-## 10. 参考实现位置
-| 算子 | 可复用模式 |
-|---|---|
-| `archive_tasks/rms_norm/` | per-row reduce + 标量写 scale 的 `vector_tile.h` / `_kernel.h` 模板 |
-| `archive_tasks/reshape_matmul_rowwise_quant_int8/` | fp32 → fp16 → int8 cast 链（`quant_kernel.h`） |
-| `archive_tasks/quant_matmul/` | int8 输出的 host pybind / tiling 模式 |
----
-## 11. 涉及的 AscendC API 速查
-| 用途 | API |
-|---|---|
-| 行内绝对值 | `AscendC::Abs(dst, src, count)` |
-| 行内最大值 reduce | `AscendC::ReduceMax<float>(dst, src, work, count, false)` |
-| 标量乘整向量 | `AscendC::Muls(dst, src, scalar, count)` |
-| 向量除（标量需先 `Duplicate`） | `AscendC::Div(dst, src0, src1, count)` |
-| 向量 clamp 上下界 | `AscendC::Mins`, `AscendC::Maxs` |
-| 向量填充常量 | `AscendC::Duplicate(dst, scalar, count)` |
-| 类型转换 | `AscendC::Cast(dst, src, RoundMode, count)` |
-| GM↔UB 传输（任意 count） | `DataCopyPad`（封装为 `LoadGmToUb` / `StoreUbToGm`） |
-完整定义见 `wiki/ascend/api-definitions/ascendc/INDEX.md`。

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/techniques/float-to-bf16-round-half-even.md DELETED Viewed

@@ -1,80 +0,0 @@
----
-id: technique-ascend-float-to-bf16-round-half-even
-title: "Explicit Round-Half-to-Even When Narrowing fp32 to bf16"
-type: technique
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910c
-languages:
-- ascendc
-evidence_level: measured
-cann_version: '9.0.1'
-confidence: experimental
-reproducibility: snippet
-prerequisites:
-- A kernel that produces fp32 internally and must hand back bf16
-- Knowing which rounding mode the reference implementation uses
-scope: >-
-  Use when the acceptance criterion compares against a reference that rounds
-  once, at the end. It does NOT help when the reference itself rounds at an
-  intermediate step - there you must reproduce the reference's rounding points,
-  not improve on them.
-tags:
-- ascendc
-related:
-- pitfall-ascend-device-side-dtype-cast
-sources:
-- exp-ascend910c-target-env-divergence
-aliases:
-- "float 转 bf16 就近偶数舍入"
-- "手写 bf16 舍入"
-- "不要依赖硬件默认舍入"
----
-# Explicit Round-Half-to-Even When Narrowing fp32 to bf16
-## Why not leave it to the hardware
-bf16 is the top 16 bits of an fp32. A truncating narrow is one instruction and
-is wrong by up to one ulp in a consistent direction, which shows up as a small
-systematic bias rather than as noise — exactly the shape that survives a loose
-absolute-error check and fails a relative-error one.
-The default rounding a given path applies is not something to assume. Writing it
-out costs three integer operations and removes the question.
-## The narrow
-```cpp
-constexpr uint32_t kBf16RoundBias = 0x7fffu;
-__aicore__ inline uint16_t FloatToBf16(float f) {
-    union { float f; uint32_t u; } v;
-    v.f = f;
-    uint32_t lsb     = (v.u >> 16) & 1u;         // parity of the kept mantissa
-    uint32_t rounded = v.u + kBf16RoundBias + lsb;
-    return static_cast<uint16_t>(rounded >> 16);
-}
-```
-Adding `0x7fff + lsb` rounds half-way values toward the even neighbour: when the
-discarded bits are exactly half an ulp, the carry propagates only if the kept
-low bit is already 1.
-## Where to put it
-Inside the kernel, templated on the output type — not as a host-side
-`Tensor::to(dtype)`, which is a device dispatch whose availability depends on
-the runtime release
-([pitfall-ascend-device-side-dtype-cast](../foundations/host-plugin/device-side-dtype-cast.md)).
-## Multi-output operators need this decided per output
-A layered operator writing intermediate results back into caller tensors has
-more than one output type in play, and they are not interchangeable. A single
-`<TOut>` template across all of them writes a 4-byte float into a 2-byte slot;
-the symptom is one output reporting mismatched NaN positions while the others
-look fine. Split the template — `<TY, TState>` — so each output carries its own
-type.