OpenAI Realtime API 适合低延迟、可打断的语音对话。浏览器应用的核心不是把长期 API 密钥放到前端，而是由服务器创建短期客户端凭证，浏览器再通过 WebRTC 建立会话，处理麦克风、播放、轮次和中断。
理解三层结构
官方 Realtime 入门给出的常见浏览器流程是：服务器创建临时客户端密钥，前端建立 RealtimeSession，通过 WebRTC 连接，随后在会话内处理音频和工具。
- 后端：验证登录用户，创建短期凭证，长期密钥只留在服务器。
- 前端：获得麦克风授权，用 WebRTC 发送和接收音频。
- 会话层：设置模型与指令，处理工具、打断、错误和结束。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const agent = new RealtimeAgent({
name: "Support",
instructions: "回答简短；不确定时请用户重复。",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: ephemeralKeyFromYourServer,
});
示例中的 ephemeralKeyFromYourServer 必须是后端生成的短期凭证。模型和 SDK 名称以当前项目权限与官方文档为准。
把“能说话”验收成可用
- 正常说一句固定短句，确认首段音频延迟和完整性。
- 在助手说话中途插话，确认播放停止并开始处理新输入。
- 关闭麦克风权限，界面应提示如何恢复，而不是显示连接成功。
- 断网再恢复，确认旧音频不会重复播放，未完成轮次不会记成成功。
- 口述订单号和日期，检查字母、数字与否定词；关键字段要求二次确认。
生产环境应明确告知用户正在与 AI 语音系统交互，并提供静音、结束和删除会话的入口。需要访问订单或执行动作时仍要走服务端工具和权限检查，不能相信语音里自报的身份。
实时语音和文件转写怎么选
已录好的文件需要最终文字，用文件转写接口；需要自然对话、打断和低延迟，选 Realtime。把文件转写当实时通话会增加延迟，把实时对话当准确会议纪要也会产生核对缺口。
常见问题
浏览器能保存长期 API 密钥吗？不能。应由服务器签发短期凭证。
为什么会抢话或不结束？检查语音活动检测、麦克风噪声和中断事件，再用录屏与事件日志复现。本文没有测试你的麦克风、网络和浏览器，真实延迟必须在目标设备上测量。
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/31642.html
