서버 측 제어

서버에서 GPT-Live 세션 제어하기

서버에서 대화 이벤트를 수신하거나 비공개 도구를 실행하거나 대화를 업데이트해야 한다면 기존 GPT-Live WebRTC 또는 SIP 세션에 애플리케이션 서버를 연결하세요. 이렇게 추가한 연결을 사이드밴드 WebSocket이라고 합니다. 두 연결은 하나의 세션을 공유하며, 기본 오디오 전송은 WebRTC 또는 SIP가 담당합니다.

사이드밴드는 이벤트와 명령어를 전달합니다. 도구 실행, 권한 확인, 비즈니스 규칙 적용은 애플리케이션이 담당합니다. API 키와 도구 자격 증명은 서버에 보관하세요.

사이드밴드가 필요한지 판단하기

브라우저 애플리케이션에서 자막을 표시하거나 로컬 UI를 업데이트할 때는 WebRTC 데이터 채널을 사용하세요. 가드레일 검사, 감정 분석, 도구 사전 호출처럼 서버에서 전사 텍스트를 처리할 때는 사이드밴드를 사용하세요. 브라우저가 WebRTC로 오디오를 계속 주고받는 동안 서버는 이벤트를 수신하면서 같은 세션을 직접 제어할 수 있습니다. 예시는 전사 텍스트 조각에 반응하기를 참고하세요.

백엔드가 기본 WebSocket 연결로 오디오를 스트리밍한다면 같은 연결로 이벤트를 수신하고 명령어를 보내세요.

Responses 위임은 사이드밴드 없이도 사용할 수 있습니다. 브라우저가 데이터 채널에서 받은 함수 호출 이벤트를 인증된 백엔드로 전달하면 백엔드에서 함수를 실행할 수 있습니다. OpenAI에서 호스팅하는 도구는 위임을 받은 백엔드를 통해 실행되므로 애플리케이션에 별도의 도구 실행기가 필요하지 않습니다.

기존 세션에 연결하기

1. 백엔드에서 제어할 세션의 ID를 저장하세요. WebRTC 또는 발신 SIP 통화에서는 session.id를 사용하세요. 이 값은 POST /v1/live/sessions의 JSON 응답에 있습니다. 수신 SIP 통화에서는 먼저 수신 통화를 수락한 다음 해당 웹훅의 data.session_id를 사용하세요. 애플리케이션의 사용자 및 대화 레코드와 함께 ID를 보관하세요.

2. 다음 URL에 저장한 ID를 그대로 넣고 서버에서 WebSocket 연결을 여세요. Authorization: Bearer $OPENAI_API_KEY로 인증할 때는 세션을 만들거나 수락한 프로젝트의 인증 정보를 사용하세요. 세션을 만들 때 필요했던 연결 헤더도 동일하게 포함하세요.

   wss://api.openai.com/v1/live/sessions/{session_id}/attach

3. 연결된 소켓에서 이벤트를 수신하고 명령어를 보내세요. 세션이 이미 실행 중이므로 session.start를 다시 보내지 마세요.

접두사를 포함한 세션 ID 전체를 그대로 사용하고, 애플리케이션에 해당 세션에 접근할 권한이 있는지 확인하세요.

이벤트 확인 및 명령어 전송

명령어에는 기본 연결과 동일한 유효성 검사 및 위임 규칙이 적용됩니다. 세션 전반에 적용할 컨텍스트를 추가할 때는 delegation_id: null을 사용하세요. ID가 null이 아니면 기존 클라이언트 위임을 가리켜야 합니다. 설정, 함수 실행, 컨텍스트 추가 예시는 위임 및 도구를 참고하세요.

브라우저 세션에서는 연결 협상에서 정한 WebRTC 미디어 트랙을 마이크 입력과 스피커 출력에 계속 사용하세요. 사이드밴드는 대화 이벤트 수신과 제어에 사용하고, 재생 상태는 오디오 플레이어에서 추적하세요.

오디오 사본 수신하기

기본 연결이 실시간 미디어를 전송하는 동안 사이드밴드에서도 연결 이후의 입력 및 출력 오디오 사본을 수신합니다.

