リアルタイムの会話

WebRTC または WebSocket 経由で Realtime API に接続すると、Realtime モデル（gpt-realtime-2.1 など）を呼び出して、音声変換による会話を行えます。そのためには、 クライアントイベントを送信 してアクションを開始し、 サーバーイベントをリッスン して Realtime API が実行したアクションに対応する必要があります。

このガイドでは、音声やテキストの生成、画像入力、Function Calling などのモデルの機能を使うために必要なイベントの流れと、リアルタイムセッションの状態の捉え方を説明します。

リアルタイムの音声変換セッション

リアルタイムセッションは、モデルと接続中のクライアントが状態を保持しながらやり取りする仕組みです。セッションの主な構成要素は次のとおりです。

• 使用するモデルや出力の生成に使う音声など、やり取りのパラメーターを制御する Session オブジェクト
• 現在のセッションで生成されたユーザー入力アイテムとモデル出力アイテムを表す Conversation
• モデルが生成し、Conversation に追加される音声またはテキストのアイテムである Responses

これらすべての構成要素が、リアルタイムセッションを構成します。クライアントイベントでセッションの状態を更新し、サーバーイベントを監視してセッション内の状態変化に対応します。

セッションのライフサイクルイベント

WebRTC または WebSockets 経由でセッションを開始すると、サーバーはセッションの準備ができたことを示す session.created イベントを送信します。クライアントでは、session.update イベントで現在のセッション構成を更新できます。ほとんどのセッションプロパティはいつでも更新できます。ただし、モデルが音声出力に使用する voice は、セッション中にモデルが一度でも音声で応答すると変更できなくなります。リアルタイムセッションの最大継続時間は 60 分です。

次の例では、session.update クライアントイベントでセッションを更新します。これらのチャネルでクライアントイベントを送信する方法については、WebRTC または WebSocket のガイドを参照してください。

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
40const event = {
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1",
    // Lock the output to audio (set to ["text"] if you want text without audio)
    output_modalities: ["audio"],
    audio: {
      input: {
        format: {
          type: "audio/pcm",
          rate: 24000,
        },
        turn_detection: {
          type: "semantic_vad",
        },
      },
      output: {
        format: {
          type: "audio/pcm",
        },
        voice: "marin",
      },
    },
    // Use a server-stored prompt by ID. Optionally pin a version and pass variables.
    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.",
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

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
35event = {
    "type": "session.update",
    "session": {
        "type": "realtime",
        "model": "gpt-realtime-2.1",
        # Lock the output to audio (add "text" if you also want text).
        "output_modalities": ["audio"],
        "audio": {
            "input": {
                "format": {
                    "type": "audio/pcm",
                    "rate": 24000,
                },
                "turn_detection": {"type": "semantic_vad"},
            },
            "output": {
                "format": {
                    "type": "audio/pcmu",
                },
                "voice": "marin",
            },
        },
        # Use a server-stored prompt by ID. Optionally pin a version and pass variables.
        "prompt": {
            "id": "pmpt_123",  # Your stored prompt ID.
            "version": "89",  # Optional: pin a specific version.
            "variables": {
                "city": "Paris",  # Example variable used by your prompt.
            },
        },
        # Direct session fields override prompt fields if they overlap.
        "instructions": "Speak clearly and briefly. Confirm understanding before taking actions.",
    },
}
ws.send(json.dumps(event))

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# Replace the illustrative IDs and URLs below with your own resource values.
connection.session.update(
  type: :realtime,
  model: "gpt-realtime-2.1",
  output_modalities: [:audio],
  audio: {
    input: {
      format: {
        type: :"audio/pcm",
        rate: 24_000
      },
      turn_detection: { type: :semantic_vad }
    },
    output: {
      format: {
        type: :"audio/pcm",
        rate: 24_000
      },
      voice: :marin
    }
  },
  prompt: {
    id: "pmpt_123",
    version: "89",
    variables: { city: "Paris" }
  },
  instructions: "Speak clearly and briefly. Confirm before taking action."
)

セッションが更新されると、サーバーはセッションの新しい状態を含む session.updated イベントを発行します。

テキストの入出力

Realtime モデルでテキストを生成するには、現在の会話にテキスト入力を追加し、モデルに応答の生成をリクエストして、その進行状況を示すサーバーイベントを監視します。テキストを生成するには、text モダリティを使用するようにセッションを設定する必要があります（デフォルトで設定されています）。

conversation.item.create クライアントイベントを使って、新しいテキストの会話アイテムを作成します。これは、REST API の Chat Completions でユーザーメッセージ（プロンプト）を送信する操作に相当します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_text",
        text: "What Prince album sold the most copies?",
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2
3
4
5
6
7
8
9
10
11
12
13
14event = {
    "type": "conversation.item.create",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "What Prince album sold the most copies?",
            }
        ],
    },
}
ws.send(json.dumps(event))

