Клиентская библиотека Azure AI Speech Transcription для JavaScript — версия 1.0.0-beta.1

Клиентская библиотека Azure AI Speech Transcription предоставляет лёгкий доступ к сервису транскрипции речи в текст Azure, позволяя конвертировать аудио в текст с высокой точностью.

Использование клиентской библиотеки для:

Транскрипция аудиофайлов в текст
Поддержка нескольких языков и мест
Включите диаризацию динамиков для идентификации разных носителей
Примените фильтрацию ненормативной лексики
Используйте пользовательские модели речи
Обрабатывайте как локальные файлы, так и удалённые URL
Используйте Enhanced Mode для транскрипции и перевода на основе LLM

Ключевые ссылки:

Начало работы

Поддерживаемые в настоящее время среды

Версии Node.js LTS
Последние версии Safari, Chrome, Edge и Firefox.

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

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

Подписка Azure.
Ресурс Azure AI Speech или Azure AI Foundry.

Установите пакет `@azure/ai-speech-transcription`.

Установите клиентскую библиотеку Azure AI Speech Transcription для JavaScript с помощью npm:

npm install @azure/ai-speech-transcription

Создание и проверка подлинности `TranscriptionClient`

Чтобы создать клиентский объект для доступа к API Azure Transcription, вам понадобятся endpoint ресурсы вашего Azure Transcription и .credential Вы можете найти конечную точку вашего ресурса Azure Transcription в Azure Portal.

Вариант 1: Аутентификация ключом API

Ключ API вашего речевого ресурса можно найти в Azure Portal.

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));

Вариант 2: Аутентификация Entra ID (рекомендуется для продакшена)

Для производственных сценариев рекомендуется использовать аутентификацию Entra ID с управляемыми идентичностями или принципалами сервисов. Установите пакет @azure/identity.

npm install @azure/identity

Вам также нужно назначить соответствующую роль (например, «Пользователь когнитивных сервисов») вашей управляемой идентичности или принципалу сервиса. Для получения дополнительной информации см. аутентификация Azure AI Services.

Используя среды Node.js и node-like, можно использовать класс DefaultAzureCredential для проверки подлинности клиента.

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

const client = new TranscriptionClient("<endpoint>", new DefaultAzureCredential());

Для браузерных сред используйте InteractiveBrowserCredential из пакета @azure/identity для аутентификации.

import { InteractiveBrowserCredential } from "@azure/identity";
import { TranscriptionClient } from "@azure/ai-speech-transcription";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new TranscriptionClient("<endpoint>", credential);

Версии API сервиса

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

import { TranscriptionClient, KnownServiceApiVersions } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"), {
  serviceVersion: KnownServiceApiVersions.V20251015,
});

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. Подробнее о том, как to do это, пожалуйста, обратитесь к нашей документации по bundling.

Основные понятия

TranscriptionClient

TranscriptionClient является основным интерфейсом для разработчиков, использующих клиентскую библиотеку Azure AI Speech Transcription. Он предоставляет два перегруженных transcribe метода — один для аудиобинарных данных и другой для аудиоURL.

Форматы звука

Сервис поддерживает различные аудиоформаты, включая WAV, MP3, OGG, FLAC и другие. Аудио должно быть следующим:

Продолжительность менее 2 часов
Размер меньше 250 МБ

Варианты транскрипции

Вы можете настроить транскрипцию с помощью таких опций, как:

Фильтрация ненормативной лексики: Контролируйте, как нецензурная лексика обрабатывается в транскрипциях ("None", "Masked", "Removed", "Tags")
Диаризация динамика: Определите разные динамики в аудио с несколькими динамиками (до 36 колонок)
Списки фраз: Предоставьте фразы, специфичные для конкретных предметов, для повышения точности
Обнаружение языка: Автоматическое обнаружение разговорного языка или указание известных мест
Улучшенный режим: Улучшить качество транскрипции с помощью обработки, перевода и настройки на основе запросов на базе LLM

Примеры

Транскрипция локального аудиофайла
Транскрибировать аудио по URL
Доступ к отдельным транскрибированным словам
Идентифицировать носителей с помощью диареза
Фильтрующая ненормативная лексика
Повышайте точность с помощью пользовательских фраз
Транскрибировать на известном языке
Используйте Enhanced Mode для максимальной точности
Перевод с расширенным режимом
Комбинируйте несколько вариантов

Транскрипция локального аудиофайла

Самая простая операция — транскрибировать аудиофайл из вашей локальной файловой системы:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
console.log(`Duration: ${result.durationInMs}ms`);
console.log("Transcription:", result.combinedPhrases[0]?.text);

