HarmonyOS NEXT 在 Ascend 310P（端侧 NPU）上跑 LLM 推理——和云端 910 完全不同：HBM 32GB→8GB（HBM→DDR，带宽 1.2TB/s→68GB/s）、功耗 300W→25W（被动散热）、延迟要求 200ms 首 token（云端不敏感但端侧用户 app 感知强烈）。

cann-recipes-harmony-infer 提供端侧部署的端到端 Recipe：ONNX→OM 模型转换、INT8 对称量化、内存规划（静态 vs 动态）、Profile-guided 算子选择。

端侧推理栈

PyTorch Model (FP32, 7B params = 28GB)
  ↓ export
ONNX (FP32, 28GB)
  ↓ ATC (Ascend Tensor Compiler) + INT8 calib
OM (INT8, 7GB)  ← 运行在 HarmonyOS 上
  ↓ ACL (Ascend Compute Language) Runtime
Ascend 310P NPU (8GB DDR, 8 TOPS INT8, 25W)

ATC 模型转换：ONNX → OM

ATC 把 PyTorch/ONNX 的通用算子映射到 Ascend 310P 硬件 ISA（比 910 少 Cube 指令、多 Vector 指令）。关键：310P 不支持某些 910 的算子（大矩阵 MatMul 用 Cube，小矩阵用 Vector 替代）。

# cann-recipes-harmony-infer/atc/convert.sh

# Step 1: ONNX 模型
# model.onnx (FP32, 28GB) - 从 PyTorch 导出的通用格式

# Step 2: INT8 量化校准（需要校准数据集）
# 生成 calibration set（500 个样本足够覆盖激活值分布）
python generate_calib_dataset.py \
    --model model.onnx \
    --output calib_set.bin \
    --num_samples 500

# Step 3: ATC 转换
atc --model=model.onnx \
    --framework=5 \                    # 5 = ONNX
    --output=model_om \                # 输出 OM 文件
    --soc_version=Ascend310P3 \        # 目标芯片
    --input_format=ND \
    --input_shape="input_ids:1,-1" \   # dynamic batch（-1 = 动态）
    --dynamic_batch_size="1,2,4,8" \  # 支持的 batch sizes
    --precision_mode=force_fp16 \      # FP16 降精度（28GB→14GB）
    --calibration_data=calib_set.bin \ # INT8 校准
    --insert_op_conf=aipp.cfg          # AIPP 预处理（图像类模型）

ATC 的算子映射失败时有三种处理：

1. 融合：ONNX 的 MatMul+Add+ReLU → 310P 的融合指令（1 条）
2. 回退：310P 没有的 Cube 指令 → Vector 指令替代（慢但可用）
3. AICPU：Vector 也做不到的 → CPU fallback（DDR→CPU→DDR，50× slowdown，紧急避免）

INT8 对称量化：FP32→INT8

端侧 8GB DDR，7B FP32 = 28GB → INT8 = 7GB（刚好 fit）。对称量化：scale = max(|x|) / 127，0 映射到 0（关键：Zero Point = 0，推理不漂移）。

# cann-recipes-harmony-infer/quant/int8_symmetric.py

