P0 实验报告 · Pipecat 传输层

日期：2026-09-15。状态：实时语音链路已闭环；A 方案验证通过。

代码：~/workspace/ai-companion/services/bot_server.py（服务端）、 client/test_client.py（自写 aiortc 客户端）

一、为什么做这个实验

方案文档写"Pipecat 作为唯一会话管线框架"，但核实后发现它一行都没被用上 （只在 requirements.txt 里声明，代码里零引用）。助手引擎是独立 asyncio，由测试脚本用文件音频驱动。

于是有个待定的架构问题：Pipecat 该用多深？

A 方案：Pipecat 只做传输与帧模型，会话语义归自有引擎（一个 FrameProcessor 吞掉整条管线）
B 方案：按 Pipecat 的 service 模型重构，STT/LLM/TTS/记忆都做成框架原生 service

实验目的：验证 A 方案的核心假设能否成立，并拿到真实传输下的延迟数字。

二、结论摘要

部分	结果
WebRTC 信令（offer/answer）	✅ 往返 47–280ms
ICE 连通	✅ 走 172.16.1.x 直连
data channel + 心跳	✅
双向媒体轨	✅ 客户端音轨送达服务端，服务端音轨客户端收到
管线启动、处理器 setup()	✅，只产生一个自动 StartFrame
帧路由到自定义处理器	✅ StartFrame 与 250+ 个音频帧实测到达
端到端出声	✅ 文件音频 → STT → DeepSeek → Qwen3-TTS → 非静音回复
浏览器真人对话	✅ SSH 隧道打开 Playground，麦克风输入与语音回复正常
单次真实链路延迟	源音频结束→客户端首个非静音约 5.8s；仍需优化

即：Pipecat 负责传输/帧/RTVI、自有引擎负责会话语义的 A 方案成立。

三、原问题根因与修复

原先看到 EngineProcessor.setup() 被调用、process_frame 却为 0，于是误判为 Pipeline 接线或模型不兼容。服务器完整日志揭示了真实顺序：Pipecat 在 setup 阶段预热 NLTK 分句器，首次运行尝试下载 punkt_tab，20 秒后 setup timeout。worker 尚未走到自动发送 StartFrame 的阶段，因此所有业务帧都还在等待。

修复后把 punkt_tab 预装到权限 700 的 ~/.local/share/ai-companion/nltk_data，启动时 fail-fast 检查；同时改用 PipelineWorker(params=PIPELINE_PARAMS)，删除客户端连接事件中手工发送的第二个 StartFrame。复测显示自动 StartFrame 正常抵达管线末端，音频持续进入处理器。

之后仍不出声是第二个独立问题：文件客户端播放完 WAV 后没有继续推进 PTS，服务端收不到 VAD 所需的 700ms 尾静音。客户端现在固定发送 1.2s 尾静音且持续推进时钟。接收端也改为只有检测到非静音音频才算成功，不再把 WebRTC 空闲静音当作回复。

四、挖出的 13 个集成坑

每个都会表现为"什么都没发生"，极难排查。无论最终选 A 还是 B 都会踩。

#	坑	现象	怎么办
1	Pipecat 客户端 SDK 不覆盖 N5095 形态	浏览器/移动端/C++/ESP32 都有，没有"Linux x86 盒子接 USB 阵列"	自己写 aiortc 客户端（已有雏形）
2	客户端必须建 data channel 并定期发 `"ping"`	不建则服务端一帧音频都不推，日志只有一句 "Data channel not established within 10s"	建 channel + 1s 心跳
3	offer 里没有媒体时 aiortc 完全不收集 ICE 候选	信令成功、SDP 交换正常，但 ICE 永远停在 `new`	即使只测连通也要加一条（静音）音轨
4	ICE 收集完成前就发 offer	SDP 里 0 个候选地址	等 `iceGatheringState == "complete"`
5	`PipelineWorker.run()` 要 `WorkerParams(task_manager=...)`，不是 `PipelineParams`	不传报 "missing 1 required positional argument"；传错报 "no attribute 'task_manager'"	两个参数分别给构造函数和 run()
6	`TaskManager()` 内部调 `asyncio.get_running_loop()`	模块级创建报 "no running event loop"	必须在异步上下文里建
7	后台任务里的异常被静默吞掉	日志里查不到任何线索，表现为"连接正常但没反应"	自己 try/except + log.exception
8	信令回调里 `await task.run()`	阻塞整个会话生命周期，管线初始化时序走歪	`asyncio.create_task(task.run(...))`
9	NLTK `punkt_tab` 在首个 worker 内临时下载	setup 20 秒超时，看起来像帧路由坏了	部署时预装到私有目录，启动前检查
10	`PipelineWorker` 本身会自动发送 StartFrame	手工再发会看到两个启动帧	删除连接回调里的手工 StartFrame
11	文件结束后静音帧 PTS 不增长	VAD 永远等不到说完	源位置与媒体时钟分离，额外发送 1.2s 静音
12	WebRTC 输出轨空闲时也有静音	“收到 34 秒音频/首音 206ms”的假成功	按非静音 RMS 判断业务回复
13	prebuilt Playground 连接前先请求 `/start`	页面正常但 Connect 在 authenticating 阶段报 Not Found	增加 `/start`，返回 `/api/offer` 的 `webrtcRequestParams`

