Skip to main content

Usar AOQ com qwen-audio-3.1-asr-flash-streaming para entrada por voz

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:
  1. 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.
  2. 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.
  3. Á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 sendDataMsg para 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.
  4. 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

  1. 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.
  2. Defina {endpoint} como {WorkspaceId}.cn-beijing.maas.aliyuncs.com para China (Pequim) ou {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com para Singapura. Substitua o placeholder pelo ID real do workspace e use a chave de API da região e do workspace correspondentes.
  3. Baixe o AOQ Client SDK mais recente em Download do SDK.
  4. 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)
  1. Coloque libPluginOpus.so do plugin Opus em app/src/main/jniLibs/armeabi-v7a/ e app/src/main/jniLibs/arm64-v8a/, de acordo com a ABI. Coloque AoqClientSdk-release.aar em app/libs e configure as dependências e ABIs suportadas em app/build.gradle:
    android {
        defaultConfig {
            minSdk 21
            ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }
        }
    }
    
    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.aar'])
    }
    
  2. Declare estas permissões em AndroidManifest.xml:
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    
  3. Solicite a permissão RECORD_AUDIO em 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.
curl -X POST \
  "https://{endpoint}/api/v1/webrtc/inference?model=qwen-audio-3.1-asr-flash-streaming" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "x-dashscope-rtc-transport: moq" \
  -d "{\"clientIp\": \"${CLIENT_REAL_IP}\"}"
Campo de respostaCampo do SDK
aoqTokenForClientAoqConnectConfig.token
sidAoqConnectConfig.sid
clientRelayCertFingerprintAoqConnectConfig.certFingerprint
clientRelayEndpointsAoqConnectConfig.relayEndpoints
extraInfo.workspaceIdHashAoqConnectConfig.workspaceIdHash

Implementação do cliente

Sequência do cliente de entrada por voz
As etapas abaixo usam Android e seguem a ordem de implementação. As outras plataformas usam o mesmo design de interfaces e fluxo de eventos.

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.
// Create the engine
AoqClientEngine.AoqCreateConfig create = new AoqClientEngine.AoqCreateConfig();
create.workDir = getCacheDir().getAbsolutePath();
engine = AoqClientEngine.createEngine(this, create, new AoqClientListener() {
    @Override
    public void onConnectionStatusChange(
            @NonNull AoqClientEngine.AoqConnectionStatus state) {
        if (state == AoqClientEngine.AoqConnectionStatus.AoqConnectionStatusConnected) {
            // Connected: send run-task (see step 4)
        }
    }

    @Override
    public void onDataMsg(@NonNull AoqClientEngine.AoqDataMsg msg) {
        // Parse server events (see step 5)
    }

    @Override
    public void onError(int code, String message) {
        // Handle errors
    }
});

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.
int SAMPLE_RATE = 16000;

// Configure PCM encoding
AoqClientEngine.AoqAudioCodecConfig codec = new AoqClientEngine.AoqAudioCodecConfig();
codec.codecType = AoqClientEngine.AoqEncoderType.AoqEncoderTypeAudioPCM;
codec.sampleRate = SAMPLE_RATE;
codec.channel = 1;
codec.bitrate = 256000;
engine.setAudioEncoderConfig(codec);

// Register the capture callback
engine.setAudioFrameObserver(new AoqClientListener.AoqAudioFrameListener() {
    @Override
    public void onCapturedAudioFrame(
            @NonNull AoqClientEngine.AoqAudioFrameData frame) {
        if (frame.dataPtr != null && frame.dataSize > 0) {
            // Buffer PCM data in the queue (see step 5)
            pcmQueue.offer(frame.dataPtr, frame.dataSize);
        }
        Arrays.fill(frame.dataPtr, (byte) 0);  // Clear the buffer to prevent outgoing audio media
    }
});

AoqClientEngine.AoqAudioObserverConfig observer = new AoqClientEngine.AoqAudioObserverConfig();
observer.sampleRate = SAMPLE_RATE;
observer.channels = 1;
observer.mode = AoqClientEngine.AoqAudioObserverMode.AoqAudioObserverModeReadWrite;
engine.enableAudioFrameObserver(true,
        AoqClientEngine.AoqAudioSource.AoqAudioSourceCaptured, observer);

// Disable outgoing audio media (send audio over the Data channel)
engine.enableSendMediaStream(AoqClientEngine.AoqTrackType.AoqTrackTypeAudio, false);

// Start capture immediately, without waiting for the connection
engine.startAudioCapture(new AoqClientEngine.AoqAudioCaptureConfig());
Escolha uma das duas formas para não iniciar dois gravadores ao mesmo tempo. Na captura própria, o aplicativo é responsável pela conversão de formato, confirmação da parada e liberação dos dispositivos de áudio.

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.
// Build the connection configuration after obtaining credentials from AppServer
AoqClientEngine.AoqConnectConfig config = new AoqClientEngine.AoqConnectConfig();
config.token = aoqTokenForClient;
config.sid = sid;
config.certFingerprint = clientRelayCertFingerprint;
config.workspaceIdHash = workspaceIdHash;
// Parse relayEndpoints from the response and add them to the configuration

// Publish Audio + Data tracks
AoqClientEngine.AoqTrackParam audioTrack = new AoqClientEngine.AoqTrackParam();
audioTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
config.publishTracks.add(audioTrack);

