ACES推理引擎 CPU 版优化教材

版本: v1.0
基于源码: zhanlu_engine.cpp (v9.0 AVX2 优化版)
目标硬件: x86-64 CPU (支持 AVX2/FMA)，14 物理核心
测试模型: Qwen2.5-1.5B-Instruct-Q4_K_M
最终性能: 11.1 tok/s (CPU-only)，原始版的 3.7 倍

开源地址: https://gitee.com/lwlzmck/zhanlu（核心源码 zhanlu_engine.cpp，性能测试脚本 test_cpu_15b.py）

前言

本教材完整记录了ACES推理引擎 CPU 版本从"原始标量实现"到"AVX2 SIMD 优化"的全过程。引擎基于 llama.cpp 思路自研，支持 GGUF 格式模型加载和推理，在 14 核 CPU 上运行 1.5B 模型达到 11.1 tok/s，同时修复了集成显卡环境下的 4094/1024 越界崩溃。

优化过程遵循"理论测量 → 工程实现 → 实测验证 → 反证修正"的闭环方法论。每一项优化都有明确的数学依据、代码实现和性能数据，所有结论均可复现。

核心设计哲学：

• 权重保持原始量化格式（Q4_K/Q6_K），不存 FP32，内存占用最小
• 矩阵乘用 fused 反量化+点积内核，避免中间缓冲区的内存往返
• 所有轻量算子（RMS Norm、RoPE、Attention、SwiGLU）用 OpenMP 并行 + SIMD 优化
• 接口与 CUDA 版（zhanlu_engine_cuda.cu）完全一致，Python backend 无感知切换
• 运行时 CPU 特性检测，不支持 AVX2 自动回退标量版

---

一、数学公式与代码实现

1.1 RMS Norm（层归一化）

数学公式：

$$\text{RMSNorm}(x)=\frac{x}{\sqrt{\frac{1}{d}{\sum }_{i=1}^d{x}_i^2+ϵ}}$$

其中 $ϵ$ 为数值稳定常数（Qwen2 用 $10^{-6}$）。

代码实现：

static inline void rms_norm(float* x, const float* weight, int n) {
    float sum = 0.0f;
    #pragma omp simd reduction(+:sum)
    for (int i = 0; i < n; ++i) sum += x[i] * x[i];
    float scale = 1.0f / sqrtf(sum / n + 1e-6f);
    #pragma omp simd
    for (int i = 0; i < n; ++i) x[i] *= scale * weight[i];
}

要点：#pragma omp simd 提示编译器自动向量化，配合 /arch:AVX2 生成 256 位 SIMD 指令。

---

1.2 RoPE（旋转位置编码）

数学公式（NeoX 风格半部分配对）：

对于第 $p$ 个位置、第 $i$ 维（$i<d/2$）：

$$q_{2i}^{\prime }=q_{2i}\cos (p\cdot {\theta }_i)-q_{2i+1}\sin (p\cdot {\theta }_i)$$
$$q_{2i+1}^{\prime }=q_{2i}\sin (p\cdot {\theta }_i)+q_{2i+1}\cos (p\cdot {\theta }_i)$$

其中 ${\theta }_i=10000^{-2i/d}$（Qwen2.5 的 rope_theta=1000000）。

代码实现：

void rope(float* q, float* k, int head_dim, int pos) {
    int half = head_dim / 2;
    for (int i = 0; i < half; ++i) {
        float c = _rope_cos[pos * half + i];
        float s = _rope_sin[pos * half + i];
        if (q) {
            float q0 = q[i], q1 = q[i + half];
            q[i] = q0 * c - q1 * s;
            q[i + half] = q0 * s + q1 * c;
        }
        if (k) { /* K 同理 */ }
    }
}

优化：模型加载时预计算 cos/sin 表（max_pos × half_dim），推理时直接查表，避免重复计算三角函数。1.5B 模型预计算表仅 8.0MB（32768 × 64 × 2 × 4字节）。

---

1.3 多头注意力（Multi-Head Attention）

数学公式：

$$\text{Attention}(Q,K,V)=\text{softmax}\left(\frac{Q{K}^T}{\sqrt{d_k}}\right)V$$

GQA（Grouped Query Attention）：$n_{kv\_heads}<n_{heads}$，多个 Q head 共享同一组 K/V head。

