Премини към основното съдържание
Български— Изберете език
Меню

Сесии, събития и жизнен цикъл

Урок 2 от 18 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Сесии, събития и жизнен цикъл
  2. Жизненият цикъл на една сесия
  3. Конфигуриране на сесия
  4. Системата от събития
  5. Обработка на грешки
  6. Ключови изводи

Обновено на 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 г. Транскрипцията на входа използваше gpt-live-transcribe, който работи само в сесия за транскрипция и не поддържа нито server_vad, нито semantic_vad. В разговорна сесия като тази, където VAD валидира всяка реплика, документацията специфицира gpt-transcribe, който транскрибира валидирани реплики и използва предишните реплики като контекст. Източници: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Сесии, събития и жизнен цикъл

Всяка WebSocket връзка към Realtime API създава сесия. Тази сесия е основната единица за управление: тя обхваща конфигурацията на модела, историята на разговора, наличните инструменти и текущото състояние на взаимодействието. Разбирането на нейния жизнен цикъл е от съществено значение за изграждането на надеждни гласови агенти.

Жизненият цикъл на една сесия

Веднага щом WebSocket връзката бъде установена, сървърът изпраща събитие session.created. Сесията преминава през няколко фази:

1

Връзка → session.created

Сървърът потвърждава сесията с уникален идентификатор и конфигурация по подразбиране.

2

Конфигурация → session.update

Вие изпращате session.update, за да дефинирате инструкции, глас, инструменти и модалности.

3

Активен разговор

Размяна на аудио и текстови събития между клиента и сървъра.

4

Затваряне → WebSocket disconnect

Сесията се унищожава, когато връзката се затвори. Никакво състояние не се запазва на сървъра.

Конфигуриране на сесия

След session.created, изпратете събитие session.update, за да конфигурирате поведението на модела. Транскрибирането на това, което потребителят казва (audio.input.transcription), е по избор: без него получавате гласа, но не и текста. languages определя очакваните езици и подобрява разпознаването:

import asyncio
import websockets
import json

async def configure_session():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        # Изчакайте session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Session created: {session_id}")

        # Конфигурирайте сесията
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "You are a French-speaking voice assistant. "
                                "Respond concisely and naturally.",
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "prefix_padding_ms": 300,
                            "silence_duration_ms": 500
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                },
                "tools": []
            }
        }))

        # Изчакайте потвърждение (други събития може да пристигнат първи)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Session updated")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Ключови параметри на сесията

Параметър Описание Препоръчителна стойност
output_modalities Изходни модалности ["audio"] (или ["text"])
audio.output.voice Глас за синтез marin, cedar, alloy, echo и др.
audio.input.turn_detection Откриване на край на речта server_vad с праг 0.5
audio.input.format Входящ аудио формат {"type": "audio/pcm", "rate": 24000}

Системата от събития

Realtime API е изцяло базиран на събития. Всяко разменено съобщение е JSON обект с поле type, което определя неговата природа. Събитията попадат в две категории:

Събития от клиента (Вие → сървър)

# Основните събития, които изпращате
client_events = {
    "session.update":              "Промяна на конфигурацията",
    "input_audio_buffer.append":   "Изпращане на аудио чънк",
    "input_audio_buffer.commit":   "Фиксиране на аудио буфера",
    "input_audio_buffer.clear":    "Изчистване на аудио буфера",
    "conversation.item.create":    "Ръчно добавяне на съобщение",
    "conversation.item.truncate":  "Съкращаване на отговор",
    "conversation.item.delete":    "Изтриване на съобщение",
    "response.create":             "Стартиране на отговор",
    "response.cancel":             "Отмяна на текущия отговор",
}

Събития от сървъра (сървър → Вие)

# Основните събития, които получавате
server_events = {
    "session.created":             "Сесията е инициализирана",
    "session.updated":             "Конфигурацията е приложена",
    "input_audio_buffer.speech_started":  "Открита е реч",
    "input_audio_buffer.speech_stopped":  "Открита е тишина",
    "conversation.item.created":   "Ново съобщение в историята",
    "response.created":            "Генерирането започна",
    "response.output_audio.delta":        "Аудио чънк от отговора",
    "response.output_audio_transcript.delta": "Транскрипционен чънк",
    "response.done":               "Отговорът приключи",
    "error":                       "Грешка",
}

Обработка на грешки

Грешките се изпращат чрез събитие от тип error. Винаги трябва да ги прихващате:

async def handle_events(ws):
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "error":
            error = event["error"]
            print(f"Error [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Грешка в конфигурацията, поправете и опитайте отново
                pass
            elif error["type"] == "server_error":
                # Проблем от страна на OpenAI, свържете се отново
                pass

        elif event_type == "session.updated":
            print("Configuration applied successfully")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Tokens used: {usage}")

Ключови изводи

  • Сесия се създава автоматично при установяване на WebSocket връзка и се унищожава при прекъсване на връзката
  • session.update конфигурира сесията след session.created; изчакайте session.updated, преди да разчитате на новата конфигурация
  • За транскрибиране на вход в разговорна сесия използвайте gpt-transcribe; gpt-live-transcribe е запазен за сесии за транскрипция
  • Протоколът е изцяло базиран на събития: всяко съобщение има type, който определя обработката му
  • Събитията от клиента управляват взаимодействието; събитията от сървъра докладват резултатите
  • Обработката на грешки е от критично значение: винаги слушайте за събития error