Day 2·3 设备画像实战：识别RK3588而不是靠猜CPU型号

真机实测通过：本文实验已在 RK3588 板端实测完成（2026-09；方法学与原始记录见仓库 docs 与《实验脚本》目录）

一句话导读：设备画像与启发式识别：讲清引擎为何用一张画像承载全部推荐配置而非散落 if-else，拆解 vllm_device.c 读设备树模型串并做子串匹配识别 RK3588 的探测，落点在 --device 覆盖实验观察画像如何改变推荐。

引言

2-2 的平台层回答的是"我在哪种指令集上"（aarch64 / NEON）。但引擎还有个更细的问题：我到底跑在哪块板上？ 同样插着 RK3588 芯片，香橙派 5 和别的 RK3588 板卡外设不同；同一块板上，跑 2B 还是 8B 模型、要不要开 NPU 直驱、推荐哪种量化——这些不该让用户每次手动调。于是引擎有一个"设备画像"模块：src/common/vllm_device.c，启动时自动探测设备，产出一张"画像"，后续所有"推荐配置"都从这张画像取值。

1. 知识点：为什么"识别设备"要用画像，而不是 if-else 满天飞

引擎需要的不是"这台机器叫什么"，而是一组适配决策。看 vllm_device.h 里的 VDevProfile（第 36–50 行），每个设备画像携带：

typedef struct {
   
    const char *id;             /* 规范 id，如 "arm-rk3588-opi5" */
    const char *name;           /* 人读名，如 "RK3588 香橙派 5" */
    VDevArch    arch;           /* x86 | arm64 */
    VDevClass   cls;            /* pc | embedded */
    const char *npu;            /* NPU 后端 id（"rk3588-direct"）或 NULL */
    const char *default_wmode;  /* 推荐量化模式（serve 安全档） */
    int         default_omp;    /* OMP_NUM_THREADS 推荐 */
    int         default_threads;/* HTTP worker 线程推荐 */
    long        mem_limit_mb;   /* 内存预算提示（0=自动） */
    const char *wmodes;         /* 支持的 wmode 白名单，如 "g256,q4,q4i,q8,dual" */
    const char *default_model_dir;  /* 默认权重目录 */
} VDevProfile;

一张画像 = 一台设备的所有"出厂推荐"。探测只负责"选对画像"，选对之后，量化档、NPU、线程数、白名单全部从画像取——业务代码里就没有散落的"if 这块板就怎样"了。设备表的实际内容（vllm_device.c 第 14–24 行）目前只有三档：

注意只有 RK3588 画像带 g256（NPU K-block 256 布局）与 NPU 直驱——这就是"画像决定能力清单"最直观的例子。

1.1 探测是"启发式"，不是"万能"

探测函数 vdev_detect（第 98–128 行）的逻辑是：

1. 架构从编译期宏判定（aarch64 编译产物在 aarch64 上跑），不是运行时猜；
2. 读设备树模型串（/proc/device-tree/model 优先，回退 /proc/cpuinfo 的 Hardware/Model）；
3. 模型串做大小写不敏感的子串匹配：命中 RK3588 / 3588 / OrangePi 5 / orangepi5 任意一个 → arm-rk3588-opi5；否则落 arm-generic。

诚实地说：这是启发式。另一款 RK3588 板卡若设备树模型串不含这些关键词，会被识别成 arm-generic——能用（dual/量化照常），但拿不到 g256 与 NPU 推荐。这正是"识别而非猜"的反面教材：宁可回退到保守画像，也不硬套一个可能不对的画像。

2. 对应代码：引擎启动时怎么用画像

