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

本项目展示如何在Rockchip RK3588/RK3588S NPU上实现完整的端侧LLM推理方案，涵盖模型转换、量化部署和Ollama兼容API服务，为边缘AI设备运行大语言模型提供可复现的技术路径。项目目标是在RK3588 NPU上运行Google Gemma4 E2B等开源模型，采用分层架构，与内核驱动项目rknpu-rk3588形成姊妹仓库。

随着LLM能力提升，边缘部署需求增长（降低延迟、保护隐私、离线服务），但资源受限设备运行大模型面临挑战。RK3588/RK3588S是AIoT高性能SoC，内置3核NPU提供6TOPS算力，广泛用于Orange Pi5 Pro等开发板，如何高效运行LLM是边缘AI重要课题。

项目使用瑞芯微官方rkllm-toolkit将HuggingFace模型转为RK3588专用.rkllm格式，流程包括：权重量化（w8a8，降低体积与内存）、校准优化（代表性提示词减少精度损失）、CI/CD集成（GitHub Actions自动转换，单次约16分钟）。转换后文件可直接部署，无需PyTorch环境。项目与rknpu-rk3588姊妹仓库分工：后者负责驱动与硬件支持，本项目专注上层工具链与推理服务。

项目支持两种服务方案：1. rkllama（推荐）：基于社区项目，提供Ollama兼容HTTP API，现有Ollama生态工具可无缝迁移；2. 精简自研服务器：直接调用librkllmrt.so运行时，适用于资源极度受限场景。推理服务以systemd单元运行，具备开机自启、崩溃重启、资源隔离、日志轮转等特性。

在Orange Pi5 Pro（RK3588S，6TOPS NPU）上验证：Qwen2.5-0.5B-Instruct（w8a8量化）推理速度约9 tok/s，支持Ollama API。硬件要求：Orange Pi5 Pro，3核NPU；软件依赖：NPU驱动加载（rknpu0.9.8）、rkllm-toolkit（x86工作站）、rkllama或自定义服务器（ARM设备）。前置条件：完成rknpu-rk3588项目Quick Start，确保驱动正确安装。

模型转换（x86工作站）：cd conversion → pip install -r requirements.txt → python convert.py --model Qwen2.5-0.5B-Instruct --output model.rkllm；或用GitHub Actions触发转换（需GITHUB_TOKEN）。板端部署：cd serving → sudo ./install.sh → sudo systemctl enable --now rkllama。验证：curl调用localhost:8080/api/generate接口测试对话。

1. 转换资源限制：大模型（如Gemma4 E2B）转换需大量资源，超出GitHub免费runner限制 → 建议本地工作站或付费CI执行。2. 量化精度损失：INT8量化可能降精度 → 通过校准数据集与参数调优平衡速度与精度，实测Qwen2.5-0.5B w8a8在对话任务稳定。3. 生态兼容性：边缘NPU生态碎片化 → 兼容Ollama API复用现有生态，保持架构清晰便于迁移。

应用场景：离线智能助手（野外/保密场所）、低延迟交互（实时应用）、隐私保护（医疗/金融合规）、成本优化（替代云端API费用）。总结：gemma-rk3588项目完整展示从HuggingFace模型到RK3588 NPU部署全流程，为边缘AI开发者提供可复现参考。随着NPU算力提升与量化技术进步，边缘运行更强LLM更可行，项目开源实践提供宝贵工程经验。