代码实现（OpenMP 并行 head 维度 + f16 KV Cache）：

#pragma omp parallel for schedule(static) num_threads(_optimal_threads)
for (int h = 0; h < n_heads; ++h) {
    float* q_head = _buf_q.data() + h * head_dim;
    int kh = h / (n_heads / n_kv_heads);  // GQA 映射
    float* scores = _buf_scores_per_head.data() + h * seq_len;
    float* out_head = _buf_attn.data() + h * head_dim;

    // QK^T + 内存预取
    for (int t = 0; t < seq_len; ++t) {
        const uint16_t* k_head = key_cache_ptr + t * n_kv_heads * head_dim + kh * head_dim;
        if (t + 1 < seq_len)
            _mm_prefetch((const char*)(k_head + n_kv_heads * head_dim), _MM_HINT_T0);
        float dot = 0.0f;
        #pragma omp simd reduction(+:dot)
        for (int d = 0; d < head_dim; ++d)
            dot += q_head[d] * fp16_to_f32(k_head[d]);
        scores[t] = dot / sqrtf((float)head_dim);
    }
    // softmax（先 max 后 exp-sum，避免溢出）
    float max_s = scores[0];
    for (int t = 1; t < seq_len; ++t) if (scores[t] > max_s) max_s = scores[t];
    float sum_exp = 0.0f;
    for (int t = 0; t < seq_len; ++t) { scores[t] = expf(scores[t] - max_s); sum_exp += scores[t]; }
    float inv_sum = 1.0f / sum_exp;
    // 加权 V + 内存预取
    for (int t = 0; t < seq_len; ++t) {
        const uint16_t* v_head = value_cache_ptr + t * n_kv_heads * head_dim + kh * head_dim;
        if (t + 1 < seq_len)
            _mm_prefetch((const char*)(v_head + n_kv_heads * head_dim), _MM_HINT_T0);
        float w = scores[t] * inv_sum;
        #pragma omp simd
        for (int d = 0; d < head_dim; ++d)
            out_head[d] += w * fp16_to_f32(v_head[d]);
    }
}

要点：

• KV Cache 用 f16（uint16_t）存储，内存减半
• 每个 OpenMP 线程处理一个 Q head，_buf_scores_per_head 按 head 独立分配避免竞争
• _mm_prefetch 预取下一个 K/V 向量，减少缓存未命中
• decode 阶段（Q 单 token）朴素注意力已最优，Flash Attention 的分块+同步是纯开销

---

1.4 SwiGLU 激活函数

数学公式：

$$\text{SwiGLU}(x)=\text{SiLU}(W_{g}x)\odot (W_{u}x)$$

其中 $\text{SiLU}(x)=x\cdot \sigma (x)=x\cdot \frac{1}{1+e^{-x}}$。

代码实现：

#pragma omp simd
for (int i = 0; i < hidden_dim; ++i)
    _buf_gate[i] = _buf_gate[i] * (1.0f / (1.0f + expf(-_buf_gate[i]))) * _buf_up[i];

历史教训：早期实现曾漏掉 gate[i] *（只做了 sigmoid(gate) * up），导致 FFN 输出完全错误。注释中明确标注了此修复。

---

1.5 Q4_K 量化格式

数学原理：

Q4_K 将 256 个元素分为 8 个 sub-block（每个 32 元素），每个 sub-block 有独立的 6-bit scale 和 6-bit min：

$$x_i=d\cdot s_j\cdot q_i-d_{min}\cdot m_j$$

其中：

• $d$：全局 scale（half，2 字节）
• $d_{min}$：全局 min（half，2 字节，存储的是 $-\min$）
• $s_j\in [0,63]$：第 j 个 sub-block 的 scale（6-bit 整数，非归一化）
• $m_j\in [0,63]$：第 j 个 sub-block 的 min（6-bit 整数）
• $q_i\in [0,15]$：4-bit 量化值

数据结构：

struct block_q4_K {
    uint16_t d;        // 全局 scale（half 位模式）
    uint16_t dmin;     // 全局 min（half 位模式）
    uint8_t scales[12]; // 8 个 sub-block 的 scale/min（6-bit 打包成 12 字节）
    uint8_t qs[128];   // 256 个 4-bit 量化值（低/高 nibble 交错）
};
static_assert(sizeof(block_q4_K) == 144, "Q4_K must be 144 bytes");