두 페이로드 모두 기본 연결의 오디오 형식과 관계없이 24 kHz의 원시 모노 PCM16LE 오디오를 base64로 인코딩한 것입니다. 두 이벤트 모두 event_id가 없습니다. 입력 오디오 사본에는 입력 음소거를 적용하기 전에 수신한 오디오가 담깁니다. 사본을 받았다고 해서 모델이 해당 샘플을 처리했다는 뜻은 아닙니다. 프레임이 누락되면 출력 오디오 사본의 시간 구간 사이에 공백이 생길 수 있으며, 이 구간만으로는 통화자가 실제로 오디오를 들은 시점을 알 수 없습니다.

마이크 오디오는 기본 연결로만 보내세요. 오디오 사본을 수신할 때는 사이드밴드를 사용하세요.

각 작업을 담당할 주체 정하기

각 작업을 브라우저와 백엔드 중 어디에서 처리할지 정하세요. 두 연결이 같은 함수 호출 이벤트를 수신하더라도 함수는 한 번만 실행하세요. 컨텍스트 업데이트와 백엔드 작업을 계속하라는 요청에도 같은 원칙을 적용하세요.

백엔드가 처음부터 대화를 모니터링해야 한다면 사이드밴드를 일찍 연결하세요. 연결 전에 수집한 기록을 포함해 전사 텍스트와 도구 상태를 애플리케이션에 저장하세요.

사이드밴드를 연결한 후에도 브라우저는 세션 이벤트를 수신할 수 있습니다. 민감한 도구 자격 증명은 백엔드에 보관하고 권한도 백엔드에서 판단하세요. 대화에 필요한 컨텍스트만 반환하세요.

대화에 가드레일 적용하기

서버의 기본 WebSocket 또는 사이드밴드로 대화를 모니터링하고 요청이 애플리케이션 정책에 맞는지 검사하세요. 검사는 애플리케이션이 수행하며, 차단 조건이 충족되면 해당 작업을 차단하고 대화를 바로잡는 지침을 보냅니다.

대화 중에 검사 실행하기

가드레일은 전사 텍스트 조각을 수신하는 즉시 처리하는 방식의 활용 사례입니다. 같은 스트림으로 검사를 수행하면서 미리 조회를 시작하거나 UI를 업데이트할 수도 있습니다.

1. 전사 텍스트를 모니터링하세요. session.input_transcript.delta 조각을 모아 사용자 요청에 탈옥 시도, 민감한 정보 또는 정책 위반이 있는지 검사하세요. session.output_transcript.delta를 사용해 어시스턴트의 발화에 근거 없는 주장이나 애플리케이션 범위를 벗어난 응답이 있는지 확인하세요. 각 검사가 어떤 전사 텍스트와 애플리케이션 요청을 평가했는지 추적할 수 있게 하세요.
2. 검사를 동시에 실행하세요. 대화가 이어지는 동안 빠르고 가벼운 모델로 요청을 평가할 수 있습니다. {"triggered": true}처럼 애플리케이션이 후속 조치를 결정할 수 있는 간단한 구조화된 결과를 반환하세요. 승인이 필요한 작업은 검사를 통과한 후에만 실행하세요. 검사에 실패하거나 제한 시간을 초과하면 차단 상태를 유지하세요.
3. 해당 작업을 차단하세요. 차단 조건이 충족되면 애플리케이션 상태에 해당 요청을 차단된 것으로 표시하세요. 이미 대기열에 있는 작업을 포함해 도구를 실행하거나 변경 사항을 확정하기 전에 이 상태를 확인하세요.
4. 관련 작업을 중지하세요. 백엔드가 취소를 지원하면 애플리케이션이 관리하는 작업을 취소하세요. 차단된 요청이나 새 요청으로 대체된 요청의 결과가 뒤늦게 도착하면 폐기하세요. Responses 위임을 사용할 때는 관련 사용자 정의 함수의 실행을 중지하고, 차단된 작업을 계속하기 위한 response.create를 보내지 마세요. 이렇게 해도 이미 실행 중인 호스팅 응답이 취소되거나 프런트엔드의 발화가 중단되지는 않습니다.
5. 결정을 기록하고 대화를 바로잡으세요. 결정 내용과 함께 해당 요청 ID와 위임 ID를 로그에 남긴 다음 수정 지침을 보내세요.

조각을 수집하는 방법은 전사 텍스트 델타를, 백엔드 결과가 현재 작업에 맞도록 관리하는 방법은 위임 및 도구를 참고하세요.

대화 방향 바로잡기

