本文件为"面向云边协同场景的分布式人工智能感知与决策关键技术研究"（赛题 XH-202606）参赛项目的 Claude Code 工作指南。任何新会话打开本项目时应先读本文件，以快速恢复团队决策、技术架构与本周推进上下文。 最后更新：2026-08-14（8/10 BoxCars 全量 test、8/12 ModelNet40 clean-guard 最终版、8/14 发榜方确认视觉任务口径；业务保持率 90.28-90.32%、冲突率 4.06%/解决率 100%，全量指标均已达标）
- 赛题：XH-202606，面向云边协同场景的分布式人工智能感知与决策关键技术研究
- 发榜单位：山东浪潮数据库技术有限公司
- 提交截止：2026-08-31（邮件提交至 wangqun@inspur.com）
- 关键时间节点：8/3 MVP、8/10 硬指标数字确认、8/17 代码冻结、8/21 最终交付、8/31 提交截止
- 仓库：https://github.com/CYWang0207/EdgeCloud（私有仓）
- 边缘实时感知与轻量化推理——基于国产开源全量大模型（如 DeepSeek）压缩构建边侧轻量大模型，毫秒级感知，离线/弱网可用
- 云边协同推理与任务调度——边缘轻量模型 + 云端全量模型互补协同，感知网络波动与任务复杂度，在线动态调度最优计算路径
- 全局决策优化与一致性保障——云端跨域认知，模型分发与更新机制，长周期更新同步至边缘，解决"局部贪婪 vs 全局最优"冲突
| 指标 | 要求 | 最新状态 (2026-08-14) |
|---|---|---|
| 边侧轻量模型保持满血能力 | 80%-90%（发榜方已确认视觉任务口径） | ✅ 发榜方已确认：按"边缘 adapter 保持云端 VLM 场景理解能力的百分比"理解 |
| TTFT 降低 | ≥75% | ✅ 86.8%（287→38ms） |
| 单次推理内存 | ≤1.5GB | ✅ 0.08GB |
| 网络波动期业务功能保持率 | ≥90% | ✅ >90%（新 adapter illumination_tuned 版全链路过线，含 adapter 前台下发 92-111ms 口径） |
| 端到端时延（≥2类场景） | ≤0.2s | ✅ 92-111ms（仿真含通信口径：T_edge 写死 80ms + 仿真通信时延，四档全达标，详见 docs/网络波动模拟器设计.md 7.2节） |
| 多节点决策冲突比例 | ≤5% | ✅ 4.06%（BoxCars test 全量 12,322×4 节点，真实多节点实测） |
| 冲突解决成功率 | ≥90% | ✅ 100%（weighted/bayesian 双策略均达标） |
- 技术效果 40（实时性 15 + 感知决策效果 15 + 资源通信效率 10）
- 方案完整性与可扩展性 25（完整性 15 + 可扩展性 10）
- 系统稳定性与一致性 20（稳定性 10 + 决策一致性 10）
- 创新性与应用价值 15（创新性 10 + 应用价值 5）
| 成员 | 模块 | 职责 |
|---|---|---|
| 王成洋（队长） | 系统集成 + 多节点协同 | 总体架构、接口统筹、AdaptFormer 模块、主循环集成、多节点冲突检测与仲裁、main_edge_cloud_real_model.py 全链路闭环 |
| 钟捷杭（B） | 模型评测 | TTFT / 内存 / 延迟测量、集中式基准对比、端到端时延、能力保持曲线、硬指标汇总、benchmark_full 一体化 |
| 张晨（C） | 第二场景 + 云端视觉教师 Adapter | BoxCars116k 全流程训练、cloud-teacher 训练管线（InternViT-6B 教师→无标签 adapter 刷新）、两场景 adapter 权重产出、clean-guard 专项调优 |
| 唐凤玲 (D) | 网络韧性 + 评测 | network_sim.py、业务连续性指标、网络韧性实验、含通信 e2e 测试、全链路闭环韧性数据 |
| 苏程鑫 （E） | 文档 / 实验统筹 | 技术报告、对比图表、Demo 视频、进度追踪、方案文档维护 |
指导老师：周睿婷、东方、孟杰 发榜单位联系人：顾问专家 金老师 15628776777 / 林老师 18811226033；联络专员 王老师 18654565200 / 赵老师 13399579966（工作日 9:00-17:00）
约定：每日 21:00 飞书站会 10 分钟；分支命名 feat/<模块>-<功能>；合并前至少 1 人 Code Review；权重（.pth/.onnx）和数据集不进 Git，统一网盘管理；临时脚本放 tmp 目录。
+---------- 云端 Cloud ----------+
| InternViT-6B-224px 视觉教师 | ← 冻结，5.9B 参数，国产开源（OpenGVLab）
| · 提视觉特征 + 场景分类头 | ← 训 linear/MLP head 产 task logits
| · 为漂移样本产 {features,logits} cache | ← 真在训练回路产监督
| · 仅训练边缘 MV-ViT-S 的 AdaptFormer |
| · 多节点冲突仲裁 |
+---+--------------------+------+
上行 representative 漂移样本 | | 下行 adapter-only checkpoint（~1.2MB）
| v
+--------------------------------+
| 边缘 Edge（路口盒子） |
| MV-ViT (ViT-Small, 2200万) 主干冻结
| + AdaptFormer adapter (可训练) |
| · 云端教师蒸馏：KL + 特征对齐 + CE + clean anchor
| · 边缘 forward 不含大模型/不依赖云端实时返回
| · Token剪枝: k_t |
| · 视角选择: v_t |
| · 协同模式: u_t ∈ {0,1,2} |
| · 漂移感知: E_drift (香农熵) |
| · Lyapunov 带宽队列 |
| · network_sim 网络韧性层 |
+--------------------------------+
当前正式方案（cloud-teacher）：云端冻结 InternViT-6B（全量视觉大模型）在独立离线标注集上训练场景分类头，再为代表性漂移样本生成 {features, logits} 教师监督；边缘 AdaptFormer 用该监督蒸馏训练，产出约 1.2MB 的 adapter-only checkpoint 下发。云端大模型真在训练回路里产监督，adapter 是其蒸馏压缩产物——"基于全量大模型压缩"叙事字面坐实。边缘 forward 只跑 MV-ViT-S + Adapter，不引入大 ViT/VLM 在线推理，不依赖云端实时返回。
FiLM / VLM-conditioned（已降为消融）：保留作消融证据，不再作正式方案。
- u=0 本地自治：边缘冻结主干+adapter 直接推理，c_comm=0，离线/弱网可用
- u=1 cloud-teacher adapter refresh：上传代表性漂移样本，云端 InternViT 产监督+更新约 0.3M 参数，下发约 1.2MB adapter；与既有通信预算兼容
- u=2 重训权重同步：结构性漂移或任务变化，更新主干/分类头等更大范围；默认异步后台进 Q_net 跨槽消化
- Actor-Critic + Lyapunov + 注水算法：Actor(DNN) 生成候选 (v,u)，Critic(注水闭式解) 算最优 k_t，Lyapunov 虚拟队列 Y_bw 保证长期平均带宽约束
- 理论证明：Slater 可行性、虚拟队列强稳定、O(1/V) 效用逼近界、KKT 注水闭式解。证明建立在单一虚拟队列 Y_bw 上，Q_net 不进 G 罚项
- Dora：把重训练对象换成小 adapter，尺度匹配时间槽
EdgeCloud/
├── module_edge_perception/ # 模块一：边缘实时感知
│ ├── model.py # EarlyFusionMultiViewViT（timm ViT + 多视角早期融合 + token剪枝 + 视角掩码）
│ ├── adaptformer.py # AdaptFormer PEFT 模块（含 attach/freeze/计数/验证工具）
│ ├── verify_adaptformer.py # adapter 三点验收脚本
│ ├── boxcars_dataset.py / boxcars_camera_drift_dataset.py / boxcars_drift_dataset.py # BoxCars 数据 + 相机退化
│ ├── train_boxcars.py # BoxCars baseline DDP 训练（30 轮，test Top-1=88.04%）
│ ├── evaluate_boxcars.py # BoxCars 官方 validation/test 评估
│ ├── evaluate_boxcars_cloud_teacher_quick_test.py # cloud-teacher 蒸馏快速评估
│ │ ===== cloud-teacher 正式管线（PR#30 已合，PR#41 clean-guard 已合）=====
│ ├── modelnet_cloud_teacher_refresh.py # ModelNet40 cloud-teacher 刷新（含 clean-guard 专项调优）
│ ├── train_boxcars_cloud_teacher_head.py # 训云端 InternViT-6B 上的 BoxCars head
│ ├── export_boxcars_cloud_teacher_cache.py # 冻结 InternViT 提特征 + head 产 cache
│ ├── train_boxcars_cloud_teacher_adapter.py # 用教师 cache 蒸馏 AdaptFormer
│ ├── evaluate_boxcars_cloud_teacher.py # cloud-teacher 评估
│ ├── modelnet_camera_drift_dataset.py # ModelNet 相机漂移数据集
│ ├── calibrate_boxcars_camera_corruptions.py / calibrate_modelnet_camera_corruptions.py # 退化档校准
│ │ ===== FiLM / VLM-conditioned 消融（保留，不作正式方案）=====
│ ├── ...（旧消融脚本，保留作对照）
│ ├── ...（BoxCars/ModelNet 旧训练管线）
│ └── benchmarks/ # B 的评测脚本
│ ├── benchmark_latency.py / benchmark_memory.py / benchmark_full.py # TTFT/内存/延迟
│ ├── benchmark_centralized.py / benchmark_e2e.py
│ ├── build_scheduler_latency.py / demo_mvp.py
│ └── results/ # CSV + PNG 实测结果
├── module_scheduling/ # 模块二：云边协同调度
│ ├── EdgeCloud_RL/
│ │ ├── main_edge_cloud_real_model.py # 主循环+真模型+adapter+network_sim 全链路闭环
│ │ ├── main_edge_cloud_new.py # 单节点主循环（已接 network_sim）
│ │ ├── ../../archive/scheduling/main_edge_cloud.py # 历史接口版本，仅用于结果追溯
│ │ ├── critic_water_filling.py # 注水闭式解 Critic
│ │ ├── actor_memory.py # Actor DNN + 经验回放
│ │ ├── network_sim.py # 网络韧性模拟器（四档+Q_net+TTL+业务五条件）
│ │ ├── run_network_resilience_tests.py # 网络韧性测试主脚本
│ │ ├── generate_real_trajectory.py / generate_boxcars_trajectory.py # 两场景轨迹生成
│ │ ├── ../../archive/prompt_experiments/evaluate_rl_policy_on_mvvit.py # 历史 Prompt 评估
│ │ └── plot_*.py
│ ├── comparison_baselines/ # LSCI/VBRD/Hyperion 统一接口对照实现
│ └── multi_node/ # 多节点仲裁（已实现骨架+真实测试）
│ ├── arbiter.py # Arbiter 类（冲突检测+加权投票/贝叶斯融合+回滚+统计）
│ └── multi_node_eval.py # 真实多节点多视角评估（4节点各看3缺1，已跑通）
├── common/drift_dataset.py
├── data/ data/README.md # 数据集不进 Git
├── models/ models/README.md # 权重不进 Git
├── docs/
│ ├── 云端视觉教师Adapter方案_20260809.md # cloud-teacher 总方案
│ ├── 第一场景_ModelNet40.md # ModelNet 场景定义（含 clean-guard 最终版结果）
│ ├── 第二场景_BoxCars116k.md # BoxCars 场景定义（baseline 88.04%）
│ ├── 网络波动模拟器设计.md # 网络韧性设计（含含通信 e2e 实测结果 7.1-7.3节）
│ ├── 实验结果总览_20260809.md # 两场景 cloud-teacher 闭环验证总结
│ ├── 多节点冲突仲裁测试结果_20260811.md # 真实多节点测试 + 全链路闭环结果
│ ├── 方案总览.md / 接口契约.md # 方案与接口说明
│ ├── 环境配置避坑指南.md
│ └── ...（旧文档，保留作参考）
├── scripts/verify_env.py / deploy_a3.sh
└── requirements.txt
| 指标 | 实测 | 状态 |
|---|---|---|
| 参数量 | 22.0M（ViT-Small 含 adapter，benchmark 实测） | ✅ |
| TTFT 降幅 | 86.8%（287→38ms，keep=0.1） | ✅ |
| 推理内存 | 0.08GB | ✅ |
| 单帧延迟 | 38ms | ✅ |
| 能力保持 | 发榜方已确认视觉任务口径："边缘 adapter 保持云端 VLM 场景理解能力的百分比" | ✅ 口径确认 |
| ModelNet40 baseline 精度 | clean 96.76%（test 全集） | ✅ 场景一 |
| BoxCars baseline 精度 | Top-1=88.04% / Top-5=97.13%（30 轮 test） | ✅ 场景二 |
| cloud-teacher Adapter（BoxCars，全量 test） | cloud-unlabeled 全量 test（12,322 条）mean drift 74.46%→79.02%（+4.56pp），三漂移 95% CI 全不跨 0（illum +4.42 / blur +1.94 / noise +7.33）；clean 88.09% 持平（+0.06pp） | ✅ |
| cloud-teacher Adapter（ModelNet40，全量 test） | cloud-unlabeled 全量 test（2,468 条）mean drift 87.318%→93.247%（+5.929pp）；illum +3.160 / defocus +6.037 / noise +8.590；clean 95.705%（−1.053pp） | ✅ |
| cloud-teacher 教师（InternViT-6B 本身） | BoxCars dev mean drift 89.83%，clean 96.15%；ModelNet40 dev mean drift 95.417%（teacher gate 通过） | ✅ |
| label-only Adapter（有标签上界） | BoxCars dev mean drift 86.08%；ModelNet40 全量 test 92.625% | ✅ 上界对照 |
| adapter 下发体积 | 299,916 参 ≈ 1.2MB（BoxCars 1,216,745 bytes / ModelNet40 1,219,859 bytes，不含 backbone/norm/head/projector） | ✅ |
| 业务保持率（四档） | 申报数：真模型全链路 90.28-90.32%（acc_floor=0.8，四档全过，异步口径不计实时通信）；仿真含通信口径 BoxCars 94.13-99.85% / ModelNet 94.22-99.96%（proxy_acc 代理值，仅作调度相对效果说明，非申报数，详见 docs/网络波动模拟器设计.md 7.2节） | ✅ |
| 端到端时延 | 80ms（异步口径，T_edge 写死、不计实时通信）；仿真含 1.2MB 前台下发口径 BoxCars 92.86-111.14ms / ModelNet 92.18-110.27ms 均 ≤200ms（仿真估计，非真机端到端实测）；e2e 达标率 100% | ✅ |
| 冲突率/解决率 | 冲突率 4.06% ≤5% / 解决率 100% ≥90%（真 multi_node 全量 test 12,322×4，weighted 与 bayesian 双融合，见 docs/多节点冲突仲裁测试结果_20260811.md） | ✅ |
| ≥2 类场景 | ModelNet40 + BoxCars116k，两场景均有 cloud-teacher 全量结果 | ✅ |
在单节点主循环外加一层"时变网络 + 时延 + 业务可用性"，不动原有 Lyapunov 证明。
- Q_net 是物理传输积压队列（状态量），不进效用目标 G 的罚项；长期平均带宽约束仍由 Y_bw 单一虚拟队列保证，Lyapunov 证明不变。
- Y_bw 更新：
Y_bw[t+1] = max(Y_bw[t] + c_comm - b_avg, 0) - Q_net 更新：追踪瞬时积压，带上限+TTL(50时隙)丢弃防无限增长；Q_net_max 代码默认
max(4·b_avg, S_max)，测试脚本用--q-net-max-mb 200覆盖 - B_t = R_eff_t × slot_duration / 8（R_eff 已含 1-p 折扣）
static：固定网络，基线对照jitter：带宽抖动，不断联jitter_outage：jitter + 随机断联 + 周期断联markov：GOOD/WEAK/DOWN 三态弱网（主模型）
- 断联 → 强制 u=0（只保留本地自治候选）
- 超带宽 → 软罚或硬过滤：
G_effective = G_raw - overflow_penalty × (comm_overflow / B_t) - u=1/u=2 均异步后台：实时链路只计下发 T_comm，生成/重训时延 T_cloud=0
- 端到端时延：
T_e2e = T_edge + T_comm + T_cloud；T_comm = 8 × realtime_comm / R_eff × 1000 + RTT - 业务可用五条件：
business_available = decision_success AND transmission_success AND e2e≤deadline AND active_views≥min AND proxy_acc≥acc_floor
Adapter 前台下发口径（S_adapter=1.2MB 进入前台 compute_e2e()，u=1 实时通信量 1.2MB）：
| 数据集 | 网络模式 | 业务保持率 | 平均端到端时延 | 时延达标率 | 是否达标 |
|---|---|---|---|---|---|
| BoxCars116k | static | 99.85% | 111.14 ms | 100.00% | ✅ |
| BoxCars116k | jitter | 94.42% | 92.86 ms | 94.72% | ✅ |
| BoxCars116k | jitter_outage | 94.13% | 92.96 ms | 94.44% | ✅ |
| BoxCars116k | markov | 94.21% | 93.32 ms | 94.49% | ✅ |
| ModelNet40 | static | 99.96% | 110.27 ms | 100.00% | ✅ |
| ModelNet40 | jitter | 94.57% | 93.36 ms | 94.61% | ✅ |
| ModelNet40 | jitter_outage | 94.85% | 92.18 ms | 94.89% | ✅ |
| ModelNet40 | markov | 94.22% | 93.06 ms | 94.26% | ✅ |
全部达标：业务保持率 >90%、平均端到端时延 92-111ms 均 ≤200ms。
高结构漂移轨迹触发 u=2 共 643 次（触发率 5.22%），50MB SCL 权重包进入异步队列跨时隙消化，Q_net_max=200MB 无容量上限丢弃，业务保持率 98.21%。后台队列服务、TTL 和完成事件记录均被实际触发。
✅ 8/3 adaptformer.py + verify 验收
✅ 8/6 两场景相机退化校准 + label-only adapter（+5-11pp 上界）
✅ 8/9 cloud-teacher 正式方案：InternViT-6B 教师 + 无标签 adapter 刷新（PR#30）
✅ 8/9 network_sim.py + 四档验收 + 含通信 e2e 测试（PR#31）
✅ 8/10 硬指标定稿 + 口径问询发榜单位
✅ 8/11 multi_node 真实冲突率 4.06%/解决率 100%（PR#39）
✅ 8/11 main_edge_cloud_real_model.py 全链路闭环（PR#37）
✅ 8/12 network_sim 含通信口径测试结果入库
✅ 8/13 ModelNet clean-guard 最终版 adapter + 全量 test 结果（PR#41）
✅ 8/14 发榜方确认视觉任务能力保持口径
✅ 8/14 全部 7 项硬指标均有真数且达标
- ✅ "VLM 压缩"叙事：已解决（8/9 cloud-teacher 落地），InternViT-6B 真在训练回路产监督。
- ✅ "80-90% 能力保持"指标口径：发榜方已确认可按"边缘 adapter 保持云端 VLM 场景理解能力的百分比"理解。
- ✅ cloud-unlabeled 全量 test：已跑完。BoxCars 全量 12,322 条 + ModelNet 全量 2,468 条均已完成。
- ✅ ModelNet cloud-teacher 全量：已跑完（clean-guard 最终版 mean drift 93.247%）。
- ✅ 业务保持率/e2e 含通信口径：已落地（docs/网络波动模拟器设计.md 7.2节，全部 >90%/≤200ms）。
- ✅ 多节点真冲突率：已跑完（4.06%/100%）。
⚠️ label-only 数字口径：两份文档数字口径待统一，已不影响正式指标。⚠️ 基线公平性：comparison_baselines 为统一接口下的简化实现，正式对比必须公开参数与实现边界。- ℹ️ 历史 Prompt 路线：Prompt 实现仅用于历史消融，不属于 Adapter 正式主线。
⚠️ 方案总览.md / 接口契约.md：cloud-teacher 叙事已更新，但可进一步精简。
- 挂载点：每个 timm Transformer block 的 mlp（FFN）旁路并行
- 瓶颈维度 r：32（vit_small embed_dim=384，压缩比 12:1，每层 ~24K 参数，12 层共 ~290K，加 scale 共 299,916）
- 结构：
down(D→r) → GELU → up(r→D)，W_up 零初始化使启动时 adapter 输出为 0 - 实现方式：
AdaptFormerMLPWrapper包裹block.mlp，forward = mlp(x) + scale × adapter(x) - 冻结策略：主干全部
requires_grad=False，只训 adapter + norm + head - 下发物：纯 adapter-only checkpoint，约 1.2MB（299,916 参数，1,219,859 bytes），不含 backbone/norm/head/projector
- save/load：
save_adapter_checkpoint/load_adapter_checkpoint/set_adapter_enabled - cloud-teacher 训练目标：
L = CE(z_S,y) + λ_KD·KL(z_S‖z_T) + λ_f·(1-cos(P(h_S),h_T)) + λ_a·KL(z_S‖z_0) - 参考论文：AdaptFormer (ICCV 2022)、LoRA (ICLR 2022)、Houlsby Adapter (ICML 2019)、Hinton 蒸馏 (2014)、InternViT (OpenGVLab)
- 训练环境：AutoDL 云 GPU（数据路径默认
/root/autodl-tmp/），N 卡 - 本会话环境：Windows 11，PowerShell + GitHub REST API（不装 git）
- GitHub 私仓访问：fine-grained PAT，走 GitHub REST API
- AutoDL 训练：autodl.com 注册+实名+充值，镜像选 PyTorch2.x+Python3.11
- 先读本文件恢复团队/架构/决策上下文
- 读
docs/云端视觉教师Adapter方案_20260809.md看 cloud-teacher 正式方案 - 读
docs/第一场景_ModelNet40.md/docs/第二场景_BoxCars116k.md看两场景结果 - 读
docs/网络波动模拟器设计.md第7节看含通信 e2e 结果 - 读
docs/多节点冲突仲裁测试结果_20260811.md看多节点测试 - 读
module_scheduling/EdgeCloud_RL/main_edge_cloud_real_model.py看全链路闭环 - 读
module_edge_perception/modelnet_cloud_teacher_refresh.py看 cloud-teacher 训练管线 - 所有回复用中文
- BoxCars116k 官方 test 全量 12,322 样本 × 4 节点（各看 3/4 视角，
[1110][1101][1011][0111]）。 - 冲突率 4.06%（500/12,322）≤ 5% ✅；解决率 100% ≥ 90% ✅。weighted 与 bayesian 均达标。
- adapter 加载验证：60 key 全命中、数值一致、非零。
- e2e 达标率 100%，avg/P95=80ms（原始异步口径）。
- 业务保持率原始 89.67-89.95%（acc_floor=0.8），根因：old adapter 在 clean 上负作用。
- 张晨新 adapter（clean-guard illumination_tuned 版）已修复：clean 退化从 -5.2pp 缩至 -1.05pp，漂移域 +3~9pp，全链路业务保持率 >90% 已过线。
- 多节点：4 视角非 4 物理摄像头（BoxCars 同摄像头 4 时间观测）；target_id=样本序号非 ReID。
- 含通信 e2e：T_edge=80ms 写死口径，但 adapter 前台下发 1.2MB 实时通信已计入（92-111ms 实测）。
- u=2 重训分支提供了权重验证（Q_net 机制验证，7.3节），但正式交付中未使用 u=2 作为主链路。