# DeepSeek部署

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# DeepSeek 介绍

**DeepSeek** 是一款由国内团队研发的高性能开源大语言模型，具备强大的自然语言理解、代码生成与逻辑推理能力。

本文档演示如何在 **Quectel PI M2**（RK3576）上通过 **RKLLM（Rockchip LLM）工具链** 在 NPU 上部署 **DeepSeek-R1-Distill-Qwen-1.5B** 蒸馏小模型。

> 完整版 DeepSeek-V3/R1（671B 参数）无法在嵌入式板端运行；本方案部署的是官方蒸馏小模型，保留 R1 的推理（thinking）能力，适合边缘端问答、推理场景。

# 部署方案

- **部署方案**：RKLLM SDK v1.2.1（SDK 内置在 `external/rknn-llm/`）

- **模型**：DeepSeek-R1-Distill-Qwen-1.5B，W4A16 量化

- **推理硬件**：RK3576 NPU（6 TOPS），单核

- **板端系统**：Debian 13 (trixie)，内存 4GB

# 整体架构

```plaintext
┌────────────────────────── PC 端（x86_64）──────────────────────────┐
│ 1. rkllm-toolkit (Python)                                          │
│ 2. HuggingFace 下载原模型                                           │
│ 3. 生成量化校准数据 (data_quant.json)                               │
│ 4. 模型转换 + 量化 → .rkllm 文件                                    │
│ 5. 交叉编译板端 demo (llm_demo)                                     │
└──────────────────────────────────┬─────────────────────────────────┘
                                   │ adb push
┌────────────────────────── RK3576 板端 ────────────────────────────┐
│ 6. librkllmrt.so（板端运行时，aarch64 预编译）                       │
│ 7. llm_demo 加载 .rkllm 模型 → NPU 推理                             │
└───────────────────────────────────────────────────────────────────┘
```

# 环境准备

## 硬件与连接

| **项目** | **说明** |
| --- | --- |
| 开发板 | Quectel PI M2（RK3576） |
| 内存 | 4GB LPDDR4X |
| NPU | 6 TOPS，可用频率最高 950MHz |
| 连接方式 | USB ADB（板端 adbd 已启用，root 权限） |
| PC 系统 | Ubuntu 22.04，Python 3.10 |

## SDK 内置资源（无需额外下载）

```plaintext
external/rknn-llm/
├── rkllm-toolkit/                 # PC 端模型转换工具（含 whl 安装包）
├── rkllm-runtime/                 # 板端运行时
│   └── Linux/librkllm_api/
│       ├── aarch64/librkllmrt.so  # aarch64 预编译运行时库
│       └── include/rkllm.h        # C/C++ API 头文件
├── examples/
│   └── DeepSeek-R1-Distill-Qwen-1.5B_Demo/
│       ├── export/                # 模型转换脚本
│       └── deploy/                # 板端 demo
├── scripts/fix_freq_rk3576.sh     # NPU/CPU 定频脚本
└── doc/                           # RKLLM SDK 文档 PDF
```

# 详细搭建步骤

## 安装 rkllm-toolkit（PC 端）

```bash
# 创建 venv，继承系统已装的 torch/numpy
python3 -m venv --system-site-packages /home/q/rkllm-venv

# 仅安装 rkllm-toolkit 本体（不拉依赖）
/home/q/rkllm-venv/bin/pip install --no-deps \
  <SDK>/external/rknn-llm/rkllm-toolkit/rkllm_toolkit-1.2.1-cp310-cp310-linux_x86_64.whl

# 补装缺失的小依赖（用国内源）
/home/q/rkllm-venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ \
  colorlog transformers==4.51.3 sentencepiece tiktoken einops safetensors \
  tqdm accelerate protobuf tabulate jinja2 jsonlines flatbuffers jsonschema datasets

# 验证
/home/q/rkllm-venv/bin/python -c "from rkllm.api import RKLLM; print('OK')"
```

