Conversas em tempo real

Depois de se conectar à Realtime API por WebRTC ou WebSocket, você pode chamar um modelo Realtime (como gpt-realtime-2.1) para ter conversas de fala para fala. Para isso, você precisará enviar eventos de cliente para iniciar ações e escutar eventos de servidor para responder às ações da Realtime API.

Este guia apresenta os fluxos de eventos necessários para usar capacidades do modelo, como geração de áudio e texto, entrada de imagens e chamada de função, além de explicar como entender o estado de uma sessão em tempo real.

Sessões de fala para fala em tempo real

Uma sessão em tempo real é uma interação que mantém estado entre o modelo e um cliente conectado. Os principais componentes da sessão são:

• O objeto Sessão , que controla os parâmetros da interação, como o modelo em uso, a voz usada para gerar a saída e outras configurações.
• Uma Conversa, que representa os itens de entrada do usuário e os itens de saída do modelo gerados durante a sessão atual.
• Respostas, que são itens de áudio ou texto gerados pelo modelo e adicionados à Conversa.

Todos esses componentes juntos formam uma sessão em tempo real. Você usará eventos do cliente para atualizar o estado da sessão e escutará eventos do servidor para reagir às mudanças de estado dentro dela.

Eventos do ciclo de vida da sessão

Após iniciar uma sessão por WebRTC ou WebSockets, o servidor enviará um evento session.created indicando que a sessão está pronta. No cliente, você pode atualizar a configuração da sessão atual com o evento session.update. A maioria das propriedades da sessão pode ser atualizada a qualquer momento. A exceção é a propriedade voice, que define a voz usada pelo modelo na saída de áudio: ela não pode ser alterada depois que o modelo responder com áudio pela primeira vez na sessão. A duração máxima de uma sessão em tempo real é de 60 minutos.

O exemplo a seguir mostra como atualizar a sessão com um evento de cliente session.update. Consulte o guia de WebRTC ou de WebSocket para saber mais sobre o envio de eventos de cliente por esses canais.

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."
)

Quando a sessão for atualizada, o servidor emitirá um evento session.updated com o novo estado da sessão.

Entradas e saídas de texto

Para gerar texto com um modelo Realtime, você pode adicionar entradas de texto à conversa atual, pedir ao modelo que gere uma resposta e escutar os eventos enviados pelo servidor que indicam o progresso da resposta. Para gerar texto, a sessão deve estar configurada com a modalidade text (essa é a configuração padrão).

Crie um novo item de texto na conversa usando o evento do cliente conversation.item.create. Isso é semelhante a enviar uma mensagem do usuário (prompt) em Chat Completions na API REST.

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?"
    }
  ]
)

Depois de adicionar a mensagem do usuário à conversa, envie o evento response.create para iniciar uma resposta do modelo. Se áudio e texto estiverem habilitados na sessão atual, o modelo responderá com conteúdo em áudio e texto. Se quiser gerar apenas texto, você pode especificar isso ao enviar o evento do cliente response.create, como mostrado abaixo.

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."
)

Quando a resposta estiver totalmente concluída, o servidor emitirá o evento response.done. Esse evento conterá o texto completo gerado pelo modelo, como mostrado abaixo.

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

Enquanto a resposta do modelo estiver sendo gerada, o servidor emitirá vários eventos do ciclo de vida. Você pode escutar esses eventos, como response.output_text.delta, para fornecer feedback em tempo real aos usuários durante a geração da resposta. A lista completa dos eventos emitidos pelo servidor está abaixo, em eventos relacionados do servidor. Eles são apresentados na ordem aproximada em que são emitidos, junto com os eventos do cliente relevantes para a geração de texto.

Entradas e saídas de áudio

Um dos recursos mais poderosos da Realtime API é a interação de voz para voz com o modelo, sem uma etapa intermediária de conversão de texto em fala ou de fala em texto. Isso permite reduzir a latência das interfaces de voz e fornece ao modelo mais dados sobre o tom e a entonação da entrada de voz.

Opções de voz

As sessões em tempo real podem ser configuradas para usar uma das várias vozes integradas ao produzir saída de áudio. Você pode definir voice na criação da sessão (ou em um evento response.create) para controlar a voz do modelo. As opções de voz atuais são alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin e cedar. Depois que o modelo emitir áudio em uma sessão, voice não poderá ser alterado nessa sessão. Para obter a melhor qualidade, recomendamos usar marin ou cedar.

