add README.md

README.md

@@ -0,0 +1,52 @@
+# 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 |
+| 4 | 5.5 tok/s |
+
+运行内存占用 ≈ 1.8 GB RSS。
+
+## 转换脚本
+
+```
+python convert_minicpm_mixed.py --model <safetensors 目录> --out minicpm_mixed.bin
+```
+
+`vocab.tsv` 为从 tokenizer.json 预提取的词表（id / token / score 三列），供服务器 tokenizer 使用。