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

Azure VoiceLive — это управляемый сервис, обеспечивающий взаимодействие голосовых агентов с низкой задержкой и высоким качеством взаимодействия между речью и речью. Сервис объединяет распознавание речи, генеративный искусственный интеллект и функции преобразования текста в речь в единый единый интерфейс, обеспечивая сквозное решение для создания бесшовного голосового опыта.

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

Создавайте голосовых ассистентов в реальном времени и разговорных агентов
Создавать приложения для преобразования речи в речь с минимальной задержкой
Интегрируйте продвинутые разговорные функции, такие как шумоподавление и подавление эхо
Используйте несколько моделей ИИ (GPT-4o, GPT-4o-mini, Phi) для различных сценариев использования
Реализовать вызов функций и интеграцию инструментов для динамических ответов
Создавайте голосовые взаимодействия с визуальными компонентами с поддержкой аватара

Примечание: этот пакет поддерживает как браузерные, так и Node.js среды. WebSocket-соединения используются для связи в реальном времени.

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

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

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

Предпосылки

Подписка Azure
Ресурс Azure AI Foundry с доступом Voice Live API

Установите пакет

Установите клиентскую библиотеку Azure VoiceLive с помощью npm:

npm install @azure/ai-voicelive

Установите библиотеку идентичности

Клиенты VoiceLive аутентифицируются с помощью библиотеки идентификации Azure. Установите её тоже:

npm install @azure/identity

Настроить TypeScript

Пользователям TypeScript необходимо иметь установленные определения типов узлов:

npm install @types/node

Вам также нужно включить compilerOptions.allowSyntheticDefaultImports свой tsconfig.json. Обратите внимание, что если у вас включен compilerOptions.esModuleInterop, allowSyntheticDefaultImports то по умолчанию включено.

Пакет JavaScript

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

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

VoiceLiveClient

Основной интерфейс для установления соединений с сервисом Azure VoiceLive. Используйте этот клиент для аутентификации и создания сессий для голосовых взаимодействий в реальном времени.

VoiceLiveSession

Представляет собой активное WebSocket-соединение для голосовой связи в реальном времени. Этот курс охватывает двустороннюю коммуникацию, позволяя отправлять аудиовход и получать аудиовыход, текстовые транскрипции и другие события в реальном времени.

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

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

Обнаружение поворотов: настройте сервис, когда пользователи начинают и перестают говорить
Обработка звука: Включите шумоподавление и подавление эха
Выбор голосов: выбирайте между стандартными голосами Azure, голосами высокого разрешения или пользовательскими голосами
Выбор модели: Выберите модель с ИИ (GPT-4o, GPT-4o-mini, варианты Phi), которая лучше всего соответствует вашим потребностям

Модели и возможности

API VoiceLive поддерживает несколько моделей ИИ с разными возможностями:

Модель	Description	Вариант использования
`gpt-4o-realtime-preview`	GPT-4o с обработкой звука в реальном времени	Высококачественный разговорный ИИ
`gpt-4o-mini-realtime-preview`	Лёгкий вариант GPT-4o	Быстрые и эффективные взаимодействия
`phi4-mm-realtime`	Модель Phi с мультимодальной поддержкой	Экономичные голосовые приложения

Улучшения беседы

API VoiceLive предоставляет специфические для Azure улучшения:

Azure Semantic VAD: продвинутое обнаружение голосовой активности, удаляющее заполняющие слова
Шумоподавление: уменьшает фоновый шум в окружающей среде
Подавление эха: удаляет эхо из собственного голоса модели
Обнаружение конца хода: позволяет естественные паузы без преждевременных прерываний

Аутентификация с Azure Active Directory

Сервис VoiceLive использует Azure Active Directory для аутентификации запросов в свои API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. README для @azure/identity предоставляет дополнительные сведения и примеры для начала работы.

Чтобы взаимодействовать с сервисом Azure VoiceLive, необходимо создать экземпляр VoiceLiveClient класса, конечную точку сервиса и объект учетных данных. Примеры, приведённые в этом документе, используют объект учетных данных с именем DefaultAzureCredential, что подходит для большинства сценариев, включая локальные среды разработки и производства. Мы рекомендуем использовать управляемую идентичность для аутентификации в производственных средах.

Больше информации о различных способах аутентификации и соответствующих типах учетных данных можно найти в документации Azure Identity.

Вот быстрый пример. Во-первых, импорт DefaultAzureCredential и VoiceLiveClient:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();