Como lidar com áudio usando WebRTC

Se você se conecta à Realtime API usando WebRTC, a Realtime API atua como um par em uma conexão ponto a ponto com seu cliente. A saída de áudio do modelo é entregue ao cliente como um fluxo de mídia remoto. A entrada de áudio do modelo é capturada por dispositivos de áudio (getUserMedia), e os fluxos de mídia são adicionados como faixas à conexão ponto a ponto.

O código de exemplo do guia de conexão por WebRTC mostra uma configuração básica de áudio local e remoto usando APIs do navegador:

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]);

O trecho de código acima permite interagir com a Realtime API, mas há muito mais que você pode fazer. Para ver mais exemplos de diferentes tipos de interfaces de usuário, confira o repositório de exemplos de WebRTC. Você também pode encontrar aqui demonstrações desses exemplos em funcionamento.

Usar capturas e fluxos de mídia no navegador permite, por exemplo, silenciar e reativar microfones, selecionar o dispositivo de entrada e muito mais.

Eventos do cliente e do servidor para áudio em WebRTC

Por padrão, os clientes WebRTC não precisam enviar nenhum evento do cliente à Realtime API antes de enviar entradas de áudio. Assim que uma faixa de áudio local é adicionada à conexão ponto a ponto, seus usuários já podem começar a falar!

No entanto, os clientes WebRTC ainda recebem vários eventos do ciclo de vida enviados pelo servidor enquanto o áudio trafega entre cliente e servidor pela conexão ponto a ponto. Alguns exemplos:

• Quando a entrada é enviada pela faixa de mídia local, você recebe eventos input_audio_buffer.speech_started do servidor.
• Quando a entrada de áudio local para, você recebe o evento input_audio_buffer.speech_stopped.
• Você recebe eventos delta da transcrição de áudio em andamento.
• Você recebe um evento response.done quando o modelo tiver transcrito e concluído o envio de uma resposta.

Usar as APIs de WebRTC para manipular fluxos de mídia pode oferecer todo o controle de que você precisa. No entanto, às vezes pode ser necessário usar interfaces de nível mais baixo para entrada e saída de áudio. Consulte a seção sobre WebSockets abaixo para obter mais informações e uma lista dos eventos necessários para controlar a entrada de áudio com mais precisão.

Como lidar com áudio usando WebSockets

Ao enviar e receber áudio por um WebSocket, você terá um pouco mais de trabalho para enviar mídia do cliente e receber mídia do servidor. A tabela abaixo descreve o fluxo de eventos necessários durante uma sessão WebSocket para enviar e receber áudio pela conexão.

Os eventos abaixo são apresentados na ordem do ciclo de vida, embora alguns deles (como os eventos delta) possam ocorrer simultaneamente.

Transmissão de áudio de entrada para o servidor

Para transmitir áudio de entrada para o servidor, você pode usar o evento de cliente input_audio_buffer.append. Esse evento exige que você envie blocos de bytes de áudio codificados em Base64 para a Realtime API pelo socket. Cada bloco não pode exceder 15 MB.

O formato dos blocos de entrada pode ser configurado para toda a sessão ou por resposta.

• Sessão: session.input_audio_format em session.update
• Resposta: response.input_audio_format em 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
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

Envie mensagens de áudio completas

Também é possível criar mensagens na conversa que contenham gravações de áudio completas. Use o evento de cliente conversation.item.create para criar mensagens com conteúdo 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
    }
  ]
)

Como trabalhar com a saída de áudio de um WebSocket

Para reproduzir o áudio de saída em um dispositivo cliente, como um navegador Web, recomendamos usar WebRTC em vez de WebSockets. O WebRTC oferece mais robustez no envio de mídia a dispositivos clientes em condições de rede imprevisíveis.

Mas, para trabalhar com a saída de áudio em aplicações que se comunicam entre servidores usando um WebSocket, você precisará escutar os eventos response.output_audio.delta que contêm os blocos de dados de áudio do modelo codificados em Base64. Você precisará armazenar esses blocos em um buffer e gravá-los em um arquivo, ou talvez transmiti-los imediatamente para outro destino, como uma chamada telefônica com a Twilio.