class INT8SymQuantizer:
    """
    对称 INT8 量化：范围 [-127, 127]
    Scale = max(|W|) / 127
    W_int8 = round(W_fp32 / scale)

    Zero Point = 0（关键：去 bias 加法时补偿为 0）
    """

    def quantize_weight(self, W_fp32):
        """权重量化（静态，已知范围）"""
        max_abs = torch.max(torch.abs(W_fp32))
        scale = max_abs / 127.0

        # 量化
        W_int8 = torch.clamp(
            torch.round(W_fp32 / scale), -127, 127
        ).to(torch.int8)

        return W_int8, scale

    def quantize_activation(self, X_fp16, calib_scale=None):
        """
        激活量化（动态范围，运行时确定）
        使用校准集统计 min/max → 固定 scale（静态）

        calib_scale: 校准集确定的范围（推理时固定）
        """
        if calib_scale is not None:
            scale = calib_scale
        else:
            max_abs = torch.max(torch.abs(X_fp16))
            scale = max_abs / 127.0

        X_int8 = torch.clamp(
            torch.round(X_fp16 / scale), -127, 127
        ).to(torch.int8)

        return X_int8, scale

    def calibrate(self, model, calib_dataloader, num_samples=500):
        """
        校准：跑 500 个样本来统计每层激活的 max(|x|)
        校准集 → 每层的 activation scale（推理时固定）
        """
        activation_stats = {}  # layer_name → (max_abs, running_count)

        model.eval()
        with torch.no_grad():
            for i, batch in enumerate(calib_dataloader):
                if i >= num_samples:
                    break

                # Hook 每层输出来收集 max(|activation|)
                hooks = self._register_act_hooks(model, activation_stats)
                _ = model(batch)
                for h in hooks:
                    h.remove()

        # 计算每层 scale
        scales = {}
        for layer_name, (max_abs, count) in activation_stats.items():
            # 用 99.9% percentile（截断 outlier）
            # percentile 比 max 更稳定（max 被 1 个 outlier 影响）
            scales[layer_name] = max_abs / 127.0
            scales[layer_name + "_percentile"] = (
                torch.quantile(activation_stats[layer_name], 0.999) / 127.0
            )

        return scales

    # MatMul with INT8 (dequant after)
    def int8_matmul(self, A_int8, A_scale, B_int8, B_scale):
        """
        A_int8 × B_int8 → FP32
        scale = A_scale × B_scale（后乘）
        """
        # A_int8 [M, K] × B_int8 [K, N] → C_int32 [M, N]
        C_int32 = torch._int8_matmul(A_int8, B_int8)

        # 反量化：C_fp32 = C_int32 × A_scale × B_scale
        C_fp32 = C_int32.float() * (A_scale * B_scale)

        return C_fp32

内存规划：静态布局 vs 动态分配

端侧 8GB DDR，LLM 推理的内存需求：

| Component                 | FP16   | INT8  |
|--------------------------|--------|-------|
| Model Weights (7B)       | 14 GB  | 7 GB  |
| KV Cache (4K context)    | 2.1 GB | 2.1 GB (int8不行，需要FP16精度) |
| Activations (1 batch)    | 0.5 GB | 0.5 GB |
| Workspace (intermediate) | 1.0 GB | 0.5 GB |
| **TOTAL**                | 17.6 GB| 10.1 GB |

8GB DDR → 即使 INT8 也超。内存优化：
1. Weight Sharing: 32 layers × weight(paged)，不是全加载（1-2 layers in DDR + rest in flash）
2. KV Cache quantization: KV int8（牺牲 0.1% 精度，省 2x）

# cann-recipes-harmony-infer/memory/memory_planner.py

class EdgeMemoryPlanner:
    """
    端侧 8GB DDR 内 7B LLaMA INT8 + 4K context 的内存规划
    → Weight streaming + KV Cache quantization + Static workspace
    """

    def plan(self, model_size_gb, kv_ctx_len, batch_size):
        total = 8.0  # 8 GB total

        # 1. Model weights: 7GB INT8（streaming 加载）
        #    32 layers → 一次加载 4 layers（1.0GB）+ rest in flash
        weight_mem = 7.0
        weight_streamed = 1.0  # 只保留 4 layers，其余从 flash 流加载

        # 2. KV Cache: 每层保存 K/V = 2 × (D × ctx_len × layers)
        #    LLaMA-7B: D=4096, ctx_len=4K, layers=32
        #    KV size = 2 × 4096 × 4096 × 32 × 2 bytes (FP16) = 2.1 GB
        #    INT8 KV: 2 × 4096 × 4096 × 32 × 1 byte = 1.05 GB
        kv_cache_fp16 = 2.1
        kv_cache_int8 = 1.05

        # 3. Activations + workspace
        activations = 0.3  # 单 batch, FP16
        workspace = 0.2

        # 总计
        total_used = (weight_streamed + kv_cache_int8 +
                      activations + workspace)  # = 1.0 + 1.05 + 0.3 + 0.2 = 2.55 GB < 8 GB

        # ✅ 剩余 5.45 GB buffer（DDR band 67GB/s 够用）
        return total_used

    def static_workspace(self, model_layers):
        """静态 workspace：编译时预分配，不会重分配"""
        # 预分配：最坏情况的 tensor（各算子的中间输出）
        # Reshape/Slice 只改 strides（零拷贝）
        # MatMul 的中间 [batch, seq, D]
        max_seq = 4096
        max_d = 4096

        # Tensor 描述符（只有 view，不会是拷贝）
        view_table = torch.empty(32 * 3, dtype=torch.long)  # 32 layers × 3 descriptors

        return view_table  # 预分配的碾压优化（再不需要 malloc/free）

踩坑一：ATC 算子回退——Cube MatMul 回退 Vector 时 20× slowdown

