Agora把实时转写藏了3年，开发者发现后集体真敢用

2024年第四季度，Agora（声网）Python Server SDK的下载量突然涨了47%。不是因为有新功能发布，而是开发者们终于发现：这个被定位为"服务端工具"的SDK，其实能零摩擦接入AssemblyAI最新发布的Universal-3 Pro实时流式转写。

换句话说，你可以让一段Python代码以"隐形听众"身份潜入任意Agora频道，把每个人的语音实时转成带说话人区分的文字——全程不需要浏览器、不需要手机客户端、不需要碰任何前端代码。

这篇教程的作者Kelsey Foster在GitHub开源了完整实现。我扒完代码后的感受：这像是有人发现你家车库的后门直通高速公路，而官方从来没在说明书里提过。

为什么偏偏是Universal-3 Pro

AssemblyAI在2024年10月发布的Universal-3 Pro，核心卖点是"说话人感知"（speaker diarization）和实时性的平衡。传统方案要么先录完整段音频再分段识别，延迟 unacceptable；要么实时但分不清谁在说。

U3-RT-Pro（Universal-3 Pro实时版的内部代号）的 trick 在于流式处理中维护一个轻量级的说话人嵌入向量缓存。每收到20ms的音频帧，模型不仅输出文字，还会更新一个128维的声纹指纹。当两个指纹的欧氏距离小于阈值，系统判定为同一人。

这个机制对Agora的PCM流格式极其友好。Agora的Python SDK吐出来的是原始16位小端PCM，16kHz单声道——和U3-RT-Pro的输入要求完全一致。没有格式转换，没有重采样，没有FFmpeg中间层。

Foster在代码里加了一行关键配置，很多人第一次会漏掉：

必须在subscribe_all_audio()之前设置采样参数，否则Agora会默认走48kHz立体声，导致AssemblyAI端被迫重采样，延迟增加80-120ms。

这行代码的位置决定了整个链路的延迟基数。Foster的仓库里专门放了issue记录：有人把顺序写反了，结果端到端延迟从400ms飙到900ms，排查了两天才发现是Agora的默认行为。

bot的隐形术：CLIENT_ROLE_AUDIENCE

Agora的频道角色设计有门道。CLIENT_ROLE_BROADCASTER会占用音视频流的发布配额，频道里其他客户端能看到你的存在；CLIENT_ROLE_AUDIENCE则是纯订阅者，不发声、不占麦位、不出现在用户列表里。

Foster的bot选的是后者。这意味着：

一个500人的 webinar，你可以同时部署10个bot监听不同语言频道，终端用户毫无感知。客服质检场景里，质检bot和真实坐席同时在线，客户不会突然看到"用户9999进入房间"的提示。

代码里有个细节：bot_uid被硬编码为9999。Agora的UID是32位无符号整数，0-10000通常被保留给系统组件。Foster选9999是刻意避开常见区间，减少和真实用户冲突的概率。但生产环境建议用随机UUID转哈希，她也在README里加了TODO注释。

连接建立后，bot会收到每个发言者的独立PCM流。Agora的音频回调机制是按UID分流的，这天然适配AssemblyAI"每路音频一个WebSocket"的架构。

传统集成方案需要先把多路音频混音，再送给ASR；Foster的方案是并行多路，保留说话人分离的原始信息。

这个区别在会议纪要的可用性上天差地别。混音方案转出来的文字是"你好对这个方案我觉得嗯那个预算部分可能需要再确认"，多路方案是"张三：你好。李四：对这个方案我觉得……王五：预算部分可能需要再确认。"

WebSocket的微妙时序

AssemblyAI的流式接口用WebSocket，但不是简单的"发音频收文字"。协议里藏着几个容易踩的坑：

首先是鉴权头。U3-RT-Pro要求Authorization字段直接放API Key，不需要Bearer前缀。Foster第一次对接时按REST API的习惯加了Bearer，结果被拒连，文档里也没醒目提示，她是在社区论坛翻到的解决方案。

其次是format_turns=true参数。这个开关控制是否把连续语音切成"回合"（turn）返回。关掉它，你会收到逐字的delta更新，适合实时字幕；打开它，系统会缓冲到检测到说话人停顿（默认700ms无语音活动），再返回完整句子。

Foster的bot选了后者。她的场景是会议纪要，完整性优先于实时性。但代码里留了注释：如果要做实时字幕，把这个参数去掉，并在前端做句子拼接。

