Compartilhar via

Azure VoiceLive client library for JavaScript - versão 1.0.0-beta.1

Azure VoiceLive é um serviço gerenciado que permite interações de fala de baixa latência e alta qualidade para agentes de voz. O serviço consolida reconhecimento de fala, IA generativa e funcionalidades de texto para fala em uma única interface unificada, oferecendo uma solução completa para criar experiências guiadas por voz sem falhas.

Use a biblioteca de clientes para:

  • Crie assistentes de voz em tempo real e agentes de conversação
  • Construa aplicações de fala com latência mínima
  • Integre recursos conversacionais avançados como supressão de ruído e cancelamento de eco
  • Aproveite múltiplos modelos de IA (GPT-4o, GPT-4o-mini, Phi) para diferentes casos de uso
  • Implementar chamada de função e integração de ferramentas para respostas dinâmicas
  • Crie interações de voz habilitadas por avatar com componentes visuais

Nota: Este pacote suporta tanto ambientes de navegador quanto Node.js. Conexões WebSocket são usadas para comunicação em tempo real.

Como começar

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote

Instale a biblioteca cliente Azure VoiceLive usando npm:

npm install @azure/ai-voicelive

Instalar a biblioteca de identidade

Os clientes VoiceLive autenticam usando a Azure Identity Library. Instale também:

npm install @azure/identity

Configure TypeScript

Usuários de TypeScript precisam ter definições de tipos de nó instaladas:

npm install @types/node

Você também precisa ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Note que, se você tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por padrão.

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

Conceitos principais

VoiceLiveClient

A interface principal para estabelecer conexões com o serviço Azure VoiceLive. Use esse cliente para autenticar e criar sessões para interações de voz em tempo real.

VoiceLiveSession

Representa uma conexão ativa WebSocket para comunicação de voz em tempo real. Esta classe lida com comunicação bidirecional, permitindo que você envie entrada de áudio e receba saída de áudio, transcrições de texto e outros eventos em tempo real.

Configuração da sessão

O serviço utiliza a configuração de sessão para controlar vários aspectos da interação de voz:

  • Detecção de Turno: Configure como o serviço detecta quando os usuários começam e param de falar
  • Processamento de Áudio: Habilitar supressão de ruído e cancelamento de eco
  • Seleção de Vozes: Escolha entre vozes padrão Azure, vozes em alta definição ou vozes personalizadas
  • Seleção de Modelo: Selecione o modelo de IA (variantes GPT-4o, GPT-4o-mini, Phi) que melhor atende às suas necessidades

Modelos e Capacidades

A API VoiceLive suporta múltiplos modelos de IA com diferentes capacidades:

Modelo Description Caso de Uso
gpt-4o-realtime-preview GPT-4o com processamento de áudio em tempo real IA conversacional de alta qualidade
gpt-4o-mini-realtime-preview Variante leve do GPT-4o Interações rápidas e eficientes
phi4-mm-realtime Modelo Phi com suporte multimodal Aplicações de voz com custo de baixo custo

Aprimoramentos de conversação

A API do VoiceLive oferece melhorias específicas do Azure:

  • Azure Semantic VAD: Detecção avançada de atividade vocal que remove palavras de preenchimento
  • Supressão de Ruído: Reduz o ruído de fundo ambiental
  • Cancelamento de Eco: Remove eco da própria voz do modelo
  • Detecção no Fim de Turno: Permite pausas naturais sem interrupções prematuras

Autenticação com Azure Active Directory

O serviço VoiceLive depende do Azure Active Directory para autenticar requisições em suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. O README para @azure/identity fornece mais detalhes e exemplos para você começar.

Para interagir com o serviço Azure VoiceLive, você precisa criar uma instância da VoiceLiveClient classe, um endpoint de serviço e um objeto de credencial. Os exemplos apresentados neste documento utilizam um objeto de credencial chamado DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Recomendamos o uso de uma identidade gerenciada para autenticação em ambientes de produção.

Você pode encontrar mais informações sobre diferentes formas de autenticação e seus tipos de credenciais correspondentes na documentação do Azure Identity.

Aqui vai um exemplo rápido. Primeiro, importar DefaultAzureCredential e 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);

Autenticação com Chave de API

Para cenários de desenvolvimento, você também pode autenticar usando uma chave 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);

Exemplos

As seções a seguir fornecem trechos de código que cobrem algumas das tarefas comuns usando o Azure VoiceLive. Os cenários abordados aqui consistem em:

Criando um assistente de voz básico

Este exemplo mostra como criar um assistente de voz simples que possa lidar com interações de fala para fala:

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

Configuração das opções de sessão

Você pode personalizar vários aspectos da interação de voz:

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

Gerenciamento de eventos em tempo real

O cliente VoiceLive oferece comunicação orientada a eventos para interações em tempo real:

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

Implementação da chamada de função

Ative seu assistente de voz para chamar funções e ferramentas externas:

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

Resolução de problemas

Erros e exceções comuns

Erros de Autenticação: Se você receber erros de autenticação, verifique que:

  • Seu recurso Azure AI Foundry está configurado corretamente
  • Sua chave de API ou credencial possui as permissões necessárias
  • A URL do endpoint está correta e acessível

Problemas de Conexão WebSocket: O VoiceLive utiliza conexões WebSocket. Certifique-se de que:

  • Sua rede permite conexões WebSocket
  • Regras de firewall permitem conexões a *.cognitiveservices.azure.com
  • Políticas de navegador permitem acesso ao WebSocket e microfone (para uso do navegador)

Problemas de áudio: Para problemas relacionados ao áudio:

  • Verifique as permissões do microfone no navegador
  • Verifique se formatos de áudio (PCM16, PCM24) são suportados
  • Garanta uma configuração adequada do contexto de áudio para a reprodução

Registro em log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de mensagens e respostas WebSocket, defina a AZURE_LOG_LEVEL variável de ambiente para info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode examinar os documentos do pacote de @azure/agente.

Próximas etapas

Você pode encontrar mais exemplos de código através dos seguintes links:

Contributing

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

  • Last updated on