Partilhar via

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

O Azure VoiceLive é um serviço gerido que permite interações de fala de baixa latência e alta qualidade para agentes de voz. O serviço consolida reconhecimento de voz, IA generativa e funcionalidades de texto para fala numa única interface unificada, proporcionando uma solução de ponta a ponta para criar experiências fluidas orientadas por voz.

Use a biblioteca de cliente para:

  • Criar assistentes de voz em tempo real e agentes de conversação
  • Construir aplicações de fala com latência mínima
  • Integrar funcionalidades avançadas de conversação 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 chamadas de funções e integração de ferramentas para respostas dinâmicas
  • Crie interações de voz com avatar e componentes visuais

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

Como Começar

Ambientes atualmente suportados

Pré-requisitos

Instale o pacote

Instale a biblioteca cliente Azure VoiceLive usando npm:

npm install @azure/ai-voicelive

Instalar a biblioteca de identidade

Os clientes VoiceLive autenticam-se usando a Azure Identity Library. Instala também:

npm install @azure/identity

Configure TypeScript

Os utilizadores de TypeScript precisam de ter definições de tipos de nó instaladas:

npm install @types/node

Também precisa de ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Note que se tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por defeito.

Pacote JavaScript

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

Conceitos-chave

VoiceLiveClient

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

VoiceLiveSession

Representa uma ligação WebSocket ativa para comunicação de voz em tempo real. Esta aula trata da comunicação bidirecional, permitindo-lhe enviar entrada e receber áudio, transcrições de texto e outros eventos em tempo real.

Configuração da sessão

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

  • Deteção de Turnos: Configure como o serviço deteta quando os utilizadores começam e param de falar
  • Processamento de Áudio: Ativar supressão de ruído e cancelamento de eco
  • Seleção de Vozes: Escolha entre vozes Azure padrão, 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 se adequa às suas necessidades

Modelos e Capacidades

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

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 GPT-4o Interações rápidas e eficientes
phi4-mm-realtime Modelo Phi com suporte multimodal Aplicações de voz económicas

Aprimoramentos de conversação

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

  • Azure Semantic VAD: Deteçã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 o eco da própria voz do modelo
  • Deteçã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 pedidos nas suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credenciais 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, é necessário criar uma instância da VoiceLiveClient classe, um endpoint de serviço e um objeto 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 a utilização de uma identidade gerida para autenticação em ambientes de produção.

Pode encontrar mais informações sobre as diferentes formas de autenticação e os respetivos tipos de credenciais na documentação Azure Identity.

Aqui está 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 API

Para cenários de desenvolvimento, 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);

Examples

As secções seguintes fornecem excertos de código que cobrem algumas das tarefas comuns que utilizam o Azure VoiceLive. Os cenários aqui abordados consistem em:

Criar um assistente de voz básico

Este exemplo mostra como criar um assistente de voz simples que consiga lidar com interações de voz 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 da sessão

Pode personalizar vários aspetos da interação vocal:

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

Gestão de eventos em tempo real

O cliente VoiceLive fornece comunicação orientada por 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 o 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",
      });
    }
  },
});

Solução de problemas

Erros e exceções comuns

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

  • O seu recurso Azure AI Foundry está corretamente configurado
  • A sua chave API ou credencial tem as permissões necessárias
  • O URL do endpoint está correto e acessível

Problemas de Ligação WebSocket: O VoiceLive utiliza ligações WebSocket. Certifique-se de que:

  • A sua rede permite ligações WebSocket
  • As regras de firewall permitem ligações a *.cognitiveservices.azure.com
  • As políticas do navegador permitem acesso a WebSocket e microfone (para uso do navegador)

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

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

Exploração Florestal

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo 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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Próximos passos

Pode encontrar mais exemplos de código através dos seguintes links:

Contributing

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

  • Last updated on