가드레일에 따라 대화 방향을 조정할 때는 session.instructions.append를 사용하세요. 진행 중인 발화를 끊고 새 지침을 적용할 수 있습니다. 예를 들어 애플리케이션에서 요청을 차단한 후 다음과 같이 보내세요.

1
2
3
4
5
6
7
8
9export function sendUpdate(connection) {
  connection.send({
    type: "session.instructions.append",
    event_id: "guardrail_block_17",
    delegation_id: null,
    content:
      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.session.instructions.append(
        event_id="guardrail_block_17",
        delegation_id=None,
        content=(
            "Stop speaking immediately. Do not continue or act on the last request. "
            "Refuse briefly, then wait."
        ),
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
	"github.com/openai/openai-go/v3/packages/param"
)

// SendSidebandUpdate uses the server connection attached to an existing session.
func SendSidebandUpdate(ctx context.Context, connection *live.SidebandConnection) error {
	return connection.Send(ctx, live.ConnectClientEventUnionParam{OfSessionInstructionsAppend: &live.InstructionsAppendEventParam{
		EventID:      openai.String("guardrail_block_17"),
		DelegationID: param.Null[string](),
		Content:      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
	}})
}

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfSessionInstructionsAppend: &live.InstructionsAppendEventParam{
		EventID:      openai.String("guardrail_block_17"),
		DelegationID: param.Null[string](),
		Content:      "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
	}})
}

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
27import com.openai.core.JsonField;
import com.openai.helpers.LiveConnection;
import com.openai.helpers.LiveSidebandConnection;
import com.openai.models.live.*;

// Use the server connection attached to an existing session.
public static void sendUpdate(LiveSidebandConnection connection) {
  connection.send(
      InstructionsAppendEvent.builder()
          .eventId("guardrail_block_17")
          .delegationId(JsonField.<String>ofNullable(null))
          .content(
              "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
          .build());
}

// Use a primary connection after its session has started.
public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofSessionInstructionsAppend(
          InstructionsAppendEvent.builder()
              .eventId("guardrail_block_17")
              .delegationId(JsonField.<String>ofNullable(null))
              .content(
                  "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
              .build()));
}

1
2
3def send_update(connection)
  connection.send_event(type: "session.instructions.append", event_id: "guardrail_block_17", delegation_id: nil, content: "Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.")
end

지침은 애플리케이션에서 작성하세요. 신뢰할 수 없는 사용자 텍스트를 복사해 지침으로 넣지 마세요. 세션 전체에 적용할 수정 지침에는 delegation_id: null을 사용하고, content는 500토큰 이내로 제한하세요.

session.instructions.appended가 어느 명령어에 대한 응답인지는 client_event_id로 확인하세요. 확인 응답은 컨텍스트가 주입된 것으로 추정되는 시점 이후에 도착합니다. 통화자에게 오디오가 전달되는 것을 막으려면 아래의 재생 제어 방법을 사용하세요.

고지 사항을 특정 문구로 읽어야 할 때도 지침을 사용하세요. 예시와 재생 시 고려할 사항은 고지 사항 전달하기를 참고하세요.

필요할 때 재생 제어하기

애플리케이션에서 모델 오디오를 차단해야 한다면 클라이언트 또는 미디어 릴레이에서 재생을 제어하세요. 출력을 일시적으로 음소거하거나 버리고, 로컬 재생 대기열에 있는 오디오를 폐기한 다음 수정 지침을 보내세요. 더 이상 유효하지 않은 오디오를 지운 뒤 애플리케이션의 복구 정책에 따라 재생을 재개하세요. 지침 수신 확인은 재생을 재개하라는 신호가 아닙니다. 사이드밴드만으로는 재생을 제어할 수 없으며, 수정 지침으로 통화자가 이미 들은 오디오를 되돌릴 수도 없습니다.

session.input_audio.mute는 통화자의 마이크 입력을 제어합니다. 모델 출력을 음소거하거나 위임된 작업을 취소하지는 않습니다.

재생 전에 발화 검사하기

대부분의 애플리케이션에서는 대화가 이어지는 동안 사용자와 어시스턴트의 전사 텍스트를 모니터링하세요. 가드레일의 차단 조건이 충족되면 애플리케이션에서 해당 작업을 차단하거나 수정 지침을 보낼 수 있습니다.