AoqClientEngine.AoqTrackParam dataTrack = new AoqClientEngine.AoqTrackParam();
dataTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.publishTracks.add(dataTrack);

// Subscribe to the Data track
AoqClientEngine.AoqTrackParam subData = new AoqClientEngine.AoqTrackParam();
subData.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.subscribeTracks.add(subData);

// Establish the connection
engine.connect(config);

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.
{
  "header": {
    "action": "run-task",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3",
    "streaming": "duplex"
  },
  "payload": {
    "task_group": "audio",
    "task": "asr",
    "function": "recognition",
    "model": "qwen-audio-3.1-asr-flash-streaming",
    "parameters": {
      "format": "pcm",
      "sample_rate": 16000
    },
    "input": {}
  }
}
As mensagens de controle e de áudio são enviadas pela mesma interface sendDataMsg:
String taskId = UUID.randomUUID().toString();
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "run-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("task_group", "audio")
                .put("task", "asr")
                .put("function", "recognition")
                .put("model", "qwen-audio-3.1-asr-flash-streaming")
                .put("parameters", new JSONObject()
                        .put("format", "pcm")
                        .put("sample_rate", 16000))
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);

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.
{
  "header": {
    "event": "task-started",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}
O exemplo contém os campos principais do evento. Leia os demais conforme necessário. Consulte Eventos do servidor. Nesse momento, o buffer geralmente contém áudio capturado durante a solicitação de credenciais, a conexão AOQ e o início da tarefa do modelo. Verifique se o 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:
CampoTipoDescrição
typestringValor fixo: input_audio_buffer.append
event_idstringIdentificador único do evento para correlação e desduplicação
audiostringDados de áudio PCM codificados em Base64
O cliente codifica o PCM capturado em Base64, o encapsula nesse JSON e o envia por 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.
{
    "type": "input_audio_buffer.append",
    "event_id": "event_550e8400-e29b-41d4-a716-446655440000",
    "audio": "AQID//+AgAAEAACAAAAA..."
}
Enviar dados de áudio: Leia PCM da fila do buffer, encapsule-o em um JSON input_audio_buffer.append e envie-o por sendDataMsg:
byte[] pcm = pcmQueue.poll(640);  // Read one PCM frame

if (pcm != null) {
    JSONObject event = new JSONObject()
            .put("type", "input_audio_buffer.append")
            .put("event_id", "event_" + UUID.randomUUID())
            .put("audio", Base64.encodeToString(pcm, Base64.NO_WRAP));

    AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
    msg.data = event.toString().getBytes(StandardCharsets.UTF_8);
    engine.sendDataMsg(msg);
}
Tratar eventos do servidor: Analise os eventos no callback onDataMsg. Inicie o envio de áudio ao receber task-started e analise os resultados ao receber result-generated. Consulte Eventos do servidor.
JSONObject root = new JSONObject(new String(msg.data, StandardCharsets.UTF_8));
String event = root.optJSONObject("header").optString("event");

if ("task-started".equals(event)) {
    // Model ready: send buffered audio at double speed, then stream in real time
} else if ("result-generated".equals(event)) {
    // Parse recognition results (see step 6)
    JSONObject sentence = root.optJSONObject("payload")
            .optJSONObject("output").optJSONObject("sentence");
    if (sentence != null && !sentence.optBoolean("heartbeat")) {
        String text = sentence.optString("text", "");
        boolean isFinal = sentence.optBoolean("sentence_end");
        // Display recognition results
    }
} else if ("task-finished".equals(event)) {
    // Task finished
} else if ("task-failed".equals(event)) {
    // Task failed
}

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.
private void handleRecognitionResult(JSONObject root) {
    JSONObject payload = root.optJSONObject("payload");
    JSONObject output = payload == null ? null : payload.optJSONObject("output");
    JSONObject sentence = output == null ? null : output.optJSONObject("sentence");
    if (sentence == null || sentence.optBoolean("heartbeat")) return;

    String text = sentence.optString("text", "");
    if (text.isEmpty()) return;
    boolean isFinal = sentence.optBoolean("sentence_end");

    // Display interim results in real time; append final results
    listener.onResult(text, isFinal);
}

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.
O evento finish-task tem a seguinte estrutura:
{
    "header": {
        "action": "finish-task",
        "task_id": "UUID",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}
Envie-o por sendDataMsg:
engine.stopAudioCapture();  // Stop capture

// Wait for the buffer to drain, then send finish-task
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "finish-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);
Quando o modelo termina, ele retorna o seguinte evento principal:
{
  "header": {
    "event": "task-finished",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}

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.
engine.stopAudioCapture();
engine.setAudioFrameObserver(null);
engine.disconnect();
AoqClientEngine.destroy();
engine = null;

Notas de uso

  1. Aguarde task-started antes de enviar áudio; caso contrário, os dados serão descartados.
  2. Envie finish-task somente após esvaziar o buffer (queue.size() == 0) para que o modelo processe o último segmento de áudio.
  3. Não desconecte imediatamente após task-finished. A conexão pode ser reutilizada para outra tarefa com um novo task_id.
  4. Ignore os pacotes de heartbeat (heartbeat: true) em result-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.
// After the first round finishes (task-finished received)
// Send run-task with a new task_id to start the second round
taskId = UUID.randomUUID().toString();
sendRunTask();

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.

Documentação relacionada