MiniCPM5-1B-rust/MODEL_GUIDE.md

# 模型格式与使用指南

## 模型格式说明

项目支持三种模型格式，适用于不同场景：

| 格式 | 精度 | 文件大小 | 适用后端 | 速度 |
|------|------|----------|----------|------|
| full | f32 全精度 | ~2.5GB | Flex / Wgpu | 基准 |
| half | f16 半精度 | ~1.2GB | Flex / Wgpu | 较快 |
| q8 | INT8 量化 | ~650MB | Flex (推荐) | 最快 |

### 1. 全精度模型 (full)
- 目录：`model/`
- 文件：`model.mpk`
- 精度：FP32
- 适用场景：精度优先、GPU 推理

### 2. 半精度模型 (half)
- 目录：`model_half/`
- 文件：`model.mpk`
- 精度：FP16
- 适用场景：GPU 推理、显存有限

### 3. INT8 量化模型 (q8)
- 目录：`model_q8/`
- 文件：`model.q8.bin` + `model.q8.json`
- 精度：INT8 + 缩放因子
- 适用场景：CPU 推理、内存有限
- 特性：SIMD 指令集加速（AVX2/SSE）

## 使用方法

### 命令行参数

所有示例都支持以下命令行参数：

```bash
--full   # 使用全精度模型
--half   # 使用半精度模型
--q8     # 使用 INT8 量化模型
```

**重要**：参数前需要加 `--` 与 cargo 分隔：

```bash
# 正确
cargo run --release -p flex-backend -- --q8
cargo run --release -p wgpu-backend -- --half

# 错误（参数会被 cargo 吃掉）
cargo run --release -p flex-backend --q8
```

### Flex 后端（CPU）

```bash
# 全精度
cargo run --release -p flex-backend -- --full

# 半精度
cargo run --release -p flex-backend -- --half

# INT8 量化（推荐，最快）
cargo run --release -p flex-backend -- --q8
```

**最佳性能编译**：
```bash
RUSTFLAGS="-C target-cpu=native" cargo build --release -p flex-backend
cargo run --release -p flex-backend -- --q8
```

### Wgpu 后端（GPU）

```bash
# 全精度（推荐）
cargo run --release -p wgpu-backend -- --full

# 半精度
cargo run --release -p wgpu-backend -- --half

# INT8 量化（不推荐，性能较差）
cargo run --release -p wgpu-backend -- --q8
```

**注意**：
- WGPU 后端下，q8 量化层使用 CPU 实现，会频繁在 CPU-GPU 间传输数据，性能可能不如全精度
- GPU 推理建议使用 `--full` 或 `--half`

## 模型转换

使用 convert 示例转换模型：

```bash
# 全精度
cargo run --release -p convert -- --full

# 半精度
cargo run --release -p convert -- --half

# INT8 量化
cargo run --release -p convert -- --q8

# 全部转换
cargo run --release -p convert -- --all
```

源模型目录：`MiniCPM5-1B/`（需要包含 safetensors 格式模型）

## 性能对比（参考）

以 MiniCPM5-1B 模型为例：

| 后端 | 格式 | 内存占用 | 推理速度 | 推荐指数 |
|------|------|----------|----------|----------|
| Flex CPU | q8 | ~1GB | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Flex CPU | half | ~1.5GB | ⭐⭐⭐ | ⭐⭐ |
| Flex CPU | full | ~3GB | ⭐⭐ | ⭐ |
| Wgpu GPU | full | ~2.5GB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Wgpu GPU | half | ~1.5GB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Wgpu GPU | q8 | ~1GB | ⭐ | ⭐ |

> 注：实际性能取决于 CPU/GPU 型号、内存带宽等因素

## 启动时的输出说明

程序启动时会打印配置信息，确认使用的模型格式：

```
========================================
后端: Flex (纯 Rust CPU)
模式: INT8 量化 (SIMD 加速)
模型目录: model_q8
配置文件: MiniCPM5-1B/config.json
  特性: INT8 量化 + SIMD 加速，推荐使用
  编译建议: RUSTFLAGS="-C target-cpu=native" cargo build --release
========================================
```

如果模式和模型目录与预期不符，请检查命令行参数是否正确传递。

## 常见问题

### Q: 加了 --q8 参数但感觉没变化？
A: 检查是否加了 `--` 分隔符。正确用法：`cargo run --release -p flex-backend -- --q8`

### Q: WGPU 上 q8 反而更慢？
A: 正常现象。q8 量化是 CPU 优化的，GPU 上建议用 full 或 half。

### Q: half 模型速度和 full 差不多？
A: Flex CPU 后端上 f16 运算会转成 f32，速度差异不大。WGPU GPU 后端上显存占用会明显减少。

### Q: 怎么确认用的是哪个模型？
A: 看启动时的打印信息，"模式"和"模型目录"字段会显示当前配置。