microsoft/azure-ai-voicelive-dotnet

Azure.AI.VoiceLive (.NET)

SDK de voz em tempo real para IA da Azure, voltado para a construção de assistentes de voz bidirecionais.

Instalação

dotnet add package Azure.AI.VoiceLive
dotnet add package Azure.Identity
dotnet add package NAudio                    # Para captura/reprodução de áudio

Versões Atuais: Estável v1.0.0, Prévia v1.1.0-beta.1

Variáveis de Ambiente

AZURE_VOICELIVE_ENDPOINT=https://<resource>.services.ai.azure.com/  # Obrigatório: endpoint do Voice Live
AZURE_VOICELIVE_MODEL=gpt-4o-realtime-preview  # Obrigatório: nome da implantação do modelo
AZURE_VOICELIVE_VOICE=en-US-AvaNeural  # Opcional: nome da voz do Voice Live
AZURE_VOICELIVE_API_KEY=<sua-chave-api>  # Necessário apenas para autenticação AzureKeyCredential
AZURE_TOKEN_CREDENTIALS=prod  # Necessário apenas se DefaultAzureCredential for usado em produção

Autenticação

Credencial de Token do Microsoft Entra

using Azure.Identity;
using Azure.AI.VoiceLive;

Uri endpoint = new Uri("https://seu-recurso.cognitiveservices.azure.com");
// Desenvolvimento local: DefaultAzureCredential. Produção: defina AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credencial_especifica>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Ou use uma credencial específica diretamente em produção:
// Veja https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);

Função Necessária: Usuário dos Serviços Cognitivos (atribua no Portal do Azure → Controle de acesso)

Chave de API

Uri endpoint = new Uri("https://seu-recurso.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("sua-chave-api");
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);

Hierarquia do Cliente

VoiceLiveClient
└── VoiceLiveSession (conexão WebSocket)
    ├── ConfigureSessionAsync()
    ├── GetUpdatesAsync() → eventos SessionUpdate
    ├── AddItemAsync() → UserMessageItem, FunctionCallOutputItem
    ├── SendAudioAsync()
    └── StartResponseAsync()

Fluxo de Trabalho Principal

1. Iniciar Sessão e Configurar

using Azure.Identity;
using Azure.AI.VoiceLive;

var endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_VOICELIVE_ENDPOINT"));
var client = new VoiceLiveClient(endpoint, new DefaultAzureCredential());

var model = "gpt-4o-mini-realtime-preview";

// Iniciar sessão
using VoiceLiveSession session = await client.StartSessionAsync(model);

// Configurar sessão
VoiceLiveSessionOptions sessionOptions = new()
{
    Model = model,
    Instructions = "Você é um assistente de IA útil. Responda naturalmente.",
    Voice = new AzureStandardVoice("en-US-AvaNeural"),
    TurnDetection = new AzureSemanticVadTurnDetection()
    {
        Threshold = 0.5f,
        PrefixPadding = TimeSpan.FromMilliseconds(300),
        SilenceDuration = TimeSpan.FromMilliseconds(500)
    },
    InputAudioFormat = InputAudioFormat.Pcm16,
    OutputAudioFormat = OutputAudioFormat.Pcm16
};

// Definir modalidades (tanto texto quanto áudio para assistentes de voz)
sessionOptions.Modalities.Clear();
sessionOptions.Modalities.Add(InteractionModality.Text);
sessionOptions.Modalities.Add(InteractionModality.Audio);

await session.ConfigureSessionAsync(sessionOptions);

2. Processar Eventos

await foreach (SessionUpdate serverEvent in session.GetUpdatesAsync())
{
    switch (serverEvent)
    {
        case SessionUpdateResponseAudioDelta audioDelta:
            byte[] audioData = audioDelta.Delta.ToArray();
            // Reproduzir áudio via NAudio ou outra biblioteca de áudio
            break;
            
        case SessionUpdateResponseTextDelta textDelta:
            Console.Write(textDelta.Delta);
            break;
            
        case SessionUpdateResponseFunctionCallArgumentsDone functionCall:
            // Tratar chamada de função (veja seção Chamada de Funções)
            break;
            
        case SessionUpdateError error:
            Console.WriteLine($"Erro: {error.Error.Message}");
            break;
            
        case SessionUpdateResponseDone:
            Console.WriteLine("\n--- Resposta completa ---");
            break;
    }
}

