如果您的应用需要将麦克风输入、通话或其他实时音频流转换为文本,但无需助手用语音回复,可以使用实时转录。推荐模型会在接收语音的同时增量返回转录文本,并在应用提交每一轮音频时返回该轮的最终转录文本。
建议先使用 gpt-live-transcribe。如果音频已录制完成,请使用文件转录。要比较这些工作流,请参阅转录概览。
创建转录会话
要使用标准 API 密钥在服务端通过 WebSocket 进行转录,请连接到 wss://api.openai.com/v1/realtime?intent=transcription。使用 WebSocket 指南中给出的身份验证请求头,但请从 URL 中省略 model。该指南中指定模型的 URL 会创建对话会话,这类会话不接受下文的转录配置更新。
连接建立后,发送 session.update,在会话配置中指定 type: "transcription",并选择 gpt-live-transcribe 模型。要处理浏览器音频,请参阅 WebRTC。
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "gpt-live-transcribe"
},
"turn_detection": null
}
}
}
}本示例使用 24 kHz PCM 音频。在 gpt-live-transcribe 转录会话中,请省略 audio.input.turn_detection 或将其设为 null。该模型不支持 server_vad 或 semantic_vad。有关完整的会话配置,请参阅 Realtime 会话 API 参考。
流式传输音频
使用 input_audio_buffer.append 分块发送音频:
ws.send(
JSON.stringify({
type: "input_audio_buffer.append",
audio: base64Pcm16,
})
);在每轮音频结束时发送 input_audio_buffer.commit,以接收该轮的最终转录文本:
ws.send(
JSON.stringify({
type: "input_audio_buffer.commit",
})
);使用客户端语音活动检测(VAD)判断说话何时结束,然后发送 input_audio_buffer.commit。
处理转录事件
监听转录增量事件和完成事件:
ws.on("message", (data) => {
const event = JSON.parse(data);
if (event.type === "conversation.item.input_audio_transcription.delta") {
process.stdout.write(event.delta);
}
if (event.type === "conversation.item.input_audio_transcription.completed") {
console.log("\nFinal transcript:", event.transcript);
}
});增量事件包含新增的转录文本:
{
"type": "conversation.item.input_audio_transcription.delta",
"item_id": "item_003",
"content_index": 0,
"delta": "Hello,"
}
完成事件包含已提交条目的最终转录文本:
{
"type": "conversation.item.input_audio_transcription.completed",
"item_id": "item_003",
"content_index": 0,
"transcript": "Hello, how are you?"
}
不同轮次的完成事件不保证按发言顺序到达。使用 item_id 将转录事件与已提交的输入条目匹配。
配置好转录会话后,使用下面的 Go 函数发送采样率为 24 kHz 的单声道 PCM16 音频,提交该轮音频,并将最终转录文本与已提交的条目匹配:
func transcribeTurn(ctx context.Context, conn *realtime.RealtimeConnection, audio []byte) error {
for start := 0; start < len(audio); start += 9600 {
end := min(start+9600, len(audio))
if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfInputAudioBufferAppend(base64.StdEncoding.EncodeToString(audio[start:end]))); err != nil {
return err
}
}
if err := conn.Send(ctx, realtime.RealtimeClientEventUnionParam{
OfInputAudioBufferCommit: &realtime.InputAudioBufferCommitEventParam{},
}); err != nil {
return err
}
// Match the final transcript to the committed item, not event arrival order.
var itemID string
for {
event, err := conn.Recv(ctx)
if err != nil {
return err
}
switch event.Type {
case "input_audio_buffer.committed":
itemID = event.OfInputAudioBufferCommittedEvent.ItemID
case "conversation.item.input_audio_transcription.delta":
delta := event.OfConversationItemInputAudioTranscriptionDeltaEvent
if itemID != "" && delta.ItemID == itemID {
fmt.Fprintf(os.Stderr, "Partial transcript (%s): %s\n", delta.ItemID, delta.Delta)
}
case "conversation.item.input_audio_transcription.completed":
completed := event.OfConversationItemInputAudioTranscriptionCompletedEvent
if itemID == "" || completed.ItemID != itemID {
continue
}
fmt.Println("Final transcript:", completed.Transcript)
return nil
case "conversation.item.input_audio_transcription.failed":
if itemID != "" && event.OfConversationItemInputAudioTranscriptionFailedEvent.ItemID == itemID {
return fmt.Errorf("transcription failed")
}
case "error":
return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
}
}
}添加转录上下文
如果音频包含专业词汇,或预计会出现多种语言,请添加上下文。要在现有会话中更改转录配置,请再次发送 session.update 事件。
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "gpt-live-transcribe",
"prompt": "A customer support call about a premium plan and account AC-42.",
"keywords": ["premium plan", "AC-42", "billing"],
"languages": ["en", "fr"],
"delay": "low"
},
"turn_detection": null
}
}
}
}- 使用
prompt描述录音内容或录音场景。 - 使用
keywords列出音频中可能出现的产品名称、首字母缩略词及其他有特定写法的词语。 - 使用
languages指定预计会出现的输入语言。
支持的语言代码格式包括:
- ISO 639-1 代码,例如
en、es和fr。 - 部分 ISO 639-3 代码,例如
eng、spa、yue和cmn。 - 带地区标识的
zh语言代码,例如zh-cn、zh-tw和zh-hk。
Realtime API 会拒绝不受支持或格式不正确的语言代码。
关键词仅用作提示,转录结果无需包含这些词。每个关键词必须写在一行内,且不能包含 <、>、回车符或换行符。如果某个关键词包含上述任一字符,或 prompt 超出模型的长度限制,Realtime API 会拒绝此次会话更新。
gpt-live-transcribe 使用 languages,而非单数形式的 language 字段。请勿同时发送这两个字段。
转录已提交的音频轮次
仅当您明确需要在提交一轮音频后才开始转录,或需要获取检测到的语言时,才在 Realtime 会话中使用 gpt-transcribe。此工作流需要 WebSocket 连接。
当 gpt-transcribe 在 Realtime API 会话中转录输入音频,或在专用转录会话中运行时,它会自动将之前各轮的转录文本用作上下文。
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "gpt-transcribe"
},
"turn_detection": null
}
}
}
}追加音频并发送 input_audio_buffer.commit。随后,模型可以在发出最终完成事件之前增量返回转录文本。完成事件还包含检测到的语言:
{
"type": "conversation.item.input_audio_transcription.completed",
"item_id": "item_003",
"content_index": 0,
"transcript": "Bonjour, pouvez-vous m'entendre ?",
"languages": [{ "code": "fr" }]
}
当 gpt-transcribe 无法可靠地判断语言时,languages 为空数组。gpt-live-transcribe 不返回语言检测结果。
调节延迟与准确率
流式转录需要在延迟和转录质量之间权衡。较低的延迟设置可以让部分转录文本更早出现。较高的延迟设置让模型在输出文本前获得更多音频上下文,有助于降低词错误率。
先设置 audio.input.transcription.delay,再用您的实际音频进行测试。您可以根据场景选择初始设置:
minimal适用于对延迟最敏感的交互。low适用于低延迟实时字幕。medium适用于需要兼顾延迟与准确率的场景。high适用于准确率比即时显示更重要的场景。xhigh适用于能够容忍最大延迟以获得更多上下文的工作流。
具体延迟毫秒数可能因模型配置而异。请使用有代表性的音频进行基准测试,避免假设每个档位都有固定的延迟。
请勿仅依据合成音频选择设置。测试时请使用有代表性的麦克风和电话音频,并覆盖不同口音、背景噪声、说话时切换语言、领域词汇以及长时间会话等情况。
处理置信度、时间戳和说话人标签
gpt-live-transcribe 不返回词级时间戳、说话人标签或转录置信度分数。如果您的应用需要时间戳或说话人标签,请使用支持相应功能的文件转录模型,或在应用层添加备用方案。
生产环境检查清单
- 在调优前确定目标延迟和准确率阈值。
- 使用生产环境中的真实音频进行测试,避免只测试无噪声的样本。
- 测试每一种目标语言。
- 在评测集中纳入数字、日期、货币金额、电子邮件地址、产品名称和领域术语。
- 除词错误率外,还要单独跟踪转录文本为空、被截断或延迟返回的情况。
- 确定后续增量事件修正先前文本时,界面应如何更新已显示的部分转录文本。
- 使用
item_id核对最终转录文本与各输入条目的对应关系,并按顺序排列文本。 - 为不支持的时间戳、说话人标签或置信度字段保留备用处理方式。
相关指南
比较语音智能体会话、翻译会话和转录会话。
使用专用翻译会话实时翻译语音。
通过服务端媒体管道流式传输原始音频。
为实时音频流配置轮次检测。