1
2
3
4
5
6
7
8
9
10connection.conversation.items.create(
  type: :message,
  role: :user,
  content: [
    {
      type: :input_text,
      text: "What is the weather like today?"
    }
  ]
)

会話にユーザーメッセージを追加したら、response.create イベントを送信してモデルの応答を開始します。現在のセッションで音声とテキストの両方が有効になっている場合、モデルは音声とテキストの両方で応答します。テキストのみを生成する場合は、次のように response.create クライアントイベントの送信時に指定できます。

1
2
3
4
5
6
7
8
9const event = {
  type: "response.create",
  response: {
    output_modalities: ["text"],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2event = {"type": "response.create", "response": {"output_modalities": ["text"]}}
ws.send(json.dumps(event))

1
2
3
4connection.response.create(
  output_modalities: [:text],
  instructions: "Respond with a concise text message."
)

応答が完全に終了すると、サーバーは response.done イベントを発行します。次に示すように、このイベントにはモデルが生成したテキストの全文が含まれます。

1
2
3
4
5
6
7
8
9
10
11
12
13function handleEvent(message) {
  const data = "data" in message ? message.data : message.toString();
  const serverEvent = JSON.parse(data);
  if (serverEvent.type === "response.done") {
    console.log(serverEvent.response.output[0]);
  }
}

// Listen for server messages (WebRTC)
dataChannel.addEventListener("message", handleEvent);

// Listen for server messages (WebSocket)
// ws.on("message", handleEvent);

1
2
3
4def on_message(ws, message):
    server_event = json.loads(message)
    if server_event["type"] == "response.done":
        print(server_event["response"]["output"][0])

1
2
3
4
5
6
7
8
9
10
11
12
13connection.each do |event|
  next unless event.is_a?(OpenAI::Realtime::ResponseDoneEvent)

  puts("Response status: #{event.response.status}")
  Array(event.response.output).each do |item|
    next unless item.is_a?(OpenAI::Realtime::RealtimeConversationItemAssistantMessage)

    item.content.each do |content|
      puts(content.text) if content.type == :output_text
    end
  end
  break
end

モデルの応答が生成される間、サーバーは複数のライフサイクルイベントを発行します。response.output_text.delta などのイベントを監視すると、応答の生成中にユーザーへリアルタイムでフィードバックを提供できます。サーバーが発行するイベントの全一覧は、以下の 関連するサーバーイベントに記載しています。おおよその発行順に、テキスト生成に関連するクライアント側のイベントとともに示しています。

音声の入出力

Realtime API の特に強力な機能のひとつが、テキストから音声、または音声からテキストへの変換を途中に挟まず、音声でモデルとやり取りできることです。これにより、音声インターフェースのレイテンシを低減でき、入力音声の声の調子や抑揚についても、モデルがより多くの情報を活用できます。

音声の選択肢

リアルタイムセッションでは、音声出力に使う声を、複数の組み込み音声から選んで設定できます。セッションの作成時（または response.create の実行時）に voice を設定すると、モデルの声を指定できます。現在選択できる音声は、alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar です。セッション内でモデルが一度でも音声を出力すると、そのセッションの voice は変更できません。最良の品質を得るには、marin または cedar をおすすめします。

WebRTC での音声処理

WebRTC を使って Realtime API に接続する場合、Realtime API はクライアントとのピア接続として動作します。モデルの音声出力は、リモートメディアストリームとしてクライアントに配信されます。モデルへの音声入力は、音声デバイスから収集され（getUserMedia）、メディアストリームはトラックとしてピア接続に追加されます。

WebRTC 接続ガイドのサンプルコードでは、ブラウザ API を使ってローカルとリモートの両方の音声を構成する基本的な例を示しています。

1
2
3
4
5
6
7
8
9
10
11
12
13// Create a peer connection
const pc = new RTCPeerConnection();

// Set up to play remote audio from the model
const audioEl = document.createElement("audio");
audioEl.autoplay = true;
pc.ontrack = (e) => (audioEl.srcObject = e.streams[0]);

// Add local audio track for microphone input in the browser
const ms = await navigator.mediaDevices.getUserMedia({
  audio: true,
});
pc.addTrack(ms.getTracks()[0]);

上記のスニペットで Realtime API とやり取りできますが、ほかにもさまざまなことが可能です。多様なユーザーインターフェースの例については、WebRTC サンプルリポジトリを参照してください。これらのサンプルの動作デモもこちらで試せます。

ブラウザでメディアキャプチャとストリームを使用すると、マイクのミュートやミュート解除、入力元デバイスの選択などができます。

WebRTC の音声に関するクライアントイベントとサーバーイベント

デフォルトでは、WebRTC クライアントは音声入力を送信する前に、Realtime API にクライアントイベントを送信する必要はありません。ローカルの音声トラックをピア接続に追加すれば、ユーザーはすぐに話し始められます。

ただし、ピア接続を通じてクライアントとサーバーの間で音声をやり取りしている間も、WebRTC クライアントはサーバーから複数のライフサイクルイベントを受信します。たとえば、次のようなイベントがあります。

• ローカルのメディアトラックで入力が送信されると、サーバーから input_audio_buffer.speech_started イベントを受信します。
• ローカルの音声入力が停止すると、input_audio_buffer.speech_stopped イベントを受信します。
• 生成中の音声の文字起こしの差分イベントを受信します。
• モデルが文字起こしを行い、応答の送信を完了すると、response.done イベントを受信します。

メディアストリーム用の WebRTC API を操作するだけで、必要な制御をすべて実現できる場合があります。ただし、音声の入出力に、より低レベルのインターフェースが必要になることもあります。詳しい説明と、音声入力をきめ細かく処理するために必要なイベントの一覧は、以下の WebSockets のセクションを参照してください。

WebSockets での音声処理

WebSocket で音声を送受信する場合、クライアントからのメディア送信とサーバーからのメディア受信に、もう少し実装が必要になります。以下の表は、WebSocket で音声を送受信するために必要な、WebSocket セッション中のイベントの流れを示しています。

以下のイベントはライフサイクル順に並べていますが、一部のイベント（delta イベントなど）は同時に発生する場合があります。

サーバーへの音声入力のストリーミング

サーバーに音声入力をストリーミングするには、input_audio_buffer.append クライアントイベントを使用できます。このイベントでは、 Base64 でエンコードされた音声バイト列 をチャンクに分割し、ソケット経由で Realtime API に送信する必要があります。各チャンクのサイズは 15 MB 以下でなければなりません。

入力チャンクの形式は、セッション全体またはレスポンスごとに設定できます。

• セッション：session.update の session.input_audio_format
• レスポンス：response.create の response.input_audio_format

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
51import fs from "fs";
import decodeAudio from "audio-decode";

// Converts Float32Array of audio data to PCM16 ArrayBuffer
function floatTo16BitPCM(float32Array) {
  const buffer = new ArrayBuffer(float32Array.length * 2);
  const view = new DataView(buffer);
  let offset = 0;
  for (let i = 0; i < float32Array.length; i++, offset += 2) {
    let s = Math.max(-1, Math.min(1, float32Array[i]));
    view.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7fff, true);
  }
  return buffer;
}

// Converts a Float32Array to base64-encoded PCM16 data
function base64EncodeAudio(float32Array) {
  const arrayBuffer = floatTo16BitPCM(float32Array);
  let binary = "";
  let bytes = new Uint8Array(arrayBuffer);
  const chunkSize = 0x8000; // 32KB chunk size
  for (let i = 0; i < bytes.length; i += chunkSize) {
    let chunk = bytes.subarray(i, i + chunkSize);
    binary += String.fromCharCode(...chunk);
  }
  return btoa(binary);
}

// Fills the audio buffer with the contents of three files,
// then asks the model to generate a response.
const files = [
  "fixtures/sample1.wav",
  "fixtures/sample2.wav",
  "fixtures/sample3.wav",
];

for (const filename of files) {
  const audioFile = fs.readFileSync(filename);
  const audioBuffer = await decodeAudio(audioFile);
  const channelData = audioBuffer.channelData[0];
  const base64Chunk = base64EncodeAudio(channelData);
  ws.send(
    JSON.stringify({
      type: "input_audio_buffer.append",
      audio: base64Chunk,
    })
  );
}

ws.send(JSON.stringify({ type: "input_audio_buffer.commit" }));
ws.send(JSON.stringify({ type: "response.create" }));

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
31import base64
import json
import struct
import soundfile as sf
from websocket import create_connection

# ... create websocket-client named ws ...


def float_to_16bit_pcm(float32_array):
    clipped = [max(-1.0, min(1.0, x)) for x in float32_array]
    pcm16 = b"".join(struct.pack("<h", int(x * 32767)) for x in clipped)
    return pcm16


def base64_encode_audio(float32_array):
    pcm_bytes = float_to_16bit_pcm(float32_array)
    encoded = base64.b64encode(pcm_bytes).decode("ascii")
    return encoded


files = ["./path/to/sample1.wav", "./path/to/sample2.wav", "./path/to/sample3.wav"]

for filename in files:
    data, samplerate = sf.read(filename, dtype="float32")
    channel_data = data[:, 0] if data.ndim > 1 else data
    base64_chunk = base64_encode_audio(channel_data)

    # Send the client event
    event = {"type": "input_audio_buffer.append", "audio": base64_chunk}
    ws.send(json.dumps(event))

1
2
3
4
5File.open("speech.pcm", "rb") do |audio|
  while (chunk = audio.read(9_600))
    connection.input_audio_buffer.append_bytes(chunk)
  end
end

音声メッセージ全体の送信

録音した音声全体を含む会話メッセージを作成することもできます。conversation.item.create クライアントイベントを使用して、input_audio コンテンツを含むメッセージを作成します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18const fullAudio = "<a base64-encoded string of audio bytes>";

const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_audio",
        audio: fullAudio,
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17fullAudio = "<a base64-encoded string of audio bytes>"

event = {
    "type": "conversation.item.create",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_audio",
                "audio": fullAudio,
            }
        ],
    },
}

