Диаризация

Как определить, кто и когда говорит, и как размечать роли говорящих.

Диаризация — это разделение аудио по говорящим: API не только распознает речь, но и определяет, какой фрагмент речи кому принадлежит. Каждому сегменту присваивается метка говорящего (например, speaker_0, speaker_1), либо его роль в диалоге.

Как включить

Передайте параметр task=diarize в запросе на POST /v1/audio/transcriptions.

curl https://api.nexara.ru/v1/audio/transcriptions \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "task=diarize" \
  -F "response_format=json"

Минимальная длительность аудио для диаризации — 3 секунды. Более короткие записи выдают ошибку 400.

Результат

В ответе каждый сегмент содержит метку говорящего в поле speaker:

{
  "task": "diarize",
  "language": "ru",
  "duration": 12.4,
  "text": "Здравствуйте! Чем могу помочь? Хочу оформить возврат.",
  "segments": [
    {
      "start": 0.0,
      "end": 2.1,
      "text": "Здравствуйте! Чем могу помочь?",
      "speaker": "speaker_0"
    },
    {
      "start": 2.5,
      "end": 5.0,
      "text": "Хочу оформить возврат.",
      "speaker": "speaker_1"
    }
  ]
}

Метки говорящих сохраняются во всех форматах вывода. Например, при response_format=text результат выглядит так:

Speaker 0: Здравствуйте! Чем могу помочь?
Speaker 1: Хочу оформить возврат.

Диаризация также работает с форматами srt, vtt и verbose_json.

Вы можете передать timestamp_granularities=['word'], чтобы получить точные временные метки слов для каждого спикера. Более подробно об этом написано на странице про временные метки.

Полезные параметры

num_speakers: если вы заранее знаете, сколько человек в записи, передайте это значение — это повысит качество диаризации. Этот параметр не гарантирует num_speakers спикеров в ответе. По умолчанию число определяется автоматически.
diarization_setting: настройка для модели диаризации - general или telephonic. telephonic лучше подходит для телефонных звонков, и в случаях, когда спикеры часто перебивают друг друга. Для всех остальных случаев general показывает более высокую точность. По умолчанию стоит general.

Многоканальное аудио

Если передавать num_speakers=2, то включается проверка похожести каналов. Если каналы разные, значит один спикер будет извлечен из одного канала, а другой — из другого. Данная настройка обеспечивает максимальное качество диаризации, но для этого нужно, чтобы телефония поддерживала режим записи звонка в два канала.

Разметка ролей (role tagging)

По умолчанию говорящие обозначаются безликими метками speaker_0, speaker_1. Разметка ролей заменяет их на понятные роли — например, Клиент и Агент.

Разметка ролей включается параметром roles и доступна только вместе с диаризацией (task=diarize). Поддерживаются три режима:

Автоматический

roles=auto — модель сама определяет и назначает подходящие роли на основе содержания разговора.

Список ролей

JSON-массив строк, например ["Клиент", "Агент"] — вы отправляете набор ролей, а модель распределяет их между говорящими.

Роли с описаниями

JSON-объект {"Клиент": "Клиент, который обратился в поддержку", "agent": "Оператор поддержки"} — фиксированные роли с описаниями, которые помогают модели точнее их распознать.

Если модель определила больше говорящих, чем было передано в списке, остальные спикеры будут помечены как неизвестные. Например, если в записи говорило 4 человека, а передано только 2 человека в списке, остальные будут помечены как unknown_1 и unknown_2.

Пример запроса с автоматической разметкой ролей:

curl https://api.nexara.ru/v1/audio/transcriptions \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -F "file=@call.mp3" \
  -F "model=whisper-1" \
  -F "task=diarize" \
  -F "roles=auto"

Пример с фиксированными ролями:

curl https://api.nexara.ru/v1/audio/transcriptions \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -F "file=@call.mp3" \
  -F "model=whisper-1" \
  -F "task=diarize" \
  -F 'roles=["Клиент", "Агент"]'

В результате метки speaker_N заменяются на назначенные роли:

{
  "task": "diarize",
  "segments": [
    {
      "start": 0.0,
      "end": 2.1,
      "text": "Здравствуйте! Чем могу помочь?",
      "speaker": "Агент"
    },
    {
      "start": 2.5,
      "end": 5.0,
      "text": "Хочу оформить возврат.",
      "speaker": "Клиент"
    }
  ]
}

Ограничения

В одном запросе можно задать не более 10 ролей.
Каждое название роли — непустая строка длиной не более 64 символов, роли не должны повторяться.
Описание роли (в режиме с описаниями) не должно превышать 500 символов.

Разметка ролей тарифицируется дополнительно к стоимости диаризации. Если разметку не удалось применить (например, в записи не оказалось говорящих), надбавка не списывается, а в ответе остаются исходные метки speaker_N. Стоимость услуги смотрите на странице тарифов.