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

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

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

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

Совет

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

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

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

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

Совет

Сведения о выборе предлагаемых языковых стандартов, использовании многоязычной модели, включению диаризации и проверке locale и speaker в ответе см. в разделе Настройка идентификации языка и диаризации для транскрипции речи.

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

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

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

  1. Перейдите на страницу функции "Речь в текст " и нажмите кнопку "Открыть на детской площадке".
  2. В верхнем раскрывающемся списке выберите быструю транскрибацию.
  3. При необходимости используйте раздел "Параметры " для изменения языка, политики ненормативной лексики и других параметров.
  4. Используйте раздел "Отправить файлы ", чтобы выбрать звуковой файл. Затем нажмите кнопку "Пуск".
  5. Просмотрите выходные данные транскрибирования на вкладке "Расшифровка ". При необходимости просмотрите выходные данные необработанного ответа API на вкладке JSON .
  6. Перейдите на вкладку "Код" , чтобы получить пример кода для использования быстрого транскрибирования в приложении.

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

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

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

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

Совет

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

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

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

Совет

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

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

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

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

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

  • Замените YourSpeechResourceKey ключом ресурса распознавания речи.
  • Замените YourResourceName на имя ресурса Speech.
  • Замените YourAudioFile путь к звуковому файлу.

Важно

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

curl --location 'https://YourResourceName.cognitiveservices.azure.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 свойство, которое должно соответствовать ожидаемому языковому стандарту звуковых данных для транскрибирования. В этом примере локаль установлена на 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 - List Supported Locales (версия API 2024-11-15 или более поздняя). Дополнительные сведения о локалях см. в документации по поддержке языков службы Речь.		 Необязательно, но рекомендуется, если вы знаете ожидаемый языковой стандарт.
phraseList Список фраз представляет собой список заранее подготовленных слов или фраз для улучшения их распознавания. Добавление фразы в список фраз увеличивает его важность, что делает его более вероятным для распознавания. Например, укажите phraseList":{"phrases":["Contoso","Jessie","Rehaan"]}. Список фраз поддерживается через API версии 2025-10-15. Дополнительные сведения см. в разделе "Улучшение точности распознавания" со списком фраз. Необязательный
profanityFilterMode Указывает способ обработки ненормативной лексики в результатах распознавания. Допустимые значения — None отключить фильтрацию ненормативной лексики, Masked заменить ненормативную лексику звездочками, Removed удалить все ненормативные выражения из результата или Tags добавить теги ненормативной лексики. Значение по умолчанию — Masked. Необязательный

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

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

предварительные требования 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}"
            )

    Справочник: TranscriptionClient | TranscriptionContent | TranscriptionOptions | 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}")

Примечание

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

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

Список фраз

Список фраз повышает точность распознавания для конкретных терминов, правильных существительных и необычных слов. Установите biasing_weight между 0.0 и 2.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=1.5,  # Weight between 0.0 and 2.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

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

  • Подписка Azure. Создайте его бесплатно.
  • набор инструментов разработки .NET 8.0 или более поздней версии.
  • Ресурс Microsoft Foundry создан в одном из поддерживаемых регионов. Дополнительные сведения о доступности регионов см. в разделе "Поддержка регионов".
  • Пример .wav звукового файла для транскрибации.

предварительные требования 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
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.CombinedPhrases.First();
Console.WriteLine(channelPhrases.Text);

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

dotnet run

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

Доступ к детальной информации о каждом слове

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

foreach (TranscribedPhrase phrase in response.Value.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);

foreach (TranscribedPhrase phrase in response.Value.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}`);
}

Справочник: ТранскрибированиеDiarizationOptions

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

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

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

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

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

  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</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. Он автоматически определяет метод, используемый на основе заданных переменных среды.

Сначала задайте конечную точку для ресурса "Речь". Замените <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, виртуальные машины).
  • Переменные среды: set 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–35). Каждая фраза в результате содержит 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()
    )
);

Примечание

Диаризация поддерживается только для одноканального (моно) аудио. Если ваш аудио стерео, не устанавливайте свойство 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