Используйте API быстрого транскрибирования с Azure Speech в инструменте Foundry

API быстрого транскрибирования используется для распознавания аудиофайлов с возвратом результатов синхронно и быстрее, чем в реальном времени. Используйте быстрое транскрибирование в сценариях, когда необходима транскрипция аудиозаписи как можно быстрее с прогнозируемой задержкой, например:

  • Быстрое транскрибирование звука или видео, субтитры и редактирование.
  • Заметки о собрании
  • Голосовую почту

В отличие от API пакетного транскрибирования, API быстрого транскрибирования создает только транскрибирование в форме отображения (не лексического). Форма отображения является более удобочитаемой формой транскрибирования, которая включает пунктуацию и прописную букву.

Совет

Вы также можете использовать новейшие технологии распознавания речи и перевода речи на базе LLM с помощью LLM.

Доступность компонентов

В этой таблице показаны функции транскрибирования, поддерживаемые API быстрого транскрибирования и без функции распознавания речи LLM (расширенный режим):

Функция Быстрое транскрибирование (по умолчанию) Речь LLM (улучшенная)
Транскрипция ✅ (модели транскрибирования речи) ✅ (многомодальная модель)
Перевод ❌ ✅ (многомодальная модель)
Диаризация ✅ ✅
Канал (стерео) ✅ ✅
Фильтрация ненормативной лексики ✅ ✅
Задать локаль ✅ ❌ (используйте подсказки для реализации)
Пользовательская подсказка ❌ ✅
Список фраз ✅ ❌ (используйте запрос для реализации)

Для LLM-речи используйте побуждение для направления стиля выхода вместо использования конкретных локалей или списков фраз.

Вы можете попробовать быстрое транскрибирование в Microsoft Foundry без написания кода.

Необходимые условия

Попробуйте быструю транскрипцию

  1. Войдите в Microsoft Foundry. Убедитесь, что переключатель New Foundry включен. Эти действия относятся к Foundry (new).
  2. Выберите "Сборка" в правом верхнем меню.
  3. Выберите модели на левой панели.
  4. На вкладке "Службы искусственного интеллекта" показаны модели Foundry, которые можно использовать из коробки в портале Foundry. Выберите Azure Speech — Речь в текст, чтобы открыть песочницу "Речь в текст".
  5. В верхнем раскрывающемся списке выберите быструю транскрипцию.
  6. При необходимости используйте раздел "Параметры " для изменения языка, политики ненормативной лексики и других параметров.
  7. Используйте раздел "Отправить файлы ", чтобы выбрать звуковой файл. Затем нажмите кнопку "Пуск".
  8. Просмотрите выходные данные транскрибирования на вкладке "Расшифровка ". При необходимости просмотрите выходные данные необработанного ответа API на вкладке JSON .
  9. Перейдите на вкладку "Код" , чтобы получить пример кода для использования быстрого транскрибирования в приложении.

Необходимые условия

Отправка звука

Вы можете предоставить звуковые данные для быстрого транскрибирования следующим образом:

  • Встроенная передача звука
--form 'audio=@"YourAudioFile"'
  • Звук из общедоступного URL-адреса
--form 'definition="{"audioUrl": "https://crbn.us/hello.wav"}"'

Совет

Для длинных звуковых файлов рекомендуется отправлять из общедоступного URL-адреса.

В следующих разделах в качестве примера используется загрузка встроенного аудио.

Использование API быстрого транскрибирования

Совет

Попробуйте быструю транскрипцию в портале Microsoft Foundry.

Мы узнаем, как использовать API для быстрой транскрипции (с помощью Transcriptions - Transcribe) со следующими сценариями:

  • Указанный известный языковой стандарт: транскрибировать аудиофайл с указанным языковым стандартом. Если вы знаете местоположение аудиофайла, можно указать его, чтобы повысить точность транскрибирования и минимизировать задержку.
  • Идентификация языка: транскрибирование звукового файла с помощью идентификации языка. Если вы не уверены в локали аудиофайла, вы можете включить определение языка, чтобы служба "Речь" могла идентифицировать локаль (одна локаль для каждого аудиофайла).
  • Многоязычное транскрибирование: транскрибирование аудиофайла с помощью последней многоязычной модели транскрибирования речи. Если звук содержит многоязычное содержимое, которое вы хотите непрерывно и точно расшифровывать, можно использовать последнюю модель транскрибирования речи с несколькими языками, не указывая коды языкового стандарта.
  • Diarization on: Расшифруйте аудиофайл с включенной диаризацией. Диаризация различает разных говорящих в беседе. Служба распознавания речи предоставляет сведения о том, какой докладчик говорил определенную часть транскрибированной речи.
  • Включение нескольких каналов: транскрибирование звукового файла с одним или двумя каналами. Транскрибирование с несколькими каналами полезно для аудиофайлов с несколькими каналами, например аудиофайлов с несколькими динамиками или звуковыми файлами с фоновым шумом. По умолчанию API быстрого транскрибирования объединяет все входные каналы в один канал, а затем выполняет транскрибирование. Если это не желательно, каналы могут быть транскрибированы независимо без объединения.

Сделайте POST-запрос формата multipart/form-data к эндпоинту transcriptions, вместе с звуковым файлом и параметрами тела запроса.

