RuView 模型训练指南：从 WiFlow 无监督姿态到 GPU 云训练与模型发布

RuView 模型训练指南：从 WiFlow 无监督姿态到 GPU 云训练与模型发布

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

本文围绕 RuView（WiFi-DensePose）生态的/ruview-train训练命令，系统讲解五条模型训练路线（Track A–E）的完整流程：从摄像头无关的 WiFlow 无监督姿态估计、摄像头监督的 92.9% PCK@20 精度路线、RuVector 对比嵌入、域泛化与本地 SNN 环境适配，到可选的 GCloud GPU 训练与 Hugging Face 发布。读完本文，你将掌握各条训练路线的数据准备、核心命令、评估指标与验证门禁，能够独立完成一次从数据采集到模型发布的端到端训练。

训练命令概览：/ruview-train

/ruview-train是 RuView 插件体系中负责"训练、微调、评估或发布 RuView 模型"的统一入口命令，其完整定义位于 plugins/ruview/commands/ruview-train.md，对应的技能（skill）与角色（agent）文档分别是 plugins/ruview/skills/ruview-model-training/SKILL.md 和 plugins/ruview/agents/ruview-training-engineer.md。

该命令的参数形态为：

[track] [--epochs N]

其中track决定走哪条训练路线，可选值为：camera-free、camera-supervised、embeddings、domain-gen、snn、gpu。执行流程为：首先调用ruview-model-training技能；然后根据$ARGUMENTS选择路线——若参数为空，则向用户询问选择哪条路线；训练完成后，还需执行验证门禁，最后移交给/ruview-verify生成见证包（witness bundle）。

数据布局：所有训练路线的基础

无论选择哪条路线，都依赖统一的数据目录布局。根据 SKILL.md 中的 Data layout 小节，关键路径如下：

路径	内容
data/recordings/	原始 CSI 采集数据（*.csi.jsonl），含过夜（overnight）连续采集
data/csi/	用于预训练（pretraining）的 CSI 数据集
data/mmfi/	MM-Fi 数据集（ADR-015）
data/paired/	摄像头 ↔ CSI 配对样本（ADR-079）
data/ground-truth/	MediaPipe 姿态关键点（ground truth）
data/pose_landmarker_lite.task	MediaPipe 姿态模型文件
models/	训练产物（模型文件）

如果需要采集更多数据，可通过python scripts/record-csi-udp.py从在线节点进行 UDP CSI 采集。

Track A — 摄像头无关的 WiFlow 姿态（无标签，自监督）

Track A 是最快、完全无监督的训练路线：仅从10 路传感器信号训练17 关键点姿态，不需要摄像头，也不需要人工标注，代价是精度为"适度"（modest accuracy）。

cd v2 # 阶段 1：在原始 CSI 上做对比预训练（contrastive pretraining） cargo run -p wifi-densepose-sensing-server -- --pretrain --dataset data/csi/ --pretrain-epochs 50 # 阶段 2：训练姿态头并保存 RVF 工件 cargo run -p wifi-densepose-sensing-server -- --train --dataset data/mmfi/ --epochs 100 --save-rvf model.rvf

• 预训练阶段在data/csi/上运行 50 个 epoch，采用对比学习范式让模型先理解 CSI 信号的底层表征；
• 微调阶段在 MM-Fi 数据集（data/mmfi/）上训练 100 个 epoch 的姿态头，最终输出 RVF（RuView Format）格式的模型工件model.rvf；
• 在 M4 Pro 上整个流程约84 秒，适合快速验证训练管线。

训练完成后可执行基准测试与评估：

node scripts/benchmark-wiflow.js # 基准测试 node scripts/eval-wiflow.js # 评估（输出 PCK@20 等指标）

Track B — 摄像头监督姿态训练（ADR-079）：92.9% PCK@20

Track B 是精度最高、被文档明确标注为92.9% PCK@20的路线：使用网络摄像头 + MediaPipe提供地面真值（ground truth），与ESP32 CSI采集数据配对，在笔记本上约19 分钟完成训练。

步骤 1：采集配对数据（摄像头 + CSI）

# 1a. 采集 MediaPipe 姿态关键点作为地面真值 python scripts/collect-ground-truth.py # 1b. 采集 CSI 数据（时间同步） python scripts/collect-training-data.py # 1c. 对齐摄像头时间戳与 CSI 时间戳，生成配对样本 node scripts/align-ground-truth.js