어시스턴트의 발화를 재생 전에 검사해야 한다면 통화자에게 오디오를 보내기 전에 플레이어나 미디어 브리지의 버퍼에 저장하세요. 검사 중에도 오디오와 전사 이벤트를 계속 수신하고, 재생 여부와 관계없이 전사 텍스트를 읽으세요.

1. 오디오와 해당 전사 텍스트를 수집하세요. 애플리케이션에 출력 음성 활동 감지(VAD)를 구현하거나 미디어 프레임워크에서 제공하는 노이즈 게이트를 사용해 검사할 발화 구간 후보를 식별하세요. GPT-Live는 이 워크플로우에 필요한 출력 VAD나 노이즈 게이트를 제공하지 않습니다. 각 구간을 검사하는 데 필요한 전사 텍스트가 도착할 때까지 기다리세요.
2. 승인된 오디오를 재생 대기열에 넣으세요. 구간이 검사를 통과하면 버퍼에 저장해 둔 해당 구간의 원본 오디오를 재생 대기열에 넣으세요. 검사에 실패하거나 전사 텍스트가 없거나 검사 제한 시간을 초과하면 해당 구간을 폐기하고 애플리케이션에서 정한 안전한 대체 동작을 수행하세요.
3. 발화 중단을 처리하세요. 애플리케이션에서 생성한 ID에 오디오, 전사 텍스트, 검사 결과, 재생 상태를 연결하세요. 도중에 해당 발화가 취소되면 버퍼와 대기열에서 해당 오디오를 지우고 이후에 도착하는 승인 결과는 무시하세요.

모델이 답변을 작성하는 중에도 잠시 말을 멈춘 지점을 검사할 구간의 경계로 삼을 수 있습니다. 정책상 전체 답변을 검사해야 한다면 애플리케이션에서 답변 완료 여부를 어떻게 판단할지 정하세요. 음성 활동 감지만으로는 전체 답변이 끝났는지 확인할 수 없습니다.

버퍼링하면 지연 시간이 늘어납니다. 폐기한 발화도 모델의 대화 컨텍스트에는 남으므로, 오디오를 전달하지 않거나 대체 동작을 수행한 뒤 대화가 어떻게 이어지는지 테스트하세요.

가드레일 개입 테스트하기

허용되는 요청과 차단되는 요청, 오탐, 검사가 지연되거나 실패하는 경우, 발화 중이나 도구 실행 중에 차단 조건이 충족되는 경우, 취소된 작업의 결과가 뒤늦게 도착하는 경우를 테스트하세요. 작업 차단, 애플리케이션 상태, 수정 지침에 따른 발화, 실제 재생을 각각 검증하세요. 출력을 제어한다면 대기열의 오디오 처리와 재생 복구도 테스트에 포함하세요. 음성 에이전트 평가 Cookbook을 활용해 작업 성공 여부와 음성 응답 시간을 비교하세요.

세션 정상 종료하기

도구 실행이 끝나고 세션에서 최종 사용량을 보고할 때까지 이벤트를 계속 수신하세요. session.closed 핸들러를 등록한 다음 session.close를 보내고, 대기 중인 작업이 모두 끝날 때까지 WebRTC 연결, 데이터 채널, 사이드밴드를 열어 두세요. 리소스를 정리하기 전에 세션의 최종 사용량과 Responses 이벤트로 수신한 백엔드 사용량을 저장하세요. 최종 이벤트가 도착하기 전에 연결이 끊기면 종료 절차가 완료되지 않은 것으로 기록하세요. 종료 순서는 세션 관리를 참고하세요.

Realtime API를 사용하면 클라이언트에서 WebRTC 또는 SIP로 API 서버에 직접 연결할 수 있습니다. 도구 사용 로직과 그 밖의 비즈니스 로직을 비공개로 유지하고 클라이언트에 종속되지 않게 하려면 일반적으로 애플리케이션 서버에서 이 로직을 처리하는 편이 좋습니다.

‘사이드밴드’ 제어 채널로 연결하면 도구 사용 로직, 비즈니스 로직 및 기타 세부 사항을 서버 측에서 안전하게 관리할 수 있습니다. 현재 SIP와 WebRTC 연결 모두 사이드밴드를 지원합니다.