В следующем примере показано, как транскрибировать аудиофайл с указанной локалью. Если вы знаете языковую локаль звукового файла, вы можете указать её, чтобы повысить точность транскрибирования и уменьшить задержку.

  • Замените YourSpeechResourceKey ключом ресурса распознавания речи.
  • Замените YourServiceRegion регион ресурсов службы "Речь".
  • Замените YourAudioFile путь к звуковому файлу.

Важно

Для рекомендуемой проверки подлинности без ключа с помощью Microsoft Entra ID замените --header 'Ocp-Apim-Subscription-Key: YourSpeechResourceKey' на --header "Authorization: Bearer YourAccessToken". Дополнительные сведения о проверке подлинности без ключа см. в руководстве по управлению доступом на основе ролей .

curl --location 'https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe?api-version=2025-10-15' \
--header 'Content-Type: multipart/form-data' \
--header 'Ocp-Apim-Subscription-Key: YourSpeechResourceKey' \
--form 'audio=@"YourAudioFile"' \
--form 'definition="{
    "locales":["en-US"]}"'

Создайте определение формы в соответствии со следующими инструкциями:

Дополнительные сведения о locales и других свойствах API быстрого транскрибирования см. в разделе параметров конфигурации запроса далее в этом руководстве.

Ответ включает durationMillisecondsи offsetMillisecondsмногое другое. Свойство combinedPhrases содержит полные транскрибирования для всех выступающих.