qs 内存布局（关键）：

• qs[0..31]：低 nibble = sub-block 0 的 32 个元素，高 nibble = sub-block 1 的 32 个元素
• qs[32..63]：sub-block 2 和 3
• qs[64..95]：sub-block 4 和 5
• qs[96..127]：sub-block 6 和 7

即两个 sub-block 共享 32 字节，低 nibble 是偶数 sub-block，高 nibble 是奇数 sub-block。

scales 打包方式：

• scales[0..3]：sub-block 0-3 的 scale（低 6 位）
• scales[4..7]：sub-block 0-3 的 min（低 6 位）
• scales[8..11]：sub-block 4-7 的 scale（低 4 位）和 min（低 4 位），高 2 位存在 scales[0…3]/scales[4…7] 的高 2 位

解包函数：

static inline void get_scale_min_k4(int j, const uint8_t* q, uint8_t& d, uint8_t& m) {
    if (j < 4) { d = q[j] & 63; m = q[j + 4] & 63; }
    else { d = (q[j+4] & 0xF) | ((q[j-4] >> 6) << 4); m = (q[j+4] >> 4) | ((q[j] >> 6) << 4); }
}

---

1.6 Q6_K 量化格式

数学原理：

Q6_K 将 256 个元素分为 16 个 sub-block（每个 16 元素），每个 sub-block 有独立的 8-bit scale：

$$x_i=d\cdot s_j\cdot q_i$$

其中 $q_i\in [-32,31]$ 为 6-bit 有符号量化值。

数据结构：

struct block_q6_K {
    uint8_t ql[128];   // 低 4 位（256 个元素，每字节 2 个）
    uint8_t qh[64];    // 高 2 位（256 个元素，每字节 4 个）
    int8_t scales[16]; // 16 个 sub-block 的 scale（8-bit 有符号）
    uint16_t d;        // 全局 scale（half 位模式）
};
static_assert(sizeof(block_q6_K) == 210, "Q6_K must be 210 bytes");

6-bit 值重组：

int8_t q1 = (int8_t)((ql[l] & 0xF) | (((qh[l] >> 0) & 3) << 4)) - 32;

Q6_K 精度更高但反量化复杂，性能比 Q4_K 慢 2-3 倍。v7.0 已将 wv/w2 层在加载时转换为 Q4_K。

---

1.7 Fused 反量化+点积（标量版）

数学公式：

$$y_r=\sum _{i=0}^{k-1}{W}_{r,i}\cdot x_i=\sum _{b=0}^{k/256-1}\sum _{j=0}^7\left(d\cdot s_j\cdot \sum _{i=0}^{31}{q}_{b,j,i}\cdot x_{b,j,i}-d_{min}\cdot m_j\cdot \sum _{i=0}^{31}{x}_{b,j,i}\right)$$

代码实现（v8.0 标量 fused 版）：

static inline float dot_q4_K_fused(const uint8_t* row_ptr, const float* vec, int k) {
    const int nb = k / QK_K;
    float sum = 0.0f;
    for (int i = 0; i < nb; i++) {
        const block_q4_K* blk = (const block_q4_K*)(row_ptr + i * sizeof(block_q4_K));
        const uint8_t* q = blk->qs;
        const float d = fp16_to_f32(blk->d);
        const float min = fp16_to_f32(blk->dmin);
        const float* vblk = vec + i * QK_K;
        int is = 0; uint8_t sc, m;
        for (int j = 0; j < QK_K; j += 64) {
            get_scale_min_k4(is + 0, blk->scales, sc, m);
            float d1 = d * sc, m1 = min * m;
            get_scale_min_k4(is + 1, blk->scales, sc, m);
            float d2 = d * sc, m2 = min * m;
            for (int l = 0; l < 32; ++l) sum += (d1 * (q[l] & 0xF) - m1) * vblk[j + l];
            for (int l = 0; l < 32; ++l) sum += (d2 * (q[l] >> 4) - m2) * vblk[j + 32 + l];
            q += 32; is += 2;
        }
    }
    return sum;
}

优势：避免先反量化到临时缓冲区再做点积，减少一次内存写入+读取（约 k×4 字节的内存往返）。

---

1.8 AVX2 优化的 Fused 反量化+点积（v9.0）

