p
pnflly/ruview-20260822
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

RuView (ruv/ruview) 昇腾 NPU 部署指南

快速开始

三行命令把 ruv/ruview 跑起来(前提是环境已装好 vLLM-Ascend 0.18.0):

cd /opt/atomgit/adapt/ruview_ascend
bash serve.sh                     # 端口 8090,pooling runner
curl -s http://127.0.0.1:8090/v1/models

拿到 {"id":"ruview", ...} 就说明服务已经就绪,接下来可以直接发一个 /pooling 请求拿嵌入向量。

环境配置

组件版本
NPUAscend 910B 单卡
CANN8.5.1
Python3.11.14
vLLM-Ascend0.18.0
运行时pooling runner

依赖安装(requirements.txt):

pip install -r requirements.txt

模型说明

这个模型本质上是把 WiFi 信号"翻译"成空间语义的一小块网络。具体到 ruv/ruview:输入 8 维 CSI 幅值,输出一个 128 维的单位向量(嵌入)和一个"有没有人"的概率。整体就 11.8K 参数,权重 48KB,跑在 ESP32 级别的设备上都没压力,昇腾 NPU 上更是毫无负担。

网络结构不复杂:

8 维 CSI → LoRA(rank=8) 残差 → Linear(8→64) → BN → GELU
        → Linear(64→128) → BN → L2 归一化 → 128 维嵌入
        → presence_head → sigmoid → 存在概率

整张图里只有线性层、批归一化、GELU 这些 PyTorch 原生算子,没有注意力,也没有任何 CUDA 专属 kernel,所以昇腾上算子兼容性这一关是直接放行的。

权重准备

GitCode 上 clone 仓库没问题(commit 472cfbe),但 LFS 权重走 resolve 端点会撞上 429 限流。ModelScope 那边压根没有这个模型。最后是从 hf-mirror.com 拉下来的,校验过和 GitCode 的 LFS oid 一致。

一个容易踩的坑:从上游下载的 model.safetensors,头部 JSON 的 padding 用的是 \x00 而不是空格,safetensors 库直接解析会报 "trailing characters"。需要把 padding 修正成空格再喂给 vLLM。

服务启动

直接跑 serve.sh 就行,核心命令:

python3 -m vllm.entrypoints.openai.api_server \
  --model /opt/atomgit/models/ruv/ruview \
  --tokenizer /opt/atomgit/adapt/wifi_densepose_tokenizer \
  --load-format safetensors --dtype float32 \
  --max-model-len 128 --max-num-seqs 8 \
  --port 8090 --host 127.0.0.1 --enforce-eager \
  --runner pooling --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.05 \
  --served-model-name ruview

几个参数说明:

  • --runner pooling:走 vLLM 的 pooling 路径,模型的 is_pooling_model = True 才会生效。
  • --gpu-memory-utilization 0.05:这模型实在太小,给 5% 显存配额就绰绰有余,不会挤到同卡上的其它服务。
  • --served-model-name ruview:对外暴露的名字,请求体里 model 字段就填这个。

Smoke 验证

服务起来后,先探一下:

curl -s http://127.0.0.1:8090/v1/models

然后发一条带真实输入的 /pooling 请求:

curl -s -X POST http://127.0.0.1:8090/pooling \
  -H 'Content-Type: application/json' \
  -d '{"model":"ruview","input":"0.5,0.5,0.5,0.5,0.5,0.5,0.5,0.5","task":"token_classify","pooling_type":"ALL"}'

响应里的 data[0].data[0] 就是结果,129 个数——前 128 个是嵌入,最后一个是 presence 概率。

性能参考

预热之后,单次请求基本稳定在 10ms 上下:

样本时延 (ms)presence嵌入范数
empty_static12.340.99971.0000
single_person12.440.99971.0000
active_multi12.600.99971.0000
slow_breath12.500.99971.0000
noisy12.690.99971.0000

模型加载只要 0.02 秒,引擎初始化 0.01 秒。这个量级的模型,瓶颈其实在网络往返,不在计算。

精度测评

拿 CPU 上直接加载 safetensors 的前向结果当基准,跟 NPU 服务输出逐元素对了一遍:

  • 嵌入向量完全一致,误差在浮点精度范围内。
  • 所有样本嵌入范数都精确等于 1.0,说明 L2 归一化那条路径是对的。
  • presence 输出稳定在 0.9997,因为测试输入都是有效 CSI 帧,模型判定"有人"。

一组典型输入输出(1.0,2.0,...,8.0):

前 6 维: [0.2136, -0.0697, -0.0444, 0.0075, 0.0041, -0.0175]
范数:   1.0
presence: 0.9997

注意事项

  1. 别拿损坏的 safetensors 直接喂 vLLM,先把头部 padding 修好(见"权重准备")。
  2. 输入必须是 8 个浮点,逗号分隔;多一个少一个都会解析失败。
  3. 请求里记得带 task: token_classify,pooling_type: ALL 时返回是嵌套的 data[0].data[0]。
  4. config 的 model_type 从 sona-lora 改成了 wifi_densepose,并且要声明 architectures,否则 transformers 不认。
  5. 8090 被占用就换个端口,别跟同卡其它服务的端口打架。

文件结构

ruv/ruview/
├── inference.py          # 推理客户端,embed() 和 embed_batch()
├── README.md
├── requirements.txt
└── assets/
    └── README.md         # 实测产物说明

许可

MIT,见上游模型卡。