310P 只有小 Cube（4×4 systolic），大矩阵 MatMul [4096, 128] × [128, 4096] 用 Cube 单元（4×4 array → burst 4KB）。但如果 310P 不支持这种尺寸的 Cube → Vector 单元逐行×逐列（128 次 Vector multiply）。

# ❌ 大矩阵 Cube 不支持 → 自动回退 Vector
# MatMul [4096, 128] × [128, 4096]
# Cube:  1.2 ms        Vec: 26 ms  (20× slowdown)
# 每层 FC (feed-forward) 都是 [1024,128]×[128,1024] → 32 layers × 2 FF → 64 MatMuls

# ✅ 分块 MatMul（手动 Tiling）
# 把 [4096, 128] 切成长度为 256 的块（310P 支持 256×256 Cube）
# 256 × 256 → 16 blocks × 16 blocks = 256 Cube ops per MatMul
# 1.2 ms (原) → 2.4 ms (tiling overhead ×2 = 2 blocks) → still 10× faster than Vector

def tiled_matmul(A, B, tile_size=256):
    """尾补 padding + tiling MatMul（适配 310P Cube）"""
    M, K = A.shape
    K, N = B.shape

    C = torch.zeros(M, N)
    for m in range(0, M, tile_size):
        for n in range(0, N, tile_size):
            for k in range(0, K, tile_size):
                C[m:m+tile_size, n:n+tile_size] += torch.matmul(
                    A[m:m+tile_size, k:k+tile_size],
                    B[k:k+tile_size, n:n+tile_size]
                )
    return C

踩坑二：INT8 calibration 用 max 时 outlier 污染

某层 Attention QKV 的 max(|activation|) = 287.2（outlier = 300+），其他 99% 样本 max(|x|) = 4.1。scale = 287.2/127 = 2.26，导致 99% activation 被量化到 [4.1/2.26=1.8] → 仅 2 of 255 bins → 精度损失 8×。

# ❌ max(|x|) 的 outlier 污染 calibration
max_abs_nn = 287.2   # Attention QKV outlier
scale = 287.2/127    # 2.26 → 4.1/data → 2 quant bins (vs 127 bins)
# → 99% data compressed to 2 of 128 levels → useless for model

# ✅ 99.9th percentile（排除 top 0.1% outlier）
sorted_act = torch.abs(X_fp16).flatten().sort(descending=True)
pct_999 = sorted_act[int(0.001 * X_fp16.numel())]  # 99% below this → 4.1
scale = pct_999 / 127.0  # 4.1/127=0.032 → data [1, 127] bins → full dynamic range

踩坑三：Dynamic shape KV Cache 的内存碎片

LLaMA-7B INT8 = 7GB static weights + 2.1GB KV Cache（dynamic）。KV Cache 随 token 增长（1→4096 tokens），每次 resize → OS 页表修改 + DDR 块移动 → 50ms per resize × 4096 tokens = 205ms（首 token 500ms + 205ms resize = 700ms → 超 200ms deadline）。

# ❌ Dynamic KV Cache: 每个 decoder step 扩 1 token → DDR resize
kv_cache: torch.Tensor = [2, 32, 4096, 4096]  # batch × layers × ctx_len × D
# KV shape dynamic dim: dim[2] 增长 = 内存 reallocation per step

# ✅ Pre-allocated KV Cache with Sliding Window
kv_cache = torch.zeros(2, 32, 4096, 4096, device="npu")  # max ctx_len
kv_window_size = 4096  # 预分配满

kv_write_ptr = 0  # 环形 buffer 写指针（不是 resize，只是指针++）
# sliding window: newest 4096 tokens → overwrite oldest
# → 写指针在 0→4096→0（没有 realloc）
# 每次 decode step: kv_cache[:, :, kv_write_ptr] = K_new, V_new
kv_write_ptr = (kv_write_ptr + 1) % kv_window_size

cann-recipes-harmony-infer 提供 310P 端侧推理的完整 Recipe：ATC ONNX→OM（算子映射+回退处理）、INT8 对称量化（7GB fit 8GB+KVCache int8）、静态内存规划（weight streaming + sliding KV Cache 零 resize）。三个踩坑：310P 大矩阵 Cube 缺失回退 Vector 20× slowdown→分块 Tiling 2.4ms vs 26ms、calibration max outlier 污染 99%→99.9th percentile、KV Cache dynamic resize 205ms→预分配环形 buffer 滑动窗口。