Транскрибировать аудио по URL

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

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const result = await client.transcribe("https://example.com/audio/sample.wav", {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Доступ к отдельным транскрибированным словам

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

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
for (const phrase of result.phrases) {
  console.log(`Phrase: ${phrase.text}`);
  console.log(
    `  Offset: ${phrase.offsetMilliseconds}ms | Duration: ${phrase.durationMilliseconds}ms`,
  );
  console.log(`  Confidence: ${phrase.confidence.toFixed(2)}`);
  // Access individual words in the phrase
  for (const word of phrase.words ?? []) {
    console.log(`    Word: '${word.text}' | Offset: ${word.offsetMilliseconds}ms`);
  }
}

Идентифицировать носителей с помощью диареза

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

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/conversation.wav");
const result = await client.transcribe(audioFile, {
  diarizationOptions: {
    maxSpeakers: 4, // Expect up to 4 speakers in the conversation
  },
});
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Примечание: общее число идентифицированных носителей никогда не превысит maxSpeakers. Если в реальном аудио больше колонок, чем указано, сервис их объединит. Установите разумную верхнюю границу, если не уверены в точном счёте.

Фильтрующая ненормативная лексика

Контролируйте, как нецензурная лексика появляется в ваших транскрипциях, используя разные режимы фильтрации:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  profanityFilterMode: KnownProfanityFilterModes.Masked, // Default - profanity replaced with asterisks
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Доступные режимы:

"None": Нет фильтрации — нецензурная лексика звучит как произнесённая
"Masked": Нецензурные слова заменены звёздочками (например, f***)
"Removed": Нецензурная лексика полностью удалена из текста
"Tags": Ненормативная лексика, упакованная в XML-теги (например, <profanity>word</profanity>)

Повышайте точность с помощью пользовательских фраз

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

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  phraseList: {
    phrases: ["Contoso", "Jessie", "Rehaan"],
  },
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Транскрибировать на известном языке

Когда вы знаете язык аудио, указание одного места повышает точность и снижает задержку:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/english-audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

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

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US", "es-ES"],
});
for (const phrase of result.phrases) {
  console.log(`[${phrase.locale}] ${phrase.text}`);
}

Используйте Enhanced Mode для максимальной точности

Расширенный режим использует обработку на базе LLM для самой высокой точности транскрипции:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  // Enhanced mode: LLM-powered speech recognition with prompt customization
  enhancedMode: {
    task: "transcribe",
    prompt: ["Output must be in lexical format."],
  },
  // Existing Fast Transcription options work alongside enhanced mode
  diarizationOptions: {
    maxSpeakers: 2,
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  activeChannels: [0, 1],
});
for (const phrase of result.phrases) {
  console.log(`[Speaker ${phrase.speaker}] ${phrase.text}`);
}

Перевод с расширенным режимом

Расширенный режим также поддерживает перевод речи на целевой язык:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/chinese-audio.wav");
const result = await client.transcribe(audioFile, {
  enhancedMode: {
    task: "translate",
    targetLanguage: "ko", // Translate to Korean
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
});
console.log("Translated to Korean:", result.combinedPhrases[0]?.text);

Комбинируйте несколько вариантов

Вы можете комбинировать несколько транскрипционных функций для сложных сценариев:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/meeting.wav");
const result = await client.transcribe(audioFile, {
  // Enable speaker diarization
  diarizationOptions: {
    maxSpeakers: 5,
  },
  // Mask profanity
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  // Add custom phrases
  phraseList: {
    phrases: ["action items", "Q4", "KPIs"],
  },
});
console.log("Full Transcript:");
console.log(result.combinedPhrases[0]?.text);
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Troubleshooting

Распространенные проблемы

Ошибки аутентификации: убедитесь, что ваш API или учетные данные Entra ID правильны и активен ли ваш ресурс речи.
Неподдерживаемый аудиоформат: убедитесь, что ваш аудио находится в поддерживаемом формате (WAV, MP3, OGG, FLAC и др.). Сервис автоматически обрабатывает определение форматов.
Медленная транскрипция: Для больших файлов убедитесь, что ваше сетевое соединение стабильное.
Плохая точность: попробуйте указать правильное место, добавить пользовательские фразы для терминов, специфичных для домена, или использовать Enhanced Mode.

Logging

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Дальнейшие действия

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

Базовая транскрипция — создание клиентов и базовая транскрипция
Варианты транскрипции — объединяют несколько функций транскрипции
Транскрипция с URL — транскрипция с удалённых URL
Enhanced Mode — транскрипция и перевод на базе LLM
Фильтрация ненормативной лексики — все режимы фильтрации ненормативной лексики
Диааризация спикера — идентификация спикера
Список фраз — пользовательский словарь
Транскрипция с помощью Locale — спецификация и обнаружение языка
Многоязычная транскрипция — многоязычный контент (предварительный просмотр)

Contributing

Если вы хотите внести вклад в эту библиотеку, пожалуйста, ознакомьтесь с руководством contributing guide чтобы узнать больше о том, как создавать и тестировать код.

Microsoft Azure SDK for JavaScript

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-16