核心思路：用 256 位 AVX2 寄存器一次处理 8 个 float，_mm256_fmadd_ps 一条指令完成乘加。

代码实现：

static inline float dot_q4_K_avx2(const uint8_t* row_ptr, const float* vec, int k) {
    const int nb = k / QK_K;
    float sum = 0.0f;
    const __m256i mask_0f = _mm256_set1_epi8(0x0F);
    for (int i = 0; i < nb; i++) {
        const block_q4_K* blk = (const block_q4_K*)(row_ptr + i * sizeof(block_q4_K));
        const float d = fp16_to_f32(blk->d);
        const float dmin = fp16_to_f32(blk->dmin);
        const float* vblk = vec + i * QK_K;
        const uint8_t* q = blk->qs;
        for (int pair = 0; pair < 4; pair++) {
            uint8_t sc0, mn0, sc1, mn1;
            get_scale_min_k4(pair*2, blk->scales, sc0, mn0);
            get_scale_min_k4(pair*2+1, blk->scales, sc1, mn1);
            __m256 vd0 = _mm256_set1_ps(d * sc0);
            __m256 vm0 = _mm256_set1_ps(dmin * mn0);
            __m256 vd1 = _mm256_set1_ps(d * sc1);
            __m256 vm1 = _mm256_set1_ps(dmin * mn1);
            __m256 vsum = _mm256_setzero_ps();
            const float* v0 = vblk + pair*64;
            const float* v1 = vblk + pair*64 + 32;
            for (int l = 0; l < 32; l += 8) {
                // 加载 8 字节（每字节含 sub0 和 sub1 各一个元素）
                __m128i q8 = _mm_loadl_epi64((const __m128i*)(q + l));
                // 无符号扩展为 8 个 32bit 整数（关键：必须用 cvtepu8，不能用 cvtepi8）
                __m256i q32 = _mm256_cvtepu8_epi32(q8);
                // 低 nibble = sub0，高 nibble = sub1
                __m256i iq0 = _mm256_and_si256(q32, mask_0f);
                __m256i iq1 = _mm256_and_si256(_mm256_srli_epi32(q32, 4), mask_0f);
                // 转为 float
                __m256 fq0 = _mm256_cvtepi32_ps(iq0);
                __m256 fq1 = _mm256_cvtepi32_ps(iq1);
                // w = d * q - m
                __m256 w0 = _mm256_sub_ps(_mm256_mul_ps(vd0, fq0), vm0);
                __m256 w1 = _mm256_sub_ps(_mm256_mul_ps(vd1, fq1), vm1);
                // 加载 vec 并 fused multiply-add
                __m256 vec0 = _mm256_loadu_ps(v0 + l);
                __m256 vec1 = _mm256_loadu_ps(v1 + l);
                vsum = _mm256_fmadd_ps(w0, vec0, vsum);
                vsum = _mm256_fmadd_ps(w1, vec1, vsum);
            }
            // 水平求和（8 个 float → 1 个）
            __m128 lo = _mm256_castps256_ps128(vsum);
            __m128 hi = _mm256_extractf128_ps(vsum, 1);
            __m128 s = _mm_add_ps(lo, hi);
            s = _mm_hadd_ps(s, s);
            s = _mm_hadd_ps(s, s);
            sum += _mm_cvtss_f32(s);
            q += 32;
        }
    }
    return sum;
}

关键指令：

• _mm256_cvtepu8_epi32：8 个无符号 8bit → 8 个 32bit 整数
• _mm256_cvtepi32_ps：8 个 32bit 整数 → 8 个 float
• _mm256_fmadd_ps：8 路 fused multiply-add（a*b+c）
• _mm256_srli_epi32：逻辑右移提取高 nibble
• _mm_hadd_ps：水平加法（相邻元素相加）

运行时 CPU 检测：

static bool _cpu_supports_avx2() {
    int cpuInfo[4];
    __cpuid(cpuInfo, 7);
    return (cpuInfo[1] & (1 << 5)) != 0;
}

---

1.9 矩阵向量乘（mat_vec_wt）

数学公式：

$$y=W\cdot x,y_i=\sum _{j=0}^{k-1}{W}_{i,j}\cdot x_j$$

代码实现（v9.0，Q4_K 路径用 AVX2）：

