GPU 训练的硬约束
类别顺序：data.yaml 的 names 顺序必须与标注 txt 第一列一致；用 v1 权重微调时还需与 v1 的 5 类 / 12 类完全一致，脚本会拦截不一致并拒绝启动。
指标可比性：自有数据集训出的 mAP 与开源数据训出的 v1 不在一个测试集上，不能横向比较；上线前用产线抓帧做影子 A/B。
续训与导出：--resume <last.pt> 断点续训，--export-onnx 顺带导出 ONNX 供边缘设备部署。

切新模型的四个检查点
1. 类别契约：成熟果占比与中文标签依赖类别名。v2 若改了类名，把 class_map.suggested.json 的 labels / ripe / flower 合并进 vision/class_map.json（服务热加载，不用重启），否则花朵数或成熟果占比会算成 0；
2. 分辨率：v2 若不是 320px 训练，须带 IMGSZ=640 python serve.py --port 8000 重启服务，热切换改不了分辨率；
3. 指标诚实性：外部权重未评估时界面显示「未评估」，不会借用 v1 的 mAP；用 --eval 补测，不同数据集的 mAP 不可横向比较；
4. 前端刷新：页面只在启动时自动探测一次，切换后点模型条的「重新连接」或刷新页面，才会显示新版本号、mAP、权重文件与许可。

商用许可提醒
Strawba 花果数据集仓库未声明许可，v1 仅限研究与原型。商业部署前建议换成明确开放许可的数据：芬兰 Luke / Ultralytics Platform 的草莓检测集（CC BY 4.0，813 张，成熟果+果柄）、Roboflow tabletop-strawberry（CC BY 4.0，flower/ripe/unripe 3 类），或直接用本厂标注数据，再执行 train_v1.py --data <新 data.yaml> 重训。

实时检测的六条边界
1. 帧率 ≠ 检测率：画面按 target_fps 推，YOLO 按 infer_interval 单独节流；本机 CPU 双模型约 0.2–0.3 秒/帧，不要设成每帧都推理。
2. 过时帧不驱动闭环：断流超过 stale_after 秒，状态置 stale，页面自动回退仿真；控制台读数不得直接用于环境控制。
3. 结果有时滞：检测框对应稍早的帧（detect_lag_frames），快速移动/云台转动时会错位，固定机位最准。
4. 单帧计数 ≠ 全槽产量：花果数是当前视野可见数量，多机位会重复计数；接入产量模型前须做去重与视野覆盖标定。
5. 尺寸标定：mm/px 依赖固定工作距离、焦距与分辨率，务必用产线标尺重新标定，否则果径不能用于商品果分级。
6. 安全：cameras.json 含明文凭据，需限制文件权限、禁止入库；当前服务仅监听 127.0.0.1 且无鉴权，跨机部署必须补 HTTPS、Token、网络隔离与 NTP 时间同步。

六条硬边界
1. 不下发设备指令：语音只能触发页面已有的查询与按钮级操作，不能直写执行器、不能改配方基因；实机控制仍须经过网关互锁与人工急停。
2. 不用于安全联锁：车间噪声、方言、回声会让识别率波动，语音告警只是提示，阈值保护必须由 PLC / 控制器硬逻辑承担。
3. 权限与隐私：浏览器原生识别通常把音频送到浏览器厂商的在线服务；file:// 或 HTTP 非 localhost 页面拿不到麦克风，需用 localhost / HTTPS。涉密车间请用 faster-whisper + pyttsx3 的全离线组合，不要用 edge-tts。
4. 播报节制：日志类播报按类型 30 秒节流，环境越界告警按点位 5 分钟冷却，22:00–07:00 只记录不发声，防止同一句话刷屏。
5. 中文音色：浏览器 TTS 的音色由操作系统决定，无中文语音时可能读不出汉字；边缘模式可指定 zh-CN-XiaoxiaoNeural 等音色。首次发声必须由用户点击触发。
6. 唤醒词不是安全口令：同音容错提高命中率的同时也提高误触率，因此语音只触发页面白名单操作，绝不直写执行器；唤醒会话随时可一键结束并释放麦克风。