ws.send(json.dumps(event))

1
2
3
4
5
6
7
8
9
10
11
12audio = Base64.strict_encode64(File.binread("speech.pcm"))

connection.conversation.items.create(
  type: :message,
  role: :user,
  content: [
    {
      type: :input_audio,
      audio: audio
    }
  ]
)

WebSocket からの音声出力の処理

ウェブブラウザなどのクライアントで出力音声を再生する場合は、WebSocket よりも WebRTC の使用を推奨します。WebRTC は、不安定なネットワーク環境でもクライアントデバイスにメディアをより安定して送信できます。

一方、WebSocket を使用するサーバー間アプリケーションで音声出力を扱う場合は、モデルからの音声データを Base64 でエンコードしたチャンクを含む response.output_audio.delta イベントをリッスンする必要があります。これらのチャンクをバッファリングしてファイルに書き出すか、Twilio での通話などに即座にストリーミングする必要があります。

response.output_audio.done イベントと response.done イベントには、音声コンテンツの文字起こしのみが含まれ、音声データそのものは含まれない点に注意してください。実際のバイト列を取得するには、response.output_audio.delta イベントをリッスンする必要があります。

出力チャンクの形式は、セッション全体またはレスポンスごとに設定できます。

• セッション：session.update の session.audio.output.format
• レスポンス：response.create の response.audio.output.format