{
    "durationMilliseconds": 182439,
    "combinedPhrases": [
        {
            "text": "Good afternoon. This is Sam. Thank you for calling Contoso. How can I help? Hi there. My name is Mary. I'm currently living in Los Angeles, but I'm planning to move to Las Vegas. I would like to apply for a loan. Okay. I see you're currently living in California. Let me make sure I understand you correctly. Uh You'd like to apply for a loan even though you'll be moving soon. Is that right? Yes, exactly. So I'm planning to relocate soon, but I would like to apply for the loan first so that I can purchase a new home once I move there. And are you planning to sell your current home? Yes, I will be listing it on the market soon and hopefully it'll sell quickly. That's why I'm applying for a loan now, so that I can purchase a new house in Nevada and close on it quickly as well once my current home sells. I see. Would you mind holding for a moment while I take your information down? Yeah, no problem. Thank you for your help. Mm-hmm. Just one moment. All right. Thank you for your patience, ma'am. May I have your first and last name, please? Yes, my name is Mary Smith. Thank you, Ms. Smith. May I have your current address, please? Yes. So my address is 123 Main Street in Los Angeles, California, and the zip code is 90923. Sorry, that was a 90 what? 90923. 90923 on Main Street. Got it. Thank you. May I have your phone number as well, please? Uh Yes, my phone number is 504-529-2351 and then yeah. 2351. Got it. And do you have an e-mail address we I can associate with this application? uh Yes, so my e-mail address is mary.a.sm78@gmail.com. Mary.a, was that a S-N as in November or M as in Mike? M as in Mike. Mike78, got it. Thank you. Ms. Smith, do you currently have any other loans? Uh Yes, so I currently have two other loans through Contoso. So my first one is my car loan and then my other is my student loan. They total about 1400 per month combined and my interest rate is 8%. I see. And you're currently paying those loans off monthly, is that right? Yes, of course I do. OK, thank you. Here's what I suggest we do. Let me place you on a brief hold again so that I can talk with one of our loan officers and get this started for you immediately. In the meantime, it would be great if you could take a few minutes and complete the remainder of the secure application online at www.contosoloans.com. Yeah, that sounds good. I can go ahead and get started. Thank you for your help. Thank you."
        }
    ],
    "phrases": [
        {
            "offsetMilliseconds": 960,
            "durationMilliseconds": 640,
            "text": "Good afternoon.",
            "words": [
                {
                    "text": "Good",
                    "offsetMilliseconds": 960,
                    "durationMilliseconds": 240
                },
                {
                    "text": "afternoon.",
                    "offsetMilliseconds": 1200,
                    "durationMilliseconds": 400
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 1600,
            "durationMilliseconds": 640,
            "text": "This is Sam.",
            "words": [
                {
                    "text": "This",
                    "offsetMilliseconds": 1600,
                    "durationMilliseconds": 240
                },
                {
                    "text": "is",
                    "offsetMilliseconds": 1840,
                    "durationMilliseconds": 120
                },
                {
                    "text": "Sam.",
                    "offsetMilliseconds": 1960,
                    "durationMilliseconds": 280
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 2240,
            "durationMilliseconds": 1040,
            "text": "Thank you for calling Contoso.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 2240,
                    "durationMilliseconds": 200
                },
                {
                    "text": "you",
                    "offsetMilliseconds": 2440,
                    "durationMilliseconds": 80
                },
                {
                    "text": "for",
                    "offsetMilliseconds": 2520,
                    "durationMilliseconds": 120
                },
                {
                    "text": "calling",
                    "offsetMilliseconds": 2640,
                    "durationMilliseconds": 200
                },
                {
                    "text": "Contoso.",
                    "offsetMilliseconds": 2840,
                    "durationMilliseconds": 440
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 3280,
            "durationMilliseconds": 640,
            "text": "How can I help?",
            "words": [
                {
                    "text": "How",
                    "offsetMilliseconds": 3280,
                    "durationMilliseconds": 120
                },
                {
                    "text": "can",
                    "offsetMilliseconds": 3440,
                    "durationMilliseconds": 120
                },
                {
                    "text": "I",
                    "offsetMilliseconds": 3560,
                    "durationMilliseconds": 40
                },
                {
                    "text": "help?",
                    "offsetMilliseconds": 3600,
                    "durationMilliseconds": 320
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 5040,
            "durationMilliseconds": 400,
            "text": "Hi there.",
            "words": [
                {
                    "text": "Hi",
                    "offsetMilliseconds": 5040,
                    "durationMilliseconds": 240
                },
                {
                    "text": "there.",
                    "offsetMilliseconds": 5280,
                    "durationMilliseconds": 160
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 5440,
            "durationMilliseconds": 800,
            "text": "My name is Mary.",
            "words": [
                {
                    "text": "My",
                    "offsetMilliseconds": 5440,
                    "durationMilliseconds": 80
                },
                {
                    "text": "name",
                    "offsetMilliseconds": 5520,
                    "durationMilliseconds": 120
                },
                {
                    "text": "is",
                    "offsetMilliseconds": 5640,
                    "durationMilliseconds": 80
                },
                {
                    "text": "Mary.",
                    "offsetMilliseconds": 5720,
                    "durationMilliseconds": 520
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        // More transcription results...
        // Redacted for brevity
        {
            "offsetMilliseconds": 180320,
            "durationMilliseconds": 680,
            "text": "Thank you for your help.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 180320,
                    "durationMilliseconds": 160
                },
                {
                    "text": "you",
                    "offsetMilliseconds": 180480,
                    "durationMilliseconds": 80
                },
                {
                    "text": "for",
                    "offsetMilliseconds": 180560,
                    "durationMilliseconds": 120
                },
                {
                    "text": "your",
                    "offsetMilliseconds": 180680,
                    "durationMilliseconds": 120
                },
                {
                    "text": "help.",
                    "offsetMilliseconds": 180800,
                    "durationMilliseconds": 200
                }
            ],
            "locale": "en-US",
            "confidence": 0.92022026
        },
        {
            "offsetMilliseconds": 181960,
            "durationMilliseconds": 280,
            "text": "Thank you.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 181960,
                    "durationMilliseconds": 200
                },
                {
                    "text": "you.",
                    "offsetMilliseconds": 182160,
                    "durationMilliseconds": 80
                }
            ],
            "locale": "en-US",
            "confidence": 0.92022026
        }
    ]
}

Примечание

Служба синтеза речи является масштабируемой. Если вы получаете код ошибки 429 (превышено число запросов), следуйте передовым методам по смягчению ограничения во время автомасштабирования.

Параметры конфигурации запроса

Ниже приведены некоторые параметры свойств для настройки транскрипции при вызове операции Транскрипция — Транскрибировать.

Свойство Описание Обязательный или необязательный
channels Список отсчитываемых от нуля индексов каналов, которые необходимо транскрибировать отдельно. Поддерживается до двух каналов, если диаризация не включена. По умолчанию API быстрого транскрибирования объединяет все входные каналы в один канал, а затем выполняет транскрибирование. Если это не желательно, каналы могут быть транскрибированы независимо без объединения.

Если вы хотите транскрибировать каналы из стереофонического звукового файла отдельно, необходимо указать [0,1], [0]или [1]. В противном случае стереофонический звук объединяется с моно и транскрибируется только один канал.

Если звук стереофонический и включена диаризация, то невозможно установить свойство channels[0,1]. Служба распознавания речи не поддерживает разделение нескольких каналов.

Для моно аудио channels свойство игнорируется, а звук всегда транскрибируется как один канал.		 Необязательный
diarization Конфигурация диаризации. Диаризация — это процесс распознавания и разделения нескольких динамиков в одном звуковом канале. Например, укажите "diarization": {"maxSpeakers": 2, "enabled": true}. Затем файл транскрипции содержит speaker запись (например, "speaker": 0 или "speaker": 1) для каждой транскрибированной фразы. Необязательный
locales Список локалей, которые должны соответствовать ожидаемой локали звуковых данных для транскрибирования.

Если вы знаете языковую локаль звукового файла, вы можете указать её, чтобы повысить точность транскрибирования и уменьшить задержку. Если указана одна локаль, эта локаль используется для транскрипции.

Но если вы не уверены в языковом стандарте, можно указать несколько языковых стандартов для использования идентификации языка. Идентификация языка может быть более точной с более детализированным списком кандидатных локалей.

Если языковой стандарт не указан, Служба распознавания речи будет использовать последнюю многоязычную модель для непрерывного транскрибирования и определения языкового стандарта.

Самые последние поддерживаемые языки можно получить с помощью REST API Transcriptions - Список поддерживаемых регионов (API версии 2024-11-15 или более поздней). Дополнительные сведения о локалях см. в документации службы речи по поддержке языков.		 Необязательно, но рекомендуется, если вы знаете предполагаемую локаль.
phraseList Список фраз — это список слов или фраз, предоставляемых заранее, чтобы улучшить их распознавание. Добавление фразы в список фраз увеличивает его важность, что делает его более вероятным для распознавания. Например, укажите phraseList":{"phrases":["Contoso","Jessie","Rehaan"]}. Список фраз поддерживается через API версии 2025-10-15. Дополнительные сведения см. в разделе "Улучшение точности распознавания" со списком фраз. Необязательный
profanityFilterMode Указывает способ обработки ненормативной лексики в результатах распознавания. Допустимые значения — None отключить фильтрацию ненормативной лексики, Masked заменить ненормативную лексику звездочками, Removed удалить все ненормативные выражения из результата или Tags добавить теги ненормативной лексики. Значение по умолчанию — Masked. Необязательный

документация Reference | Package (PyPi) | GitHub Samples

Необходимые условия

предварительные требования Microsoft Entra ID

Для рекомендуемой проверки подлинности без ключа с помощью Microsoft Entra ID необходимо:

  • Установите Azure CLI, который используется для безключевой аутентификации в Microsoft Entra ID.
  • Назначьте Cognitive Services User роль вашей учетной записи пользователя. Роли можно назначить на портале Azure в разделе Access control (IAM)>Add role assignment.

Установка

  1. Создайте новую папку с именем transcription-quickstart и перейдите в папку быстрого запуска с помощью следующей команды:

    mkdir transcription-quickstart && cd transcription-quickstart

  2. Создайте и активируйте виртуальную среду Python для установки пакетов, необходимых для этого руководства. Мы рекомендуем всегда использовать виртуальную или конда-среду при установке пакетов Python. В противном случае можно разорвать глобальную установку Python. Если у вас уже установлена Python 3.9 или более поздней версии, создайте виртуальную среду с помощью следующих команд:

    py -3 -m venv .venv
.venv\Scripts\Activate.ps1

    При активации среды Python выполнение python или pip из командной строки использует интерпретатор Python в папке .venv приложения. Используйте команду deactivate для выхода из виртуальной среды Python. При необходимости его можно повторно активировать.

  3. Создайте файл с именемrequirements.txt. Добавьте в файл следующие пакеты:

    azure-ai-transcription
azure-identity

  4. Установите пакеты:

    pip install -r requirements.txt

Получение сведений о ресурсе

Для проверки подлинности необходимо получить конечную точку ресурса и ключ API.

  1. Войдите на портал Foundry.

  2. Выберите центр управления в меню слева. В разделе Подключенные ресурсы выберите ресурс для работы с речью или многосервисный ресурс.

  3. Выберите ключи и конечную точку.

  4. Скопируйте значения конечной точки и ключа . Используйте эти значения для задания переменных среды.

  5. Задайте следующие переменные среды:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"
$env:AZURE_SPEECH_API_KEY="<your-api-key>"

Примечание

Для проверки подлинности Microsoft Entra ID (рекомендуется для рабочей среды), установите azure-identity и настройте проверку подлинности, как описано в разделе Microsoft Entra ID предварительные требования.

Код

  1. Создайте файл с именем transcribe_audio_file.py со следующим кодом:

    import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]
api_key = os.environ["AZURE_SPEECH_API_KEY"]

# Create the transcription client
client = TranscriptionClient(endpoint=endpoint, credential=AzureKeyCredential(api_key))

# Path to your audio file (replace with your own file path)
audio_file_path = "<path-to-your-audio-file.wav>"

# Open and read the audio file
with open(audio_file_path, "rb") as audio_file:
    # Create transcription options
    options = TranscriptionOptions(locales=["en-US"])  # Specify the language

    # Create the request content
    request_content = TranscriptionContent(definition=options, audio=audio_file)

    # Transcribe the audio
    result = client.transcribe(request_content)

    # Print the transcription result
    print(f"Transcription: {result.combined_phrases[0].text}")

    # Print detailed phrase information
    if result.phrases:
        print("\nDetailed phrases:")
        for phrase in result.phrases:
            print(
                f"  [{phrase.offset_milliseconds}ms - "
                f"{phrase.offset_milliseconds + phrase.duration_milliseconds}ms]: "
                f"{phrase.text}"
            )

    Справочник. ТранскрипцияClient | ТранскрипцияContent | ТранскрипцияOptions | AzureKeyCredential

  2. Замените <path-to-your-audio-file.wav> путь к звуковому файлу. Служба поддерживает WAV, MP3, FLAC, OGG и другие распространенные звуковые форматы.

  3. Запустите скрипт Python:

    python transcribe_audio_file.py

Выход

Скрипт выводит результат транскрибирования в консоль:

Transcription: Hi there! This is a sample voice recording created for speech synthesis testing. The quick brown fox jumps over the lazy dog. Just a fun way to include every letter of the alphabet. Numbers, like 1, 2, 3, are spoken clearly. Let's see how well this voice captures tone, timing, and natural rhythm. This audio is provided by samplefiles.com.

Detailed phrases:
  [40ms - 4880ms]: Hi there! This is a sample voice recording created for speech synthesis testing.
  [5440ms - 8400ms]: The quick brown fox jumps over the lazy dog.
  [9040ms - 12240ms]: Just a fun way to include every letter of the alphabet.
  [12720ms - 16720ms]: Numbers, like 1, 2, 3, are spoken clearly.
  [17200ms - 22000ms]: Let's see how well this voice captures tone, timing, and natural rhythm.
  [22480ms - 25920ms]: This audio is provided by samplefiles.com.

Параметры конфигурации запроса

Используется TranscriptionOptions для настройки поведения транскрибирования. В следующих разделах описана каждая поддерживаемая конфигурация и показано, как применить ее.

Обнаружение нескольких языков

Передайте несколько кандидатов локалей в locales для включения идентификации языка. Служба определяет, какой язык используется, и помечает каждую фразу обнаруженной локалью. Опустить locales полностью, чтобы служба автоматически обнаруживла все языки без списка кандидатов.

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    # Provide candidate locales — the service selects the best match per phrase
    options = TranscriptionOptions(locales=["en-US", "es-ES", "fr-FR", "de-DE"])
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    for phrase in result.phrases:
        locale = phrase.locale if phrase.locale else "detected"
        print(f"[{locale}] {phrase.text}")

Ссылка: TranscriptionOptions

Диаризация динамиков

Diarization обнаруживает и метки разных динамиков в одном звуковом канале. TranscriptionDiarizationOptions Создайте объект с максимальным ожидаемым количеством спикеров (2–35) и передайте его в TranscriptionOptions. Каждая фраза в результате содержит speaker идентификатор.

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import (
    TranscriptionContent,
    TranscriptionOptions,
    TranscriptionDiarizationOptions,
)

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    diarization_options = TranscriptionDiarizationOptions(
        max_speakers=5  # Hint for maximum number of speakers (2-35)
    )
    options = TranscriptionOptions(
        locales=["en-US"], diarization_options=diarization_options
    )
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    for phrase in result.phrases:
        speaker = phrase.speaker if phrase.speaker is not None else "Unknown"
        print(f"Speaker {speaker} [{phrase.offset_milliseconds}ms]: {phrase.text}")

Примечание

Diarization поддерживается только в одноканальном (моно) аудиофайле. Если ваш звук в формате стерео, не устанавливайте свойство channels в значение [0, 1], если включена диаризация.

Справочник: TranscriptionDiarizationOptions, TranscriptionOptions

Список фраз

Список фраз повышает точность распознавания для конкретных терминов, правильных существительных и необычных слов. Установите biasing_weight между 1.0 и 20.0 чтобы контролировать, насколько сильно фразы благоприятны (более высокие значения увеличивают предвзятость).

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import (
    TranscriptionContent,
    TranscriptionOptions,
    PhraseListProperties,
)

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    phrase_list = PhraseListProperties(
        phrases=["Contoso", "Jessie", "Rehaan"],
        biasing_weight=5.0,  # Weight between 1.0 and 20.0
    )
    options = TranscriptionOptions(locales=["en-US"], phrase_list=phrase_list)
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    print(result.combined_phrases[0].text)

Дополнительные сведения см. в разделе "Улучшение точности распознавания" со списком фраз.

Справочник: PhraseListProperties, TranscriptionOptions

Фильтрация ненормативной лексики

Контролируйте отображение ненормативной лексики в результатах транскрипции с помощью параметра profanity_filter_mode. Доступны следующие режимы:

Режим Поведение
"None" Ненормативная лексика проходит без изменений.
"Masked" Ненормативность заменяется звездочками (по умолчанию).
"Removed" Ненормативная лексика полностью удаляется из выходных данных.
"Tags" Ненормативность упаковывается в <profanity> XML-теги. 
from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    options = TranscriptionOptions(
        locales=["en-US"],
        profanity_filter_mode="Masked"  # Options: "None", "Removed", "Masked", "Tags"
    )
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    print(result.combined_phrases[0].text)

Ссылка: TranscriptionOptions

справочная документация Пакет (NuGet)примеры GitHub

Необходимые условия

предварительные требования Microsoft Entra ID

Для рекомендуемой проверки подлинности без ключа с помощью Microsoft Entra ID необходимо:

  • Установите Azure CLI, который используется для безключевой аутентификации в Microsoft Entra ID.
  • Войдите с помощью Azure CLI, выполнив az login.
  • Назначьте Cognitive Services User роль вашей учетной записи пользователя. Роли можно назначить на портале Azure в разделе Access control (IAM)>Add role assignment.

Настройка проекта

  1. Создайте консольное приложение с помощью интерфейса командной строки .NET:

    dotnet new console -n transcription-quickstart
cd transcription-quickstart

  2. Установите необходимые пакеты:

    dotnet add package Azure.AI.Speech.Transcription --prerelease
dotnet add package Azure.Identity

Получение сведений о ресурсе

Для аутентификации необходимо получить конечную точку ресурса.

  1. Войдите на портал Foundry.

  2. Выберите центр управления в меню слева. В разделе Подключенные ресурсы выберите ресурс для работы с речью или многосервисный ресурс.

  3. Выберите ключи и конечную точку.

  4. Скопируйте значение конечной точки и задайте его в качестве переменной среды:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Транскрибирование звука

Замените содержимое Program.cs следующим кодом:

using System;
using System.ClientModel;
using System.Linq;
using System.Threading.Tasks;
using Azure.AI.Speech.Transcription;
using Azure.Identity;

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_SPEECH_ENDPOINT")
    ?? throw new InvalidOperationException("Set the AZURE_SPEECH_ENDPOINT environment variable."));

// Use DefaultAzureCredential for keyless authentication (recommended).
// To use an API key instead, replace with:
// ApiKeyCredential credential = new ApiKeyCredential("<your-api-key>");
var credential = new DefaultAzureCredential();
TranscriptionClient client = new TranscriptionClient(endpoint, credential);

string audioFilePath = "<path-to-your-audio-file.wav>";
using FileStream audioStream = File.OpenRead(audioFilePath);

TranscriptionOptions options = new TranscriptionOptions(audioStream);
ClientResult<TranscriptionResult> response = await client.TranscribeAsync(options);

var channelPhrases = response.Value.PhrasesByChannel.First();
Console.WriteLine(channelPhrases.Text);

Запустите приложение:

dotnet run

Транскрибированные тексты из звукового файла печатаются в консоли.

Доступ к деталям на уровне слов

Чтобы получить доступ к меткам времени, оценке достоверности и отдельным словам, выполните итерацию по фразам:

var channelPhrases = response.Value.PhrasesByChannel.First();

foreach (TranscribedPhrase phrase in channelPhrases.Phrases)
{
    Console.WriteLine($"\nPhrase: {phrase.Text}");
    Console.WriteLine($"  Offset: {phrase.Offset} | Duration: {phrase.Duration}");
    Console.WriteLine($"  Confidence: {phrase.Confidence:F2}");

    foreach (TranscribedWord word in phrase.Words)
    {
        Console.WriteLine(
            $"    Word: '{word.Text}' | " +
            $"Confidence: {word.Confidence:F2} | " +
            $"Offset: {word.Offset}");
    }
}

Справочник: TranscribedPhrase, TranscribedWord

Идентификация спикеров с диаризацией

Диаризация динамиков определяет, кто говорил при использовании аудио с несколькими динамиками:

TranscriptionOptions options = new TranscriptionOptions(audioStream)
{
    DiarizationOptions = new TranscriptionDiarizationOptions
    {
        MaxSpeakers = 4
    }
};

ClientResult<TranscriptionResult> response = await client.TranscribeAsync(options);

var channelPhrases = response.Value.PhrasesByChannel.First();
foreach (TranscribedPhrase phrase in channelPhrases.Phrases)
{
    Console.WriteLine($"Speaker {phrase.Speaker}: {phrase.Text}");
}

Ссылка: TranscriptionDiarizationOptions

Справочная документация | Пакет (npm) | Примеры GitHub

Необходимые условия

предварительные требования Microsoft Entra ID

Для рекомендуемой проверки подлинности без ключа с помощью Microsoft Entra ID необходимо:

  • Установите Azure CLI, который используется для безключевой аутентификации в Microsoft Entra ID.
  • Войдите с помощью Azure CLI, выполнив az login.
  • Назначьте Cognitive Services User роль вашей учетной записи пользователя. Роли можно назначить на портале Azure в разделе Access control (IAM)>Add role assignment.

Настройка проекта

  1. Создайте папку и инициализируйте проект Node.js:

    mkdir transcription-quickstart
cd transcription-quickstart
npm init -y

  2. Установите необходимые пакеты:

    npm install @azure/ai-speech-transcription @azure/identity

  3. Настройте проект для использования модулей ES, добавив тип модуля в ваш package.json:

    npm pkg set type=module

    Или вручную добавьте "type": "module" в package.json файл. Это необходимо для того, чтобы import операторы в примере кода работали.

Получение сведений о ресурсе

Для аутентификации необходимо получить конечную точку ресурса.

  1. Войдите на портал Foundry.

  2. Выберите центр управления в меню слева. В разделе Подключенные ресурсы выберите ресурс для работы с речью или многосервисный ресурс.

  3. Выберите ключи и конечную точку.

  4. Скопируйте значение конечной точки и задайте его в качестве переменной среды:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Транскрибирование звука

  1. Создайте файл с именем transcribe-audio-file.js со следующим кодом:

    import { readFileSync } from "node:fs";
import { DefaultAzureCredential } from "@azure/identity";
import { TranscriptionClient } from "@azure/ai-speech-transcription";

const endpoint = process.env.AZURE_SPEECH_ENDPOINT;
if (!endpoint) {
  throw new Error("Set the AZURE_SPEECH_ENDPOINT environment variable.");
}

// Use DefaultAzureCredential for keyless authentication (recommended).
const client = new TranscriptionClient(endpoint, new DefaultAzureCredential());

const audioFile = readFileSync("<path-to-your-audio-file.wav>");

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
});

console.log("Transcription:", result.combinedPhrases[0]?.text ?? "No text");

    Референс: TranscriptionClient | DefaultAzureCredential

  2. Замените <path-to-your-audio-file.wav> путь к звуковому файлу.

  3. Запустите приложение:

    node transcribe-audio-file.js

Выход

Приложение выводит транскрибированные тексты в консоль:

Transcription: Hi there! This is a sample voice recording.

Распространенные параметры запроса

Идентификация спикеров с диаризацией

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  diarizationOptions: {
    maxSpeakers: 4,
  },
});

for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Справочник: ТранскрибированиеОпцииДиаризации

Настройка фильтрации ненормативной лексики

import {
  KnownProfanityFilterModes,
} from "@azure/ai-speech-transcription";

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  profanityFilterMode: KnownProfanityFilterModes.Masked,
});

