Архитектура на WebSocket за Realtime API
На тази страница
Обновено на 2 ноември 2026 г. — Аудио модели. Няколко модела в този курс са депрецирали:
tts-1,tts-1-hdиgpt-4o-mini-ttsще спрат да работят на 6 януари 2027 г. (замяна:gpt-realtime-2.1-mini, който според ръководството на OpenAI за TTS не се поддържа от/v1/audio/speech: миграцията на синтез на реч преминава към Realtime API);gpt-realtime,gpt-4o-realtimeи наследените аудио модели на 20 януари 2027 г. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeи/v1/audio/translationsна 26 февруари 2027 г. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). За двупосочна гласова връзка GPT-Live 1 е достъпен в API от 10 септември 2026 г. Добавка от 3 ноември 2026 г.: раздел за трите гласови архитектури на OpenAI (GPT-Live, Realtime API, верига за обработка) и избор на транспорт (WebRTC, WebSocket, SIP), базиран на ръководствата Voice agents, Audio and voice и Getting started with the Realtime API; максимална продължителност на сесията: 60 минути (Realtime conversations).
Архитектура на WebSocket за Realtime API
Realtime API на OpenAI представлява фундаментална промяна в парадигмата на взаимодействие с езиковите модели. За разлика от традиционните REST API, които работят на цикъл „заявка-отговор“, Realtime API използва протокола WebSocket, за да установи постоянна, двупосочна връзка между Вашето приложение и модела.
Тази архитектура позволява обмен на аудио в реално време: Вие изпращате аудио, моделът го обработва и отговаря гласово с ниска латентност, пропускайки междинните стъпки на транскрипция или текст-към-реч. Това е един от основните градивни елементи за разговорни гласови агенти и сърцето на този курс.
Три гласови архитектури през 2026 г.
Преди да отворите WebSocket връзка, поставете Realtime API в контекста на другите решения на OpenAI. Ръководството Voice agents разграничава три подхода:
| Архитектура | Най-подходящо за | Защо да го изберете |
|---|---|---|
| GPT-Live | Пълнодуплексни разговори със отделен бекенд | Гласовият модел слуша, докато говори, и делегира разсъжденията и използването на инструменти на бекенд по Ваш избор; запазва Вашия съществуващ текстов агент непокътнат |
| Realtime API | Реч, разсъждения и инструменти в една сесия | Един модел интерпретира аудиото, решава какво да прави и произнася отговора |
| Верига за обработка | Грануларен контрол над всяка стъпка | Транскрипция, след това текстов агент, след това синтез на реч: Вие инспектирате или трансформирате текста между стъпките и заменете всеки компонент независимо |
За нови приложения за гласови разговори, страницата Audio and voice на OpenAI сега препоръчва започване с GPT-Live. Realtime API остава правилната отправна точка, когато агентът трябва да се побере в една сесия, поддържайки прекъсване от потребителя, бърз първи аудио отговор, естествена смяна на репликите и директни извиквания на инструменти. Веригата за обработка работи най-добре, когато всяка стъпка трябва да остане видима: запазване на транскрипции, налагане на правила, преди агентът да отговори, или издаване на глас само след валидиране на отговора.
Този курс се фокусира върху Realtime API и веригата за обработка, чиито компоненти (транскрипция, синтез на реч) са разгледани в следващите раздели.
WebRTC, WebSocket или SIP
Изборът на транспорт зависи от това откъде произлиза аудиото. Според документацията: използвайте WebRTC за браузерно аудио, с ефемерен клиентски секрет, генериран от Вашия сървър; WebSocket за сървърни аудио пайплайни; SIP за телефонни обаждания. Контролна връзка от страна на сървъра също позволява на доверен бекенд да наблюдава и управлява медийна сесия. Този урок детайлизира WebSocket, най-простият начин за разбиране на разменените събития; в браузър предпочитайте WebRTC. една Realtime сесия трае най-много 60 минути.
WebSocket срещу REST: Защо този избор?
В традиционната REST архитектура всяко взаимодействие изисква пълна HTTP заявка: отваряне на TCP връзка, TLS договаряне, изпращане на хедъри, чакане на отговора и затваряне на връзката. За аудио в реално време това натоварване е неприемливо.
| Критерий | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Латентност | 200–500 ms на заявка | < 50 ms след свързване |
| Посока | Само Клиент → Сървър | Едновременно двупосочно |
| Връзка | Нова за всяка заявка | Постоянна (сесия) |
| Аудио | Изисква се цял файл | Потоково предаване парче по парче |
Протоколът WebSocket поддържа канал отворен непрекъснато. След като се установи, клиентът и сървърът могат да изпращат съобщения по всяко време, без да чакат другия да приключи.
Установяване на WebSocket връзка
Ето как да установите връзка с Realtime API в Python:
import asyncio
import websockets
import json
OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
async def connect_realtime():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
print("Connected to Realtime API")
# Receive the welcome event
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Keep the connection open
await asyncio.Future()
asyncio.run(connect_realtime())
URL адресът на връзката включва модела като параметър на заявката. Тъй като API достигна обща достъпност, се изисква само хедърът за удостоверяване – хедърът OpenAI-Beta: realtime=v1 от бета фазата отпадна.
Интерфейс, отбелязан на 5 август 2026 г. — Realtime API еволюира (модели, имена на събития, формат на сесията): когато имате съмнения, проверете официалната документация.
Архитектура на Realtime приложение
Приложение, използващо Realtime API, следва слоева архитектура:
Аудио слой (заснемане/възпроизвеждане)
Заснема микрофона, възпроизвежда аудио отговори. Използва PyAudio, sounddevice или Web Audio API в браузъра.
WebSocket слой (транспорт)
Управлява постоянната връзка, кодира/декодира JSON събития, обработва повторни свързвания.
Слой на приложението (бизнес логика)
Оркестрира разговора, управлява контекста, извиква инструменти, обработва резултатите.
Сървърен слой (опционален прокси)
В продукция междинен сървър защитава API ключа и добавя бизнес логика от страна на сървъра.
Ролята на прокси сървъра
По време на разработка можете да свържете приложението си директно с Realtime API. В продукция прокси сървърът е от съществено значение за:
- Защита на Вашия API ключ – никога не го излагайте от страна на клиента
- Удостоверяване на Вашите потребители – проверка на токени преди отваряне на сесията
- Контрол на разходите – ограничаване на продължителността на сесията и използването на токени
- Регистриране на взаимодействията – за отстраняване на грешки и съответствие
# Simplified example of a WebSocket proxy with FastAPI
from fastapi import FastAPI, WebSocket
import websockets
app = FastAPI()
@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
await client_ws.accept()
headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}
async with websockets.connect(URL, additional_headers=headers) as openai_ws:
async def forward_to_openai():
async for message in client_ws.iter_text():
await openai_ws.send(message)
async def forward_to_client():
async for message in openai_ws:
await client_ws.send_text(message)
await asyncio.gather(forward_to_openai(), forward_to_client())
Ключови изводи
- Три гласови архитектури при OpenAI: GPT-Live (препоръчително за нови разговорни приложения), Realtime API (реч, разсъждения и инструменти в една сесия) и веригата транскрипция → агент → синтез
- WebRTC за браузерно аудио, WebSocket за сървърни пайплайни, SIP за телефония; сесиите траят най-много 60 минути
- Realtime API използва WebSocket за двупосочна комуникация с ниска латентност
- Връзката е постоянна: едно отваряне за цялата разговорна сесия
- Слоевата архитектура разделя аудиото, транспорта, бизнес логиката и сървърния прокси
- В продукция прокси сървърът е от съществено значение за сигурност и контрол на разходите
- Протоколът е събитийно-ориентиран: всяко съобщение е JSON обект с поле
type