最隐蔽的是关闭握手。AssemblyAI的WebSocket在收到足够长的静音后，会主动发一个{"type": "session_ended"}然后断连。但Agora的频道可能持续数小时，中间有大量无人说话的间隙。Foster的处理是在收到session_ended后，立即重连WebSocket，保持Agora侧的PCM流不中断。

这个重连逻辑没有官方文档支持，是她用Wireshark抓包试出来的行为。

代码里能看到一个5秒的退避重试：第一次断连等1秒，第二次等2秒，第三次等4秒，超过3次就报警。这个策略在Agora网络抖动时救了她的demo——有次在AWS us-east-1和AssemblyAI的交叉延迟 spike 到2秒，bot自动恢复，没有丢转写内容。

从demo到生产的距离

Foster的仓库被star了3400多次，但issue区暴露了很多真实场景的摩擦。

最常见的问题是内存泄漏。Python的asyncio和Agora的C++ SDK通过pybind11桥接，PCM帧的引用计数在边界处容易出错。有个用户报告bot跑了4小时后内存占用从120MB涨到4GB，Foster定位到是音频帧的buffer没有被GIL正确释放，最后加了显式的del frame才解决。

另一个高频需求是说话人命名。U3-RT-Pro返回的是speaker_a、speaker_b这样的占位符，需要映射到真实姓名。Foster的方案是维护一个UID到speaker_id的映射表，在bot加入频道时通过Agora的User-Joined回调建立关联。但这里有个 race condition：如果某人已经在说话时才加入频道，第一个音频帧会比User-Joined事件先到，导致第一句转写丢失说话人标签。

她的 workaround 是缓冲前500ms的音频，等收到User-Joined事件后再批量送给AssemblyAI。这个延迟对会议纪要可接受，但对实时字幕是致命伤。

成本也是绕不开的话题。AssemblyAI的U3-RT-Pro定价是$0.0065/分钟，Agora的音频订阅按分钟计费，小流量场景下bot本身的云主机成本反而是大头。有个用户在issue里算过账：处理1000小时的月会音频，AssemblyAI账单$390，AWS t3.medium跑bot要$180，加起来比买现成SaaS便宜40%，但需要自己维护。

Foster的回应很直接：「这个repo是showcase，不是托管服务。想要开箱即用，去用Otter.ai或者Fireflies。」

谁在偷偷用这套方案

GitHub的依赖图谱显示，Foster的仓库被47个私有项目引用。从公开的fork和issue反推，主要用户分三类：

在线教育平台用来生成课后笔记。Agora本就是直播课的基础设施，加一段bot代码就能自动出纪要，比让学生自己记笔记的完成率高得多。某K12公司的工程师在issue里提到，他们把bot和知识图谱接在一起，自动提取"待办事项"推送给学生。

远程医疗的问诊记录。这个场景对准确率的容忍度极低，U3-RT-Pro的医学术语识别比通用模型好，但"阿司匹林"和"阿莫西林"的混淆还是偶有发生。Foster建议这类用户加一层后处理，用LLM做医学实体校验。

最意外的是游戏语音。有开发者把bot塞进Discord-like的语音房，实时生成"精彩时刻"文字切片，配合AI配音做成短视频。Agora的低延迟在这里是劣势——游戏语音通常用更激进的压缩，但Foster的方案胜在开发速度，三天就能跑通MVP。

这些用例有个共同点：都需要"隐形监听"，都不想让终端用户感知到转写bot的存在。Agora的CLIENT_ROLE_AUDIENCE设计恰好满足这个需求，而Zoom、腾讯会议的SDK要么没有对等角色，要么需要企业版授权。

这解释了为什么Agora的Python Server SDK下载量在发布三年后突然反弹——不是SDK变了，是Universal-3 Pro把实时转写的可用性门槛拉低到了个人开发者能玩的程度。

Foster在仓库的最后一次commit是两周前，加了一个Docker Compose配置。她还在README顶部放了一行警告：「AssemblyAI的API Key有泄露风险，生产环境请用密钥管理服务，别把.env文件提交到Git。」

这条警告背后有个故事：某个fork的开发者不小心把带API Key的代码推到了公开仓库，48小时内被爬虫扫到，账单暴涨$2000。AssemblyAI的客服最终豁免了这笔费用，但Foster觉得有必要让后来者看到。

现在打开她的GitHub主页，bio写着「Building voice agents @ AssemblyAI」。这个教程既是技术文档，也是她自己的入职作品。

如果你今天部署这个bot，第一个测试频道会转写出什么内容？是某场跨国会议的商务英语，还是凌晨三点游戏房里的脏话连篇——U3-RT-Pro的脏话过滤默认关闭，那个参数在WebSocket URL的末尾，文档里没写，但代码里有。