1
2
3
4
5
6
7
8
9
10function handleEvent(message) {
  const serverEvent = JSON.parse(message.toString());
  if (serverEvent.type === "response.output_audio.delta") {
    // Access Base64-encoded audio chunks
    // console.log(serverEvent.delta);
  }
}

// Listen for server messages (WebSocket)
ws.on("message", handleEvent);

1
2
3
4
5def on_message(ws, message):
    server_event = json.loads(message)
    if server_event["type"] == "response.output_audio.delta":
        # Access Base64-encoded audio chunks:
        print(server_event["delta"])

1
2
3
4
5
6
7
8
9connection.each do |event|
  case event
  when OpenAI::Realtime::ResponseAudioDeltaEvent
    audio_bytes = Base64.strict_decode64(event.delta)
    puts("Received #{audio_bytes.bytesize} audio bytes")
  when OpenAI::Realtime::ResponseDoneEvent
    break
  end
end

画像入力

gpt-realtime-2 と gpt-realtime は画像入力にも対応しています。ユーザーメッセージのコンテンツの一部として画像を添付すると、モデルは画像の内容を踏まえて応答できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18const base64Image = "<a base64-encoded string of image bytes>";

const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_image",
        image_url: `data:image/{format};base64,${base64Image}`,
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17encoded_image = Base64.strict_encode64(File.binread("image.png"))

connection.conversation.items.create(
  type: :message,
  role: :user,
  content: [
    {
      type: :input_image,
      image_url: "data:image/png;base64,#{encoded_image}"
    },
    {
      type: :input_text,
      text: "Describe this image."
    }
  ]
)
connection.response.create(output_modalities: [:text])

音声区間検出

リアルタイムセッションでは、デフォルトで 音声区間検出（VAD） が有効になっています。API はユーザーが話し始めたタイミングと話し終えたタイミングを判断し、自動的に応答します。

VAD の設定方法について詳しくは、音声区間検出ガイドをご覧ください。

VAD の無効化

session.update クライアントイベントで turn_detection を null に設定すると、VAD を無効にできます。これは、プッシュトゥトークのように、音声入力を細かく制御したいインターフェースで便利です。

