Este tutorial descreve como usar o AOQ SDK com qwen-audio-3.1-asr-flash-streaming para implementar a entrada por voz.
Visão geral da solução
Em uma interação típica de entrada por voz, o usuário clica no botão de entrada por voz e começa a falar imediatamente. Os resultados do reconhecimento aparecem no campo de entrada em tempo real. A implementação do cliente tem os seguintes pontos principais:
- Captura imediata: Comece a capturar áudio e armazenar dados PCM no buffer assim que o botão for clicado, enquanto solicita credenciais e estabelece a conexão de forma assíncrona. A conexão leva algum tempo e o usuário pode já estar falando; por isso, armazene o áudio primeiro e envie-o depois.
- Envio em velocidade dupla: Depois que a conexão for estabelecida e o evento de modelo pronto for recebido, envie o áudio armazenado em velocidade dupla. Quando alcançar o áudio atual, passe ao envio em tempo real.
- Áudio pelo canal Data: qwen-audio-3.1-asr-flash-streaming usa o protocolo Inference (run-task / finish-task). Este cenário requer armazenar o áudio antes de enviá-lo em velocidade dupla. Use
sendDataMsgpara transmitir áudio em mensagens JSON. O servidor AOQ oferece suporte a esse formato de mensagem de áudio JSON e converte automaticamente as mensagens em dados binários para encaminhá-los ao modelo. - Resultados intermediários e finais: O modelo retorna resultados continuamente. Exiba resultados intermediários (
sentence_end: false) em tempo real e acrescente os resultados finais (sentence_end: true) ao campo de entrada.
Preparação
Pré-requisitos
- Ative o Alibaba Cloud Model Studio e obtenha uma chave de API conforme Obter e configurar uma chave de API. Guarde a chave somente no AppServer. Não a inclua no código do cliente nem a envie para o repositório de código.
- Defina
{endpoint}como{WorkspaceId}.cn-beijing.maas.aliyuncs.compara China (Pequim) ou{WorkspaceId}.ap-southeast-1.maas.aliyuncs.compara Singapura. Substitua o placeholder pelo ID real do workspace e use a chave de API da região e do workspace correspondentes. - Baixe o AOQ Client SDK mais recente em Download do SDK.
- Configure um AppServer seguindo as Etapas de autenticação AOQ do Qwen-Audio-ASR-Streaming. Antes de cada nova conexão, o cliente deve obter novas credenciais de conexão no AppServer.
Importar o SDK
Baixe o AOQ Client SDK mais recente em Download do SDK e importe o SDK da plataforma de desenvolvimento. Os exemplos de cliente a seguir usam Android. As outras plataformas usam o mesmo design de interfaces e fluxo de eventos.
- Android
- iOS
- HarmonyOS
- Linux (Python)
-
Coloque
libPluginOpus.sodo plugin Opus emapp/src/main/jniLibs/armeabi-v7a/eapp/src/main/jniLibs/arm64-v8a/, de acordo com a ABI. ColoqueAoqClientSdk-release.aaremapp/libse configure as dependências e ABIs suportadas emapp/build.gradle: -
Declare estas permissões em
AndroidManifest.xml: -
Solicite a permissão
RECORD_AUDIOem tempo de execução antes de usar o microfone.
Obter um token no AppServer
O AppServer chama a API de alocação do Model Studio e retorna o Token, SID, endpoints Relay e outras informações necessárias para o SDK estabelecer uma conexão.
| Campo de resposta | Campo do SDK |
|---|---|
aoqTokenForClient | AoqConnectConfig.token |
sid | AoqConnectConfig.sid |
clientRelayCertFingerprint | AoqConnectConfig.certFingerprint |
clientRelayEndpoints | AoqConnectConfig.relayEndpoints |
extraInfo.workspaceIdHash | AoqConnectConfig.workspaceIdHash |
Implementação do cliente

