OpenAI Realtime

OpenAI Realtime sử dụng kết nối liên tục và sự kiện hai chiều để xử lý văn bản, âm thanh và lệnh gọi hàm theo thời gian thực. Máy khách gửi sự kiện phiên, bộ đệm âm thanh, mục hội thoại và điều khiển phản hồi; máy chủ liên tục trả về trạng thái phiên, văn bản chuyển đổi từ giọng nói, văn bản, âm thanh, tham số hàm và sự kiện lỗi.

Trang này sử dụng WebSocket làm phương thức kết nối chính. Khi kết nối, thay MODEL_ID bằng ID mô hình khả dụng với tài khoản hiện tại và hỗ trợ Realtime.

Các tình huống điển hình gồm hội thoại giọng nói thời gian thực, chuyển giọng nói cuộc họp thành văn bản và trợ lý giọng nói, dịch thời gian thực, chuyển giọng nói thành văn bản, tương tác mã nguồn thời gian thực và tích hợp thời gian thực phía máy chủ. Kết nối có thể truyền cả văn bản lẫn âm thanh và xử lý VAD, gọi hàm cùng cập nhật trạng thái qua sự kiện.

Xác thực và kết nối

Xác thực WebSocket

Ứng dụng phía máy chủ thiết lập kết nối WSS bằng Bearer API Key và gửi Header Realtime Beta trong yêu cầu bắt tay.

Chỉ sử dụng API Key dài hạn trên máy chủ đáng tin cậy; không đưa khóa vào trình duyệt, gói ứng dụng di động hoặc kho mã công khai. Mọi kết nối nên dùng HTTPS/WSS.

Token tạm thời

Khi máy khách kết nối, máy chủ đáng tin cậy có thể tạo trước một token tạm thời có hiệu lực một phút và chỉ dùng cho một kết nối.

POST https://api.agtcloud.cn/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "model": "MODEL_ID",
  "voice": "verse"
}

Quy trình kết nối

Trong quy trình WebSocket chính, máy chủ trực tiếp thiết lập kết nối bằng API Key; sau khi bắt tay thành công, gửi sự kiện máy khách và nhận sự kiện máy chủ trên cùng kết nối.

Trong quy trình WebRTC, máy khách trước tiên yêu cầu token tạm thời từ máy chủ ứng dụng của mình. Máy chủ ứng dụng gọi API phiên để tạo token; sau đó máy khách tạo SDP Offer, gửi tới điểm cuối Realtime và nhận SDP Answer, rồi trao đổi sự kiện JSON qua kênh dữ liệu oai-events.

Ví dụ kết nối WebSocket

Các ví dụ dưới đây trình bày Node.js, Python, gửi và nhận sự kiện. Sau khi kết nối, máy khách gửi sự kiện JSON và máy chủ cũng liên tục trả về kết quả dưới dạng sự kiện JSON.

import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
    'OpenAI-Beta': 'realtime=v1',
  },
});

ws.on('open', () => {
  console.log('Đã kết nối với máy chủ.');
});

ws.on('message', (message) => {
  console.log(JSON.parse(message.toString()));
});

Hướng dẫn tích hợp WebRTC

Hiện khuyến nghị sử dụng WebSocket. Trước khi dùng WebRTC, hãy xác nhận mô hình mục tiêu có hỗ trợ hay không; các ví dụ sau trình bày cấu trúc kết nối cơ bản với token tạm thời, SDP, luồng âm thanh và kênh dữ liệu.

async function init() {
  const tokenResponse = await fetch('/session');
  const data = await tokenResponse.json();
  const ephemeralKey = data.client_secret.value;

  const pc = new RTCPeerConnection();
  const audioElement = document.createElement('audio');
  audioElement.autoplay = true;
  pc.ontrack = (event) => {
    audioElement.srcObject = event.streams[0];
  };

  const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
  pc.addTrack(mediaStream.getTracks()[0]);

  const dataChannel = pc.createDataChannel('oai-events');
  dataChannel.addEventListener('message', (event) => {
    console.log(JSON.parse(event.data));
  });

  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const response = await fetch(
    'https://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
    {
      method: 'POST',
      body: offer.sdp,
      headers: {
        Authorization: `Bearer ${ephemeralKey}`,
        'Content-Type': 'application/sdp',
      },
    },
  );

  await pc.setRemoteDescription({
    type: 'answer',
    sdp: await response.text(),
  });
}