main.c 的参数分发阶段（第 4956–4979 行）做了三件事：解析 --device 覆盖 → 自动探测 → 打印画像。先看自动探测与覆盖：

} else if (strcmp(argv[i], "--device") == 0 && i + 1 < argc) {
   
    g_dev_override = argv[++i];      /* 人工覆盖自动探测结果 */
}
/* ... */
vdev_detect(&g_dev);                 /* 自动探测 */
g_dev_profile = g_dev.profile;
if (g_dev_override) {
   
    const VDevProfile *p = vdev_lookup(g_dev_override);
    if (p) {
   
        g_dev_profile = p;
        printf("[DEV] device overridden: %s -> %s\n", g_dev_override, p->name);
    } else {
   
        fprintf(stderr, "[DEV] WARNING: unknown --device '%s', keeping auto-detect (%s)\n",
                g_dev_override, g_dev.model_id);
    }
}

然后打印画像（每次启动都打，第 4975–4979 行）：

printf("[DEV] device=%s arch=%s class=%s model=%s npu=%s recommended_wmode=%s\n",
       g_dev_profile->id, vdev_arch_str(g_dev.arch), vdev_class_str(g_dev.cls),
       g_dev.model_hint[0] ? g_dev.model_hint : "-",
       g_dev_profile->npu ? g_dev_profile->npu : "none",
       g_dev_profile->default_wmode ? g_dev_profile->default_wmode : "-");

探测本身在 detect_arm_model（第 65–96 行）：优先读 /proc/device-tree/model（一个不带换行的纯文本文件），失败才回退 /proc/cpuinfo。

3. 改动后果：让同一台机器"被识别成"三种画像

实验思路：设备树文件你改不了（它在内核只读的 /proc 里），但代码提供了 --device 这把"人工覆盖"的钥匙——它和"伪造识别结果"是同一件事：换一张画像，看引擎的推荐怎么跟着变。板端实测（RK3588 / Orange Pi 5 Plus / 2026-09），三次都跑 --test-l3：

形态一：自动探测（默认）

./vllm_kestrel --test-l3 | grep "\[DEV\]"

真实输出：

[DEV] device=arm-rk3588-opi5 arch=arm64 class=embedded model=RK3588 OPi 5 Plus npu=rk3588-direct recommended_wmode=dual

model=RK3588 OPi 5 Plus 不是代码写死的——它来自板子的 /proc/device-tree/model（实测内容 18 字节：RK3588 OPi 5 Plus）。命中关键词 → RK3588 画像 → NPU 直驱 + dual。

形态二：强制"通用 ARM 板"（模拟识别回退）

./vllm_kestrel --device arm-generic --test-l3 | grep "\[DEV\]"

真实输出：

[DEV] device overridden: arm-generic -> ARM 通用嵌入式
[DEV] device=arm-generic arch=arm64 class=embedded model=RK3588 OPi 5 Plus npu=none recommended_wmode=dual

注意两处变化：npu 从 rk3588-direct 变成 none；wmode 白名单里 g256 随之消失（画像决定了能力清单）。同时注意 model= 仍是探测到的真实串——探测照跑，只是画像被替换。

形态三：给了不存在的设备名

./vllm_kestrel --device foo-board --test-l3 2>&1 | grep "\[DEV\]"

真实输出：

[DEV] WARNING: unknown --device 'foo-board', keeping auto-detect (arm-rk3588-opi5)

未知画像不会让引擎崩溃，而是警告后保留自动探测结果——"宁缺毋滥"。

最值得注意的共同点：三种形态下 --test-l3 的推理路径完全一致，变的只是画像携带的推荐参数——这正说明"画像"把设备差异收敛到了一张表里，业务代码无需感知具体板卡。

收尾

设备画像的核心价值，是把「这台机器该用什么配置」收敛成一张表，而不是散落在业务代码里的 if-else。探测负责选对画像，选对之后，量化档、NPU、线程数、白名单全部从画像取。启发式识别允许回退到保守画像，--device 则提供人工覆盖的出口——三者配合，让引擎在「识别」与「猜」之间守住底线。

关键词：设备画像、RK3588、自动探测、启发式匹配

• 开源仓库：Kestrel-LLM (Gitee)（源码可得双许可：学习 / 学术研究免费）

上一篇：Day 2·2 跨平台头文件设计：vllm_platform.h守护全平台契约

下一篇：Day 3·1 mmap直挂权重为什么只要1.2秒