使用实时翻译,您可以将源音频流式传入专用翻译会话,在说话者讲话的同时接收译音和增量转写文本。这适用于现场口译、多语言通话、广播、会议、课堂和视频聊天室。
如果您的应用需要翻译说话者的语音,请使用 gpt-realtime-translate。如果您需要能回答问题、调用工具并管理对话的助手,请在标准 Realtime API 会话中使用 gpt-realtime-2.1。
下表对比了实时翻译会话与语音智能体会话的架构。
| 语音智能体会话 |
翻译会话 |
连接到 /v1/realtime。 |
连接到 /v1/realtime/translations。 |
| 模型充当助手。 |
模型充当口译员。 |
| 按对话和响应的生命周期运行。 |
根据传入的音频持续流式输出翻译。 |
| 模型可以调用工具并生成助手回复。 |
模型输出译音和增量转写文本。 |
可以调用 response.create。 |
不调用 response.create。 |
音频流本身即可触发翻译。请持续追加音频,包括讲话间的静音片段,并在收到输出事件时进行处理。
如果浏览器负责采集或播放音频,请使用 WebRTC。WebRTC 通过媒体轨道发送源音频,并通过远端音轨接收译音,因此您无需手动重采样或播放 PCM 音频块。
如果服务器已在接收原始音频,例如来自 Twilio Media Streams、SIP 媒体流、广播接入流或媒体处理进程的音频,请使用 WebSocket。使用 WebSocket 时,请发送经 base64 编码的 24 kHz PCM16 音频,并自行播放陆续返回的音频片段。
对于浏览器应用,请在服务器上创建短期有效的客户端密钥。请勿在浏览器中暴露您的标准 API 密钥。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25app.post("/session", async (req, res) => {
const language = req.body.targetLanguage ?? "es";
const response = await fetch(
"https://api.openai.com/v1/realtime/translations/client_secrets",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
"Content-Type": "application/json",
"OpenAI-Safety-Identifier": "hashed-user-id",
},
body: JSON.stringify({
session: {
model: "gpt-realtime-translate",
audio: {
output: { language },
},
},
}),
}
);
res.status(response.status).json(await response.json());
});
在浏览器中采集音频,创建对等连接,然后将 SDP offer 通过 POST 请求发送到翻译通话端点。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50const { value: clientSecret } = await fetch("/session", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ targetLanguage: "es" }),
}).then((response) => response.json());
const sourceStream = await navigator.mediaDevices.getUserMedia({
audio: true,
});
const pc = new RTCPeerConnection();
pc.addTrack(sourceStream.getAudioTracks()[0], sourceStream);
const translatedAudio = new Audio();
translatedAudio.autoplay = true;
pc.ontrack = ({ streams }) => {
translatedAudio.srcObject = streams[0];
};
const events = pc.createDataChannel("oai-events");
events.onmessage = ({ data }) => {
const event = JSON.parse(data);
if (event.type === "session.output_transcript.delta") {
subtitles.textContent += event.delta;
}
};
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const sdpResponse = await fetch(
"https://api.openai.com/v1/realtime/translations/calls",
{
method: "POST",
headers: {
Authorization: `Bearer ${clientSecret}`,
"Content-Type": "application/sdp",
},
body: offer.sdp,
}
);
if (!sdpResponse.ok) {
throw new Error(await sdpResponse.text());
}
await pc.setRemoteDescription({
type: "answer",
sdp: await sdpResponse.text(),
});
连接到专用翻译端点,并在 URL 中指定模型。
运行此示例前,请安装 Node.js 的 ws 包。
运行此示例前,请安装 Python 的 websocket-client 和 sounddevice 包。
运行此示例前,请安装 Ruby 的 openai 0.121.0 版和 async-websocket(分别运行 gem install openai -v 0.121.0 和 gem install async-websocket)。
运行此示例前,请添加 Maven 依赖 com.openai:openai-java:4.75.1。
Java 示例分别演示如何建立连接、配置语言和输入音频。Java SDK 也支持接收事件和结束会话,但本指南未提供这两个步骤的 Java 示例。要按下文的步骤完成整个翻译流程,请使用 Node.js 或 Python 示例。
1
2
3
4
5
6
7
8
9
10
11import WebSocket from "ws";
const ws = new WebSocket(
"wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
{
headers: {
Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
"OpenAI-Safety-Identifier": "hashed-user-id",
},
}
);
1
2
3
4
5
6
7
8
9
10
11import os
import websocket
ws = websocket.WebSocket()
ws.connect(
"wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
header=[
f"Authorization: Bearer {os.environ['OPENAI_API_KEY']}",
"OpenAI-Safety-Identifier: hashed-user-id",
],
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
session, err := client.Realtime.ConnectTranslation(ctx, "gpt-realtime-translate", realtime.TranslationConnectionOptions{}, option.WithHeader("OpenAI-Safety-Identifier", "hashed-user-id"))
if err != nil {
return err
}
defer session.Abort()
created, err := session.Recv(ctx)
if err != nil {
return err
}
fmt.Println(created.Type)
if created.Type != "session.created" {
return fmt.Errorf("expected session.created, got %s", created.Type)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.TranslationConnection;
import com.openai.helpers.TranslationWebSocketOptions;
import com.openai.models.realtime.*;
var http = OkHttpClient.builder().build();
var options =
ClientOptions.builder()
.fromEnv()
.httpClient(http)
.putHeader("OpenAI-Safety-Identifier", "hashed-user-id")
.build();
try (http;
var connection =
TranslationConnection.connect(
options,
TranslationWebSocketOptions.builder()
.model("gpt-realtime-translate")
.sendTimeout(java.time.Duration.ofSeconds(30))
.build())) {
while (true) {
var event = connection.receive();
if (event.error().isPresent())
throw new IllegalStateException(event.error().orElseThrow().toString());
if (event.sessionCreated().isPresent()) {
System.out.println("Connected to translation session.");
System.out.println(event);
break;
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"
require "base64"
client = OpenAI::Client.new
client.realtime.connect_translation(
model: "gpt-realtime-translate",
request_options: { extra_headers: { "OpenAI-Safety-Identifier" => "hashed-user-id" } }
) do |session|
created = session.receive
unless created.is_a?(OpenAI::Realtime::RealtimeTranslationSessionCreatedEvent)
raise "Connection closed before session creation"
end
puts created.type
# Insert the configuration, audio, listener, and closing steps here.
end
如果使用 Ruby,请将下文配置语言、追加音频、监听事件和关闭会话的四段代码放在同一个 client.realtime.connect_translation 块内,紧接在确认会话已创建的检查之后。监听代码定义事件处理器。关闭代码通过 session.finish 从现有连接接收剩余事件,并调用该处理器处理事件,直到收到 session.closed。这四个步骤都应在同一个代码块内完成,以便使用已配置为输出西班牙语的会话。
Java 连接示例会在 try 块结束时关闭套接字。Java 配置示例和音频输入示例都需要已打开的 TranslationConnection。发送音频和接收输出期间,请保持该连接打开。退出代码块前,请先结束会话,并持续读取会话事件,直到收到 session.closed。具体步骤请参阅关闭 WebSocket 会话。
套接字打开后,配置目标语言。
1
2
3
4
5
6
7
8
9
10
11
12
13
14ws.on("open", () => {
ws.send(
JSON.stringify({
type: "session.update",
session: {
audio: {
output: {
language: "es",
},
},
},
})
);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import json
ws.send(
json.dumps(
{
"type": "session.update",
"session": {
"audio": {
"output": {
"language": "es",
},
},
},
}
)
)
1
2
3
4
5
6
7
8
9if err := session.Send(ctx, realtime.RealtimeTranslationClientEventParamOfSessionUpdate(realtime.RealtimeTranslationSessionUpdateRequestParam{
Audio: realtime.RealtimeTranslationSessionUpdateRequestAudioParam{
Output: realtime.RealtimeTranslationSessionUpdateRequestAudioOutputParam{
Language: openai.String("es"),
},
},
})); err != nil {
return err
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.TranslationConnection;
import com.openai.helpers.TranslationWebSocketOptions;
import com.openai.models.realtime.*;
connection.send(
RealtimeTranslationClientEvent.ofSessionUpdate(
RealtimeTranslationSessionUpdateEvent.builder()
.session(
RealtimeTranslationSessionUpdateRequest.builder()
.audio(
RealtimeTranslationSessionUpdateRequest.Audio.builder()
.output(
RealtimeTranslationSessionUpdateRequest.Audio.Output.builder()
.language("es")
.build())
.build())
.build())
.build()));
1
2
3
4
5
6
7session.send_event(type: "session.update", session: { audio: { output: { language: "es" } } })
updated = session.receive
unless updated.is_a?(OpenAI::Realtime::RealtimeTranslationSessionUpdatedEvent)
raise "Connection closed before session update"
end
puts updated.type
然后持续追加音频。
1
2
3
4
5
6ws.send(
JSON.stringify({
type: "session.input_audio_buffer.append",
audio: base64Pcm16,
})
);
1
2
3
4
5
6
7
8ws.send(
json.dumps(
{
"type": "session.input_audio_buffer.append",
"audio": base64_pcm16,
}
)
)
1
2
3
4
5
6
7// audio contains mono PCM16 samples at 24 kHz.
for start := 0; start < len(audio); start += 4800 {
end := min(start+4800, len(audio))
if err := session.Send(ctx, realtime.RealtimeTranslationClientEventParamOfSessionInputAudioBufferAppend(base64.StdEncoding.EncodeToString(audio[start:end]))); err != nil {
return err
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.TranslationConnection;
import com.openai.helpers.TranslationWebSocketOptions;
import com.openai.models.realtime.*;
import java.util.Base64;
// Call for each PCM16, 24 kHz, mono chunk supplied by your audio source.
static void appendAudio(TranslationConnection connection, byte[] pcmAudio) {
String base64Pcm16 = Base64.getEncoder().encodeToString(pcmAudio);
connection.send(
RealtimeTranslationClientEvent.ofSessionInputAudioBufferAppend(
RealtimeTranslationInputAudioBufferAppendEvent.builder().audio(base64Pcm16).build()));
}
1
2
3
4
5
6
7
8# speech.pcm contains nonempty mono PCM16 audio sampled at 24 kHz.
raise "Expected nonempty PCM16 audio" unless File.size("speech.pcm").positive? && File.size("speech.pcm").even?
File.open("speech.pcm", "rb") do |input|
while (chunk = input.read(4800))
session.send_event(type: "session.input_audio_buffer.append", audio: Base64.strict_encode64(chunk))
end
end
监听译音和转写文本。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "session.output_audio.delta") {
playPcm16(event.delta);
}
if (event.type === "session.output_transcript.delta") {
process.stdout.write(event.delta);
}
if (event.type === "session.input_transcript.delta") {
updateSourceTranscript(event.delta);
}
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50import base64
import json
from concurrent.futures import ThreadPoolExecutor
from contextlib import suppress
from queue import SimpleQueue
import sounddevice as sd
audio_queue = SimpleQueue()
def play_audio():
try:
# Closing the stream waits for PortAudio's pending buffers to finish.
with sd.RawOutputStream(samplerate=24000, channels=1, dtype="int16") as stream:
while (pcm := audio_queue.get()) is not None:
stream.write(pcm)
except Exception:
# The receiver may have already closed the socket.
with suppress(OSError):
ws.abort() # Wake recv() so the receiver can report the playback failure.
raise
with ThreadPoolExecutor(max_workers=1) as executor:
playback = executor.submit(play_audio)
try:
while True:
event = json.loads(ws.recv())
if playback.done():
playback.result() # Report a playback failure on the receiver.
if event["type"] == "session.output_audio.delta":
audio_queue.put(base64.b64decode(event["delta"]))
if event["type"] in (
"session.output_transcript.delta",
"session.input_transcript.delta",
):
print(event["delta"], end="", flush=True)
if event["type"] == "error":
raise RuntimeError(f"Translation error: {event['error']['code']}")
if event["type"] == "session.closed":
break
finally:
ws.close()
audio_queue.put(None)
playback.result()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24// Run this listener while another goroutine sends audio into the session.
func listen(ctx context.Context, session *realtime.TranslationSession) error {
for {
event, err := session.Recv(ctx)
if err != nil {
return err
}
switch event.Type {
case "error":
return fmt.Errorf("translation error: %s", event.OfRealtimeErrorEvent.Error.Message)
case "session.output_transcript.delta":
fmt.Print(event.OfRealtimeTranslationOutputTranscriptDeltaEvent.Delta)
case "session.output_audio.delta":
pcm, err := base64.StdEncoding.DecodeString(event.OfRealtimeTranslationOutputAudioDeltaEvent.Delta)
if err != nil {
return err
}
// Feed pcm into your application's 24 kHz audio player.
fmt.Fprintln(log.Writer(), "Received audio bytes:", len(pcm))
case "session.closed":
return session.Close()
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13handle_translation_event = lambda do |event, output|
case event
when OpenAI::Realtime::RealtimeErrorEvent
raise "Translation error: #{event.error.message}"
when OpenAI::Realtime::RealtimeTranslationOutputTranscriptDeltaEvent
print event.delta
$stdout.flush
when OpenAI::Realtime::RealtimeTranslationOutputAudioDeltaEvent
pcm = Base64.strict_decode64(event.delta)
output.write(pcm)
warn "Received audio bytes: #{pcm.bytesize}"
end
end
如果使用 Go,请在发送音频的同时并发运行 listen。它会在收到 session.closed 后关闭传输连接。
源音频流结束时,请先发送 session.close 事件,再关闭 WebSocket。此事件会指示服务处理完剩余的输入音频,输出剩余的译音和转写文本,然后发送 session.closed 事件。只有翻译会话支持 session.close 事件。
发送 session.close 后,请停止追加音频,并在常规接收循环中继续读取事件,直到收到 session.closed。如果立即关闭套接字,可能会丢失会话尚未发送完的翻译结果。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59let translationSessionClosing = false;
let gotTranslationClosed = false;
let drainDeadline: ReturnType<typeof setTimeout> | undefined;
ws.on("close", () => {
clearTimeout(drainDeadline);
if (!gotTranslationClosed) {
console.error("Translation disconnected before final session.closed");
process.exitCode = 1;
}
});
function closeTranslationSession() {
if (translationSessionClosing) {
return;
}
translationSessionClosing = true;
// Adjust this deadline for your application's finalization requirements.
drainDeadline = setTimeout(() => {
console.error("Translation finalization timed out");
process.exitCode = 1;
ws.close();
}, 15_000);
ws.send(JSON.stringify({ type: "session.close" }));
}
// Use this in place of the earlier output handler, so audio plays only once.
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "session.output_audio.delta") {
playPcm16(event.delta);
}
if (event.type === "session.output_transcript.delta") {
process.stdout.write(event.delta);
}
if (event.type === "session.input_transcript.delta") {
updateSourceTranscript(event.delta);
}
if (event.type === "error") {
clearTimeout(drainDeadline);
console.error("Translation error", event.error?.code);
process.exitCode = 1;
ws.close();
}
if (event.type === "session.closed") {
clearTimeout(drainDeadline);
gotTranslationClosed = true;
ws.close();
}
});
// Call this when the source stream ends.
closeTranslationSession();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76import base64
import json
import time
from concurrent.futures import ThreadPoolExecutor
from contextlib import suppress
from queue import SimpleQueue
import sounddevice as sd
audio_queue = SimpleQueue()
def play_audio():
try:
# Closing the stream waits for PortAudio's pending buffers to finish.
with sd.RawOutputStream(samplerate=24000, channels=1, dtype="int16") as stream:
while (pcm := audio_queue.get()) is not None:
stream.write(pcm)
except Exception:
# The receiver may have already closed the socket.
with suppress(OSError):
ws.abort() # Wake recv() so the receiver can report the playback failure.
raise
translation_session_closing = False
def close_translation_session():
global translation_session_closing
if translation_session_closing:
return
translation_session_closing = True
ws.send(json.dumps({"type": "session.close"}))
with ThreadPoolExecutor(max_workers=1) as executor:
playback = executor.submit(play_audio)
try:
# Call this when the source stream ends.
close_translation_session()
# Adjust this deadline for your application's finalization requirements.
drain_deadline = time.monotonic() + 15.0
while True:
remaining = drain_deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError("Translation finalization timed out")
ws.settimeout(remaining)
data = ws.recv()
if not data:
raise RuntimeError("Translation disconnected before session.closed")
event = json.loads(data)
if playback.done():
playback.result() # Report a playback failure on the receiver.
if event["type"] == "error":
raise RuntimeError(f"Translation error: {event['error']['code']}")
if event["type"] == "session.output_audio.delta":
audio_queue.put(base64.b64decode(event["delta"]))
if event["type"] in (
"session.output_transcript.delta",
"session.input_transcript.delta",
):
print(event["delta"], end="", flush=True)
if event["type"] == "session.closed":
break
finally:
# The server deadline covers receiving events, not local playback.
ws.close()
audio_queue.put(None)
playback.result()
1
2
3
4
5
6// Stop sending audio first. The listener closes the transport after session.closed.
if err := session.Send(ctx, realtime.RealtimeTranslationClientEventUnionParam{
OfSessionClose: &realtime.RealtimeTranslationSessionCloseEventParam{},
}); err != nil {
return err
}
1
2
3
4
5
6
7# Finish the existing session and consume its trailing output through session.closed.
File.open("translated.pcm", "wb") do |output|
session.finish(timeout: 15) do |event|
handle_translation_event.call(event, output)
end
end
# translated.pcm is ready for your application's 24 kHz PCM16 audio player.
如果需要为听众提供来自一位说话者或一路音频流的译音,可以采用这种方式。适用场景包括直播、会议演讲、网络研讨会、财报电话会议、讲座和视频。
典型架构如下图所示。
源音频 -> 翻译会话 -> 译音 + 字幕
为每种目标语言创建一个翻译会话。如果同一路英语音频需要同时翻译成西班牙语和法语,请分别创建英语到西班牙语、英语到法语的翻译会话。
如果应用在浏览器中为听众提供翻译,请使用 getDisplayMedia() 采集标签页音频,通过 WebRTC 发送音频,然后播放远端译音轨道。对于生产环境中的广播,请在服务器端媒体处理进程中运行翻译,并向听众发布译音轨道或字幕。
当两名或更多参与者使用不同语言交流时,可以使用对话翻译。适用场景包括客服通话、销售通话、辅导课和视频聊天室。
请为每位参与者保留独立音轨。将多人语音混合到一路音频流中,会增加识别说话者、为每位说话者显示字幕以及处理多人同时讲话的难度。
对于双人通话,请按下图为每个翻译方向各创建一个翻译会话。
通话者 A 的音频 -> 翻译成通话者 B 使用的语言 -> 播放给通话者 B
通话者 B 的音频 -> 翻译成通话者 A 使用的语言 -> 播放给通话者 A
对于多人聊天室,可根据正在发言的说话者音轨数和不同目标语言的数量估算会话数。
翻译会话数 ~= 正在发言的说话者的源音轨数 x 不同目标语言的数量
在小型聊天室中,每位听众可以在浏览器端为需要翻译的远端说话者分别创建辅助翻译组件。在较大的聊天室中,请使用服务器端的参会客户端或媒体处理进程,订阅每位说话者的源音轨一次,为每种目标语言各创建一个翻译会话,再重新发布译音轨道。
请使用真实音频测试翻译,并请熟悉两种语言的人员审查结果。自动化指标可以辅助评估,但无法发现用户会注意到的所有错误。
测试时请检查以下项目。
- 各语言对的翻译质量
- 姓名、数字、日期、货币和电话号码的翻译
- 专业术语的翻译
- 对话中切换或混用语言的情况
- 带口音、语速快或多人同时说话的情况
- 首段译音的输出延迟
- 一段话说完后的延迟
- 字幕显示时机
- 声音的一致性
- 重新连接时的行为
如果您的应用场景要求准确翻译名称或专业术语,请在上线前建立一套带有标准答案的测试样例,并人工审查未通过的样例。
- 浏览器端媒体传输使用 WebRTC,服务器端媒体传输使用 WebSocket。
- 使用专用的
/v1/realtime/translations 端点。
- 持续传输音频,包括讲话间的静音片段。
- 发送
session.close 并等待收到 session.closed 后,再关闭 WebSocket 会话。
- 对话翻译中,为每位说话者保留独立音轨。
- 为每种输出语言创建一个会话。
- 根据需要同时显示源语言和目标语言的转写文本。
- 提供原声、译音、字幕、静音和音量控件。
- 显示正在重新连接、出现延迟和服务不可用等状态。
- 分别跟踪延迟和翻译质量。