VAD が無効の場合、音声レスポンスを生成するには、クライアントが追加のクライアントイベントを手動で送信する必要があります。

• input_audio_buffer.commit を手動で送信します。これにより、会話に新しいユーザー入力アイテムが作成されます。
• response.create を手動で送信し、モデルによる音声レスポンスの生成を開始します。
• 新しいユーザー入力を開始する前に、input_audio_buffer.clear を送信します。

VAD を維持したまま自動応答を無効化

VAD モードを有効にしたまま、レスポンスを生成するタイミングを手動で決めたい場合は、session.update クライアントイベントで turn_detection.interrupt_response と turn_detection.create_response を false に設定できます。これにより、VAD の動作はすべて維持されますが、新しいレスポンスは自動的に作成されなくなります。クライアントは response.create イベントでレスポンスの生成を手動で開始できます。

これは、モデレーション、入力検証、RAG パターンなど、入力を制御するために対話のレイテンシーが多少増えてもよい場合に便利です。

デフォルトの会話外でのレスポンスの作成

デフォルトでは、セッション中に生成されたすべてのレスポンスが、セッションの会話の状態（「デフォルトの会話」）に追加されます。ただし、セッションのデフォルトの会話のコンテキスト外でモデルのレスポンスを生成したり、複数のレスポンスを同時に生成したりしたい場合もあります。また、モデルがレスポンスを生成する際に考慮する会話アイテムを、たとえば直近の N ターンのみに限定するなど、より細かく制御したい場合もあります。

response.create クライアントイベントでレスポンスを作成する際に、response.conversation フィールドを文字列 none に設定すると、デフォルトの会話の状態に追加されない「アウトオブバンド」のレスポンスを生成できます。

アウトオブバンドのレスポンスを作成する際は、サーバーから送信されるイベントのうち、どれがそのレスポンスに対応するかを識別する方法も必要になるでしょう。モデルのレスポンスに metadata を指定すると、クライアントから送信したイベントに対して生成されているレスポンスを識別しやすくなります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23const prompt = `
Analyze the conversation so far. If it is related to support, output
"support". If it is related to sales, output "sales".
`;

const event = {
  type: "response.create",
  response: {
    // Setting to "none" indicates the response is out of band
    // and will not be added to the default conversation
    conversation: "none",

    // Set metadata to help identify responses sent back from the model
    metadata: { topic: "classification" },

    // Set any other available response fields
    output_modalities: ["text"],
    instructions: prompt,
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20prompt = """
Analyze the conversation so far. If it is related to support, output
"support". If it is related to sales, output "sales".
"""

event = {
    "type": "response.create",
    "response": {
        # Setting to "none" indicates the response is out of band,
        # and will not be added to the default conversation
        "conversation": "none",
        # Set metadata to help identify responses sent back from the model
        "metadata": {"topic": "classification"},
        # Set any other available response fields
        "output_modalities": ["text"],
        "instructions": prompt,
    },
}

ws.send(json.dumps(event))

1
2
3
4
5
6connection.response.create(
  conversation: :none,
  metadata: { topic: "classification" },
  output_modalities: [:text],
  instructions: "Classify the conversation as support or sales."
)

これで、response.done サーバーイベントをリッスンすると、アウトオブバンドのレスポンスの結果を識別できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17function handleEvent(message) {
  const data = "data" in message ? message.data : message.toString();
  const serverEvent = JSON.parse(data);
  if (
    serverEvent.type === "response.done" &&
    serverEvent.response.metadata?.topic === "classification"
  ) {
    // this server event pertained to our OOB model response
    console.log(serverEvent.response.output[0]);
  }
}

// Listen for server messages (WebRTC)
dataChannel.addEventListener("message", handleEvent);

// Listen for server messages (WebSocket)
// ws.on("message", handleEvent);

1
2
3
4
5
6
7
8
9
10
11
12
13def on_message(ws, message):
    server_event = json.loads(message)
    topic = ""

    # See if metadata is present
    try:
        topic = server_event["response"]["metadata"]["topic"]
    except KeyError:
        print("topic not set")

    if server_event["type"] == "response.done" and topic == "classification":
        # this server event pertained to our OOB model response
        print(server_event["response"]["output"][0])

1
2
3
4
5
6
7
8
9
10
11
12
13
14connection.each do |event|
  next unless event.is_a?(OpenAI::Realtime::ResponseDoneEvent)
  next unless event.response.metadata&.fetch(:topic, nil) == "classification"

  puts("Classification response completed: #{event.response.status}")
  Array(event.response.output).each do |item|
    next unless item.is_a?(OpenAI::Realtime::RealtimeConversationItemAssistantMessage)

    item.content.each do |content|
      puts("Classification: #{content.text}") if content.type == :output_text
    end
  end
  break
end

レスポンス用のカスタムコンテキストの作成

デフォルトの会話、つまり現在の会話とは別に、モデルがレスポンスの生成に使用するカスタムコンテキストを構築することもできます。これには、response.create クライアントイベントの input 配列を使用します。新しい入力を使用することも、会話内の既存の入力アイテムを ID で参照することもできます。

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
31const event = {
  type: "response.create",
  response: {
    conversation: "none",
    metadata: { topic: "pizza" },
    output_modalities: ["text"],

    // Create a custom input array for this request with whatever context
    // is appropriate
    input: [
      // potentially include existing conversation items:
      {
        type: "item_reference",
        id: "some_conversation_item_id",
      },
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Is it okay to put pineapple on pizza?",
          },
        ],
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

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
27event = {
    "type": "response.create",
    "response": {
        "conversation": "none",
        "metadata": {"topic": "pizza"},
        "output_modalities": ["text"],
        # Create a custom input array for this request with whatever
        # context is appropriate
        "input": [
            # potentially include existing conversation items:
            {"type": "item_reference", "id": "some_conversation_item_id"},
            # include new content as well
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Is it okay to put pineapple on pizza?",
                    }
                ],
            },
        ],
    },
}

