118 lines
9.7 KiB
Markdown
118 lines
9.7 KiB
Markdown
HEL-714 日常成片+本地半身交谈样机,基于远端 main `1e9b08a` 和 P10 `6a5e155`。独立交付,不合并、不部署。PR #1 仍是旧分层小样,目标 main;本目录不依赖其尚未合并代码。
|
||
|
||
## 模块边界
|
||
|
||
- `src/main.ts`:日常选片、可切点、真实进退素材、WebRTC、麦克风/能量 VAD、原生 PCM AudioWorklet、取消、恢复和浏览器音画录制。
|
||
- `runtime/server.py`:aiohttp 同源网关;既有 FunASR WebSocket、LLM HTTP、CosyVoice HTTP、LiveTalking WebRTC 信令与音频上传。只读素材 manifest。不写人格、八字、记忆、关系或生活数据。
|
||
- `src/tokens.css` 原样复用 HEL-711 的唯一 token 表;`controls.css` 从已确认雨夜界面的基础控件抽取,未另造主题。页面布局在 `style.css`,无追加覆盖旧样式。没有引入动画库;Emil animate 模块的目的为避免场景跳变,主体过渡依赖真实正向素材,减少动态偏好下 UI 无按压位移。
|
||
- `tools/patch_driver.py` 仅修改独立 LiveTalking 代码副本,给 peer 记录 session id,并增加精确关闭该 peer 的端点。模型权重复用,不改 P10 安装、18080/18081、ASR/TTS 或系统环境。
|
||
|
||
## 运行候选
|
||
|
||
先解压本卡复核包,恢复 `assets/personas/wanwan-v2-cream-night`(整个外观包)。素材二进制不入 Git。依赖锁来自既有小样,没有新增 npm 依赖。
|
||
|
||
```bash
|
||
npm ci --ignore-scripts --no-audit --no-fund
|
||
python3 tools/pack_assets.py
|
||
npm run build
|
||
```
|
||
|
||
在 .12 复用 `/opt/hel715-verify/venv`(aiohttp 3.14.5、aiortc 1.15.0、PyAV 17.1.0、torch 2.8.0+cu128、numpy 2.5.4、resampy 0.4.3),不安装或升级系统依赖。先检查 8010、8014 没有其他监听者。
|
||
|
||
```bash
|
||
python3 tools/prepare_driver.py --destination /opt/hel714-review/LiveTalking
|
||
python3 tools/patch_driver.py /opt/hel714-review/LiveTalking
|
||
```
|
||
|
||
把构建结果、runtime 和素材放在独立样机目录后,在独立 LiveTalking 目录生成本包 avatar(仓库中没有权重或预处理张量):
|
||
|
||
```bash
|
||
cd /opt/hel714-review/LiveTalking
|
||
/opt/hel715-verify/venv/bin/python -m avatars.musetalk.genavatar \
|
||
--file /path/to/sample/dist/assets/talk/gaze.mp4 --avatar_id hel714-gaze-v1
|
||
/opt/hel715-verify/venv/bin/python app.py --model musetalk \
|
||
--avatar_id hel714-gaze-v1 --batch_size 8 --transport webrtc --tts cosyvoice \
|
||
--REF_FILE xiaoyun --TTS_SERVER http://127.0.0.1:9880 \
|
||
--listenport 8010 --stun ''
|
||
```
|
||
|
||
另一个前台终端在本目录启动网关;Ctrl-C 后确认两个自测进程都退出。禁止 pkill、fuser -k 或停止共享服务。`runtime/config.json` 是本样机唯一模型/端点配置。
|
||
|
||
```bash
|
||
/opt/hel715-verify/venv/bin/python runtime/server.py --port 8014
|
||
```
|
||
|
||
浏览器在 .12 本机可打开 `http://localhost:8014`。远程麦克风需要 HTTPS;本次自测只读复用已有 `/opt/voice-agent/web/certs/cert.pem`、`key.pem`,给网关传 `--host 0.0.0.0 --cert ... --key ...`。未改系统证书信任、防火墙或开机启动。自动化使用 Chromium 的忽略证书检查,仅作用于该测试浏览器;普通浏览器是否能授权须实际确认。
|
||
|
||
## 行为和取消契约
|
||
|
||
日常片目前只有一份雨夜阅读。活动、手动天气、时段全部匹配才选中;无匹配时明确回退默认片。没有接真实天气,没有批量换装或跨人物验证。
|
||
|
||
进入时等阅读第 96 帧,播真实正向进场,再交谈;返回用独立正向生成回程,续播原日常切点。v2 新底板来自已确认的 `04-交谈近景-v2.png`,有微动作和目视镜头候选;表情/身体/目光来自底板,只有口型实时驱动。全部仍待总工人工观感审核,不能据“可播放”判断自然。
|
||
|
||
每轮回复拥有独立 peer。取消首先断开浏览器音频图、静音/暂停旧视频、关闭 peer、递增轮次;后端取消 LLM/TTS HTTP 任务,关闭上游响应,再精确销毁该 driver session(含其推理/输出队列)。旧 peer 的 RTP 和旧轮异步错误不进入新轮。这个选择增加建连成本,换来不复用难以完整清理的上游队列。共享 CosyVoice 服务不由本样机管理:客户端断开不等于已证明共享模型内部 GPU 生成即时停止。
|
||
|
||
LLM 和整句 TTS 生成与 ICE/转场并行。网关等浏览器 `/api/ready` 才把音频送入驱动器,防止转场期间提前说话。整句缓冲减少标点分句空隙,代价是长回复要等整句生成;未声称首包 SLA 或流式生成性能通过。前端的“等待首声”是真实等待。
|
||
|
||
麦克风请求 AEC/降噪,原生 Worklet 输出 16k PCM;150ms 连续能量启动会立即停止旧回复,650ms 静音发送 ASR 端点。FunASR `2pass-online` 仅展示,`2pass-offline` 收集终稿后提交。失败不伪造文字。长停顿、轻声、扬声器回声仍需真人校准;请用耳机。按钮和合成 WAV 结果均不冒充真人自然抢话通过。
|
||
|
||
## 素材版本和回滚
|
||
|
||
`assets/personas/wanwan-v2-cream-night/manifest.json`:稳定 `companion_id=wanwan`、外观 `persona_id`、服装/光线/天气标签、avatar id、帧级切点、v2 版本、v1 前版和逐文件 SHA256。换包不创建伴侣或写入身份状态。
|
||
|
||
先把候选完整包解压到新目录,用 `tools/pack_assets.py --assets <目录>` 校验,再整体替换 `assets/personas/<persona_id>`,在 `assets/active.json` 选择它,再构建、重启独立测试服务。禁止把不同版本的单文件混放。avatar 按 manifest 的 id 重新生成或复用对应缓存;网关从 manifest 指定 avatar,不使用别的脸兜底。构建先校验再把所选整包挂载到生成目录 `public/assets`,该目录可由构建重建,勿作为用户素材唯一副本。回滚对旧完整包执行同样步骤。复核包另附 `packs/hel714-v1`,仓库只保留它的 manifest 元数据;当前包为 hel714-v2。
|
||
|
||
## 检查
|
||
|
||
```bash
|
||
npm run build
|
||
python3 -m ruff check samples/companion/runtime samples/companion/tools # 仓库根目录
|
||
python3 -m pytest -q # 仓库根目录,原78项
|
||
/opt/hel715-verify/venv/bin/python tools/check_gateway.py # .12,5项取消/音色/模型故障检查
|
||
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_browser.py
|
||
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_races.py
|
||
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_microphone.py
|
||
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/soak.py
|
||
```
|
||
|
||
浏览器脚本依赖运行机已安装 Playwright/Chromium;麦克风脚本需复核包内的 `evidence/synthetic-microphone.wav`。它是 CosyVoice 合成的测试句,经 Chromium 假麦克风送入实际 Worklet→ASR→LLM→TTS→口型链路,绝不是人现场说话。录制用页面实际绘制画面和实际播放的 WebAudio 输出、同一个 MediaRecorder 时钟,不按帧数重建时间戳;静音时钟从开头持续输出零样本,保留进入前的日常画面。连续音画是浏览器播放图的合成采集,不是物理屏幕/扬声器校准。
|
||
|
||
实测结果和未通过项见 `REPORT.md`。生成工作流、history、原始候选片、浏览器证据和资源采样放复核附件,不在主仓库存大文件。
|
||
|
||
## HEL-718 驱动器补丁(候选,尚未通过同步门槛)
|
||
|
||
`tools/patch_driver.py` 追加类型透传:`AudioFrameData.type` 经
|
||
`BaseAvatar.process_frames → WebRTCOutput → HumanPlayer` 到未赋 PTS 的
|
||
`PendingAudio`。仅合成空闲 `type=1` 且无事件的块限至3块(60ms);
|
||
真实语音(包括零值 PCM)、自定义音频和事件保留,100块队列提供背压。
|
||
首次音频随真实首帧建立时间原点,此后轨道每20ms从队列取最新待播块,
|
||
饥饿时补320样本静音;所有已输出包保持320步长,不在 RTP 队列跳时间戳。
|
||
时钟改用 monotonic,`warm_up` 排空左右全部上下文,不移动 Whisper 特征窗。
|
||
取消仍销毁本轮 peer,补丁不改变前后端取消协议。
|
||
|
||
先用 `prepare_driver.py` 新建私有副本,再运行补丁;源为已选 c726943。
|
||
已验证从 P10 干净副本首次及重复应用,拒绝直接修改 P10 复用目录。
|
||
`driver_audio.py` 必须与 `patch_driver.py` 一起携带。回滚时停止自己的候选
|
||
服务,重建全新 c726943 副本,使用 `git show ae4fd5c:samples/companion/tools/patch_driver.py`
|
||
导出的旧版补丁恢复 HEL-714 endpoint,再指向原 avatar/权重;不要原地混用新旧文件。
|
||
|
||
新增有效检查(使用原有 P10 venv,无新增依赖):
|
||
|
||
```bash
|
||
/opt/hel715-verify/venv/bin/python tools/check_driver_audio.py /path/to/private/LiveTalking
|
||
# 按真实 RTP PTS 录制刚进入、空闲15秒、连续多轮、打断后再次送入相同音频
|
||
/opt/hel715-verify/venv/bin/python tools/record_driver.py \
|
||
--wav fixed.wav --out server-rounds.mp4 --rounds 0,15,1,1 --post 9
|
||
```
|
||
|
||
`trace_driver.py` 仅用于隔离测试,以 `PYTHONPATH=私有驱动器目录` 从该目录运行,
|
||
首参为 JSONL 路径,其余为原 `app.py` 参数。记录逐块生产/接收 RMS、类型、深度、
|
||
丢弃合成静音计数、PTS 和 monotonic 墙钟,不随产品默认开启。
|
||
`record_graph.html/graph_server.py/record_graph.py` 复现浏览器产品音频图;
|
||
`record_product.py` 记录三轮日常→进场→交谈→说话中取消→正向回程→续读。
|
||
`measure_sync.py` 固定 ROI 和阈值并保存检测器 SHA256、完整命令、offset、窗口、
|
||
idle-until、输入/底板哈希、检测误差及逐 lag 相关性。相关性很低时不能把最佳 lag 当作可靠对齐。
|
||
|
||
本轮仍未达到服务端绝对偏差≤0.15秒/浏览器≤0.25秒,详见 `REPORT-HEL718.md`。
|
||
本补丁解决的是可确认的空闲队列/时钟问题,不能据此宣称音画同步已修好。
|