RK3588 部署 RKLLM：先锁版本，再转换模型和验证板端推理

把 Hugging Face 权重复制到 RK3588 板卡，并不会自动变成 NPU 推理。Rockchip 的 RKLLM 路径分成两端：在 x86-64 开发机上用 RKLLM-Toolkit 载入、量化并导出 .rkllm，在板端用 RKLLM Runtime 的 C/C++ 接口加载该文件，再由 RKNPU 驱动与硬件交互。**先固定模型、Toolkit、Runtime、驱动和系统镜像的版本组合，再谈启动命令与速度。**少了这张对应表，转换成功和板端启动失败就很难定位是不是同一个问题。Rockchip 官方仓库

这是一条以 Rockchip release-v1.3.1 及其示例代码为依据的可执行验收路径，不是某块量产设备的实测报告。文中的命令需要替换模型路径、交叉编译器和目标板镜像；我们没有在指定 RK3588 板卡上取得转换日志、推理日志、峰值内存或长期运行数据，因此不提供 tokens/s、首 token 延迟、功耗或“已兼容量产镜像”的结论。

封面与正文设备图都是生成的场景示意，不是目标板照片，也不构成运行证据。

开始转换前，先把五个版本写在同一行

最容易浪费时间的做法，是从网上找一个 .rkllm 文件，再到另一台板子的旧镜像里试跑。文件名里虽然有 RK3588，但并没有写清它来自哪个模型 revision、采用什么量化和上下文设置、由哪版 Toolkit 导出，也没有说明板端 librkllmrt.so 与内核驱动版本。初始化失败时，单看“模型打不开”无法区分文件损坏、运行库不匹配，还是驱动或内存条件不满足。

建议第一张记录表至少保留这些字段，且把它当作一个不可拆开的部署单元：上游模型仓库和 revision、tokenizer/chat template、量化数据集及其版本、Toolkit wheel 版本、导出脚本 commit、目标平台、.rkllm 的 SHA-256、Runtime 库版本、RKNPU 驱动版本、系统镜像和板卡 revision。若应用还有自己的提示模板和采样参数，也要随同锁定。模型换一版而运行库不换，或刷了新镜像却沿用旧驱动，都应视为新的组合重新验证，而不是“只改了一个小文件”。

官方仓库在该 release 中同时提供 Toolkit wheel、Linux/Android Runtime、C API 头文件、示例、驱动压缩包和 doc/Rockchip_RKLLM_SDK_CN_1.3.1.pdf。它们可以证明 v1.3.1 发布包里有什么，不能证明供应商镜像已经集成了相同版本。检查目标板时，要向镜像维护方索要内核构建信息、NPU 驱动标识、用户态库来源和更新方式。若团队无法取得这些信息，先暂停“直接换模型”这一步，要求提供能重建的镜像或受控刷机包。官方 release、仓库目录

这里还有一个容易误判的版本规则。官方 rkllm_api_demo 的 README 写的是 rkllm-toolkit>=1.3.0、rkllm-runtime>=1.3.0，这是示例的最低要求，不是任意新旧模型文件与 Runtime 可互换的承诺。要复现本文路径，最简单的起点是取同一 release 的 Toolkit、Runtime、头文件和示例；之后每次升级做成组回归。不要把示例最低版本解释成“以后只升级 Toolkit 也安全”。官方 API demo

插图只说明交付时应把制品、设备和版本清单放在一起，不是本文所述型号或运行结果的照片。

PC 端按什么顺序转换，才能知道失败在哪一步

先确认输入能被这版工具理解

Rockchip 的示例选择 DeepSeek-R1-Distill-Qwen-1.5B 展示流程。这个选择仅是官方示例，不等于它适合所有产品，也不代表在每种内存配置的 RK3588 板上都达到可接受的响应。换模型时，先核对该架构是否在锁定版本的支持范围内、权重和 tokenizer 是否来自同一 revision、模型许可证是否允许你的用途，再看转换脚本是否需要改 chat template 或自定义配置。未经这一步，转换报错可能并非“RK3588 不支持大模型”，而是输入模型和脚本并不匹配。

再让量化样本代表真实任务

官方示例的第一步不是直接 export_rkllm.py，而是生成量化样本 data_quant.json。示例脚本会加载模型并生成用于校准的输入/目标对；脚本自身提示应按模型特点和使用场景准备数据。默认示例里混合了数学、代码、日常问答等内容，不能当作工业设备问答、中文客服或指令控制产品的现成质量基线。

若产品要回答设备维护问题，校准与验收集要覆盖真实的术语、长短输入、拒答及错误边界；同时将集合与模型文件分开保存，避免后来换集却忘记重测。示例脚本调用 trust_remote_code=True，在运行前还应审阅所选模型仓库的代码和许可证，使用隔离的开发环境，不要把陌生模型代码直接放进生产构建机。量化样本脚本

生成 data_quant.json 后还要抽查内容，不能以“文件存在”判定校准集可用。官方脚本会捕获部分生成异常并写入空 target；先统计总条目数、空目标数、无效记录数，并核对实际内容是否覆盖预定任务，再决定是否进入 build。否则量化失败或效果偏差会被误归咎于模型或 NPU。