ws.send(json.dumps(event))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21connection.response.create(
  conversation: :none,
  metadata: { topic: "classification" },
  output_modalities: [:text],
  input: [
    {
      type: :item_reference,
      id: existing_item_id
    },
    {
      type: :message,
      role: :user,
      content: [
        {
          type: :input_text,
          text: "Classify this issue: my order is late."
        }
      ]
    }
  ]
)

コンテキストなしでのレスポンスの作成

ほかのすべての指示やコンテキストを無視したレスポンスを、デフォルトの会話に挿入することもできます。そのためには、input を空の配列に設定します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17const prompt = `
Say exactly the following:
I'm a little teapot, short and stout!
This is my handle, this is my spout!
`;

const event = {
  type: "response.create",
  response: {
    // An empty input array removes existing context
    input: [],
    instructions: prompt,
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16prompt = """
Say exactly the following:
I'm a little teapot, short and stout!
This is my handle, this is my spout!
"""

event = {
    "type": "response.create",
    "response": {
        # An empty input array removes all prior context
        "input": [],
        "instructions": prompt,
    },
}

ws.send(json.dumps(event))

1
2
3
4
5connection.response.create(
  input: [],
  output_modalities: [:text],
  instructions: "Generate a concise greeting without conversation context."
)

Function Calling

Realtime モデルは Function Calling にも対応しており、独自のコードを実行してモデルの機能を拡張できます。大まかな仕組みは次のとおりです。

1. セッションを更新するときやレスポンスを作成するときに、モデルが呼び出せる関数の一覧を指定できます。
2. モデルは入力を処理する際に関数の呼び出しが必要だと判断すると、関数呼び出しの引数を表すアイテムを会話に追加します。
3. クライアントは関数呼び出しの引数を含む会話アイテムを検出すると、その引数を使って独自のコードを実行します。
4. 独自のコードの実行が完了すると、クライアントは関数呼び出しの出力を含む新しい会話アイテムを作成し、モデルに応答を求めます。

モデルのユーザーに今日の星占いを提供する呼び出し可能な関数を追加して、実際の動作を見てみましょう。送信する必要があるクライアントイベントオブジェクトの構造と、それに対してサーバーが送信するイベントを示します。

呼び出し可能な関数の設定

まず、ユーザーの入力に応じて呼び出せる関数をモデルに提示する必要があります。利用可能な関数は、セッション単位でも、個々のレスポンス単位でも設定できます。

• セッション：session.update の session.tools プロパティ
• レスポンス：response.create の response.tools プロパティ

次の例は、星占いを生成する関数を設定する session.update のクライアントイベントペイロードです。この関数は、星占いの対象となる星座を唯一の引数として受け取ります。

session.update

12345678910111213141516171819202122232425262728293031323334353637{
  "type": "session.update",
  "session": {
    "tools": [
      {
        "type": "function",
        "name": "generate_horoscope",
        "description": "Give today's horoscope for an astrological sign.",
        "parameters": {
          "type": "object",
          "properties": {
            "sign": {
              "type": "string",
              "description": "The sign for the horoscope.",
              "enum": [
                "Aries",
                "Taurus",
                "Gemini",
                "Cancer",
                "Leo",
                "Virgo",
                "Libra",
                "Scorpio",
                "Sagittarius",
                "Capricorn",
                "Aquarius",
                "Pisces"
              ]
            }
          },
          "required": ["sign"]
        }
      }
    ],
    "tool_choice": "auto"
  }
}

関数とパラメーターの description フィールドは、関数を呼び出すかどうか、各パラメーターにどのデータを含めるかをモデルが判断するのに役立ちます。ユーザーが自分の星占いを知りたがっているとわかる入力を受け取ると、モデルは sign パラメーターを指定してこの関数を呼び出します。

モデルによる関数呼び出し要求の検出

モデルは入力に基づいて、最適なレスポンスを生成するために関数を呼び出すと判断することがあります。アプリケーションが conversation.item.create イベントで次の会話アイテムを追加し、その後レスポンスを作成する場合を考えてみましょう。

12345678910111213{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "What is my horoscope? I am an aquarius."
      }
    ]
  }
}