void mat_vec_wt(const WeightTensor& wt, const float* vec, float* out, int rows, int cols) {
    const uint8_t* base = (const uint8_t*)wt.data;
    size_t row_bytes = (size_t)cols / 256 * 144;  // Q4_K
    bool use_avx2 = has_avx2();
    #pragma omp parallel for schedule(static) num_threads(_optimal_threads)
    for (int i = 0; i < rows; ++i) {
        if (i + 2 < rows)  // 预取下一行权重
            _mm_prefetch((const char*)(base + (i+2)*row_bytes), _MM_HINT_T0);
        if (use_avx2)
            out[i] = dot_q4_K_avx2(base + i * row_bytes, vec, cols);
        else
            out[i] = dot_q4_K_fused(base + i * row_bytes, vec, cols);
    }
}

要点：

• OpenMP 行级并行，每个线程处理一行输出
• _mm_prefetch 提前加载下一行权重，减少缓存未命中
• 运行时检测 AVX2，不支持自动回退标量 fused 版

---

二、优化方向

2.1 优化路线总览

v5.0 原始版（标量反量化+点积，~3.0 tok/s）
    │
    ├─ v6.0：越界修复 + QK合并 + gate_up合并 → 5.4 tok/s (+80%)
    ├─ v7.0：wv/w2 Q6_K→Q4_K 加载转换 → 6.8 tok/s (+26%)
    ├─ v8.0：fused 反量化+点积 + 预取 → 7.9 tok/s (+16%)
    └─ v9.0：AVX2 SIMD 优化 → 11.1 tok/s (+41%)

2.2 各项优化详解

P0-1：越界崩溃修复（4094/1024 错误）

问题：集成显卡环境下出现 4094/1024 越界错误，系统崩溃。

根因：_buf_scores_per_head 在 allocate_buffers 中分配为 n_heads * max_kv_cache_len（默认 4096，旧版 1024），但 transformer_block 中访问 _buf_scores_per_head.data() + h * seq_len，seq_len 可增长到 131072，导致堆缓冲区溢出。

修复：transformer_block 开头动态检查并扩容：

size_t needed = (size_t)n_heads * seq_len;
if (_buf_scores_per_head.size() < needed) _buf_scores_per_head.resize(needed);

收益：消除崩溃，长上下文稳定运行。

P0-2：QK 权重合并

问题：每层需要 wq 和 wk 两次 matvec，每次都要遍历权重内存。

方案：wq（n_heads×head_dim 行）+ wk（n_kv_heads×head_dim 行）行拼接为 wqk，一次 matvec 得到 Q 和 K。

约束：wv 的 k（kv_heads×head_dim=256）与 wq/wk 的 k（dim=1536）不同，无法合并，保持单独 matvec。

收益：减少一次 matvec 调用，从 ~3.0 → 5.4 tok/s（含越界修复和 gate_up 合并）。

P0-3：gate_up 权重合并

问题：FFN 需要 w1（gate）和 w3（up）两次 matvec。

方案：w1（hidden_dim 行）+ w3（hidden_dim 行）行拼接为 w13，一次 matvec 得到 gate 和 up。

收益：减少一次 matvec 调用。

P0-4：wv/w2 Q6_K→Q4_K 加载转换

问题：Q4_K_M 模型中 wv（attn_v）和 w2（ffn_down）用 Q6_K 格式（精度敏感层），但 Q6_K 反量化比 Q4_K 慢 2-3 倍（6-bit 重组复杂）。

方案：加载时将 Q6_K 权重反量化为 FP32，再量化为 Q4_K，统一用高效的 Q4_K 内核。

实现：

static inline void quant_row_q4_K(const float* x, uint8_t* out, int k) {
    // 8 个 sub-block 分别计算 min/max
    // 全局 d = max(sub_scale) / 63, dmin = max(sub_minoff) / 63
    // sc/m 为 0-63 整数（非归一化）
    // qs 布局：低 nibble=偶数sub, 高nibble=奇数sub
}
static inline void convert_q6k_to_q4k(const uint8_t* q6k, uint8_t* q4k, int k) {
    dequantize_row_q6_K(q6k, tmp, k);
    quant_row_q4_K(tmp, q4k, k);
}

权衡：Q6_K→Q4_K 转换可能影响生成质量（wv/w2 是精度敏感层），当前 NaN=0，未系统验证 perplexity。