1. Criar o mecanismo e registrar callbacks
Crie uma instância de AoqClientEngine e registre os callbacks de status da conexão e mensagens Data. Envie run-task após a conexão ser estabelecida. O callback de mensagens Data trata os eventos do servidor.
2. Configurar a codificação de áudio e iniciar a captura
Configure a codificação PCM (16 kHz, mono), registre um callback de captura com setAudioFrameObserver para obter PCM e chame enableSendMediaStream(Audio, false) para desativar o envio de mídia de áudio (o áudio será enviado pelo canal Data). Por fim, chame startAudioCapture() para iniciar a captura.
Este exemplo usa a captura interna do AOQ SDK e obtém PCM por onCapturedAudioFrame. Também é possível implementar uma captura própria, por exemplo com AudioRecord no Android. Coloque o PCM na fila do buffer; a lógica de envio seguinte é a mesma.
- Forma A: Captura interna do SDK
- Forma B: Captura própria
O exemplo chama
startAudioCapture, obtém PCM por onCapturedAudioFrame e o copia para o buffer do aplicativo. Registre o callback de captura bruta AoqAudioSourceCaptured para armazenar áudio antes de a conexão ser estabelecida.3. Configurar as credenciais e faixas e estabelecer a conexão
Preencha AoqConnectConfig com as credenciais retornadas pelo AppServer. Publique as faixas Audio + Data e assine a faixa Data. A declaração de Audio é necessária à conexão, mas o envio de mídia de áudio está desativado. O áudio real é transmitido pelo canal Data.
A faixa Audio deve ser publicada: O modelo ASR exige a declaração de Audio ao conectar; caso contrário, a conexão falha. Os dados de áudio são enviados pelo canal Data em mensagens
input_audio_buffer.append, não pelo canal de mídia de áudio. Chame enableSendMediaStream(Audio, false) antes de conectar para impedir que o SDK envie automaticamente o áudio capturado.4. Enviar run-task para iniciar o reconhecimento
Após a conexão ser estabelecida, gere um novo task_id para cada rodada de entrada por voz, por exemplo com UUID.randomUUID().toString(). No callback de conexão bem-sucedida, envie o JSON abaixo usando sendDataMsg. Envie run-task uma única vez por rodada.
O evento run-task tem a estrutura abaixo. O ID de tarefa é ilustrativo; substitua-o pelo ID gerado para a rodada atual. Consulte Eventos do cliente.
sendDataMsg:
5. Enviar o áudio armazenado em velocidade dupla após task-started
Analise o JSON em onDataMsg. Mude o estado de envio para pronto somente após receber o evento abaixo para a tarefa atual.
task_id das respostas corresponde à tarefa atual. Um task-started duplicado não deve iniciar um segundo loop de envio.
Formato da mensagem de áudio: O protocolo Inference de qwen-audio-3.1-asr-flash-streaming (Eventos do cliente) define somente dois eventos de controle: run-task e finish-task. O áudio em si não é enviado como evento JSON. No canal Data AOQ, porém, o áudio deve ser enviado em mensagens JSON. Para isso, o AOQ encapsula o áudio no evento input_audio_buffer.append na camada do SDK:
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Valor fixo: input_audio_buffer.append |
event_id | string | Identificador único do evento para correlação e desduplicação |
audio | string | Dados de áudio PCM codificados em Base64 |
sendDataMsg. O servidor AOQ decodifica audio em PCM binário e o encaminha ao modelo ASR de acordo com o protocolo do modelo. O cliente não precisa tratar o encapsulamento de quadros binários. Verifique se o formato PCM (taxa de amostragem, número de canais e profundidade de bits) corresponde a format e sample_rate de run-task.
input_audio_buffer.append e envie-o por sendDataMsg:
onDataMsg. Inicie o envio de áudio ao receber task-started e analise os resultados ao receber result-generated. Consulte Eventos do servidor.
6. Tratar e exibir os resultados
result-generated carrega a frase reconhecida com campos como text e sentence_end. Exiba resultados intermediários em tempo real e acrescente os finais ao campo de entrada. Consulte Eventos do servidor para as definições.
7. Enviar finish-task para encerrar o reconhecimento
Quando o usuário encerrar a entrada, chame primeiro engine.stopAudioCapture() para parar a captura. Aguarde o envio de todo o PCM restante no buffer e envie finish-task para informar ao servidor que todo o áudio foi enviado. Consulte Eventos do cliente para as definições.
task_id deve ser o mesmo usado no run-task da rodada atual.sendDataMsg:
8. Desconectar e destruir o mecanismo
Após receber task-finished, libere os recursos conforme a seguir se não precisar reutilizar a conexão. Libere os recursos também em caso de erro ou timeout.
Notas de uso
- Aguarde
task-startedantes de enviar áudio; caso contrário, os dados serão descartados. - Envie
finish-tasksomente após esvaziar o buffer (queue.size() == 0) para que o modelo processe o último segmento de áudio. - Não desconecte imediatamente após
task-finished. A conexão pode ser reutilizada para outra tarefa com um novotask_id. - Ignore os pacotes de heartbeat (
heartbeat: true) emresult-generated; não os trate como resultados.
Cenários comuns
Várias rodadas de reconhecimento na mesma conexão
A conexão continua disponível após task-finished. O cliente pode enviar novamente run-task com outro task_id para iniciar a próxima rodada sem reconectar. Isso atende à entrada de voz contínua e reduz a latência de conexões repetidas.
Captura de áudio própria
Este exemplo usa a captura interna do AOQ SDK (startAudioCapture + onCapturedAudioFrame), mas também é possível implementar uma captura própria. Adicione PCM (16 kHz, mono, 16 bits) a PcmQueue. A lógica de envio acelerado do buffer e de transmissão seguinte é a mesma.