feat(转换工具): 1. 添加模型转换示例 2. 更新 Cargo.toml 文件以包含新依赖 3. 删除过时的模型指南文档 4. 更新 README 文件以反映项目结构和使用说明
This commit is contained in:
Generated
+13
@@ -564,6 +564,7 @@ version = "0.21.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0098bf6555c151517b4c98ca0e8ed1ab6a976e40f5f4e967c117b00eee21e192"
|
||||
dependencies = [
|
||||
"aligned-vec",
|
||||
"burn-backend",
|
||||
"burn-ir",
|
||||
"burn-std",
|
||||
@@ -571,7 +572,9 @@ dependencies = [
|
||||
"gemm",
|
||||
"half",
|
||||
"libm",
|
||||
"macerator",
|
||||
"num-traits",
|
||||
"rayon",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -749,6 +752,7 @@ dependencies = [
|
||||
"aligned-vec",
|
||||
"bon",
|
||||
"burn-cubecl",
|
||||
"burn-flex",
|
||||
"burn-fusion",
|
||||
"burn-ir",
|
||||
"burn-tensor",
|
||||
@@ -1080,6 +1084,15 @@ version = "0.6.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "136d3e02915a2cea4d74caa8681e2d44b1c3254bdbf17d11d41d587ff858832c"
|
||||
|
||||
[[package]]
|
||||
name = "convert"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"burn",
|
||||
"minicpm-convert",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "convert_case"
|
||||
version = "0.8.0"
|
||||
|
||||
@@ -3,6 +3,7 @@ members = [
|
||||
"crates/minicpm-core",
|
||||
"crates/minicpm-convert",
|
||||
"crates/minicpm-inference",
|
||||
"examples/convert",
|
||||
"examples/wgpu-backend",
|
||||
]
|
||||
resolver = "2"
|
||||
|
||||
-155
@@ -1,155 +0,0 @@
|
||||
# 模型格式与使用指南
|
||||
|
||||
## 模型格式说明
|
||||
|
||||
项目支持三种模型格式，适用于不同场景：
|
||||
|
||||
| 格式 | 精度 | 文件大小 | 适用后端 | 速度 |
|
||||
|------|------|----------|----------|------|
|
||||
| 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: 看启动时的打印信息，"模式"和"模型目录"字段会显示当前配置。
|
||||
@@ -0,0 +1,13 @@
|
||||
[package]
|
||||
name = "convert"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[[bin]]
|
||||
name = "convert"
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
minicpm-convert = { path = "../../crates/minicpm-convert" }
|
||||
burn = { version = "0.21", default-features = false, features = ["std", "flex"] }
|
||||
anyhow = "1.0"
|
||||
@@ -0,0 +1,20 @@
|
||||
use burn::backend::{flex::FlexDevice, Flex};
|
||||
use minicpm_convert::{run_export, ExportTask, Format};
|
||||
use std::path::Path;
|
||||
|
||||
fn main() -> anyhow::Result<()> {
|
||||
let safetensors_path = Path::new("MiniCPM5-1B/model-00000-of-00001.safetensors");
|
||||
let config_path = Path::new("MiniCPM5-1B/config.json");
|
||||
let tokenizer_path = Path::new("MiniCPM5-1B/tokenizer.json");
|
||||
|
||||
println!("模型转换工具");
|
||||
println!("源文件: {:?}", safetensors_path);
|
||||
println!();
|
||||
|
||||
let device = FlexDevice::default();
|
||||
let tasks = vec![ExportTask::new(Format::Full)];
|
||||
|
||||
run_export::<Flex>(safetensors_path, config_path, tokenizer_path, &tasks, &device)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
@@ -1,186 +1,126 @@
|
||||
# MiniCPM5-1B-rust
|
||||
|
||||
基于 [Burn](https://burn.dev/) 深度学习框架实现的 MiniCPM5-1B 大语言模型推理库，纯 Rust 编写，支持 GPU 加速。
|
||||
MiniCPM5-1B 模型的 Rust 推理实现，基于 [Burn](https://github.com/tracel-ai/burn) 框架。
|
||||
|
||||
## 模型架构参数
|
||||
## 特性
|
||||
|
||||
| 参数 | 值 |
|
||||
|------|-----|
|
||||
| 层数 | 24 |
|
||||
| 注意力机制 | GQA (16 Query / 2 KV) |
|
||||
| head_dim | 128 |
|
||||
| hidden_size | 1536 |
|
||||
| intermediate_size | 8960 |
|
||||
| vocab_size | 151936 |
|
||||
| RoPE theta | 5000000 |
|
||||
| 归一化 | RMSNorm |
|
||||
| 激活函数 | SiLU (SwiGLU) |
|
||||
| KV Cache | 支持 |
|
||||
- 🔥 **Wgpu GPU 加速**：支持 CUDA / Metal / Vulkan / DX12 等多种 GPU 后端
|
||||
- 🚀 **算子融合**：启用 fusion + autotune 优化，自动选择最优 kernel
|
||||
- 📝 **流式输出**：实时生成文本，支持逐字输出
|
||||
- 🧠 **思考模式**：支持开启模型的推理思考过程
|
||||
- 📦 **纯 Rust**：无 C/C++ 依赖，跨平台编译简单
|
||||
|
||||
## Workspace 结构
|
||||
## 项目结构
|
||||
|
||||
项目采用 Cargo workspace 多成员结构，包含三个 crate：
|
||||
|
||||
### minicpm-core
|
||||
|
||||
核心模型定义，包含：
|
||||
|
||||
- `LlamaConfig` — 模型配置（从 `config.json` 加载）
|
||||
- `LlamaForCausalLM` — 因果语言模型主体
|
||||
- `LlamaKVCache` — KV 缓存结构
|
||||
- `EosTokenId` — EOS token 标识（支持单个或多个）
|
||||
- 各模块实现：Attention、Decoder、FFN、RMSNorm、RoPE
|
||||
|
||||
### minicpm-convert
|
||||
|
||||
模型格式转换工具，负责将 HuggingFace safetensors 格式的权重转换为 Burn MPK 格式：
|
||||
|
||||
- `export_model()` — 完整转换流程（加载 safetensors → 构建模型 → 导出 MPK）
|
||||
- 支持 BF16 / F16 / F32 精度输入
|
||||
- 支持 `tie_word_embeddings` 权重共享
|
||||
|
||||
### minicpm-inference
|
||||
|
||||
推理功能封装，提供高层 API：
|
||||
|
||||
- `MiniCPM` — 高层封装，整合模型 + tokenizer + 推理逻辑
|
||||
- `TokenizerWrapper` — tokenizer 封装，支持 MiniCPM5 chat template
|
||||
- `GenerationConfig` — 生成配置（max_new_tokens、temperature、top_p）
|
||||
- `generate_with_cache()` — 带 KV Cache 的自回归生成
|
||||
- 支持 temperature 采样、top-p 采样、greedy 解码
|
||||
```
|
||||
MiniCPM5-1B-rust/
|
||||
├── crates/
|
||||
│ ├── minicpm-core/ # 核心模型实现（Transformer、Attention、FFN）
|
||||
│ ├── minicpm-inference/ # 推理引擎（生成、采样、tokenizer）
|
||||
│ └── minicpm-convert/ # 模型转换库
|
||||
└── examples/
|
||||
├── convert/ # 模型转换示例（safetensors → Burn 格式）
|
||||
└── wgpu-backend/ # Wgpu GPU 推理示例
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 转换模型
|
||||
### 1. 准备模型
|
||||
|
||||
首先将 HuggingFace 格式的 MiniCPM5-1B 模型转换为 Burn MPK 格式：
|
||||
|
||||
```rust
|
||||
use minicpm_convert::export_model;
|
||||
use burn::backend::Wgpu;
|
||||
use std::path::Path;
|
||||
|
||||
fn main() -> anyhow::Result<()> {
|
||||
let device = Default::default();
|
||||
|
||||
export_model::<Wgpu>(
|
||||
Path::new("MiniCPM5-1B/model.safetensors"),
|
||||
Path::new("MiniCPM5-1B/config.json"),
|
||||
Path::new("MiniCPM5-1B-burn"),
|
||||
&device,
|
||||
)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
转换完成后，`MiniCPM5-1B-burn/` 目录下会生成 `model.mp` 文件。
|
||||
|
||||
### 2. 推理使用
|
||||
|
||||
使用 `MiniCPM` 高层 API 进行文本生成：
|
||||
|
||||
```rust
|
||||
use minicpm_inference::{MiniCPM, GenerationConfig};
|
||||
use burn::backend::Wgpu;
|
||||
|
||||
fn main() -> anyhow::Result<()> {
|
||||
let device = Default::default();
|
||||
|
||||
// 加载模型
|
||||
let model = MiniCPM::<Wgpu>::load(
|
||||
"MiniCPM5-1B-burn/model",
|
||||
"MiniCPM5-1B/config.json",
|
||||
"MiniCPM5-1B/tokenizer.json",
|
||||
&device,
|
||||
)?;
|
||||
|
||||
// 生成配置
|
||||
let gen_config = GenerationConfig {
|
||||
max_new_tokens: Some(512),
|
||||
temperature: 0.7,
|
||||
top_p: 0.8,
|
||||
};
|
||||
|
||||
// 生成回答（think = true 启用思考模式）
|
||||
let response = model.generate("用 Rust 写一个 Hello World", true, &gen_config)?;
|
||||
|
||||
println!("{}", response);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## 移植到其他项目
|
||||
|
||||
### 依赖配置
|
||||
|
||||
在你的 `Cargo.toml` 中添加：
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
minicpm-inference = { path = "../MiniCPM5-1B-rust/crates/minicpm-inference" }
|
||||
burn = { version = "0.21", features = ["std", "wgpu"] }
|
||||
anyhow = "1.0"
|
||||
```
|
||||
|
||||
> 也可以根据需要选择其他 backend（如 `tch-gpu`、`cuda` 等）。
|
||||
|
||||
### 最小示例
|
||||
|
||||
```rust
|
||||
use minicpm_inference::{MiniCPM, GenerationConfig};
|
||||
use burn::backend::Wgpu;
|
||||
|
||||
fn main() -> anyhow::Result<()> {
|
||||
let device = Default::default();
|
||||
|
||||
let model = MiniCPM::<Wgpu>::load(
|
||||
"model",
|
||||
"config.json",
|
||||
"tokenizer.json",
|
||||
&device,
|
||||
)?;
|
||||
|
||||
let config = GenerationConfig {
|
||||
max_new_tokens: Some(256),
|
||||
temperature: 1.0,
|
||||
top_p: 1.0,
|
||||
};
|
||||
|
||||
let output = model.generate("你好", false, &config)?;
|
||||
println!("{}", output);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## 模型文件准备
|
||||
|
||||
`MiniCPM5-1B/` 目录需要包含以下文件：
|
||||
将 MiniCPM5-1B safetensors 模型放到 `MiniCPM5-1B/` 目录：
|
||||
|
||||
```
|
||||
MiniCPM5-1B/
|
||||
├── config.json # 模型配置文件
|
||||
├── model.safetensors # safetensors 格式权重
|
||||
└── tokenizer.json # tokenizer 配置
|
||||
├── model-00000-of-00001.safetensors
|
||||
├── config.json
|
||||
└── tokenizer.json
|
||||
```
|
||||
|
||||
转换后 Burn 模型目录结构：
|
||||
### 2. 转换模型
|
||||
|
||||
```
|
||||
MiniCPM5-1B-burn/
|
||||
└── model.mp # Burn MPK 格式权重
|
||||
```bash
|
||||
cargo run --release -p convert
|
||||
```
|
||||
|
||||
## 性能说明
|
||||
转换完成后会生成 `model/` 目录（全精度 f32，Burn mpk 格式）。
|
||||
|
||||
| Backend | 设备 | 速度 | 显存占用 |
|
||||
|---------|------|------|----------|
|
||||
| WGPU (Vulkan) | RTX 4060 | ~10 tokens/s | ~4 GB (F32) |
|
||||
### 3. 运行推理
|
||||
|
||||
> 以上数据仅供参考，实际性能因硬件配置、生成长度等因素而异。
|
||||
```bash
|
||||
# 普通模式
|
||||
cargo run --release -p wgpu-backend
|
||||
|
||||
## 许可证
|
||||
# 开启思考模式
|
||||
cargo run --release -p wgpu-backend -- --think
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
### wgpu-backend 命令行参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--think` | 开启思考模式，模型会在回答前进行推理思考 |
|
||||
|
||||
### GenerationConfig
|
||||
|
||||
```rust
|
||||
GenerationConfig {
|
||||
max_new_tokens: Some(1200), // 最大生成 token 数
|
||||
temperature: 0.7, // 温度，越高越随机
|
||||
top_p: 0.95, // nucleus sampling 参数
|
||||
}
|
||||
```
|
||||
|
||||
### 作为库使用
|
||||
|
||||
```rust
|
||||
use burn::backend::{wgpu::WgpuDevice, Wgpu};
|
||||
use minicpm_inference::{GenerationConfig, MiniCPM};
|
||||
|
||||
let device = WgpuDevice::default();
|
||||
let model = MiniCPM::<Wgpu>::load(
|
||||
"model/model",
|
||||
"config.json",
|
||||
"tokenizer.json",
|
||||
&device,
|
||||
)?;
|
||||
|
||||
let config = GenerationConfig {
|
||||
max_new_tokens: Some(500),
|
||||
temperature: 0.7,
|
||||
top_p: 0.95,
|
||||
};
|
||||
|
||||
// 流式生成
|
||||
let stream = model.generate_stream("你好", false, &config)?;
|
||||
for text in stream {
|
||||
print!("{}", text);
|
||||
}
|
||||
```
|
||||
|
||||
## 发布构建
|
||||
|
||||
```bash
|
||||
# Release 构建（启用 LTO + 最高优化级别）
|
||||
cargo build --release
|
||||
|
||||
# 发布到 gitea registry
|
||||
cargo publish -p minicpm-core --registry gitea
|
||||
cargo publish -p minicpm-inference --registry gitea
|
||||
cargo publish -p minicpm-convert --registry gitea
|
||||
```
|
||||
|
||||
Release profile 配置：
|
||||
- `opt-level = 3`：最高优化级别
|
||||
- `lto = true`：链接时优化
|
||||
- `codegen-units = 1`：单代码生成单元，最大化优化
|
||||
|
||||
## 依赖
|
||||
|
||||
- Rust 1.75+
|
||||
- 支持 Wgpu 的 GPU（CUDA / Metal / Vulkan / DX12）
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user