Observe que os eventos response.output_audio.done e response.done não contêm dados de áudio, apenas transcrições do conteúdo do áudio. Para obter os bytes em si, você precisará escutar os eventos response.output_audio.delta.

O formato dos blocos de saída pode ser configurado para toda a sessão ou por resposta.

• Sessão: session.audio.output.format em session.update
• Resposta: response.audio.output.format em response.create

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

Entradas de imagem

gpt-realtime-2 e gpt-realtime também aceitam entradas de imagem. Você pode anexar uma imagem como parte do conteúdo de uma mensagem do usuário, e o modelo pode incorporar o conteúdo da imagem ao responder.

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])

Detecção de atividade de voz

Por padrão, as sessões em tempo real têm a detecção de atividade de voz (VAD) ativada. Isso significa que a API determinará quando o usuário começou ou parou de falar e responderá automaticamente.

Saiba mais sobre como configurar a VAD no nosso guia de detecção de atividade de voz.

Desative a VAD

A VAD pode ser desativada definindo turn_detection como null com o evento de cliente session.update. Isso pode ser útil em interfaces nas quais você deseja ter controle granular sobre a entrada de áudio, como interfaces de pressionar para falar.

Quando a VAD está desativada, o cliente precisa emitir manualmente alguns eventos de cliente adicionais para acionar respostas em áudio:

• Envie input_audio_buffer.commit manualmente para criar um novo item de entrada do usuário na conversa.
• Envie response.create manualmente para acionar uma resposta em áudio do modelo.
• Envie input_audio_buffer.clear antes de iniciar uma nova entrada do usuário.

Mantenha a VAD, mas desative as respostas automáticas

Se quiser manter o modo VAD ativado, mas decidir manualmente quando uma resposta será gerada, você pode definir turn_detection.interrupt_response e turn_detection.create_response como false com o evento de cliente session.update. Isso manterá todo o comportamento da VAD, mas não criará novas Respostas automaticamente. Os clientes podem acioná-las manualmente com um evento response.create.

Isso pode ser útil para moderação, validação de entradas ou padrões de RAG, quando você aceita um pouco mais de latência na interação em troca de controle sobre as entradas.

Crie respostas fora da conversa padrão

Por padrão, todas as respostas geradas durante uma sessão são adicionadas ao estado da conversa da sessão (a "conversa padrão"). No entanto, você pode querer gerar respostas do modelo fora do contexto da conversa padrão da sessão ou gerar várias respostas simultaneamente. Também pode querer controlar com mais precisão quais itens da conversa são considerados pelo modelo ao gerar uma resposta (por exemplo, apenas os últimos N turnos).

É possível gerar respostas "fora de banda", que não são adicionadas ao estado da conversa padrão, definindo o campo response.conversation como a string none ao criar uma resposta com o evento de cliente response.create.

Ao criar uma resposta fora de banda, você provavelmente também vai querer uma forma de identificar quais eventos enviados pelo servidor pertencem a essa resposta. Você pode fornecer metadata para a resposta do modelo, o que ajudará a identificar qual resposta está sendo gerada para esse evento enviado pelo cliente.

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."
)

Agora, ao escutar o evento de servidor response.done, você pode identificar o resultado da sua resposta fora de banda.

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

Crie um contexto personalizado para as respostas

Você também pode construir um contexto personalizado que o modelo usará para gerar uma resposta fora da conversa padrão/atual. Para isso, use o array input em um evento de cliente response.create. Você pode usar novas entradas ou referenciar pelo ID os itens de entrada existentes na conversa.

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."
        }
      ]
    }
  ]
)

Crie respostas sem contexto

Você também pode inserir respostas na conversa padrão, ignorando todas as outras instruções e o contexto. Para isso, defina input como um array vazio.

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."
)

Chamada de função

Os modelos Realtime também oferecem suporte à chamada de função, que permite executar código personalizado para ampliar as capacidades do modelo. Veja como isso funciona em linhas gerais:

1. Ao atualizar a sessão ou criar uma resposta, você pode especificar uma lista de funções disponíveis para o modelo chamar.
2. Se, ao processar a entrada, o modelo determinar que deve fazer uma chamada de função, ele adicionará à conversa itens que representam os argumentos dessa chamada.
3. Quando o cliente detectar itens da conversa que contenham argumentos de uma chamada de função, ele executará código personalizado usando esses argumentos
4. Após a execução do código personalizado, o cliente criará novos itens na conversa com a saída da chamada de função e pedirá ao modelo que responda.