// Build the URL to reach your AI Foundry resource
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the VoiceLive client
const client = new VoiceLiveClient(endpoint, credential);

Аутентификация с помощью ключа API

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

import { AzureKeyCredential } from "@azure/core-auth";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const endpoint = "https://your-resource.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("your-api-key");

const client = new VoiceLiveClient(endpoint, credential);

Примеры

В следующих разделах представлены фрагменты кода, охватывающие некоторые распространённые задачи с использованием Azure VoiceLive. Описанные здесь сценарии включают:

Создание базового голосового помощника
Настройка опций сессии
Обработка событий в реальном времени
Реализация вызова функций

Создание базового голосового помощника

В этом примере показано, как создать простого голосового помощника, способного обрабатывать взаимодействие речи в речь:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the client
const client = new VoiceLiveClient(endpoint, credential);

// Create and connect a session
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Configure session for voice conversation
await session.updateSession({
  modalities: ["text", "audio"],
  instructions: "You are a helpful AI assistant. Respond naturally and conversationally.",
  voice: {
    type: "azure-standard",
    name: "en-US-AvaNeural",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.5,
    prefixPaddingMs: 300,
    silenceDurationMs: 500,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

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

Вы можете настраивать различные аспекты голосового взаимодействия:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-realtime-preview");

// Advanced session configuration
await session.updateSession({
  modalities: ["audio", "text"],
  instructions: "You are a customer service representative. Be helpful and professional.",
  voice: {
    type: "azure-custom",
    name: "your-custom-voice-name",
    endpointId: "your-custom-voice-endpoint",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.6,
    prefixPaddingMs: 200,
    silenceDurationMs: 300,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

Обработка событий в реальном времени

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

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Set up event handlers using subscription pattern
const subscription = session.subscribe({
  onResponseAudioDelta: async (event, context) => {
    // Handle incoming audio chunks
    const audioData = event.delta;
    // Play audio using Web Audio API or other audio system
    playAudioChunk(audioData);
  },

  onResponseTextDelta: async (event, context) => {
    // Handle incoming text deltas
    console.log("Assistant:", event.delta);
  },

  onInputAudioTranscriptionCompleted: async (event, context) => {
    // Handle user speech transcription
    console.log("User said:", event.transcript);
  },
});

// Send audio data from microphone
function sendAudioChunk(audioBuffer: ArrayBuffer) {
  session.sendAudio(audioBuffer);
}

Реализация вызова функций

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

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Define available functions
const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state or country",
        },
      },
      required: ["location"],
    },
  },
];

// Configure session with tools
await session.updateSession({
  modalities: ["audio", "text"],
  instructions:
    "You can help users with weather information. Use the get_weather function when needed.",
  tools: tools,
  toolChoice: "auto",
});

// Handle function calls
const subscription = session.subscribe({
  onResponseFunctionCallArgumentsDone: async (event, context) => {
    if (event.name === "get_weather") {
      const args = JSON.parse(event.arguments);
      const weatherData = await getWeatherData(args.location);

      // Send function result back
      await session.addConversationItem({
        type: "function_call_output",
        callId: event.callId,
        output: JSON.stringify(weatherData),
      });

      // Request response generation
      await session.sendEvent({
        type: "response.create",
      });
    }
  },
});

Устранение неполадок

Распространенные ошибки и исключения

Ошибки аутентификации: Если вы получили ошибки аутентификации, проверьте:

Ваш ресурс Azure AI Foundry настроен корректно
Ваш API или учетная запись имеют необходимые права
URL конечной точки правильный и доступный

Проблемы с подключением к WebSocket: VoiceLive использует подключения WebSocket. Убедитесь в следующем:

Ваша сеть поддерживает подключения через WebSocket
Правила межсетевого экрана позволяют подключаться к *.cognitiveservices.azure.com
Политики браузера позволяют доступ к WebSocket и микрофону (для использования браузером)

Проблемы со звуком: Для проблем со звуком:

Проверьте разрешения микрофона в браузере
Проверьте, поддерживаются ли аудиоформаты (PCM16, PCM24)
Убедитесь, что для воспроизведения правильно настроен аудиоконтекст

Logging

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

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

setLogLevel("info");

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

Дальнейшие шаги

Больше примеров кода можно найти по следующим ссылкам:

Contributing

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

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

Была ли эта страница полезна?

Last updated on 2025-11-18