続いて、response.create クライアントイベントでレスポンスを生成します。

123{
  "type": "response.create"
}

モデルはテキストや音声のレスポンスをすぐに返す代わりに、開発者のアプリケーション内の関数に渡す引数を含むレスポンスを生成します。response.function_call_arguments.delta サーバーイベントをリッスンすると、関数呼び出しの引数の更新をリアルタイムで受け取れますが、response.done にも関数の呼び出しに必要なすべてのデータが含まれます。

response.done

12345678910111213141516171819202122{
    "type": "response.done",
    "event_id": "event_AeqLA8iR6FK20L4XZs2P6",
    "response": {
        "object": "realtime.response",
        "id": "resp_AeqL8XwMUOri9OhcQJIu9",
        "status": "completed",
        "status_details": null,
        "output": [
            {
                "object": "realtime.item",
                "id": "item_AeqL8gmRWDn9bIsUM2T35",
                "type": "function_call",
                "status": "completed",
                "name": "generate_horoscope",
                "call_id": "call_sHlR7iaFwQ2YQOqm",
                "arguments": "{\"sign\":\"Aquarius\"}"
            }
        ],
        ...
    }
}

サーバーから送信される JSON から、モデルが独自の関数を呼び出そうとしていることを検出できます。

この情報を使ってアプリケーション内でコードを実行し、星占いを生成できます。その結果をモデルに返すことで、モデルがレスポンスを生成できるようになります。

関数呼び出しの結果をモデルに提供

関数呼び出しの引数を含むレスポンスをモデルから受け取ると、アプリケーションはその関数呼び出しに応じたコードを実行できます。外部 API との通信やデータベースへのアクセスなど、必要な処理を自由に実装できます。

独自のコードの実行結果をモデルに渡す準備ができたら、conversation.item.create クライアントイベントで、その結果を含む新しい会話アイテムを作成できます。

12345678{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_sHlR7iaFwQ2YQOqm",
    "output": "{\"horoscope\": \"You will soon meet a new friend.\"}"
  }
}

• 会話アイテムの型は function_call_output
• item.call_id は、上記の response.done イベントで受け取ったものと同じ ID
• item.output は、関数呼び出しの結果を含む JSON 文字列

関数呼び出しの結果を含む会話アイテムを追加したら、クライアントから再び response.create イベントを送信します。これにより、モデルは関数呼び出しから得たデータを使ってレスポンスを生成します。

123{
  "type": "response.create"
}

エラー処理

セッション中にサーバーでエラーが発生するたびに、サーバーは error イベントを送信します。これらのエラーは、アプリケーションが送信したクライアントイベントに起因する場合があります。

HTTP ではレスポンスがクライアントからのリクエストに暗黙的に対応付けられますが、ここでは、どのクライアントイベントがサーバーでエラーを引き起こしたかを特定するために、クライアントイベントの event_id プロパティを使う必要があります。以下のコードは、クライアントが未対応のイベントタイプを送信しようとする例で、この方法を示しています。

1
2
3
4
5
6const event = {
  event_id: "my_awesome_event",
  type: "scooby.dooby.doo",
};

dataChannel.send(JSON.stringify(event));

クライアントが送信したこのイベントは失敗し、次のようなエラーイベントが送信されます。

1234567{
  "type": "invalid_request_error",
  "code": "invalid_value",
  "message": "Invalid value: 'scooby.dooby.doo' ...",
  "param": "type",
  "event_id": "my_awesome_event"
}

割り込みと切り詰め

多くの音声アプリケーションでは、モデルが話している途中でユーザーが割り込めます。VAD が有効な場合、Realtime API はユーザーの発話を検出し、進行中のレスポンスをキャンセルして新しいレスポンスを開始することで、割り込みに対応します。ただし、自然に会話を続けられるようにするには、どこで割り込まれたかをモデルが把握できるようにする必要があります。たとえば、ユーザーが「最後に何と言いましたか？」と尋ねた場合に、この情報が必要です。モデルの最後のレスポンスから未再生の部分を会話内から削除することを、レスポンスの 切り詰め と呼びます。