三个脚本的职责与细节：

• collect-ground-truth.py（scripts/collect-ground-truth.py）：通过 MediaPipe Tasks API 的PoseLandmarker捕获网络摄像头关键点，并将 MediaPipe 的 33 个关节点映射为COCO 17 关键点格式（映射表见脚本内MP_TO_COCO = [0, 2, 5, 7, 8, 11, 12, 13, 14, 15, 16, 23, 24, 25, 26, 27, 28]），输出到data/ground-truth/。该脚本还支持--preview --duration 60预览模式、--server http://192.168.1.10:3000连接传感服务器，以及可选的--calibration <bundle.json>（由scripts/calibrate-camera-room.py生成，用于房间坐标系对齐防过拟合）。
• collect-training-data.py：进行 CSI 采集，与摄像头采集保持时间同步。
• align-ground-truth.js（scripts/align-ground-truth.js）：将摄像头关键点（data/ground-truth/gt-*.jsonl）与 CSI 记录（data/recordings/*.csi.jsonl）按时间窗口对齐，输出配对样本（data/paired/*.paired.jsonl）。关键参数包括：--window-ms 200（CSI 窗口毫秒数）、--window-frames 20（每窗口帧数）、--min-camera-frames 3（每窗口最少摄像头帧数）、--min-confidence 0.5（置信度阈值）、--clock-offset-ms 0（手动时钟偏移校正，摄像头超前 50ms 时传-50）。

步骤 2：训练摄像头监督模型

cd v2 cargo run -p wifi-densepose-sensing-server -- --train --dataset data/paired/ --epochs <N> --save-rvf model.rvf

该命令通过wifi-densepose-sensing-servercrate（位于 v2/Cargo.toml 工作区成员列表中）训练姿态模型，在data/paired/配对数据集上训练指定 epoch 数，输出model.rvf。

步骤 3：评估 PCK@20

cd .. && node scripts/eval-wiflow.js

scripts/eval-wiflow.js 是 WiFlow 的 PCK 评估脚本（实现 ADR-079）：以摄像头关键点为地面真值，计算PCK（Percentage of Correct Keypoints）与MPJPE（Mean Per-Joint Position Error）指标，其中 PCK 以躯干长度（DEFAULT_TORSO_LENGTH = 0.3）归一化。其命令行用法为：

node scripts/eval-wiflow.js --model models/wiflow-supervised/wiflow-v1.json --data data/paired/aligned.paired.jsonl node scripts/eval-wiflow.js --baseline --data data/paired/aligned.paired.jsonl # 无模型代理基线 node scripts/eval-wiflow.js --model <path> --data <paired-jsonl> --verbose

前置条件：需要data/pose_landmarker_lite.task（MediaPipe 模型文件）。完整设计见 docs/adr/ADR-079-camera-ground-truth-training.md。

Track C — RuVector 对比嵌入（AETHER，ADR-024）

Track C 将 CSI 子载波幅度/相位转换为嵌入向量（embeddings），用于行人重识别（re-ID）与检索场景，在 M4 Pro 上可达171K emb/s。该路线由wifi-densepose-train与wifi-densepose-ruvector（RuVector v2.0.4）两个 crate 驱动，谱图嵌入见 ADR-076。

cd v2 cargo check -p wifi-densepose-train --no-default-features # 编译期健全性检查 cargo run -p wifi-densepose-sensing-server -- --model model.rvf --embed # 生成嵌入 cargo run -p wifi-densepose-sensing-server -- --model model.rvf --build-index env # 构建环境索引

三个命令分别对应：编译检查、嵌入生成、基于嵌入构建环境索引，为后续的检索与重识别提供向量索引基础。

Track D — 域泛化（MERIDIAN，ADR-027）

Track D 的目标是让模型无需重训即可跨环境迁移（跨房间、跨部署场景）。该路线通过训练管线的域泛化选项配置实现，涉及的模块包括wifi-densepose-train与ruview_metrics，完整方案见 docs/adr/ADR-027-cross-environment-domain-generalization.md。从源码结构看，它不依赖单独的命令入口，而是在训练管线中开启 domain-generalization 配置项后随 Track A/B 的训练流程生效。

Track E — 本地 SNN 环境自适应

Track E 使用**脉冲神经网络（Spiking Neural Network）**实现新房间环境的快速自适应：在设备端或 Cognitum Seed 上30 秒内完成适配。

node scripts/snn-csi-processor.js --port 5006

scripts/snn-csi-processor.js 通过 UDP 接收实时 CSI 帧（ADR-018 二进制格式），将子载波幅度增量送入128-64-8 三层 SNN（128 输入、64 隐藏、8 输出），采用STDP（Spike-Timing-Dependent Plasticity）在线学习。8 个输出神经元分别映射到：presence（存在）、motion（运动）、breathing（呼吸）、HR（心率）、phase_var（相位方差）、persons（人数）、fall（跌倒）、RSSI。常用参数：

参数	默认值	说明
--port	5006	UDP 监听端口
--max-rate	200	最大脉冲率（Hz）
--learning-rate	0.005	STDP a_plus/a_minus 学习率
--hidden	64	隐藏层神经元数
--no-learn	关闭	冻结权重（禁用 STDP）
--send-vectors	关闭	转发脉冲向量到 Cognitum Seed
--seed-host/--seed-port	localhost / 5007	Cognitum Seed 地址

相关背景见 docs/tutorials/cognitum-seed-pretraining.md，以及 ADR-084（RaBitQ 相似度传感器）、ADR-085、ADR-086（边缘新颖性门控）。

GPU 训练：GCloud 按需租用与自动销毁

当本地算力不足时，可通过 GCloud GPU 训练。项目cognitum-20260110具备L4 / A100 / H100的配额。

初始化与冒烟测试

gcloud auth login gcloud config set project cognitum-20260110 bash scripts/gcloud-train.sh --dry-run # 冒烟测试（合成数据） bash scripts/gcloud-train.sh --gpu l4 --hours 2 # 原型开发 bash scripts/gcloud-train.sh --gpu a100 --config scripts/training-config-sweep.json bash scripts/gcloud-train.sh --sweep # 完整超参数扫描

脚本参数与成本

scripts/gcloud-train.sh 是完整的 7 步自动化脚本：创建 VM → 等待驱动与工具链 → 克隆仓库并编译训练二进制 → 上传训练数据 → 运行训练 → 下载产物 → 删除 VM。其支持的完整参数如下：

参数	默认值	说明
--gpu	l4	GPU 类型：l4/a100/h100
--zone	us-central1-a	GCloud 区域
--hours	2	VM 最大存活时长（小时），超时自动关机
--config	空	训练配置 JSON（默认用scripts/training-config-sweep.json的第 0 项）
--data-dir	data/recordings	需要上传的本地数据目录
--dry-run	关闭	用合成数据做冒烟测试
--sweep	关闭	运行完整超参数扫描（遍历配置文件中所有 configs）
--keep-vm	关闭	训练结束后不删除 VM
--instance	wdp-train-{gpu}-{timestamp}	自定义 VM 实例名

三种 GPU 的规格映射（源码中GPU_ACCELERATOR/GPU_MACHINE_TYPE/GPU_BOOT_DISK三个关联数组）：

GPU 类型	加速器类型	机器类型	启动盘	成本参考
l4	nvidia-l4	g2-standard-8	200 GB	~$0.80/小时
a100	nvidia-tesla-a100	a2-highgpu-1g	300 GB	~$3.60/小时（40GB）
h100	nvidia-h100-80gb	a3-highgpu-1g	300 GB	~$11.00/小时（80GB）

成本数字取自 scripts/gcloud-train.sh 头部注释中的估算值，实际费用以云厂商账单为准。

脚本内部的关键机制

• GPU 驱动就绪探测：启动脚本轮询nvidia-smi，最多等待 300 秒；
• libtorch 定位：优先复用深度学习 VM 自带 PyTorch 的 libtorch（python3 -c "import torch; print(torch.__path__[0] + '/lib')"），缺失时通过 pip 安装 CUDA 12.1 版 PyTorch；
• 编译：在 VM 上用cargo build --release --features tch-backend --bin train编译训练二进制，依赖tch-backendfeature；
• 数据上传：将本地数据目录打包为 tar.gz 后通过gcloud compute scp上传，解压到 VM 的data/；
• 自动销毁：脚本在训练命令中设置sudo shutdown -P +$((MAX_HOURS * 60))作为兜底，训练结束后默认执行gcloud compute instances delete删除 VM（除非--keep-vm）；
• 产物回传：打包checkpoints/、logs/（以及 sweep 结果）下载到本地training-results/<instance>/。

超参数扫描（--sweep）

--sweep模式会读取scripts/training-config-sweep.json，将base配置与每个configs[i]合并，逐个运行训练并写入独立的checkpoints/sweep_XX与logs/sweep_XX目录，最终把全部sweep_*.log与产物打包回传。VM 上还会打印每个配置的关键超参数（lr、batch_size、backbone_channels）。

本地替代方案

• Mac（M4 Pro）本地训练：bash scripts/mac-mini-train.sh（scripts/mac-mini-train.sh）—— 7 步流水线：拉取仓库 → 安装 Node.js → 通过 Tailscale 从 Windows 主机拷贝训练数据（scp .../pretrain-*.csi.jsonl）→ 运行node scripts/train-ruvllm.js训练 →node scripts/benchmark-ruvllm.js基准 → 回传结果 → 发布 Hugging Face。
• 模型基准：python scripts/benchmark-model.py。

训练后的验证门禁与发布

验证门禁（训练改动后的强制步骤）

任何训练相关改动之后，必须按顺序执行：

cd v2 && cargo test --workspace --no-default-features # 1,400+ 测试通过，0 失败 cd .. && python archive/v1/data/proof/verify.py # 必须输出 VERDICT: PASS

• Rust 工作区全量测试（禁用默认 features）；
• 确定性 Python 证明脚本（如因 numpy/scipy 合法升级导致哈希漂移，可加--generate-hash后重跑）；
• 若测试或证明有变化，需重新生成见证包：bash scripts/generate-witness-bundle.sh，并自验证 7/7 通过。

发布模型到 Hugging Face

python scripts/publish-huggingface.py # 或使用 Shell 版本：bash scripts/publish-huggingface.sh

scripts/publish-huggingface.py 的工作流程：先从GCloud Secret Manager读取HUGGINGFACE_API_KEY（gcloud secrets versions access latest --secret=HUGGINGFACE_API_KEY --project=cognitum-20260110），再将dist/models/下的模型文件上传到 Hugging Face 仓库。其上传的预期文件清单包括：

pretrained-encoder.onnx pretrained-heads.onnx pretrained.rvf room-profiles.json collection-witness.json config.json README.md

常用参数：--repo ruvnet/wifi-densepose-pretrained --version v0.5.4指定仓库与版本，--dry-run冒烟测试，--token hf_xxxxx跳过 GCloud 查询直接使用令牌。模型卡片模板见 docs/huggingface/MODEL_CARD.md。

收尾：移交 /ruview-verify 生成见证包

训练、评估、验证完成后，将结果移交给/ruview-verify（plugins/ruview/commands/ruview-verify.md）生成见证包（witness bundle），形成"训练 → 验证 → 见证"的完整信任链。/ruview-verify支持四种模式：tests（Rust 测试）、proof（确定性证明）、bundle（见证包生成 + 自验证 7/7 PASS）、all（默认，按序全部执行）。

路线选择速查

路线	适用场景	数据	时间/精度参考	关键命令
A · camera-free	快速验证、无标注环境	data/csi/+data/mmfi/	~84 s（M4 Pro），适度精度	cargo run -p wifi-densepose-sensing-server -- --pretrain/--train
B · camera-supervised	高精度姿态估计	data/paired/（摄像头+CSI 配对）	~19 min，92.9% PCK@20	collect-ground-truth.py→collect-training-data.py→align-ground-truth.js→ 训练 →eval-wiflow.js
C · embeddings	重识别、检索	CSI 子载波	171K emb/s	--embed/--build-index env
D · domain-gen	跨环境迁移	随 A/B	无需重训	训练管线 domain-gen 配置
E · snn	新房间快速自适应	实时 CSI（UDP）	<30 s 适配	node scripts/snn-csi-processor.js --port 5006
GPU	大算力训练	data/recordings/	按小时计费	bash scripts/gcloud-train.sh [--gpu l4\|a100\|h100]

所有路线训练完成后都必须通过验证门禁（cargo test --workspace --no-default-features+archive/v1/data/proof/verify.py），再通过publish-huggingface.py发布，最后移交/ruview-verify完成见证闭环。相关 ADR 参考：ADR-015（MM-Fi 数据集）、ADR-016（RuVector 训练集成）、ADR-017、ADR-024、ADR-027、ADR-076、ADR-079、ADR-084/085、ADR-095/096。

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView