我们最近发布了最新的语音到语音模型 gpt-realtime,同时宣布 Realtime API 正式可用,并推出了多项 API 新功能。Realtime API 和语音到语音(s2s)模型现已正式可用(GA),模型质量、可靠性和开发体验都有了显著提升。
您可以在开发文档和 API 参考中了解这些新功能。本文将介绍其中几项容易忽略的功能,并说明何时适合使用。如果您正在接入 Realtime API,希望这些笔记能对您有所帮助。
模型改进
新模型做了多项改进,以更好地支持生产环境中的语音应用。本文主要介绍 API 的变化。如果您想深入了解模型、掌握使用方法,建议阅读发布公告和实时模型提示词指南。这里先介绍几个具体要点。
使用新模型时,我们建议您:
- 在实时模型 Playground 中尝试不同的提示词。
- 使用
marin或cedar音色,以获得最佳的助手语音效果。 - 为新模型重新编写提示词。模型遵循指令的能力有所提升,因此具体指令对模型行为的影响比以前大得多。
- 例如,对于“只要出现 Y,就一定要说 X”这样的提示词,旧模型可能只把它当作大致的指引,而新模型可能会在您意想不到的情况下也照做。
- 请仔细斟酌每条具体指令,并假定模型会照做。
API 接口变化
我们在正式发布时更新了 Realtime API 的接口,因此目前有 Beta 和 GA 两套接口。我们建议客户端迁移到 GA 接口,以便使用新功能。Beta 接口最终将被弃用。
迁移所需的全部改动,请参阅从 Beta 迁移到 GA 的文档。
您可以通过 Beta 接口访问新的 gpt-realtime 模型,但部分功能可能不受支持。详情见下文。
功能支持情况
Realtime API 的 GA 版本新增了多项功能,其中一些也可在旧模型上使用。
| 功能 | GA 模型 | Beta 模型 |
|---|---|---|
| 图像输入 | ✅ | ❌ |
| 长上下文 | ✅ | ✅ |
| 异步函数调用 | ✅ | ❌ |
| 提示词 | ✅ | ✅ |
| MCP | ✅ 配合异步函数调用效果最佳 | ✅ 缺少异步函数调用时功能受限* |
| 音频 Token → 文本 | ✅ | ❌ |
| 欧盟数据驻留 | ✅ | ✅ 仅限 06-03 版本 |
| SIP | ✅ | ✅ |
| 空闲超时 | ✅ | ✅ |
*由于 Beta 模型不支持异步函数调用,模型可能无法妥善处理尚未返回结果的 MCP 工具调用。我们建议搭配 GA 模型使用 MCP。
温度参数的变化
GA 接口已移除模型参数 temperature。Beta 接口将温度限制在 0.6 - 1.2 范围内,默认值为 0.8。
您可能会问:“为什么用户不能自由设置温度,比如通过调低温度让回复更具确定性?”这是因为温度在这种模型架构中的作用与以往不同。几乎在所有情况下,使用推荐值 0.8 都是最佳选择。
根据我们的观察,降低温度并不能让语音回复具有确定性,而较高的温度会导致声音异常。如果您想控制模型在这些方面的表现,我们建议尝试调整提示词。
新功能
除了从 Beta 到 GA 的接口变化,我们还为 Realtime API 新增了几项功能。
开发文档和 API 参考涵盖了全部功能。下面重点介绍在接入和迁移时可以如何使用这些新功能。
对话空闲超时
在某些应用中,用户长时间没有输入并不寻常。就像打电话时,如果一直听不到对方的声音,我们就会开口问一问。也许模型漏听了用户的话,也许用户不确定模型是否还在说话。我们新增了一项功能,遇到这种情况时,模型会自动开口询问,比如:“您还在吗?”
要启用这项功能,请将 idle_timeout_ms 加入对话轮次检测的 server_vad 设置中,并指定超时时长。超时从模型上一次回复的音频播放完毕后开始计时。也就是说,超时触发时刻等于 response.done 的时间加上音频播放时长,再加上设定的超时时长。如果在等待期间没有触发语音活动检测(VAD),就会触发超时。
超时触发后,服务器会发送 input_audio_buffer.timeout_triggered 事件,随后将空音频片段提交到对话历史记录中,并触发模型回复。提交空音频片段后,模型便有机会检查 VAD 是否漏检了用户在这段时间说的话。
客户端可以按以下方式启用这项功能:
{
"type": "session.update",
"session": {
"type": "realtime",
"instructions": "You are a helpful assistant.",
"audio": {
"input": {
"turn_detection": {
"type": "server_vad",
"idle_timeout_ms": 6000
}
}
}
}
}
长对话与上下文处理
我们调整了 Realtime API 处理长会话的方式。有几点需要注意:
- 实时会话的最长时长已从 30 分钟延长至 60 分钟。
gpt-realtime模型的上下文窗口为 32,768 个 Token。每次回复最多可使用 4,096 个 Token,因此模型最多可接收 28,672 个输入 Token。- 会话指令与工具定义合计最长为 16,384 个 Token。
- 当会话达到 28,672 个 Token 时,服务会自动截断上下文,丢弃部分消息。您可以配置此行为。
- 如果已有转录文本,GA 版服务会自动丢弃部分音频 Token,以节省 Token。
配置截断行为
当对话的上下文窗口达到 Token 上限后,Realtime API 会自动从会话开头截断上下文,先丢弃最早的消息。您可以设置 "truncation": "disabled" 来禁用截断。这样一来,如果生成回复所需的输入 Token 过多,API 就会抛出错误。启用截断的好处是,即使输入超出模型容量,会话也能继续。Realtime API 不会对丢弃的消息进行摘要或压缩,但您可以自行实现这些功能。
截断的一个副作用是,改动对话开头的消息会使提示词缓存失效。提示词缓存通过匹配提示词开头完全相同的内容来复用 Token。在后续每轮对话中,只有保持不变的前缀 Token 才能命中缓存。截断会改变对话的开头,从而减少可缓存的 Token 数量。
为了缓解这个问题,我们新增了一项功能,允许每次截断时多丢弃一些内容。将保留比例设为 0.8,就会截去上下文窗口的 20%,而不是仅截去刚好能让输入 Token 数量低于上限的部分。这样,每次截去的上下文都 更多,只需 一次 截断就能为后续多轮对话腾出空间,避免每轮都截去一点,从而降低缓存失效的频率。对于达到输入上限的长会话,这种做法有助于利用缓存控制成本。
{
"type": "session.update",
"session": {
"truncation": {
"type": "retention_ratio",
"retention_ratio": 0.8
}
}
}
异步函数调用
Responses API 要求在函数调用之后立即提供函数响应,而 Realtime API 允许客户端在等待函数返回结果时继续会话。这样,实时对话可以自然地进行,用户体验也更好。不过,模型有时会编造尚未返回的函数结果。
为缓解这个问题,GA 版 Responses API 增加了占位回复。我们通过实验评估并调整了回复内容,以确保模型在等待函数返回结果时也能作出恰当回应。如果您此时向模型询问函数调用的结果,它会回答类似“我还在等结果”的话。新模型会自动启用这项功能,您无需做任何改动。
欧盟数据驻留
目前支持欧盟数据驻留的具体模型是 gpt-realtime-2025-08-28 和 gpt-4o-realtime-preview-2025-06-03。您必须为组织显式启用数据驻留,并通过 https://eu.api.openai.com 访问服务。
追踪
Realtime API 会在开发者控制台中记录追踪信息,涵盖实时会话中的关键事件,方便排查问题和调试。随 GA 版本一同推出的新事件类型包括:
- 会话更新(向客户端发送
session.updated事件时记录) - 输出文本生成(记录模型生成的文本)
托管提示词
现在,您可以在 Realtime API 中使用提示词,让应用代码引用可单独编辑的提示词。提示词既包含指令,也包含会话配置,例如对话轮次检测设置。
您可以在实时模型 Playground 中创建提示词,根据需要反复调整并管理版本。客户端随后便可通过 ID 引用该提示词,如下所示:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {
"id": "pmpt_123", // your stored prompt ID
"version": "89", // optional: pin a specific version
"variables": {
"city": "Paris" // example variable used by your prompt
}
},
// You can still set direct session fields; these override prompt fields if they overlap:
"instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
}
}
如果提示词中的设置与传给会话的其他配置重叠,如上例所示,则以会话配置为准。因此,客户端既可以沿用提示词中的配置,也可以在会话期间调整它。
带外连接
Realtime API 允许客户端通过 WebRTC 或 SIP 直接连接到 API 服务器。不过,您通常会希望由应用服务器处理工具调用和其他业务逻辑,以便这些逻辑保持私有,并独立于客户端。
您可以通过带外控制通道建立连接,将工具调用、业务逻辑及其他实现细节安全地保留在服务器端。SIP 和 WebRTC 连接现在都支持带外控制。
使用带外连接时,同一个实时会话会有两个活跃连接:一个来自用户的客户端,另一个来自您的应用服务器。您可以通过服务器连接监控会话、更新指令并响应工具调用。
详情请参阅带外连接文档。
开始构建
希望这些笔记能帮助您了解正式可用的 Realtime API 和新一代实时模型有哪些变化。
了解这些变化后,您可以查阅 Realtime API 文档,构建语音智能体、建立连接,或开始为实时模型编写提示词。