收益：从 5.4 → 6.8 tok/s（+26%），加载时间增加约 0.5s（一次性转换开销）。

P0-5：Fused 反量化+点积

问题：mat_vec_wt 先反量化整行到临时缓冲区（4096 float），再做点积。反量化结果需要写入内存再读回，增加内存带宽压力。

方案：实现 dot_q4_K_fused，在反量化的同时直接做点积，避免中间缓冲区。

收益：从 6.8 → 7.9 tok/s（+16%），长上下文从 222.5s → 199.5s（+10%）。

P0-6：AVX2 SIMD 优化（最新突破）

问题：dot_q4_K_fused 是标量实现，每个元素需要多次标量运算（nibble 提取、int→float 转换、乘加）。

方案：用 AVX2 256 位寄存器一次处理 8 个 float，_mm256_fmadd_ps 一条指令完成 8 路乘加。

关键技术：

• _mm256_cvtepu8_epi32 无符号扩展（有符号扩展会导致字节>=128时高 nibble 计算错误）
• _mm256_fmadd_ps fused multiply-add
• 水平求和用 _mm_hadd_ps 两步完成

收益：从 7.9 → 11.1 tok/s（+41%），长上下文从 199.5s → 150.8s（+24%）。

2.3 Profiling 分析

CPU 推理的性能瓶颈按优先级：

1. 矩阵乘（反量化+点积）：占总时间约 60-70%，是最大瓶颈
2. 注意力计算：占约 15-20%，长序列时占比上升
3. 其他（rms/rope/swiglu/内存拷贝）：占约 10-15%

矩阵乘中，Q4_K 反量化的 nibble 提取和 int→float 转换是主要开销，AVX2 优化直接针对这一点。

2.4 理论极限分析

内存带宽受限理论极限：

• 1.5B Q4_K 模型权重约 0.9GB
• DDR4-3200 双通道带宽约 50 GB/s
• 理论最小时间 = 0.9GB / 50GB/s ≈ 18ms/token ≈ 55 tok/s
• 当前 11.1 tok/s 达到理论极限的 20%

未达到极限的原因：

• Q4_K 反量化的 nibble 提取有额外开销（有效带宽低于理论值）
• OpenMP 线程同步开销
• 注意力计算和其他算子的计算时间
• CPU 缓存未命中（权重超过 L3 缓存）

进一步优化方向：

• Q4_K 重排（qs_low/qs_high 分开），改善内存访问连续性，预计 +10-15%
• Q6_K AVX2 版本（剩余 Q6_K 层），预计 +5-10%
• Flash Attention（长序列），预计 +15-20%

---

三、实施过程碰到的困难

3.1 4094/1024 越界崩溃

现象：集成显卡环境下运行系统，出现 4094/1024 错误，随后崩溃。

根因：_buf_scores_per_head 固定分配为 n_heads * max_kv_cache_len（默认 4096），但 seq_len 可增长到模型 context_length（1.5B 为 32768，7B 为 131072），h * seq_len 越界导致堆缓冲区溢出。

修复：transformer_block 开头动态检查并扩容。

教训：所有与序列长度相关的缓冲区都必须动态扩容，不能假设固定上限。

3.2 Q6_K→Q4_K 转换崩溃（k 值硬编码）

现象：v7.0 第一次尝试，编译通过但运行时 ACCESS_VIOLATION 崩溃，发生在 wv[9] 转换的 row 256。

根因：convert_wv_to_q4k 中硬编码 k = config.dim = 1536，但 wv 的实际 k = kv_heads × head_dim = 256。导致 q6k_row_bytes = 1536/256*210 = 1260（实际应为 210），源数据指针越界。

修复：使用 weights.wv[l].k 而非 config.dim。

教训：权重矩阵的 k 值必须从权重张量本身读取，不能假设所有层的 k 都等于 dim。attn_v/attn_k 的 k = kv_heads×head_dim，与 dim 不同。

3.3 Q4_K qs 布局理解错误

现象：Q6_K→Q4_K 转换后，反量化结果范围异常（[-1008, 2898] 而非 [-32, 31]），误差巨大。

根因：最初认为每个 sub-block 的前 16 个元素存在低 nibble、后 16 个存在高 nibble。实际 Q4_K 布局是：两个 sub-block 共享 32 字节，低 nibble 全部是偶数 sub-block 的 32 个元素，高 nibble 全部是奇数 sub-block 的 32 个元素。