사이드밴드를 사용하면 같은 Realtime 세션에 두 연결이 동시에 활성화됩니다. 하나는 사용자의 클라이언트에서, 다른 하나는 애플리케이션 서버에서 연결합니다. 서버 연결을 통해 세션을 모니터링하고 지침을 업데이트하며 도구 호출에 응답할 수 있습니다.

WebRTC 사용 시

1. 피어 연결을 설정할 때는 Realtime API에 요청을 보내고 SDP 응답을 받아 연결을 구성합니다. WebRTC 가이드의 샘플 코드를 사용했다면 다음과 비슷합니다.

1
2
3
4
5
6
7
8
9const baseUrl = "https://api.openai.com/v1/realtime/calls";
const sdpResponse = await fetch(baseUrl, {
  method: "POST",
  body: offer.sdp,
  headers: {
    Authorization: `Bearer ${EPHEMERAL_KEY}`,
    "Content-Type": "application/sdp",
  },
});

2. fetch 응답의 Location 헤더에는 고유한 통화 ID가 들어 있습니다. 서버는 이 ID로 같은 Realtime 세션에 WebSocket 연결을 열 수 있습니다.

1
2
3
4// Location: /v1/realtime/calls/rtc_123456
const location = sdpResponse.headers.get("Location");
const callId = location?.split("/").pop();
console.log(callId);

3. 이제 서버에서 일반적인 Realtime API WebSocket 연결과 마찬가지로 이벤트를 수신하고 세션을 구성할 수 있습니다. 아래 예시처럼 통화 ID를 URL wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx에 넣어 사용하세요.

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
30import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";

// Connect to a WebSocket for the in-progress call
const url = "wss://api.openai.com/v1/realtime?call_id=" + callId;
const ws = new WebSocket(url, {
  headers: {
    Authorization: "Bearer " + process.env.OPENAI_API_KEY,
  },
});

ws.on("open", function open() {
  console.log("Connected to server.");

  // Send client events over the WebSocket once connected
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        instructions: "Be extra nice today!",
      },
    })
  );
});

// Listen for and parse server events
ws.on("message", function incoming(message) {
  console.log(JSON.parse(message.toString()));
});

Go에서는 서버 측 세션 업데이트 함수에 통화 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
28func updateSession(ctx context.Context, client openai.Client, callID string) error {
	conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("call_id", callID))
	if err != nil {
		return err
	}
	defer conn.Close()
	if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfSessionUpdate(realtime.RealtimeSessionCreateRequestParam{
		Instructions: openai.String("Be extra nice today!"),
	})); err != nil {
		return err
	}
	for {
		event, err := conn.Recv(ctx)
		if err != nil {
			return err
		}
		if event.Type == "error" {
			return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
		}
		if event.Type == "session.updated" {
			if event.OfSessionUpdatedEvent.Session.OfRealtimeSessionCreateRequest.Instructions != "Be extra nice today!" {
				return fmt.Errorf("session update was not applied")
			}
			fmt.Println("session.updated")
			return nil
		}
	}
}

이렇게 하면 클라이언트에서 별도로 구성할 필요 없이 서버에서 도구를 추가하고 세션을 모니터링하며 비즈니스 로직을 실행할 수 있습니다.

SIP 사용 시

1. 사용자가 SIP를 통해 전화로 OpenAI에 연결합니다.
2. OpenAI가 애플리케이션 서버의 웹훅 URL로 웹훅을 보내 세션 상태를 알립니다. 웹훅은 다음과 비슷합니다.

123456789101112131415161718192021POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI

{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "realtime.call.incoming",
  "created_at": 1750287018, // Unix timestamp
  "data": {
    "call_id": "some_unique_id",
    "sip_headers": [
      { "name": "From", "value": "sip:+142555512112@sip.example.com" },
      { "name": "To", "value": "sip:+18005551212@sip.example.com" },
      { "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
    ]
  }
}

3. 애플리케이션 서버는 웹훅에서 받은 call_id 값을 wss://api.openai.com/v1/realtime?call_id={callId}와 같은 URL에 넣어 Realtime API에 WebSocket 연결을 엽니다. WebSocket 연결은 SIP 통화가 끝날 때까지 유지됩니다.

이후에는 WebSocket 연결로 시작한 세션에서와 마찬가지로 WebSocket을 통해 이벤트를 주고받으며 통화를 제어할 수 있습니다. 통화를 모니터링하고, 통화 중에 지침을 업데이트하고, 도구 호출에 응답할 수 있습니다.