Vamos ver como isso funcionaria na prática adicionando uma função que o modelo pode chamar para fornecer o horóscopo do dia aos usuários. Mostraremos a estrutura dos objetos de evento do cliente que precisam ser enviados e o que o servidor emitirá em seguida.

Configure funções que o modelo pode chamar

Primeiro, precisamos fornecer ao modelo um conjunto de funções que ele pode chamar com base na entrada do usuário. As funções disponíveis podem ser configuradas tanto para a sessão quanto para cada resposta individual.

• Sessão: propriedade session.tools em session.update
• Resposta: propriedade response.tools em response.create

Veja um exemplo de payload de evento do cliente para session.update que configura uma função de geração de horóscopo. Essa função recebe um único argumento: o signo para o qual o horóscopo deve ser gerado.

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"
  }
}

Os campos description da função e dos parâmetros ajudam o modelo a decidir se deve chamar a função e quais dados incluir em cada parâmetro. Se o modelo receber uma entrada que indique que o usuário quer saber seu horóscopo, ele chamará essa função com um parâmetro sign.

Detecte quando o modelo quer chamar uma função

Com base nas entradas recebidas, o modelo pode decidir chamar uma função para gerar a melhor resposta. Suponha que nosso aplicativo adicione o seguinte item à conversa com um evento conversation.item.create e depois crie uma resposta:

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

Em seguida, um evento do cliente response.create é enviado para gerar uma resposta:

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

Em vez de retornar imediatamente uma resposta em texto ou áudio, o modelo gerará uma resposta contendo os argumentos que devem ser passados a uma função no aplicativo do desenvolvedor. Você pode acompanhar as atualizações dos argumentos da chamada de função em tempo real por meio do evento do servidor response.function_call_arguments.delta, mas response.done também conterá todos os dados necessários para chamar nossa função.

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\"}"
            }
        ],
        ...
    }
}

No JSON emitido pelo servidor, podemos detectar que o modelo quer chamar uma função personalizada:

Com essas informações, podemos executar código em nosso aplicativo para gerar o horóscopo e depois enviar essas informações de volta ao modelo para que ele gere uma resposta.

Forneça os resultados de uma chamada de função ao modelo

Ao receber uma resposta do modelo com argumentos para uma chamada de função, seu aplicativo pode executar o código que realiza a operação solicitada. Esse código pode fazer o que você quiser, como se comunicar com APIs externas ou acessar bancos de dados.

Quando estiver pronto para fornecer ao modelo os resultados do seu código personalizado, você poderá criar um novo item na conversa contendo o resultado por meio do evento do cliente 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.\"}"
  }
}

• O tipo do item da conversa é function_call_output
• item.call_id é o mesmo ID que recebemos no evento response.done acima
• item.output é uma string JSON contendo os resultados da nossa chamada de função

Depois de adicionar o item da conversa contendo os resultados da chamada de função, emitimos novamente o evento response.create a partir do cliente. Isso acionará uma resposta do modelo usando os dados da chamada de função.

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

Tratamento de erros

O evento error é emitido pelo servidor sempre que ocorre um erro no servidor durante a sessão. Às vezes, é possível identificar um evento do cliente emitido pelo seu aplicativo como a origem desses erros.

Diferentemente das requisições e respostas HTTP, em que uma resposta está implicitamente vinculada a uma requisição do cliente, precisamos usar uma propriedade event_id nos eventos do cliente para saber quando um deles causou um erro no servidor. Essa técnica é mostrada no código abaixo, em que o cliente tenta emitir um tipo de evento não suportado.

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

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

Esse evento malsucedido enviado pelo cliente resultará na emissão de um evento de erro como o seguinte:

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

Interrupção e truncamento

Em muitos aplicativos de voz, o usuário pode interromper o modelo enquanto ele está falando. Quando a VAD está habilitada, a Realtime API lida com interrupções detectando a fala do usuário, cancelando a resposta em andamento e iniciando uma nova. Nesse cenário, porém, é importante que o modelo saiba em que ponto foi interrompido para continuar a conversa naturalmente (por exemplo, se o usuário perguntar "qual foi a última coisa que você disse?"). Chamamos isso de truncar a última resposta do modelo, ou seja, remover da conversa a parte dessa resposta que não foi reproduzida.