修复：

// 正确：qs[0..31]低nibble=sub0, 高nibble=sub1
for (int sp = 0; sp < 4; sp++) {
    int sb0 = sp*2, sb1 = sp*2+1;
    for (int l = 0; l < 32; l++) {
        int q0 = quantize(x[sb0*32+l]);
        int q1 = quantize(x[sb1*32+l]);
        qs[sp*32 + l] = (q0 & 0xF) | ((q1 & 0xF) << 4);
    }
}

教训：量化格式的内存布局必须从反量化代码反推，不能凭直觉假设。

3.4 Q4_K sc/m 是整数而非归一化值

现象：Q4_K 量化后反量化结果仍然异常。

根因：最初认为 sc/m 是 0-1 的归一化系数，公式为 x = d * (sc/63) * q - dmin * (m/63)。实际 Q4_K 公式为 x = d * sc * q - dmin * m，其中 sc/m 是 0-63 的整数。

修复：全局 d = max(sub_scale) / 63，sc = round(sub_scale / d)。

教训：量化格式的 scale 字段含义必须从反量化代码确认，Q4_K 的 sc 是整数系数而非归一化值。

3.5 AVX2 有符号扩展 bug

现象：AVX2 版本的 dot_q4_K 结果完全错误（误差 17 亿%），标量版本正确。

根因：使用 _mm256_cvtepi8_epi32（有符号扩展），当 qs 字节值 >= 128（高 nibble >= 8）时，扩展为负数，逻辑右移 4 位后高 nibble 值错误（0xFFFFFFF0 >> 4 = 0x0FFFFFFF 而非 0x0000000F）。

修复：改用 _mm256_cvtepu8_epi32（无符号扩展），并在右移后加 & mask_0f 确保只有低 4 位有效。

教训：SIMD 的整数扩展指令分有符号/无符号，处理无符号量化值必须用无符号扩展。

3.6 完整 QKV 合并不可能

现象：尝试将 wq+wk+wv 合并为一个矩阵，减少到一次 matvec。

根因：1.5B 模型中 wq/wk 的 k = dim = 1536，但 wv 的 k = kv_heads×head_dim = 256。行拼接要求所有矩阵的 k 相同，因此无法合并。

结论：保持 QK 合并（wq+wk，k 相同）+ wv 单独 matvec。7B 模型中 wv 的 k = dim = 3584（存储方式不同），理论上可以合并，但需验证。

3.7 编译环境兼容性

现象：多个 MSVC 版本编译失败或运行异常。

MSVC 版本	结果
VS 2022 Community 14.44	可用但路径复杂
VS 2026 BuildTools 14.51	安装后与其他版本冲突
VS 2022 BuildTools 14.29.30133	可用

关键编译选项：

• /openmp:experimental：支持 #pragma omp simd（标准 /openmp 不支持 simd 子句）
• /arch:AVX2：生成 AVX2 指令（v9.0 必需）
• /utf-8：源码含中文注释，避免 C4819 编码错误
• /std:c++17：C++17 标准

解决方案：使用 VS 2022 BuildTools MSVC 14.29.30133，路径 C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.29.30133。

3.8 中文编码问题（C4819）

现象：含中文注释的 cpp 文件编译报 C4819 警告，部分中文字符乱码。

根因：Edit 工具修改文件时编码不一致，导致文件含 BOM 或混合编码。

解决方案：所有含中文的 cpp 文件修改必须用 Python 脚本 open(encoding='utf-8') 读写，禁止用 Edit 工具直接修改。

3.9 已验证的死路（避免重复尝试）

尝试	结果	原因
完整 QKV 合并	不可能	wv 的 k 与 wq/wk 不同
Q6_K AVX2 优化	收益小	v7.0 已将 wv/w2 转 Q4_K，剩余 Q6_K 层很少
Flash Attention（decode）	负优化	decode 阶段 Q 单 token，朴素注意力已最优
动态批处理	不适用	单用户场景无并发请求
投机解码	需 draft 模型	增加复杂度，收益不确定

---

四、参考的文献和软件

4.1 开源软件

