# 在RK3588 NPU上实现端侧大模型推理：从HuggingFace到rkllama的完整流水线

> 该项目展示了如何在Rockchip RK3588/RK3588S NPU上实现完整的端侧LLM推理方案，涵盖模型转换、量化部署和Ollama兼容API服务，为边缘AI设备运行大语言模型提供了可复现的技术路径。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-16T21:17:55.000Z
- 最近活动: 2026-04-16T21:25:59.269Z
- 热度: 163.9
- 关键词: RK3588, NPU, edge inference, llama, Ollama, quantization, w8a8, rkllm, on-device AI, Orange Pi
- 页面链接: https://www.zingnex.cn/forum/thread/rk3588-npu-huggingfacerkllama
- Canonical: https://www.zingnex.cn/forum/thread/rk3588-npu-huggingfacerkllama
- Markdown 来源: ingested_event

---

## 背景：边缘设备上的大模型推理需求\n\n随着大语言模型（LLM）能力的快速提升，将模型部署到边缘设备而非云端的需求日益增长。边缘部署不仅能降低延迟、保护隐私，还能在离线环境下提供服务。然而，在资源受限的嵌入式设备上运行数十亿参数的模型面临巨大挑战。\n\nRockchip RK3588/RK3588S是一款面向AIoT场景的高性能SoC，内置3核NPU提供6 TOPS算力，广泛应用于Orange Pi 5 Pro等开发板。如何在其上高效运行LLM，成为边缘AI领域的重要技术课题。\n\n## 项目概述：gemma-rk3588\n\n该项目提供了一套完整的端侧LLM推理解决方案，目标是在RK3588 NPU上运行Google Gemma 4 E2B等开源模型。项目采用分层架构设计，将内核驱动层与用户空间应用层分离，专注于模型转换和推理服务两大核心环节。\n\n值得注意的是，该项目与内核驱动项目`rknpu-rk3588`形成姊妹仓库关系——后者负责DKMS驱动、设备树和底层硬件支持，而本项目专注于上层的模型转换工具链和推理服务框架。\n\n## 技术架构与核心组件\n\n### 模型转换流水线\n\n项目使用瑞芯微官方提供的`rkllm-toolkit`将HuggingFace格式的模型转换为RK3588专用的`.rkllm`格式。转换流程包括：\n\n- **权重量化**：支持w8a8（8位权重、8位激活）量化，显著降低模型体积和内存占用\n- **校准优化**：使用代表性提示词进行校准，减少量化带来的精度损失\n- **CI/CD集成**：通过GitHub Actions工作流在ubuntu-latest runner上自动完成转换，单次转换耗时约16分钟\n\n转换后的`.rkllm`文件可直接部署到RK3588设备上运行，无需原始PyTorch环境。\n\n### 推理服务部署\n\n项目支持两种服务方案：\n\n**方案一：rkllama（推荐）**\n\n基于社区项目`rkllama`构建，提供与Ollama兼容的HTTP API接口。这使得现有基于Ollama生态的工具和客户端可以无缝迁移到RK3588设备上。\n\n**方案二：精简自研服务器**\n\n对于资源极度受限的场景，项目也提供了最小化的手写服务器实现，直接调用`librkllmrt.so`运行时库。\n\n### 系统集成\n\n推理服务以systemd服务单元形式运行，具备以下特性：\n- 开机自启动\n- 崩溃自动重启\n- 资源隔离与安全加固\n- 日志轮转管理\n\n## 实测性能数据\n\n项目在Orange Pi 5 Pro（RK3588S，6 TOPS NPU）上完成了端到端验证：\n\n| 模型 | 量化格式 | 推理速度 | API兼容 |\n|------|----------|----------|---------|\n| Qwen2.5-0.5B-Instruct | w8a8 | ~9 tok/s | Ollama |\n\n这一结果表明，即使是0.5B参数级别的小模型，在边缘NPU上也能达到可用的交互速度。项目团队计划下一步将目标升级到Gemma 4 E2B，这需要更强大的转换主机（CI runner资源不足以处理）。\n\n## 硬件与软件环境\n\n**目标硬件**：\n- Orange Pi 5 Pro（RK3588S）\n- 3核NPU，6 TOPS算力\n- Armbian 6.18.22内核\n\n**软件依赖**：\n- NPU驱动已加载（`/dev/dri/renderD129`存在，`rknpu 0.9.8`）\n- rkllm-toolkit（x86工作站运行）\n- rkllama或自定义服务器（ARM设备运行）\n\n**前置条件**：\n用户需先完成`rknpu-rk3588`项目的Quick Start，确保内核驱动和DKMS模块正确安装。\n\n## 项目目录结构\n\n```\ngemma-rk3588/\n├── .github/workflows/convert.yml   # CI转换工作流\n├── conversion/                     # 模型转换（x86 Linux）\n│   ├── convert.py\n│   ├── requirements.txt\n│   └── calibration/prompts.txt\n└── serving/                        # 板端部署（rkllama + systemd）\n    ├── install.sh\n    ├── systemd/rkllama.service\n    └── tests/e2e.sh\n```\n\n每个子目录都包含独立的README文档，详细说明该模块的使用方法。\n\n## 快速上手指南\n\n### 模型转换（在x86工作站上执行）\n\n```bash\ncd conversion\npip install -r requirements.txt\npython convert.py --model Qwen2.5-0.5B-Instruct --output model.rkllm\n```\n\n或使用GitHub Actions自动转换：\n\n```bash\ncurl -X POST \
  -H \"Authorization: token $GITHUB_TOKEN\" \
  -H \"Accept: application/vnd.github.v3+json\" \
  https://api.github.com/repos/antonioacg/gemma-rk3588/actions/workflows/convert.yml/dispatches \
  -d '{\"ref\":\"main\",\"inputs\":{\"model\":\"Qwen2.5-0.5B-Instruct\"}}'\n```\n\n### 板端部署（在RK3588设备上执行）\n\n```bash\ncd serving\nsudo ./install.sh\nsudo systemctl enable --now rkllama\n```\n\n### 验证测试\n\n```bash\ncurl http://localhost:8080/api/generate -d '{\n  \"model\": \"Qwen2.5-0.5B-Instruct\",\n  \"prompt\": \"你好，请介绍一下自己\"\n}'\n```\n\n## 技术挑战与解决方案\n\n### 挑战一：模型转换资源需求\n\n较大模型（如Gemma 4 E2B）的转换需要大量内存和计算资源，超出GitHub Actions免费runner的限制。\n\n**解决方案**：项目已验证转换流水线的正确性，建议用户在有充足资源的本地工作站或付费CI runner上执行大模型转换。\n\n### 挑战二：量化精度损失\n\nINT8量化虽然大幅降低模型体积，但可能带来精度下降。\n\n**解决方案**：通过校准数据集和精细的量化参数调优，在速度和精度之间取得平衡。实测显示w8a8量化后的Qwen2.5-0.5B在常规对话任务上表现稳定。\n\n### 挑战三：生态兼容性\n\n边缘NPU的推理生态远不如CUDA成熟，工具链碎片化严重。\n\n**解决方案**：项目选择兼容Ollama API，复用现有生态；同时保持架构清晰，便于迁移到其他服务框架。\n\n## 应用场景与价值\n\n该项目为以下场景提供了可行方案：\n\n**离线智能助手**：在无法连接云端的环境中提供AI对话能力，适用于野外作业、保密场所等。\n\n**低延迟交互**：本地推理消除了网络延迟，适合对响应速度敏感的实时应用。\n\n**隐私保护**：数据不出设备，满足医疗、金融等领域的合规要求。\n\n**成本优化**：一次性硬件投入替代持续的API调用费用，适合高并发边缘场景。\n\n## 相关资源与生态\n\n- **姊妹项目**：[rknpu-rk3588](https://github.com/antonioacg/rknpu-rk3588) — 内核驱动与硬件支持\n- **转换工具**：[rkllm-toolkit](https://github.com/airockchip/rknn-llm/tree/main/rkllm-toolkit) — 瑞芯微官方模型转换工具\n- **推理框架**：[rkllama](https://github.com/NotPunchnox/rkllama) — 社区驱动的Ollama兼容服务\n- **上游运行时**：[rknn-llm](https://github.com/airockchip/rknn-llm) — 瑞芯微LLM推理运行时\n\n## 许可协议\n\n项目采用Apache-2.0许可证，与所依赖的`rknn-llm`运行时保持一致。\n\n## 总结\n\ngemma-rk3588项目完整展示了从HuggingFace模型到RK3588 NPU端侧部署的全流程，为边缘AI开发者提供了可复现的技术参考。随着NPU算力的持续提升和量化技术的进步，在边缘设备上运行更强大的语言模型正变得越来越可行。该项目的开源实践为这一趋势提供了宝贵的工程经验。