如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

实时转录

在 Realtime 会话中转录实时音频。

如果您的应用需要将麦克风输入、通话或其他实时音频流转换为文本,但无需助手用语音回复,可以使用实时转录。推荐模型会在接收语音的同时增量返回转录文本,并在应用提交每一轮音频时返回该轮的最终转录文本。

建议先使用 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 核对最终转录文本与各输入条目的对应关系,并按顺序排列文本。
  • 为不支持的时间戳、说话人标签或置信度字段保留备用处理方式。

相关指南

Realtime 与音频概览

比较语音智能体会话、翻译会话和转录会话。

实时翻译

使用专用翻译会话实时翻译语音。

WebSocket 连接

通过服务端媒体管道流式传输原始音频。

语音活动检测

为实时音频流配置轮次检测。