项目	用途	参考文件
llama.cpp	GGUF 加载、量化格式、CPU kernel 设计	ggml/src/ggml.c（dequantize_row_q4_K、vec_dot_q4_K）、ggml/src/ggml-quants.c
GGUF 格式规范	模型文件格式、张量布局	github.com/ggerganov/ggml/blob/master/docs/gguf.md
Intel Intrinsics Guide	AVX2/FMA 指令参考	software.intel.com/sites/landingpage/IntrinsicsGuide/
pybind11	Python/C++ 绑定	github.com/pybind/pybind11
OpenMP API	并行编程规范	openmp.org/specifications/

4.2 llama.cpp 关键实现参考

dequantize_row_q4_K（llama.cpp 的 Q4_K 反量化）：

• 8 个 sub-block，每个 32 元素
• get_scale_min_k4 解包 6-bit scale/min
• qs 低/高 nibble 分别对应偶数/奇数 sub-block
• 与本引擎的反量化逻辑一致

vec_dot_q4_K（llama.cpp 的 Q4_K 点积）：

• AVX2 版本用 _mm256_cvtepu8_epi32 无符号扩展
• _mm256_madd_epi16 等指令优化整数点积
• 本引擎的 AVX2 实现参考了其无符号扩展的处理方式

与本引擎的差异：

• llama.cpp 支持更多量化格式（Q2_K、Q3_K、Q5_K 等），本引擎聚焦 Q4_K/Q6_K
• llama.cpp 的 matvec 用更复杂的线程分工，本引擎用简单的行级 OpenMP 并行
• llama.cpp 有 ARM NEON 等多架构支持，本引擎聚焦 x86 AVX2

4.3 学术论文

论文	贡献	应用点
RoFormer: Enhanced Transformer with Rotary Position Embedding (Su et al., 2021)	RoPE 旋转位置编码	rope 预计算表
GLU Variants Improve Transformer (Shazeer, 2020)	SwiGLU 激活函数	FFN 激活函数
GQA: Training Generalized Multi-Query Transformer Models (Ainslie et al., 2023)	分组查询注意力	注意力的 GQA 映射
FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness (Dao et al., 2022)	分块注意力	仅 prefill 阶段适用，decode 阶段验证为负优化
GGUF: GPT-Generated Unified Format (Gerganov et al., 2023)	模型量化格式规范	Q4_K/Q6_K 数据结构
Intel AVX2 Programming Reference (Intel, 2013)	256 位 SIMD 指令集	dot_q4_K_avx2 实现

4.4 Intel 技术文档

• Intel Intrinsics Guide：AVX2/FMA 指令查询、延迟/吞吐量数据
• Intel 64 and IA-32 Architectures Optimization Reference Manual：缓存优化、预取、SIMD 编程
• OpenMP 4.5 Specification：#pragma omp simd、reduction 子句

4.5 硬件规格

参数	测试环境
CPU	14 物理核心（支持 AVX2/FMA）
内存	DDR4（双通道）
操作系统	Windows 11
编译器	MSVC 14.29.30133 (VS 2022 BuildTools)
Python	3.12.7 嵌入式版本
测试模型	Qwen2.5-1.5B-Instruct-Q4_K_M

---

附录：性能数据汇总

版本	1.5B tok/s (CPU)	长上下文(1030)	关键优化
v5.0 原始版	~3.0	-	标量反量化+点积
v6.0	5.4	-	越界修复 + QK/gate_up 合并
v7.0	6.8	222.5s	wv/w2 Q6_K→Q4_K 转换
v8.0	7.9	199.5s	fused 反量化+点积 + 预取
v9.0	11.1	150.8s	AVX2 SIMD
理论极限（带宽）	~55	-	0.9GB/50GB/s

当前达到理论极限的 20%，是原始版的 3.7 倍。

CPU 版与 CUDA 版对比

指标	CPU 版 (v9.0)	CUDA 版 (51 tok/s)
测试模型	1.5B	7B
速度	11.1 tok/s	51 tok/s
内存/显存	~1.5GB	~4.5GB
核心优化	AVX2 SIMD	__dp4a + Q4_K 重排
适用场景	无 GPU 环境	有 NVIDIA GPU

---

本教材基于 zhanlu_engine.cpp v9.0（AVX2 优化版）编写，所有代码片段均来自实际运行的源码，所有性能数据均可通过 test_cpu_15b.py 复现。