README.md

# MiniCPM5-2B-cpu-mixed — 混合精度量化权重 (4-bit 主体 / 8-bit 边缘层 / 3值部分层)

本仓库是 [tchbcb/MiniCPM5-2B-cpu](https://huggingface.co/tchbcb/MiniCPM5-2B-cpu)（MiniCPM-2B）的**混合精度 CPU 量化版本**，配套一个零依赖的 AVX2 C 推理服务器。

## 权重文件

`minicpm_mixed.bin` — 单文件混合精度权重容器（1.56 GiB，bf16 原始 5.03 GB → **3.2× 压缩**）。

容器格式：`magic('MCPQ') | count | [key_len | key | ndim | dims | qtype | payload_len | payload]...`

## 混合精度分布（294 个权重矩阵）

| 类型 | 矩阵数 | 说明 |
|------|--------|------|
| Q8_0 (8-bit block q) | 14 | 第 0 / 41 层（网络首尾边缘层，对量化敏感） |
| Q4_K (4-bit, llama.cpp 兼容超块) | 272 | 主体权重，6-bit scale + 4-bit sub-block min/max |
| TERNARY (3值, {-1,0,+1}) | 8 | 自适应余弦门控挑选（cos ≥ 0.897 的 top-8，块级最小二乘 scale，TWN 阈值） |
| Q8 row-wise | embed + lm_head | 词嵌入与输出头（512 MB） |
| F32 | 所有 norm | RMSNorm/Attention/QKV-Norm 全程保持 FP32 |

## 质量方案

- 三值量化采用 **TWN（Trained Ternary Weight Networks）阈值** `δ = 0.7·mean(|W|)` 产生三值矩阵，再用**块级最小二乘**求 scale：`s* = Σ|W|·T / ΣT²`，避免 absmean 幅度塌缩（余弦相似度从 ~0.80 提升到 ~0.897）。
- 对全部 48 个候选矩阵计算与原 bf16 权重的**余弦相似度**，仅保留 cos ≥ 0.897 的 top-8 做三值，其余自动回退 Q4_K。

## CPU 推理服务器

`server/minicpm_server.c`（~850 行 C，单文件零依赖，仅 Windows API + AVX2）：

- LlamaForCausalLM 前向：GQA（16 Q heads / 2 KV heads）、RoPE theta=5e6、SwiGLU
- 混合精度逐矩阵分发：Q8row / Q8_0 / Q4_K / TERNARY 各自内核
- TERNARY 内核：bit0/bit1 位流 + LUT 展开 + `maddubs`/`madd` AVX2
- Q4_K 内核与 llama.cpp 位级兼容
- `CreateFileMapping` mmap 权重、QPC 精确计时、greedy longest-match BPE、MiniCPM5 chat template

## 性能（i5-4258U 2C4T / 16 GB / Windows 11，纯 CPU）

| 线程 | 生成速度 |
|------|---------|
| 1 | 3.5 tok/s |
| 2 | 5.3 tok/s（v2: 亲和性绑定物理核后 5.5 tok/s，仅占一半 CPU） |
| 4 | 5.5 tok/s |

运行内存占用 ≈ 1.8 GB RSS（v2 锁定常驻内存，零缺页）。

## v2 优化版（server/minicpm_server_v2.c）

基于内置热点分析器（`--profile`）定位瓶颈后的优化版本，同条件 A/B 实测：

| 指标 | v1 | v2 | 提升 |
|------|----|----|------|
| prefill（16 tok 提示词） | 3.44-3.61 s | 2.71-2.76 s | **+25-30%** |
| decode（4 线程） | 4.8-4.9 tok/s | 5.3-5.4 tok/s | **+10%** |
| decode（2 线程+物理核绑定） | 4.7 tok/s | 5.5 tok/s | **+17%**（CPU 占用减半） |

v2 主要改动：

1. **prefill 隐藏路径**：提示词 token 不再逐个跑 13 万词表的 lm_head + 采样（只有最后一个 token 需要 logits），省去 15-25% 的无效读带宽；同时把真实提示词 token 加入重复惩罚窗口（v1 加入的是 prefill 期间的随机采样 token，属于行为缺陷）。
2. **融合 OpenMP 并行区**：q/k/v 三矩阵与 gate/up 双矩阵各自共享输入向量与量化类型，合并为单一并行区，每 token 的 OMP 屏障进入次数约减半（每 token ~210 → ~130 次）。
3. **热点分析结论**（--profile 实测，GB/s 为有效读带宽）：
   - `lm_head`（int8 内核）：17.7 GB/s —— 接近机器流带宽极限
   - `qkv` / `o_proj` / `gate_up` / `down`（Q4_K 内核）：仅 6.4-7.8 GB/s，约 8-10 Gelem/s
   - 结论：瓶颈**不是内存带宽而是 Q4_K 内核在 HT 争用下的访存并行度（MLP/延迟墙）**；因此把 lm_head 换成 Q4_K 反而更慢（元素数不变、计算强度翻倍），实验后弃用。
   - 预取距离实验：pf_dist=2（原值）优于 5，内核已处于该结构的局部最优。
4. **权重常驻内存**：`PrefetchVirtualMemory` 预取 + `VirtualLock` 锁定 1.59 GB 权重（工作集提升至 3 GB），在内存压力下零缺页、速度恒定。
5. **电源计划**：Windows「高性能」计划实测比「平衡」快 ~8%（笔记本默认降频是隐形杀手）。
6. 新增命令行：`--profile`（逐阶段耗时/带宽表）、`--pin-memory 0/1`、`--affinity <hex>`（如 `0x5` 绑定两个物理核）。

推荐运行（2 线程绑物理核，速度不变但 CPU 占用减半，笔记本风扇更安静）：

```
minicpm_server_v2.exe --weights minicpm_mixed.bin --tokenizer MiniCPM5-2B-cpu ^
    --prompt-file prompt.txt --n 128 --threads 2 --affinity 0x5
```

## 转换脚本

```
python convert_minicpm_mixed.py --model <safetensors 目录> --out minicpm_mixed.bin
```

`vocab.tsv` 为从 tokenizer.json 预提取的词表（id / token / score 三列），供服务器 tokenizer 使用。