> **坑点**：wheel 元数据里写死 torch==2.3.0 等版本，直接 `pip install xxx.whl` 会在线下载全套依赖（2GB+）。用 `--no-deps` + 系统 torch 可绕开。

## 下载原模型

从 HuggingFace 镜像站下载（hf-mirror 国内速度快）：

```bash
mkdir -p /home/q/deepseek-1.5b && cd /home/q/deepseek-1.5b
for f in model.safetensors config.json generation_config.json tokenizer.json tokenizer_config.json; do
  wget -c "https://hf-mirror.com/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B/resolve/main/$f" -O "$f"
done
```

模型文件：`model.safetensors`（约 3.4GB）+ 4 个配置文件。

## 生成量化校准数据

```bash
cd /home/q/deepseek-1.5b
/home/q/rkllm-venv/bin/python \
  <SDK>/external/rknn-llm/examples/DeepSeek-R1-Distill-Qwen-1.5B_Demo/export/generate_data_quant.py \
  -m /home/q/deepseek-1.5b \
  -o /home/q/deepseek-1.5b/data_quant.json
```

产出 `data_quant.json`（21 条样本）。CPU 推理耗时约 20~40 分钟。

## 模型转换（关键步骤）

转换脚本关键参数（**必须针对 RK3576 修改**，官方示例默认 RK3588）：

```python
# export_rkllm_rk3576.py（基于官方 export_rkllm.py 修改）
from rkllm.api import RKLLM
import os
os.environ['CUDA_VISIBLE_DEVICES']='-1'          # 无 GPU，强制 CPU

modelpath = '/home/q/deepseek-1.5b'
llm = RKLLM()
ret = llm.load_huggingface(model=modelpath, device='cpu',
                           dtype="float32", custom_config=None, load_weight=True)

dataset = "/home/q/deepseek-1.5b/data_quant.json"
target_platform = "RK3576"        # ★ 官方示例是 RK3588，必须改
quantized_dtype = "W4A16"         # ★ W4A16 内存减半、速度更快
quantized_algorithm = "grq"       # ★ grq 算法配合 W4A16
num_npu_core = 1                  # ★ RK3576 单核

ret = llm.build(do_quantization=True, optimization_level=1,
                quantized_dtype=quantized_dtype, quantized_algorithm=quantized_algorithm,
                target_platform=target_platform, num_npu_core=num_npu_core,
                dataset=dataset, hybrid_rate=0, max_context=4096)
ret = llm.export_rkllm(f"/home/q/deepseek-1.5b/deepseek-1.5b_W4A16_RK3576.rkllm")
```

执行：

```bash
/home/q/rkllm-venv/bin/python /home/q/deepseek-1.5b/export_rkllm_rk3576.py
```

产出：`deepseek-1.5b_W4A16_RK3576.rkllm`（约 1.3GB）。耗时约 75 分钟（CPU 量化）。

## 交叉编译板端 demo

```bash
TC=<SDK>/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu

# 复制 deploy 目录到工作区（避免污染 SDK 仓库）
cp -r <SDK>/external/rknn-llm/examples/DeepSeek-R1-Distill-Qwen-1.5B_Demo/deploy /home/q/llm_demo_deploy

# CMakeLists.txt 中 RKLLM_API_PATH 改为绝对路径：
#   set(RKLLM_API_PATH "/home/q/rkllm-runtime/Linux/librkllm_api")

mkdir -p /home/q/llm_demo_deploy/build && cd /home/q/llm_demo_deploy/build
cmake .. \
  -DCMAKE_SYSTEM_PROCESSOR=aarch64 -DCMAKE_SYSTEM_NAME=Linux \
  -DCMAKE_C_COMPILER=$TC-gcc -DCMAKE_CXX_COMPILER=$TC-g++ \
  -DCMAKE_BUILD_TYPE=Release -DCMAKE_POSITION_INDEPENDENT_CODE=ON
make -j4 && make install
```