外部浏览器「点了没反应 / 叫不醒贵贵」的排查顺序
1. 先看打开方式：必须走 http(s)://服务器地址:端口/index.html（同源，勿用 file://）。运行 python start_web.py --with-voice（或双击 start_web.bat）会同时起页面与 8200 离线语音服务；直接双击 index.html 用 file:// 打开，浏览器会静默拒绝麦克风，界面表现就是点了没反应。
2. 再看在线识别服务：Chrome / Edge 的原生 webkitSpeechRecognition 把音频送到境外在线服务。本机实测 google.com 与 speech.googleapis.com 均连接超时，因此原生识别必然报 network，不是代码故障。点面板「语音自检」可看到红色阻断项。
3. 用离线服务：本机已装 faster-whisper（中文 base 模型，实测「查温度」识别准确；--asr-model tiny 更轻但会出同音错字）+ pyttsx3（系统 Microsoft Huihui 中文音色），并预置 hf-mirror.com 镜像与本地模型缓存。启动 8200 后页面会自动切换识别后端；也可点「切换离线识别」。换机器时执行 pip install faster-whisper pyttsx3。
4. 麦克风权限：地址栏右侧的麦克风图标设为「允许」；被拒过一次要去站点设置里改回允许。localhost / HTTPS 才会弹授权。
5. 看唤醒会话状态条：点「唤醒贵贵」后应显示「待唤醒」；说「贵贵」后变「请说指令」，此时再下指令。播报期间暂停收音，等它念完再说；想立刻静音就说「退出唤醒」。首次发声由这次点击授权，不用再单独点「开启播报」。
6. 叫不醒时先看「最近唤醒片段」：面板里这段流水会逐条显示 丢弃（未检测到足够人声）/ 跳过（播报静音窗）/ 送ASR / 听到 / 未唤醒 / 已唤醒，并附上该段峰值与自适应阈值——能直接看出是麦克风电平太低、声音被切段、ASR 没认出，还是唤醒词没匹配上。旧版固定窗口硬切 + 固定 0.012 阈值会把轻声的「贵贵」整段丢掉，现已改为自适应底噪阈值、检测到声音才起算、尾静音才收段。
7. 绕过唤醒词：点「手动唤醒（叫不醒时点这里）」直接进入「请说指令」，仍可用语音下指令并听结果；这是唤醒词识别不稳时的兜底入口。另外「识别后端」下拉框现在不再影响唤醒会话：只要 8200 离线 ASR 在线就会自动接管，避免手动选过「浏览器原生」后永久走不通的在线服务。
8. 还不行：看「语音自检」的唤醒循环 / 离线 ASR 两行与「指令与播报记录」；python vision/voice_service.py --self-test 可确认后端。这台机器 2 核且负载偏高，base 模型单段转写约 4~17 秒，说完请等 1~2 秒再继续；明显偏慢可换 --asr-model tiny。文字输入框始终可用，功能与语音指令等价。
0. 最常见的原因：服务没在运行 —— 页面能打开不代表 8200 在线。语音服务是本机独立进程，必须运行 start_server.bat / start_server.sh 并保持终端开启；关掉窗口、重启电脑、或关闭会话都会让服务停止。面板顶部有「离线语音服务已连接 / 未启动」状态灯，每 15 秒刷新一次。喊不醒时先点「点击说话（免唤醒词）」验证录音与识别链路，再点「复制诊断报告（发我定位）」把真实流水发出来；服务端同时会把流水写到 voice_debug.log。

请留意
产量、糖度真值、病害率来自内置的机理+经验混合模型，用于验证闭环逻辑与优化算法，不是田间实测值。本原型模拟的是「无损测糖仪 BX-01 的读数」（含仪器重复性与标定残差），与 YOLO 视觉链路完全独立。

实机落地要点
NIR 无损测糖需定期用折光糖度计做破坏性对照标定；果温、果皮蜡质、测量姿态与果实大小都会影响光谱，要固定采样条件并保留原始光谱以便回溯。视觉链路只输出计数、尺寸、成熟度分级与病虫害，不得用图像反推糖度。

YOLO v1 的能力边界
v1 权重用开源田间/温室数据训练，与本厂 LED 光源、品种、相机角度和栽培槽背景存在域差异，首次上线检出率会明显低于实验室指标；类别语义中病虫害 12 类由数据集标注 id 与样本名推断，需按本厂植保标准重建映射。尺寸由框宽乘 mm/px 估算，未标定前不可用于商品果分级。Strawba 花果数据集仓库未显式声明许可，v1 仅供研究与原型验证，商用前须取得作者授权或替换为自有标注数据。落地前请用工厂历史数据校准模型，并在小面积试验区做 A/B 验证。