Use o SDK Node.js de voz para configurar sessões Qwen-Audio-Realtime, trocar áudio e processar transcrição e chamadas de funções.
Instalar o SDK
Requer Node.js 18 ou posterior. Baixe o pacote SDK 0.1.0 e execute no projeto:
Início rápido
Obtenha uma chave de API no console e defina-a na variável de ambiente DASHSCOPE_API_KEY.
Baixe o áudio de exemplo como input.mp3 e converta para PCM mono de 16 kHz e 16 bits:
example.mjs e execute node example.mjs.
Referência da API
Opções do construtor
Opções do construtor de RealtimeClient:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
apiKey | string | Não | Chave de API. Usa DASHSCOPE_API_KEY por padrão. |
workspaceId | string | Não | ID do espaço de trabalho. Usa DASHSCOPE_WORKSPACE_ID por padrão. |
baseUrl | string | Não | Defina o hostname como dashscope-intl.aliyuncs.com (Singapura). |
model | string | Sim | ID do modelo. |
voice | string | Não | ID da voz. Usa a voz padrão do serviço se omitida. |
instructions | string | Não | Instruções de sistema para papel, estilo e outros comportamentos. |
turnDetection | TurnDetection | null | Não | Padrão: { type: "server_vad" }. null ativa o envio manual. Também aceita smart_turn e smart_turn_v2. |
modalities | Array<'text' | 'audio'> | Não | Modalidades de saída. Padrão: ["text", "audio"]. |
maxHistoryTurns | number | Não | Turnos de histórico: [1,50]. Padrão do serviço: 20. |
tools | ToolDefinition[] | Não | Definições de ferramentas. A aplicação executa as ferramentas e valida os argumentos. |
inputTranscription | { model?: string; language?: string } | null | Não | Configuração de transcrição de entrada, como { model: "fun-asr", language: "zh" }; null desativa. |
sessionExtras | SessionConfig | Não | Configurações adicionais, como speech_rate e enable_search. Substituem as de nível superior correspondentes; consulte os campos em eventos do cliente. |
connectTimeoutMs | number | Não | Tempo limite de conexão em ms. Padrão: 10000. |
Métodos principais
| Método | Retorno | Descrição |
|---|---|---|
connect() | Promise<void> | Conecta e envia a configuração. sessionUpdated confirma a aplicação. |
updateSession(session: SessionConfig) | void | Atualiza a sessão; confirme em sessionUpdated. |
appendAudio(pcm: Buffer | Uint8Array) | void | Envia áudio PCM mono de 16 kHz e 16 bits. |
commit() | void | Confirma o buffer no modo manual. |
clearAudioBuffer() | void | Limpa o buffer ainda não confirmado. |
createResponse(response?: Record<string, unknown>) | void | Solicita uma resposta do modelo. |
cancelResponse() | void | Cancela a resposta atual mantendo a sessão. |
createConversationItem(item: ConversationItem, previousItemId?: string) | void | Adiciona histórico ou resultados. previousItemId define a posição. |
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean) | void | Envia o resultado como string. autoCreateResponse é true por padrão e solicita a próxima resposta. |
deleteConversationItem(itemId: string) | void | Exclui um item da conversa. |
retrieveConversationItem(itemId: string) | void | Consulta um item; receba-o via event. |
sendEvent(event: ClientEvent) | void | Envia um evento bruto do cliente. |
close(code?: number, reason?: string) | void | Fecha a sessão e a conexão WebSocket. |
Eventos de callback
Registre callbacks com on(event, listener). Consulte os campos completos em eventos do servidor.
| Evento | Payload | Descrição |
|---|---|---|
open | void | Conexão estabelecida e configuração inicial enviada. |
sessionCreated / sessionUpdated | ServerEvent | Criação da sessão ou confirmação da configuração. |
audio | Buffer | Trecho binário de áudio; pode ocorrer várias vezes. |
audioTranscriptDelta | { delta: string } | Texto incremental da transcrição do áudio de saída. |
outputTranscript | { transcript: string } | Transcrição completa do áudio de saída. |
textDelta / textDone | { delta: string } / { text: string } | Texto incremental ou completo na modalidade somente texto. |
inputTranscriptDelta | { text: string; stash: string } | text é texto confirmado e stash, provisório. Substitua a exibição pela combinação dos dois, sem concatenar aos anteriores. |
inputTranscript | { transcript: string } | Transcrição final do áudio de entrada. |
speechStarted / speechStopped | ServerEvent | A fala do usuário começou ou parou. |
responseCreated / responseDone | ServerEvent | Resposta iniciada ou encerrada. Verifique se responseDone.response.status é completed, cancelado ou falhou. |
functionCall | { callId: string; name: string; arguments: string } | Argumentos completos da chamada. A aplicação analisa e valida a string JSON arguments. |
ambientTranscript / ambientTranscriptCompleted | { text: string; stash: string } / { transcript: string } | Transcrição atual ou final do áudio ambiente, excluída do contexto da conversa. |
event | ServerEvent | Mensagem JSON original do serviço. |
error | DashScopeError | Erro de conexão ou serviço. |
close | { code: number; reason: string } | Notificação de fechamento da conexão subjacente. |