3. Enviar Mensagem do Usuário

await session.AddItemAsync(new UserMessageItem("Olá, você pode me ajudar?"));
await session.StartResponseAsync();

4. Chamada de Funções

// Definir função
var weatherFunction = new VoiceLiveFunctionDefinition("get_current_weather")
{
    Description = "Obter o clima atual para um determinado local",
    Parameters = BinaryData.FromString("""
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "A cidade e estado ou país"
                }
            },
            "required": ["location"]
        }
        """)
};

// Adicionar às opções da sessão
sessionOptions.Tools.Add(weatherFunction);

// Tratar chamada de função no loop de eventos
if (serverEvent is SessionUpdateResponseFunctionCallArgumentsDone functionCall)
{
    if (functionCall.Name == "get_current_weather")
    {
        var parameters = JsonSerializer.Deserialize<Dictionary<string, string>>(functionCall.Arguments);
        string location = parameters?["location"] ?? "";
        
        // Chamar serviço externo
        string weatherInfo = $"O clima em {location} está ensolarado, 75°F.";
        
        // Enviar resposta
        await session.AddItemAsync(new FunctionCallOutputItem(functionCall.CallId, weatherInfo));
        await session.StartResponseAsync();
    }
}

Opções de Voz

Tipo de Voz	Classe	Exemplo
Azure Standard	AzureStandardVoice	"en-US-AvaNeural"
Azure HD	AzureStandardVoice	"en-US-Ava:DragonHDLatestNeural"
Azure Custom	AzureCustomVoice	Voz personalizada com ID de endpoint

Modelos Suportados

Modelo	Descrição
gpt-4o-realtime-preview	GPT-4o com áudio em tempo real
gpt-4o-mini-realtime-preview	Interações leves e rápidas
phi4-mm-realtime	Multimodal com bom custo-benefício

Referência de Tipos Principais

Tipo	Propósito
VoiceLiveClient	Cliente principal para criar sessões
VoiceLiveSession	Sessão WebSocket ativa
VoiceLiveSessionOptions	Configuração da sessão
AzureStandardVoice	Provedor de voz padrão da Azure
AzureSemanticVadTurnDetection	Detecção de atividade de voz
VoiceLiveFunctionDefinition	Definição de ferramenta de função
UserMessageItem	Mensagem de texto do usuário
FunctionCallOutputItem	Resposta de chamada de função
SessionUpdateResponseAudioDelta	Evento de bloco de áudio
SessionUpdateResponseTextDelta	Evento de bloco de texto

Melhores Práticas

1. Sempre defina ambas as modalidades — Inclua Text e Audio para assistentes de voz
2. Use AzureSemanticVadTurnDetection — Proporciona fluxo de conversação natural
3. Configure uma duração de silêncio adequada — 500ms é típico para evitar cortes prematuros
4. Use a instrução using — Garante o descarte adequado da sessão
5. Trate todos os tipos de eventos — Verifique erros, áudio, texto e chamadas de função
6. Use DefaultAzureCredential — Nunca codifique chaves de API

Tratamento de Erros

if (serverEvent is SessionUpdateError error)
{
    if (error.Error.Message.Contains("Cancellation failed: no active response"))
    {
        // Erro benigno, pode ser ignorado
    }
    else
    {
        Console.WriteLine($"Erro: {error.Error.Message}");
    }
}

Configuração de Áudio

• Formato de Entrada: InputAudioFormat.Pcm16 (PCM de 16 bits)
• Formato de Saída: OutputAudioFormat.Pcm16
• Taxa de Amostragem: 24kHz recomendada
• Canais: Mono

SDKs Relacionados

SDK	Propósito	Instalação
Azure.AI.VoiceLive	Voz em tempo real (este SDK)	dotnet add package Azure.AI.VoiceLive
Microsoft.CognitiveServices.Speech	Fala para texto, texto para fala	dotnet add package Microsoft.CognitiveServices.Speech
NAudio	Captura/reprodução de áudio	dotnet add package NAudio

Links de Referência

Recurso	URL
Pacote NuGet	https://www.nuget.org/packages/Azure.AI.VoiceLive
Referência da API	https://learn.microsoft.com/dotnet/api/azure.ai.voicelive
Código Fonte no GitHub	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.VoiceLive
Início Rápido	https://learn.microsoft.com/azure/ai-services/speech-service/voice-live-quickstart