校准集与验收集也不应完全相同。前者帮助量化过程覆盖产品常见输入分布，后者留作独立检查：模型是不是仍能识别专业术语、遵守输出格式、在无依据时不乱答。如果两套数据混用，某次量化看似“样例全对”，可能只是反复看同一批问题；换成真实用户表达后，误答才暴露。这里没有给出某种量化格式的准确率数字，因为准确率取决于模型、数据和具体任务，必须由目标产品自行测试。

最后构建并保存一个能回溯的模型制品

第二步是载入并导出。该版本示例先用 RKLLM().load_huggingface(...) 读取模型，再以 build(do_quantization=True, quantized_dtype="W8A8", target_platform="RK3588", num_npu_core=3, max_context=4096, dataset="./data_quant.json", ...) 构建，最后用 export_rkllm(...) 输出 .rkllm。这些是官方示例值，不是对任何模型都最优的配置。

max_context 增大会改变上下文需求，量化方式会影响精度、内存和模型制品；三核设置也不能替代目标板资源检查。先用官方示例跑通一条受支持路径，再一次只改变一个变量，并把每次结果与导出文件 hash 对齐。官方导出脚本

在固定的官方 tag 中，下面是具备可用 CUDA 环境的开发机按示例执行的命令顺序。运行前须把 export_rkllm.py 里的 modelpath 改为本地真实模型目录，并确认量化文件、Python 环境和所需内存。官方脚本将 load_huggingface(..., device='cuda') 写在主路径，还设置了 CUDA_VISIBLE_DEVICES='0'；后者只是选择 GPU，不会让无 CUDA 的机器具备 GPU 能力。若开发机只有 CPU，应先确认所用模型与 Toolkit 支持该路径，再把脚本的 device 改为 cpu，并重新评估转换时间和主机内存，不能原样运行下面的示例。本文未在目标机执行这些命令。官方导出脚本

cd examples/rkllm_api_demo/export
python generate_data_quant.py -m /path/to/your/model
python export_rkllm.py

如果导出失败，应按故障发生位置处理，而不是马上降量化精度。载入阶段失败，优先核对模型目录、权重格式、tokenizer 和依赖版本；构建阶段失败，再看模型架构、校准数据、算子与目标平台；导出阶段失败，则保留完整日志、磁盘余量和输出路径。每次失败都应留下 Toolkit wheel 版本、脚本 commit、输入模型 revision、参数和第一条有效错误信息。没有这些信息，就难以判断下次重跑是在复现同一问题，还是又换了一套组合。

板端最小部署步骤：先验证加载，再谈推理效果

编译与库路径先过关

模型转换完成后，还要把板端代码编译成目标架构的程序。官方 Linux demo 的 build-linux.sh 使用 AArch64 交叉编译器路径；这个路径是示例机上的占位，不会自动出现在你的开发机。你需要指定实际 toolchain，确认其 ABI 与板端系统一致，并使程序加载同一 release 的 librkllmrt.so。只把可执行文件复制到板上，漏了运行库或 libomp.so，出现动态库错误并不说明 NPU 模型有问题。官方 README 也单独提示了某些平台缺少 libomp.so 的情况。Linux 构建脚本、官方 README

build-linux.sh 的 GCC_COMPILER_PATH 需要先指向本机实际的 AArch64 交叉编译器；编译完成后再核对 install/demo_Linux_aarch64 中的可执行文件和 lib。不要把官网示例里的 adb push 路径照抄到没有 ADB 的产品环境，文件传输方式应服从目标设备的刷机与访问策略。

初始化成功不等于应用可交付

示例在板上设置 LD_LIBRARY_PATH=./lib，然后运行 ./llm_demo <模型路径> 2048 4096；程序先调用 rkllm_createDefaultParam()，填入 model_path、max_new_tokens 和 max_context_len，再执行 rkllm_init()，通过 callback 接收输出。这里的 2048 与 4096 是 demo 参数，不是所有项目都该照抄的生成上限。

第一次验收应先看模型能否初始化、能否对一个固定短提示正常结束，再测长上下文。官方单进程 demo 不能证明业务并发能力；并发要在接入服务层后另设负载与资源测试。若最小输入都不能初始化，优先核对 .rkllm hash、板端 Runtime 路径和驱动，不要先改业务提示词。C API demo 源码、运行说明

不要把“出现第一句回答”当成部署成功。把同一个 .rkllm 连续运行在刚开机、运行数小时、同时启动摄像头或业务服务的状态下，才能看出模型加载是否挤占其他服务、长上下文是否触发内存压力，以及进程失败后是否能恢复。每次测试都先保存模型 hash、镜像、库和驱动信息；否则第二次输出不同，团队无法判断是输入、温度、采样随机性还是版本漂移。若项目尚无目标外壳与供电条件，就把结果标成开发板阶段，不要提前用于交付承诺。