Справочник: KnownProfanityFilterModes

Добавление списка фраз

Используйте список фраз для улучшения распознавания терминов, правильных существительных и акронимов:

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  phraseList: {
    phrases: ["Contoso", "Jessie", "Rehaan"],
  },
});

console.log("Transcription:", result.combinedPhrases[0]?.text ?? "No text");

Справочник: PhraseListProperties

Включение многоязычного обнаружения

Если вы не уверены, какой язык используется, передайте несколько возможных локалей. Сервис определяет язык и возвращает региональные параметры для каждой фразы.

const result = await client.transcribe(audioFile, {
  locales: ["en-US", "es-ES"],
});

for (const phrase of result.phrases) {
  console.log(`[${phrase.locale}] ${phrase.text}`);
}

Справочник: TranscribedPhrase

документация Reference | Package (Maven) | GitHub Samples

Необходимые условия

Настройка среды

  1. Создайте новую папку с именем transcription-quickstart и перейдите к ней:

    mkdir transcription-quickstart && cd transcription-quickstart

  2. pom.xml Создайте файл в корневом каталоге проекта со следующим содержимым:

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>transcription-quickstart</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>Speech Transcription Quickstart</name>
    <description>Quickstart sample for Azure Speech Transcription client library.</description>
    <url>https://github.com/Azure/azure-sdk-for-java</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-ai-speech-transcription</artifactId>
            <version>1.0.0-beta.2</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.18.1</version>
        </dependency>
    </dependencies>

    <build>
        <sourceDirectory>.</sourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <mainClass>TranscriptionQuickstart</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

    Примечание

    Конфигурация <sourceDirectory>.</sourceDirectory> указывает Maven искать Java исходные файлы в текущем каталоге вместо структуры src/main/java по умолчанию. Это изменение конфигурации позволяет упростить структуру неструктурированного проекта.

  3. Установите необходимые зависимости:

    mvn clean install