WebRTC と SIP の接続では、サーバーが出力音声のバッファを管理するため、その時点で音声がどこまで再生されたかを把握しています。ユーザーが割り込むと、サーバーは未再生の音声を自動的に切り詰めます。

WebSocket 接続ではクライアントが音声再生を管理するため、クライアント側で再生を停止し、切り詰めを処理する必要があります。手順は次のとおりです。

1. クライアントは、ユーザーが話し始めたことを示す新しい input_audio_buffer.speech_started イベントがサーバーから届くのを監視します。サーバーは進行中のモデルのレスポンスを自動的にキャンセルし、response.cancelled イベントを送信します。
2. クライアントはこのイベントを検出したら、再生中のモデルの音声を直ちに停止する必要があります。また、割り込まれる前に最後の音声レスポンスがどこまで再生されたかを記録します。
3. クライアントは conversation.item.truncate イベントを送信し、モデルの最後のレスポンスのうち未再生の部分を会話から削除する必要があります。

以下に例を示します。

123456{
    "type": "conversation.item.truncate",
    "item_id": "item_1234", # this is the item ID of the model's last response
    "content_index": 0,
    "audio_end_ms": 1500 # truncate audio after 1.5 seconds
}

文字起こしも同様に切り詰められるでしょうか。Realtime モデルには、文字起こしと音声を正確に対応付けるための十分な情報がありません。そのため、conversation.item.truncate は指定された位置で音声を切り、未再生部分の文字起こしテキストを削除します。これにより未再生の音声を削除するという問題は解決しますが、切り詰めた文字起こしは提供されません。

プッシュツートーク

Realtime API はデフォルトで音声区間検出（VAD）を使用し、音声入力をきっかけにモデルのレスポンスを生成します。VAD を無効にし、モデルに音声入力を送るタイミングをアプリケーション側で制御すれば、プッシュツートーク方式で対話することもできます。たとえば、スペースバーを押している間は音声を収録し、離すとレスポンスの生成を開始します。アプリによっては、この方法が驚くほど効果的です。ユーザーが対話のタイミングを制御でき、VAD の検出ミスを避けられるうえ、VAD のタイムアウトを待たずに済むため、きびきびとした操作感になります。

プッシュツートークの実装は、WebSocket と WebRTC で少し異なります。Realtime API の WebSocket 接続では、すべてのイベントが同じチャネルで順序を保って送信されます。一方、WebRTC 接続では、音声と制御イベントに別々のチャネルを使用します。

WebSockets

WebSocket 接続でプッシュツートークを実装するには、クライアント側で音声再生の停止、割り込みの処理、新しいレスポンスの開始を行います。詳しい手順は次のとおりです。

1. session.update イベントで "turn_detection": null を設定し、VAD を無効にします。
2. ボタンを押したら、クライアントで音声の録音を開始します。
   1. モデルのレスポンスが進行中の場合は、response.cancel イベントを送信してキャンセルします。
   2. モデルの出力音声を再生中の場合は、直ちに再生を停止し、conversation.item.truncate イベントを送信して未再生の音声を会話から削除します。
3. ボタンを離したら、音声を含む input_audio_buffer.append メッセージを送信して、新しい音声を入力バッファに追加します。
4. input_audio_buffer.commit イベントを送信します。これにより、入力バッファに書き込まれた音声がコミットされ、入力の文字起こしが有効な場合は開始されます。
5. 続いて、response.create イベントでレスポンスの生成を開始します。

WebRTC と SIP

WebRTC でのプッシュトゥトークの実装も同様ですが、入力音声バッファを明示的にクリアする必要があります。手順は次のとおりです。

1. session.update イベントで "turn_detection": null を設定し、VAD を無効にします。
2. ボタンを押したら、input_audio_buffer.clear イベントを送信して、以前の音声入力をクリアします。
   1. モデルのレスポンスが進行中の場合は、response.cancel イベントを送信してキャンセルします。
   2. モデルの出力音声を再生中の場合は、output_audio_buffer.clear イベントを送信して未再生の音声をクリアします。これにより、会話も切り詰められます。
3. ボタンを離したら、input_audio_buffer.commit イベントを送信します。これにより、入力バッファに書き込まれた音声がコミットされ、入力音声の文字起こしが有効になっている場合は文字起こしが開始されます。
4. 続いて、response.create イベントで応答の生成を開始します。