# 数字人现场故障分诊与巡检清单

> 来源：AI智工坊数字人 kiosk 现场交付台账（展厅 / 门店 / 政务大厅，无人值守长期开机）。
> 在线版（含实测数字与判据）：https://www.aizhigongfang.com/blog/digital-human-onsite-fault-triage

## A. 先分清是哪一类（4 分钟）

按客户描述直接跳到对应小节，**不要一上来就重装环境**。

- [ ] **嘴慢半拍** → 查口型时序日志：`出画面` 是否 >2.5s、`primed` 是否 False
- [ ] **后半段嘴定格** → 页面里可见视频的 `currentTime` 是否贴住 `duration`
- [ ] **叫它不理** → `micStream` 是否 false、麦克风 rms 是否长期 <0.01
- [ ] **欢迎词不响但聊天正常** → `/motion` 的 `ok` 与 `frames` 是否递增

## B. 嘴慢半拍（音画延迟）

- [ ] 取三个数：`等空闲 / 喂音频 / 出画面`；健康值是 出画面 **1.5~1.7s**
- [ ] `primed=False` 一律当故障（等超时就放声 = 声音先到、画面后到）
- [ ] 管线粒度 = `batch_size × 40ms`；`16 → 8` 可把两轮 1.28s 压到 0.64s
- [ ] **改小要同时看帧率**：`batch_size=4` 时推理帧率掉到 21.7~22.7 fps（低于 25 输出帧率）→ 画面越播越落后
- [ ] 渲染主循环的积压刹车阈值 5 → 60（单改这条无效，别当主因）
- [ ] 避免"文本 + echo"二次合成（1.4~2.4s/句、串行排队），改为**音频同源**喂同一份 mp3
- [ ] 验收：音画偏移在 ±150ms 内；**必须用头部 ROI 量，不能用全画帧差**
- [ ] **验证时页面侧强制静音**（勾 `play()` 设 `muted=true;volume=0`），现场不能出声

## C. 后半段嘴定格（素材不循环）

- [ ] 确认口播素材是否 `loop=false`，以及单次会话累计朗读是否可能超过素材时长（我们的案例是 12.84s）
- [ ] 页面侧 250ms 巡检四项：可见层是口播素材 / 未暂停 / 帧数在增长 / 未贴末帧
- [ ] 贴末帧 → 硬回卷 `currentTime=0`（首帧=待机锚点帧，看不出接缝）
- [ ] 设三个防误报闸门：冷却 1800ms、起播 1400ms 内不判、淡化期间不判
- [ ] 验证三连：正常朗读 0 误报 / 人为置末帧被检出 / 人为停待机层被重挂

## D. 叫它不理（弱网 / 麦克风）

- [ ] 设备本机测媒体下载速度：**<50 KB/s 基本不可用**（页面里的视频是缓存，能播不代表网络通）
- [ ] 查幽灵网卡抢默认路由：`Get-NetRoute -DestinationPrefix 0.0.0.0/0`，静态 IP 的断连网卡度量值可能更优 → 实测 391 B/s → 30 KB/s（约 77 倍）
- [ ] 链路质量：`ping -l 1400 -n 15 <网关>`，一跳就丢包 13%、平均 152ms = 射频问题
- [ ] 麦克风 rms 空闲应在 0.005~0.01、说话应 >0.05；长期贴地板 = 上传的全是噪声
- [ ] 日志：只有"识别耗时"、没有"[听] 文字"、没有合成就等于识别为空
- [ ] 重载页面后 **`micStream:false` + `status:'online'` = 聋了**；验收标准是 20s 内自愈成 `listening`

## E. 欢迎词不响（地址 / 摄像头）

- [ ] 日志 `present=True` + `speak=skip(no-srv)` / `SRV_UNRESOLVED` = 播报地址解析失败
- [ ] 根因：服务端地址写死局域网 IP + 启动参数禁用页面探测 → 一离开内网就哑
- [ ] 修法：显式参数 → 局域网兜底 → **从页面同源推断**（换网不用改配置）
- [ ] `/motion` 的 `ok=false`：先分清"黑帧"还是"打不开"
- [ ] 黑帧判据：像素均值 ≈0.01、标准差 ≈1、最大值 255 只有几颗噪点
- [ ] 调亮度/增益接口返回 **-1** = 驱动不支持，软件救不了
- [ ] 禁用/启用设备**不算断电**，必须物理拔插 USB；重启也修不好通常就是这个原因
- [ ] 查 USB 根集线器：摄像头与无线网卡同挂一个根集线器会抢供电/带宽；不少 UVC 摄像头插 USB2 反而稳
- [ ] 防复发：关闭电源计划里的 USB 选择性暂停

## F. 交付前必做的 6 项巡检（建议做成定时任务）

- [ ] 人像页 200 且 `status` = `listening`
- [ ] `micStream=true`、`vad=true`
- [ ] `/motion` 的 `ok=true` 且 `frames` 递增
- [ ] 一次播报"出画面" <2.5s、`primed=true`
- [ ] 音画偏移在 ±150ms 内（静音测量）
- [ ] 媒体下载 >50 KB/s

---

需要按你的现场做一次远程体检，或部署一套无人值守数字人：
https://www.aizhigongfang.com/services/ （订单前缀 ORDER-OPS- / ORDER-FORK-）