官方 demo 还把 fix_freq_rk3588.sh 放进性能测试流程。固定频率可以帮助比较不同配置，但它不是生产默认设置，也不等于设备在封闭机箱里可以持续维持该频率。产品验收至少应分成“默认系统策略”和“受控性能测试”两组；前者反映真实部署约束，后者便于查找模型与配置差异。任何性能数字都要连同板型、散热、供电、频率策略、系统镜像、输入长度和生成上限一起给出，否则读者无法复现。官方 demo 运行说明

先把失败分层，再动参数

部署链有三个明显的分界：开发机是否生成了目标 .rkllm；板端进程是否能加载库和初始化模型；推理是否在目标负载下给出可接受的结果。把所有失败都叫“模型不兼容”会让团队不断重做耗时转换，却没有触碰真正的驱动或资源问题。

这张图的关键不是箭头数量，而是 .rkllm 与板端镜像/驱动在 Runtime 加载处汇合。若加载失败，先核对两侧的版本和日志，再决定是否重新转换模型。

这张表是排障顺序，不是“症状与原因一一对应”的诊断结论。例如初始化失败可能是版本、文件或资源多种原因；只有对照板端日志和锁定组合才能缩小范围。转换脚本如果改过，先回到同版示例的最小基线重现：CUDA 开发机用原示例，CPU-only 开发机保留必要的 device='cpu' 适配，再逐项恢复其他改动。板端镜像如果升级过，先在可回退的测试设备上核对旧制品加载，再决定是否扩大升级。不要直接覆盖全部设备上的运行库，导致旧模型也无法回滚。

从一次问答到可交付应用，中间还有四道验收

第一道是制品可追溯。把模型来源、许可证、输入 revision、校准集、导出脚本、Toolkit、目标 .rkllm SHA-256、Runtime、驱动与镜像版本放进发布清单。只有这些字段齐全，失败时才知道该回退模型、库，还是整个镜像。日志里不要记录客户完整提示或敏感数据；保留可复现的脱敏测试集即可。官方仓库证明流程入口，不替你维护版本台账。

第二道是功能正确。用固定且可公开复现的提示集分别检查短问答、长上下文、中文术语、结束条件和错误输入。若产品接设备操作指令，模型输出绝不能直接当控制命令执行；身份、权限、参数范围、确认和审计必须在应用层完成。回答质量要与产品任务相符，不能靠官方 demo 的鸡兔同笼题判断工业场景可用。量化前后的答案变化也要用同一套测试集对照，而不只看单条示例。

第三道是资源与稳定性。在目标板与目标外壳中记录冷启动、模型加载时间、首 token 时间、持续生成速度、进程峰值内存、NPU/CPU 占用、温度、是否降频，以及与其他服务同时运行时的情况。官方仓库给出了 RKLLM_LOG_LEVEL=1、CPU/NPU 观察脚本和频率脚本，适合作为采集起点；但它没有替本文指定目标设备、工况或通过阈值。通过阈值应由产品的最大等待、并发、热条件和断网约束事先定义；若要统一 TTFT、TPOT、内存与功耗的测量口径，可另看边缘大模型性能验收方法。官方性能测试方法

第四道是升级和回退。模型、Runtime、驱动、镜像、应用提示模板应有各自的版本和联动规则，且至少保留一个能在测试设备上恢复的上一套组合。验证不仅是新版本能启动，还包括旧版本能否回退、失败后设备能否重新进入服务、运行中断后是否会留下损坏的制品。若镜像升级会替换内核驱动，不能把这次升级当成“只发一个模型文件”。这是验收方案，不是我们已完成 OTA 或长稳测试的声明。

什么时候不该把 RKLLM 当成默认答案

目标硬件还没定、模型每周都在换，或团队拿不到板卡镜像与驱动的维护责任时，先绑定 RKLLM 会让模型探索变成版本兼容工程。此时可在通用 Linux 设备上验证模型是否能解决业务问题，再决定是否值得将模型转换和 NPU 路径产品化；边缘大模型运行时选型一文讨论不同运行时的交付制品，本文只处理已明确选择 RK3588 + RKLLM 后的执行路径。

反过来，若产品已锁定 RK3588，要求离线推理，并且团队能控制镜像、Runtime 与模型的成组发布，RKLLM 才有清晰的试点价值。此时的下一步不是买更多算力宣传材料，而是选一个受支持的小模型，在一块明确板型上跑通“转换、初始化、固定提示集、记录性能与回退”的最小闭环。没有闭环记录，就只能称为部署计划，不能称为已验证的设备能力。

参考资料与证据边界

• Rockchip RKLLM release-v1.3.1：版本、发布包与变更说明。
• Rockchip RKLLM 官方仓库：PC Toolkit、板端 Runtime、驱动和性能观察入口。
• Rockchip API demo：示例模型、转换、编译与运行步骤。
• Rockchip 导出脚本与板端 C++ 示例：参数及 API 调用位置。

本文核对的是公开发布包和示例代码，没有在目标板执行模型转换、烧录、推理或性能采集。所有“应记录”“先核查”“验收”均为建议的操作与判断顺序，不是本项目的测试结果。SDK、模型支持范围和板卡镜像可能变化；正式采购或上线前，请用拟交付的具体版本重新核对并运行目标设备验证。