Nas conexões WebRTC e SIP, o servidor gerencia um buffer de áudio de saída e, por isso, sabe quanto áudio já foi reproduzido em determinado momento. O servidor truncará automaticamente o áudio não reproduzido quando o usuário interromper.

Em uma conexão WebSocket, o cliente gerencia a reprodução de áudio e, por isso, deve parar a reprodução e lidar com o truncamento. Veja como funciona esse procedimento:

1. O cliente monitora novos eventos input_audio_buffer.speech_started do servidor, que indicam que o usuário começou a falar. O servidor cancelará automaticamente qualquer resposta do modelo em andamento, e um evento response.cancelled será emitido.
2. Quando o cliente detectar esse evento, deverá parar imediatamente a reprodução de qualquer áudio do modelo que esteja sendo reproduzido. Ele deverá registrar quanto da última resposta em áudio foi reproduzido antes da interrupção.
3. O cliente deve enviar um evento conversation.item.truncate para remover da conversa a parte não reproduzida da última resposta do modelo.

Veja um exemplo:

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
}

E quanto a truncar também a transcrição? O modelo Realtime não tem informações suficientes para alinhar com precisão a transcrição e o áudio. Por isso, conversation.item.truncate cortará o áudio em um determinado ponto e removerá a transcrição em texto da parte não reproduzida. Isso resolve o problema de remover o áudio não reproduzido, mas não fornece uma transcrição truncada.

Pressionar para falar

Por padrão, a Realtime API usa detecção de atividade de voz (VAD), o que significa que as respostas do modelo são acionadas pela entrada de áudio. Você também pode implementar uma interação de pressionar para falar desabilitando a VAD e usando um controle no aplicativo para definir quando a entrada de áudio é enviada ao modelo. Por exemplo, o usuário pode manter a barra de espaço pressionada para capturar áudio e acionar uma resposta ao soltá-la. Em alguns aplicativos, isso funciona surpreendentemente bem: dá aos usuários controle sobre as interações, evita falhas da VAD e transmite uma sensação de agilidade, já que não é preciso aguardar o tempo limite da VAD.

A implementação de pressionar para falar é um pouco diferente em WebSockets e WebRTC. Em uma conexão WebSocket da Realtime API, todos os eventos são enviados no mesmo canal e na mesma ordem, enquanto uma conexão WebRTC tem canais separados para áudio e eventos de controle.

WebSockets

Para implementar pressionar para falar com uma conexão WebSocket, o cliente deverá parar a reprodução de áudio, lidar com interrupções e iniciar uma nova resposta. Veja o procedimento em mais detalhes:

1. Desabilite a VAD definindo "turn_detection": null em um evento session.update.
2. Ao pressionar o botão, inicie a gravação de áudio no cliente.
   1. Se houver uma resposta do modelo em andamento, cancele-a enviando um evento response.cancel.
   2. Se o áudio de saída do modelo estiver sendo reproduzido, interrompa a reprodução imediatamente e envie um evento conversation.item.truncate para remover da conversa todo o áudio ainda não reproduzido.
3. Ao soltar o botão, envie uma mensagem input_audio_buffer.append com o áudio para adicionar o novo áudio ao buffer de entrada.
4. Envie um evento input_audio_buffer.commit. Isso confirmará o áudio gravado no buffer de entrada e iniciará a transcrição da entrada, se estiver habilitada.
5. Em seguida, acione uma resposta com um evento response.create.

WebRTC e SIP

A implementação de pressionar para falar com WebRTC é semelhante, mas o buffer de áudio de entrada precisa ser limpo explicitamente. Siga este procedimento:

1. Desative a VAD definindo "turn_detection": null em um evento session.update.
2. Ao pressionar o botão, envie um evento input_audio_buffer.clear para limpar qualquer entrada de áudio anterior.
   1. Se houver uma resposta do modelo em andamento, cancele-a enviando um evento response.cancel.
   2. Se o áudio de saída do modelo estiver sendo reproduzido, envie um evento output_audio_buffer.clear para limpar o áudio ainda não reproduzido. Isso também trunca a conversa.
3. Ao soltar o botão, envie um evento input_audio_buffer.commit. Isso confirma o áudio gravado no buffer de entrada e inicia a transcrição da entrada (se estiver habilitada).
4. Em seguida, inicie uma resposta com um evento response.create.