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

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

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

• Создавайте голосовых ассистентов в реальном времени и разговорных агентов
• Создавать приложения для преобразования речи в речь с минимальной задержкой
• Интегрируйте продвинутые разговорные функции, такие как шумоподавление и подавление эхо
• Используйте несколько моделей искусственного интеллекта (GPT-Realtime, GPT-Realtime-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-Realtime, GPT-Realtime-Mini, Phi), которая лучше всего соответствует вашим потребностям

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

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

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

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

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

Режимы сессии

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

Режим модели (LLM как главный актор)

В режиме модели модель LLM является основным актором ИИ. Вы указываете название модели и по желанию настраиваете инструменты, такие как функции или MCP-серверы.

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);

// Model mode - LLM is the main actor
const session = await client.startSession("gpt-realtime");

Режим агента (Агент как главный актёр)

В режиме агента агент Foundry является основным актором ИИ. Конфигурация агента (инструменты, инструкции, температура) управляется в портале Azure AI Foundry, а не в сессионном коде. Это идеально подходит для:

• Существующие текстовые агенты, поддерживающие голос
• Сценарии, где конфигурация агентов должна управляться централизованно
• Упрощённая интеграция без настройки во время выполнения

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);

// Agent mode - Foundry agent is the main actor
const session = await client.startSession({
  agent: {
    agentName: "my-agent",
    projectName: "my-foundry-project",
  },
});

Аутентификация с 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);

Examples

В следующих разделах представлены фрагменты кода, охватывающие некоторые распространённые задачи с использованием 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-realtime-mini");

// 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,
    prefixPaddingInMs: 300,
    silenceDurationInMs: 500,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

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

В этом примере показано, как создать голосового помощника, работающего на агенте Foundry. В режиме агента конфигурация агента управляется в портале Azure AI Foundry:

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 with an agent as the main actor
const session = await client.startSession({
  agent: {
    agentName: "your-agent-name",
    projectName: "your-foundry-project",
  },
});

// Subscribe to events - audio settings can still be configured
const subscription = session.subscribe({
  onResponseAudioDelta: async (event, context) => {
    // Handle audio from the agent
    playAudioChunk(event.delta);
  },
  onResponseTextDelta: async (event, context) => {
    console.log("Agent:", event.delta);
  },
});

// 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-realtime");

// 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,
    prefixPaddingInMs: 200,
    silenceDurationInMs: 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-realtime-mini");

// 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);
  },

  onConversationItemInputAudioTranscriptionCompleted: 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-realtime-mini");

// 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",
      });
    }
  },
});

Troubleshooting

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

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

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

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

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

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

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

Телеметрия / распределённое трассирование

VoiceLive SDK поддерживает распределённое трассирование через пакет @azure/core-tracing . Трассировка по умолчаниюno-op — диапазоны не создаются, если вы не зарегистрируете поставщика трассировки, совместимого с OpenTelemetry.

Принцип работы

При включении трассировки SDK автоматически создаёт интервалы для жизненного цикла сессии:

connect (parent span — open for the entire session lifetime)
├── send session.update
├── send conversation.item.create
├── send response.create
├── recv session.created
├── recv response.done          ← turn count incremented, token usage recorded
├── send response.cancel        ← interruption count incremented
├── recv error                  ← error event recorded
└── close                       ← session-level counters finalized

Атрибуты Span следуют семантическим конвенциям OpenTelemetry GenAI (gen_ai.system, gen_ai.operation.namegen_ai.request.model, , и др.), а также специфичным расширениям VoiceLive (gen_ai.voice.session_id, gen_ai.voice.turn_count, gen_ai.voice.audio_bytes_sent, ...). Метрики на уровне сессии агрегируются в промежутке connect после окончания сессии.

Включить трассировку (Node.js, CommonJS — рекомендую)

Для CommonJS apps используйте стандартный инструментальный мост Azure SDK:

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/instrumentation @opentelemetry/sdk-trace-node

const {
  NodeTracerProvider,
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} = require("@opentelemetry/sdk-trace-node");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { createAzureSdkInstrumentation } = require("@azure/opentelemetry-instrumentation-azure-sdk");

// 1. Configure an OpenTelemetry tracer provider
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();

// 2. Register the Azure SDK instrumentation BEFORE requiring @azure/ai-voicelive
registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()],
});

// 3. Use VoiceLive — spans are emitted automatically
const { VoiceLiveClient } = require("@azure/ai-voicelive");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new VoiceLiveClient(endpoint, new DefaultAzureCredential());
const session = client.createSession("gpt-realtime");
await session.connect(); // creates "connect" span

Включите трассировку (Node.js ESM и браузерах)

createAzureSdkInstrumentation опирается на CommonJS require-hooks и не создаёт spans при загрузке SDK как ESM (то есть "type": "module" пакеты или браузерные пакетеры, такие как Vite). Для таких сред регистрируйте минимальное Instrumenter значение прямо useInstrumenter из @azure/core-tracing:

import { useInstrumenter } from "@azure/core-tracing";
import { trace, context } from "@opentelemetry/api";

useInstrumenter({
  startSpan(name, spanOptions) {
    const ctx = spanOptions.tracingContext ?? context.active();
    const tracer = trace.getTracer(spanOptions.packageName ?? "@azure/ai-voicelive", spanOptions.packageVersion);
    const span = tracer.startSpan(name, { attributes: spanOptions.spanAttributes }, ctx);
    return {
      span: {
        end: () => span.end(),
        setStatus: (s) => { if (s.status === "error") span.setStatus({ code: 2, message: String(s.error ?? "") }); },
        setAttribute: (k, v) => span.setAttribute(k, v),
        isRecording: () => span.isRecording(),
        recordException: (e) => span.recordException(e),
      },
      tracingContext: trace.setSpan(ctx, span),
    };
  },
  withContext: (ctx, fn, ...args) => context.with(ctx, fn, undefined, ...args),
  parseTraceparentHeader: () => undefined,
  createRequestHeaders: () => ({}),
});

Это даёт пролёты, идентичные мосту CommonJS.

Полные, используемые сэмплы:

• Node.js (ESM):samples/telemetry/ — консольный экспортер и Azure Monitor вариант.
• Browser (Vite):samples/telemetry-browser/ — просмотрщик внутри страницы.

Атрибуты диапазона

SDK задаёт атрибуты следующим семантическим конвенциям GenAI:

Logging

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

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

setLogLevel("info");

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

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

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

• Сэмплы VoiceLive (JavaScript/TypeScript)
• Тестовые случаи VoiceLive

Contributing

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