第 5、6、7 条各花了好几轮才发现——因为异常在后台任务里，日志什么都不显示。

五、对 A/B 决策的影响

实验前的判断是"Pipecat 的独特价值收敛到传输层"（因为方案 §5 的音频边界决定把 AEC 和播放放在客户端，绕开了 Pipecat 的打断机制）。

根因已经证明既不是 Pipeline 接线，也不是自定义处理器模型不兼容。因此确定采用 A 方案：保留已验证的 ConversationEngine，由薄 EngineProcessor 适配 Pipecat 的输入输出帧。网页客户端需要的 RTVI 继续开启；N5095 精简客户端可以忽略暂不认识的 RTVI data-channel 消息。

不做 B 方案的全量重构。后续只在确有收益时渐进引入 Pipecat 的 VAD、turn processor、 metrics 与 interruption，不重写已有的记忆、身份、LLM/TTS 适配。

六、下一步

优化真实首音延迟：分别记录 VAD、STT、LLM 首 token、TTS 首段和客户端播放时间
继续用 prebuilt 网页客户端做真人语音、浏览器 AEC 与主观试听（基础对话已通过）
Tailscale tailnet 开启 Serve 后，用 HTTPS 暴露 /client/
音频硬件到货后实现 N5095 声卡、AEC、播放参考与打断
录本人普通话语料，对 Zipformer / SenseVoice / faster-whisper 做 CER 对比

七、当前代码状态

服务端 services/bot_server.py：

已实现：SmallWebRTC 信令端点 /api/offer、prebuilt 网页客户端挂载 /client/、 Playground 启动端点 /start、EngineProcessor（自写能量 VAD + 引擎调用）
已改用 PipelineWorker，保留 RTVI；启动/超时/错误有显式日志
音频缓冲加入 1 秒预卷、60 秒上限和短噪声丢弃，连接结束释放会话资源
VAD 是极简能量判定，不是最终方案（方案 §5 的说完判定还没选型）
当前没有唤醒门控：网页连接后每段有效语音都会触发回复。正式唤醒仍在 P2 的 N5095 本地实现，待机时不上传音频；本次按用户决定暂不处理

客户端 client/test_client.py：

已实现：非 trickle ICE、data channel + 心跳、文件音频实时发送、1.2s 尾静音、回复录音
只有检测到非静音回复才成功；按 WebRTC 实际 48kHz 保存 WAV
不做 AEC、不做播放参考、不做打断——那些要真实声卡和硬件
它是 N5095 客户端的雏形，不是产品代码

八、复现

# 服务端（服务器上）
cd ~/ai-companion
.venv/bin/python services/bot_server.py --host 0.0.0.0 --port 7860

# 客户端（N5095 上）
cd ~/workspace/ai-companion
python client/test_client.py \
  --server http://cadadmin-server.taild0f91d.ts.net:7860 \
  --wav p0/stt_tts_bench/wavs/stt_1.wav --out /tmp/reply.wav

当前实测：连接成功，收到非静音语音回复；源音频结束到首个非静音约 5.8 秒。浏览器通过 SSH 隧道访问 http://localhost:7860/client/ 也已完成真人对话； 2026-09-16 一轮服务端指标约 3.0 秒。

九、顺带发现的环境问题

局域网被重新编址了：两台机器从 192.168.0.x 变成 172.16.1.x （N5095 现为 172.16.1.99，服务器 172.16.1.101）。

已处理：客户端默认地址改用 tailscale 域名（cadadmin-server.taild0f91d.ts.net），抗重新编址。

未处理：方案文档与 N5095 配置里仍有 192.168.0.20 的残留引用。

8.4 KiB Raw Blame History Unescape Escape