Задание переменных среды

Приложение должно пройти проверку подлинности для доступа к службе "Речь". Пакет SDK поддерживает как проверку подлинности с помощью ключа API, так и Microsoft Entra ID. Он автоматически определяет метод, используемый на основе заданных переменных среды.

Сначала задайте конечную точку для ресурса распознавания речи. Замените <your-speech-endpoint> фактическим именем ресурса:

$env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Затем выберите один из следующих методов проверки подлинности:

Задайте переменную среды ключа API:

$env:AZURE_SPEECH_API_KEY="<your-speech-key>"

Вместо параметра AZURE_SPEECH_API_KEYнастройте один из следующих источников учетных данных:

  • Azure CLI: запустите az login на компьютере разработки.
  • Managed Identity: для приложений, работающих в Azure (служба приложений, Функции Azure, виртуальные машины).
  • Переменные среды: установите AZURE_TENANT_ID, AZURE_CLIENT_ID, и AZURE_CLIENT_SECRET.
  • Visual Studio Code или IntelliJ: войдите через интегрированную среду разработки.

Вам также необходимо назначить роль Cognitive Services User вашему удостоверению:

az role assignment create --assignee <your-identity> \
    --role "Cognitive Services User" \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<speech-resource-name>

Примечание

После задания переменных среды в Windows перезапустите все запущенные программы, которые должны читать их, включая окно консоли. В Linux или macOS запустите source ~/.bashrc (или эквивалентный файл конфигурации оболочки), чтобы внести изменения в силу.

