156 lines
4.1 KiB
Markdown
156 lines
4.1 KiB
Markdown
# 模型格式与使用指南
|
||
|
||
## 模型格式说明
|
||
|
||
项目支持三种模型格式，适用于不同场景：
|
||
|
||
| 格式 | 精度 | 文件大小 | 适用后端 | 速度 |
|
||
|------|------|----------|----------|------|
|
||
| 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: 看启动时的打印信息，"模式"和"模型目录"字段会显示当前配置。
|