产出：`/home/q/llm_demo_deploy/install/demo_Linux_aarch64/`，含 `llm_demo` + `lib/librkllmrt.so`。

## 部署到板子

```bash
adb shell mkdir -p /root/llm_demo/lib
cd /home/q/llm_demo_deploy/install/demo_Linux_aarch64
adb push llm_demo /root/llm_demo/
adb push lib/librkllmrt.so /root/llm_demo/lib/
adb push /home/q/deepseek-1.5b/deepseek-1.5b_W4A16_RK3576.rkllm /root/llm_demo/
adb shell chmod +x /root/llm_demo/llm_demo
```

## NPU/CPU 定频（跑模型前必须执行）

官方 `fix_freq_rk3576.sh` 写死 NPU 1GHz，但本板 NPU 最高 **950MHz**，需适配：

```bash
# 板端执行（root）
echo userspace > /sys/class/devfreq/27700000.npu/governor
echo 950000000 > /sys/class/devfreq/27700000.npu/userspace/set_freq   # 最高 950MHz

# CPU 大核（policy4）定频到最高 2208MHz：
echo userspace > /sys/devices/system/cpu/cpufreq/policy4/scaling_governor
echo 2208000 > /sys/devices/system/cpu/cpufreq/policy4/scaling_setspeed
```

## 运行

```bash
adb shell
cd /root/llm_demo
export LD_LIBRARY_PATH=./lib
sh fix_freq_rk3576_debian.sh
export RKLLM_LOG_LEVEL=1          # 打印性能统计
./llm_demo deepseek-1.5b_W4A16_RK3576.rkllm 2048 4096
# 参数说明：2048=推理 batch 大小上限，4096=最大上下文长度
```

进入交互后输入 `0` 测试鸡兔同笼，或直接输入自定义问题。

# 实测结果

## 功能验证

鸡兔同笼问题（头 14、腿 38）回答正确：**鸡 9 只、兔 5 只**，带完整 thinking 推理过程。

## 性能数据（NPU 950MHz 定频）

| **指标** | **实测值** |
| --- | --- |
| 模型加载时间 | 1.54 s |
| Prefill | 103.31 tokens/s（40 tokens / 0.39s） |
| 生成速度 | **10.29 tokens/s**（459 tokens / 44.6s） |
| 峰值内存 | **1.10 GB**（4GB 内存余量充足） |

## 量化方案对比（RK3576 官方 benchmark，1.5B）

| **量化** | **内存占用** | **生成速度** |
| --- | --- | --- |
| W8A8 | 1665 MB | 8.51 tokens/s |
| **W4A16** | **932 MB** | **14.45 tokens/s** |

> 结论：RK3576（4GB 内存）选 **W4A16** 更优——内存省一半、速度提升约 70%。

# 常见问题

| **问题** | **原因与解决** |
| --- | --- |
| pip 装 rkllm-toolkit 卡死 | wheel 依赖 torch 2.3.0 等大包，用 `--no-deps` + 系统已有 torch |
| `rkllm.h: No such file or directory` | deploy 目录复制后 CMakeLists 相对路径失效，改为绝对路径 |
| `aarch64-linux-gnu-g++: command not found` | 用 SDK prebuilts 完整工具链 |
| 定频写 1GHz 失败 | 本板 NPU 最高 950MHz，改 `echo 950000000` |
| 板端 `failed to open model` | 模型文件路径不对或未 push |
| libgomp.so.1 找不到 | 板端安装 `libgomp1` |

# 后续扩展

1. **OpenAI 兼容 API 服务**：SDK 自带 `examples/rkllm_server_demo`，可起 HTTP 服务远程调用

2. **固件集成**：可将 llm_demo + 模型打进 rootfs，开机自启

3. **换更大模型**：7B W4A16 约 4GB，4GB 内存紧张，不建议；1.5B 是当前最优解