init();

import express from 'express';

const app = express();

app.get('/session', async (_request, response) => {
  const result = await fetch('https://api.agtcloud.cn/v1/realtime/sessions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'MODEL_ID',
      voice: 'verse',
    }),
  });

  response.send(await result.json());
});

app.listen(3000);

const dataChannel = pc.createDataChannel('oai-events');

dataChannel.addEventListener('message', (event) => {
  const realtimeEvent = JSON.parse(event.data);
  console.log(realtimeEvent);
});

dataChannel.send(JSON.stringify({
  type: 'response.create',
  response: {
    modalities: ['text'],
    instructions: 'Hãy viết một bài haiku về mã nguồn',
  },
}));

const ws = new WebSocket(
  'wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
  [
    'realtime',
    'openai-insecure-api-key.your-api-key',
    'openai-organization.ORGANIZATION_ID',
    'openai-project.PROJECT_ID',
    'openai-beta.realtime-v1',
  ],
);

ws.addEventListener('open', () => {
  console.log('Đã kết nối với máy chủ.');
});

ws.addEventListener('message', (event) => {
  console.log(JSON.parse(event.data));
});

Phiên, âm thanh và hội thoại

Realtime hỗ trợ hội thoại chỉ có văn bản, giọng nói hoặc kết hợp cả hai. Cấu hình phiên có thể bao gồm định dạng âm thanh đầu vào và đầu ra, giọng nói, nhiệt độ, độ dài đầu ra tối đa, công cụ và tham số VAD.

• Định dạng âm thanh đầu vào và đầu ra: pcm16, g711_ulaw, g711_alaw.
• Các lựa chọn giọng nói trong ví dụ: alloy, echo, shimmer.
• Cấu hình VAD gồm ngưỡng, khoảng âm thanh đệm trước giọng nói và thời gian im lặng.
• Hội thoại tiến triển thông qua phiên, mục hội thoại, phần nội dung và sự kiện phản hồi.

Xem các trường sự kiện cụ thể trong trình duyệt sự kiện bên dưới; tham số và miền giá trị dùng chung được tập hợp trong “Kiểu dùng chung”.

Tham khảo sự kiện

Chọn sự kiện để xem định nghĩa trường và ví dụ JSON. Có thể chuyển hướng sự kiện, lọc theo danh mục hoặc tìm tên sự kiện.

{
  "event_id": "event_123",
  "type": "session.update",
  "modalities": [
    "text",
    "audio"
  ],
  "instructions": "Hãy trả lời ngắn gọn và chính xác.",
  "voice": "alloy",
  "input_audio_format": "pcm16",
  "output_audio_format": "pcm16",
  "input_audio_transcription": {
    "model": "whisper-1"
  },
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.8,
    "prefix_padding_ms": 500,
    "silence_duration_ms": 1000
  },
  "tools": [],
  "tool_choice": "auto",
  "temperature": 0.8,
  "max_output_tokens": "inf"
}

Kiểu dùng chung

Các phần thu gọn sau tập hợp bảng tham số cho giới hạn tốc độ, gọi hàm, âm thanh, VAD, công cụ, mô hình, sự kiện, phiên, mục hội thoại, nội dung, phản hồi, chuyển giọng nói thành văn bản, luồng âm thanh và WebRTC.

Xử lý lỗi và khôi phục

Lỗi Realtime thường thuộc bốn nhóm: kết nối, xác thực, âm thanh hoặc phiên:

Chiến lược khôi phục có thể bao gồm tự động kết nối lại, khôi phục phiên, thử lại có giới hạn và giảm chức năng. Khi có lỗi, ưu tiên đọc sự kiện error, lưu event_id, error.type, error.code, error.message cùng thông tin sự kiện liên quan, rồi quyết định có gửi lại hay không.