Создание приложения

Создайте файл с именем TranscriptionQuickstart.java в каталоге проекта с помощью следующего кода:

import com.azure.ai.speech.transcription.TranscriptionClient;
import com.azure.ai.speech.transcription.TranscriptionClientBuilder;
import com.azure.ai.speech.transcription.models.AudioFileDetails;
import com.azure.ai.speech.transcription.models.TranscriptionOptions;
import com.azure.ai.speech.transcription.models.TranscriptionResult;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TranscriptionQuickstart {
    public static void main(String[] args) {
        try {
            // Get credentials from environment variables
            String endpoint = System.getenv("AZURE_SPEECH_ENDPOINT");
            String apiKey = System.getenv("AZURE_SPEECH_API_KEY");

            // Create client with API key or Entra ID authentication
            TranscriptionClientBuilder builder = new TranscriptionClientBuilder()
                .endpoint(endpoint);

            TranscriptionClient client;
            if (apiKey != null && !apiKey.isEmpty()) {
                // Use API key authentication
                client = builder.credential(new KeyCredential(apiKey)).buildClient();
            } else {
                // Use Entra ID authentication
                client = builder.credential(new DefaultAzureCredentialBuilder().build()).buildClient();
            }

            // Load audio file
            String audioFilePath = "<path-to-your-audio-file.wav>";
            byte[] audioData = Files.readAllBytes(Paths.get(audioFilePath));

            // Create audio file details
            AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));

            // Transcribe
            TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
            TranscriptionResult result = client.transcribe(options);

            // Print result
            System.out.println("Transcription:");
            result.getCombinedPhrases().forEach(phrase ->
                System.out.println(phrase.getText())
            );

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Замените <path-to-your-audio-file.wav> путь к звуковому файлу.

Запуск приложения

Запустите приложение с помощью Maven:

mvn compile exec:java

Параметры конфигурации запроса

Используется TranscriptionOptions для настройки поведения транскрибирования. В следующих разделах описана каждая поддерживаемая конфигурация и показано, как применить ее.

Обнаружение нескольких языков

Если языковой стандарт не указан, служба автоматически обнаруживает и транскрибирует все языки, присутствующие в звуке. Каждая возвращаемая фраза содержит locale поле, определяющее обнаруженный язык.

// No locale specified — service auto-detects all languages in the audio
TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
TranscriptionResult result = client.transcribe(options);

// Each phrase reports the detected locale
result.getPhrases().forEach(phrase ->
    System.out.println(phrase.getLocale() + ": " + phrase.getText())
);

Примечание

Если языковой стандарт не указан, locale поле отдельных фраз может не всегда точно отражать точный язык конкретной фразы. Для максимальной точности укажите ожидаемый языковой стандарт, если он вам известен.

Справочник: TranscriptionOptions, TranscribedPhrase.getLocale()

Диаризация динамиков

Diarization обнаруживает и метки разных динамиков в одном звуковом канале. Используется TranscriptionDiarizationOptions для включения и задания максимального ожидаемого количества динамиков (2–36). Каждая фраза в результате содержит speaker идентификатор.

import com.azure.ai.speech.transcription.models.TranscriptionDiarizationOptions;

// Configure diarization with a maximum of 5 speakers
TranscriptionDiarizationOptions diarizationOptions =
    new TranscriptionDiarizationOptions()
        .setMaxSpeakers(5);

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setDiarizationOptions(diarizationOptions);

TranscriptionResult result = client.transcribe(options);

// Each phrase includes the detected speaker ID
result.getPhrases().forEach(phrase ->
    System.out.println(
        "[Speaker " + phrase.getSpeaker() + "] " + phrase.getText()
    )
);

Примечание

Diarization поддерживается только в одноканальном (моно) аудиофайле. Если ваш звук в формате стерео, не устанавливайте свойство channels в значение [0,1], если включена диаризация.

Справочник: TranscriptionDiarizationOptions, TranscriptionOptions.setDiarizationOptions()TranscribedPhrase.getSpeaker()

Список фраз

Список фраз повышает точность распознавания для конкретных терминов, правильных существительных и необычных слов. Добавляемые фразы в значительной степени взвешиваются распознавателем, что увеличивает вероятность их правильной транскрипции.

import com.azure.ai.speech.transcription.models.PhraseListOptions;
import java.util.Arrays;

// Add terms that appear in your audio to improve recognition
PhraseListOptions phraseListOptions = new PhraseListOptions()
    .setPhrases(Arrays.asList("Contoso", "Jessie", "Rehaan"));

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setPhraseListOptions(phraseListOptions);

TranscriptionResult result = client.transcribe(options);

result.getCombinedPhrases().forEach(phrase ->
    System.out.println(phrase.getText())
);

Дополнительные сведения см. в разделе "Улучшение точности распознавания" со списком фраз.

Справочник: PhraseListOptions, TranscriptionOptions.setPhraseListOptions()

Фильтрация ненормативной лексики

Настройте отображение ненормативной лексики в выходных данных транскрибирования с помощью ProfanityFilterMode. Доступны следующие режимы:

Режим Поведение
NONE Ненормативная лексика проходит без изменений.
MASKED Ненормативность заменяется звездочками (по умолчанию).
REMOVED Ненормативная лексика полностью удаляется из выходных данных.
TAGS Ненормативность упаковывается в XML-теги. 
import com.azure.ai.speech.transcription.models.ProfanityFilterMode;

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setProfanityFilterMode(ProfanityFilterMode.MASKED);

TranscriptionResult result = client.transcribe(options);

System.out.println(result.getCombinedPhrases().get(0).getText());

Справочник: ProfanityFilterMode, TranscriptionOptions.setProfanityFilterMode()

Очистка ресурсов

Когда вы закончите работу с быстрым стартом, вы можете удалить папку проекта.

rm -rf transcription-quickstart

Обработка ошибок транскрибирования

При вызове API быстрого транскрибирования реализуйте логику повторных попыток для обработки временных ошибок и ограничения скорости. API применяет ограничения скорости, что может привести к ошибке во время операций с высоким параллелизмом.

  • Повторите попытку до пяти раз при временных ошибках.

  • Используйте экспоненциальный отступ: 2 секунды, 4 с, 8 с, 16 с, 32 с.

  • Общее время отката: 62 с.

Эта конфигурация предоставляет достаточно времени для восстановления API в интервалах ограничения скорости, особенно при выполнении пакетных операций с несколькими параллельными рабочими.

Когда следует использовать логику повторных попыток

Реализуйте логику повторных попыток для следующих категорий ошибок:

  • Ошибки HTTP — повторите попытку в:

    • HTTP 429 (ограничение скорости)
    • HTTP 500, 502, 503, 504 (ошибки сервера)
    • status_code=None (неполные загрузки данных ответов)

  • Azure SDK сетевые ошибки — повторите попытку:

    • ServiceRequestError
    • ServiceResponseError

    Эти ошибки перехватывают исключения сети низкого уровня, такие как urllib3.exceptions.ReadTimeoutError, сброс соединения и сбои TLS.

  • Python сетевые исключения — повторить при:

    • ConnectionError
    • TimeoutError
    • OSError

Не повторяйте следующие ошибки, так как они указывают на проблемы на стороне клиента, требующие исправления:

  • HTTP 400 (недопустимый запрос)
  • HTTP 401 (несанкционированный)
  • HTTP 422 (необрабатываемый объект)
  • Другие ошибки клиента (коды состояния 4xx)

Заметки о реализации

  • Сбросьте поток аудиофайла (seek(0)) перед каждой попыткой повтора.

  • При использовании параллельных рабочих ролей время ожидания чтения HTTP по умолчанию (300 секунд) может быть превышено при ограничении высокой скорости.

  • API может принять запрос, но истекло время ожидания при создании ответа. Это условие может отображаться как ошибка, упаковаемая в пакет SDK, а не стандартная ошибка HTTP.

Связанное содержимое

  • Last updated on