Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Qwen-Audio-3.0-Realtime conversa por voz em tempo real HarmonyOS SDK

Use o HarmonyOS SDK para Qwen-Audio-3.0-Realtime para construir conversas de voz em tempo real com entrada de áudio e saída de áudio ou texto.

Guia do usuário: Para apresentações de modelos e conselhos de seleção, consulte Conversa por voz em tempo real.

Início rápido

Obtenha e configure uma chave API.
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote SDK mais recente.
- Extraia o .tar.gz Pacote SDK. Obtenha o SDK do HAR em entry/libs e adicione-o às dependências do seu projeto. Para integração C++, use native/libs e native/include no pacote para obter as bibliotecas dinâmicas e arquivos de cabeçalho.
- Abra o projeto no DevEco Studio. O código de exemplo está em DashQwenAudioChatPage.ets. Substitua a chave API para testar o recurso.

Procedimento de chamada

Inicialize o SDK.
Defina parâmetros para seu caso de uso. Use o parameters argumento de inicializar para definir os parâmetros de conexão e controle e use setParams para definir os parâmetros de conversação por voz.
Chame startDialog para iniciar a conversa.
Em onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
Forneça continuamente dados de gravação em onNuiNeedAudioData ou ligue para updateAudio para enviar ativamente dados de gravação.
Receba continuamente o áudio retornado pelo modelo em onNuiAssistEventCallback.
Ouça eventos e obtenha informações sobre eventos em onNuiEventCallback.
Chame stopDialog para interromper a conversa e ouvir EVENT_TRANSCRIBER_COMPLETE para confirmar que terminou.
Quando o recurso de conversa não for mais necessário, ligue para release para liberar os recursos do SDK.

Gerenciamento de dispositivos de áudio

Ao contrário do Android, que usa AudioRecord e AudioTrack, o HarmonyOS fornece captura e reprodução de áudio por meio de @kit.AudioKit, usando AudioCapturer para gravação e AudioRenderer para reprodução. O projeto de exemplo fornece o AudioRecorder.ets e AudioPlayer.ets classes utilitárias para reutilização.

Gravação (AudioCapturer)

Criar: Ligar audio.createAudioCapturer(capturerOptions) de forma assíncrona. A amostra usa áudio mono de 16 kHz e 16 bits (SAMPLE_RATE_16000, CHANNEL_1, SAMPLE_FORMAT_S16LEe ENCODING_TYPE_RAW).
<strong>Fonte de áudio (audio.SourceType):</strong>
- SOURCE_TYPE_MIC: Áudio bruto do microfone. Use esta fonte quando o AEC interno do SDK estiver habilitado e envie dados para o SDK chamando updateAudio.
- SOURCE_TYPE_VOICE_COMMUNICATION: Chama o áudio no qual o sistema já executou o cancelamento de eco. Use esta fonte quando o AEC interno do SDK estiver desabilitado e forneça áudio por meio de onNuiNeedAudioData.
Evento de dados: Ligar capturer.on('readData', (buffer: ArrayBuffer) => void) para obter continuamente áudio gravado.
Evento estadual: Ligar capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING indica que a gravação começou e STATE_STOPPED indica que parou.
Controle: Ligar start() para começar, stop() parar, e release() para liberar o gravador.

import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioCapturerInfo: audio.AudioCapturerInfo = {
  source: audio.SourceType.SOURCE_TYPE_MIC,
  capturerFlags: 0
};
const options: audio.AudioCapturerOptions = { streamInfo: audioStreamInfo, capturerInfo: audioCapturerInfo };

audio.createAudioCapturer(options).then((capturer) => {
  capturer.on('readData', (buffer: ArrayBuffer) => {
    // Send the recorded audio to the SDK.
    nuiInstance.updateAudio(buffer, false);
  });
  capturer.start();
});

Nota: HarmonyOS cria AudioCapturer de forma assíncrona. Ligar start() somente após a conclusão da criação. Não crie e inicie imediatamente um gravador em STATE_OPEN. Crie-o primeiro e depois ligue start() do STATE_OPEN retorno de chamada. A amostra cria o gravador durante doInit e inicia durante onNuiAudioStateChanged.

Reprodução (AudioRenderer)

Criar: Ligar audio.createAudioRenderer(rendererOptions) de forma assíncrona.
Taxa de amostragem: O áudio de resposta sintetizado retornado pelo serviço é de 24 kHz. Passe essa taxa para o AudioPlayer construtor.
Evento de dados: Ligar renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => ...) para fornecer áudio para reprodução. Retorno AudioDataCallbackResult.VALID depois de encher o buffer ou INVALID quando não há dados disponíveis.
Evento estadual: Ligar renderer.on('stateChange', (state: audio.AudioState) => void) para ouvir os eventos de início e fim da reprodução.
Controle: Ligar start() para começar, stop() parar, e pause() para pausar a reprodução. A pausa retém os dados armazenados em buffer.

import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_24000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_VOICE_ASSISTANT,
  rendererFlags: 0
};
const options: audio.AudioRendererOptions = { streamInfo: audioStreamInfo, rendererInfo: audioRendererInfo };

audio.createAudioRenderer(options, (err, renderer) => {
  renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => {
    // Fill data with model response audio from the queue and return VALID or INVALID.
    return audio.AudioDataCallbackResult.VALID;
  });
  renderer.start();
});

Sinal de referência AEC: Quando o AEC interno do SDK estiver ativado, envie o áudio de saída do player para o SDK como sinal de referência chamando nuiInstance.pushReferenceData(data, false), que corresponde a updateRefAudio no Android.

Declaração de permissão

Declare a permissão do microfone em module.json5 antes de gravar o áudio:

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}

Parâmetros de solicitação

Parâmetros de conexão e controle

Passe uma string JSON no parameters argumento de inicializar.

Exemplo: A sequência JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para seu caso de uso.

{
  "url": "wss://maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "20%" }} />

<col style={{ width: "40%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Obrigatório**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Ponto final do serviço: `wss://maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>`.
  </td>
</tr>

<tr>
  <td>
    `apikey`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Chave de API.
  </td>
</tr>

<tr>
  <td>
    `service_mode`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Modo de tempo de execução. Defina este parâmetro como `"1"` para conversação por voz em tempo real.
  </td>
</tr>

<tr>
  <td>
    `device_id`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Uma string exclusiva que identifica o usuário final. Você pode usar um ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. Esse ID é usado principalmente para rastreamento de log e solução de problemas.
  </td>
</tr>

<tr>
  <td>
    `audio_update_manually`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve enviar ativamente dados de áudio. Padrão: `"false"`. Se definido para `"true"` e o SDK oferece suporte a recursos de áudio no dispositivo, como AEC e VAD, esses recursos são habilitados por padrão.
  </td>
</tr>

<tr>
  <td>
    `workspace`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    O caminho de armazenamento para arquivos de recursos no dispositivo. Este parâmetro é necessário quando `audio_update_manually` é `"true"` e um recurso de áudio no dispositivo, como AEC ou VAD, está ativado.
  </td>
</tr>

<tr>
  <td>
    `debug_path`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    O caminho de armazenamento do arquivo de log. Este parâmetro entra em vigor somente quando `save_log` é `true` em `initialize`. Neste caso, o caminho é obrigatório. O SDK retém no máximo dois arquivos de log localmente.
  </td>
</tr>

<tr>
  <td>
    `save_wav`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio de depuração em `debug_path`. Padrão: `"false"`. Os valores válidos são `"true"` e `"false"`. Este parâmetro entra em vigor somente quando `save_log` é `true`e `debug_path` também deve ser definido.
  </td>
</tr>

<tr>
  <td>
    `max_log_file_size`
  </td>

  <td>
    `int`
  </td>

  <td>
    Não
  </td>

  <td>
    O tamanho máximo do arquivo de log em bytes. Este parâmetro entra em vigor somente quando `save_log` é `true`. Padrão: `104857600` (100 × 1024 × 1024 bytes ou 100 MiB).
  </td>
</tr>

<tr>
  <td>
    `log_track_level`
  </td>

  <td>
    `int`
  </td>

  <td>
    Não
  </td>

  <td>
    O nível de filtro para logs enviados por meio `onNuiLogTrackCallback`. Padrão: `2`. Valores válidos: `0` (VERBOSO), `1` (DEBUGAR), `2` (INFORMAÇÕES), `3` (AVISO), `4` (ERRO) e `5` (NENHUMA). Um log é retornado somente quando seu nível é maior ou igual a ambos `log_track_level` e o `level` passou para `initialize`. Por exemplo, se `log_track_level` é `2` (INFORMAÇÕES) e `level` é `3` (WARNING), apenas WARNING e logs de nível superior (valores maiores ou iguais a `3`) são retornados.
  </td>
</tr>

<tr>
  <td>
    `aec_params`
  </td>

  <td>
    `object`
  </td>

  <td>
    Não
  </td>

  <td>
    Configuração AEC avançada no dispositivo. Este objeto entra em vigor somente quando `audio_update_manually` é `"true"`.
  </td>
</tr>

<tr>
  <td>
    `aec_params.enable_aec`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve ativar o AEC no dispositivo. Se `audio_update_manually` é `"true"` e o SDK oferece suporte a AEC no dispositivo, o AEC é habilitado por padrão.
  </td>
</tr>

<tr>
  <td>
    `aec_params.save_audio`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio processado pelo módulo AEC no dispositivo. Se `save_wav` é `"true"` e `debug_path` estiver definido, esse recurso será ativado por padrão e o áudio será salvo em `debug_path`.
  </td>
</tr>

<tr>
  <td>
    `aec_params.enable_aec_data_callback`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve retornar áudio processado por AEC através `EVENT_AEC_DATA` em `onNuiAssistEventCallback`. Padrão: `false`.
  </td>
</tr>

<tr>
  <td>
    `vad_params`
  </td>

  <td>
    `object`
  </td>

  <td>
    Não
  </td>

  <td>
    Configuração avançada de VAD no dispositivo. Este objeto entra em vigor somente quando `audio_update_manually` é `"true"`.
  </td>
</tr>

<tr>
  <td>
    `vad_params.enable_vad`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve ativar o VAD no dispositivo. Se `audio_update_manually` é `"true"` e o SDK oferece suporte ao VAD no dispositivo, o VAD é habilitado por padrão.
  </td>
</tr>

<tr>
  <td>
    `vad_params.save_audio`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio processado pelo módulo VAD no dispositivo. Se `save_wav` é `"true"` e `debug_path` estiver definido, esse recurso será ativado por padrão e o áudio será salvo em `debug_path`.
  </td>
</tr>

</tbody> </table>

Parâmetros de conversação por voz

Passe uma string JSON no params argumento de setParams.

Exemplo: A sequência JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para seu caso de uso.

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "20%" }} />

<col style={{ width: "40%" }} />

</colgroup>

<thead> <tr> <th style={{ verticalAlign: "top" }}> Parâmetro de nível superior </th>

  <th style={{ verticalAlign: "top" }}>
    **Tipo**
  </th>

  <th style={{ verticalAlign: "top" }}>
    **Obrigatório**
  </th>

  <th style={{ verticalAlign: "top" }}>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td style={{ verticalAlign: "top" }}> service_type </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Tipo de serviço de voz. Defina este parâmetro como `4` para conversação por voz em tempo real.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `object`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Configuração central de conversação por voz, incluindo seleção de modelo e comportamento de conversação.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.model`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Nome do modelo. Suporta o `qwen-audio-3.1-realtime-plus`, `qwen-audio-3.0-realtime-plus`e `qwen-audio-3.0-realtime-flash` série de modelos.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.sr_format`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Formato de áudio de entrada. Somente `pcm` é suportado. O formato padrão é PCM mono de 16 kHz, 16 bits.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.modalities`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de modalidades de saída. Valores válidos:<ul><li><code>\["texto"]</code>: retorna apenas texto.</li><li><code>\["áudio", "texto"]</code> (padrão): retorna áudio e texto.</li></ul>
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.voice`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Voz TTS. O padrão é `longanqian_v3.1` para 3.1 Plus e `longanqian` para 3.0 Plus/Flash. Este parâmetro pode ser definido apenas no primeiro `session.update`; valores posteriores são ignorados. Vozes do sistema: `longanqian`, `longanlingxin`, `longanlingxi`, `longanxiaoxin`e `longanlufeng`. Você também pode especificar um clone `voice_id` criado por meio da API de clonagem de voz. Consulte [Configuração de voz](/developer-guides/speech/qwen-audio-realtime#voice-configuration).

    3.1 Plus também suporta `longanqian_v3.1`, `longanhuan_v3.1`, `longanlingxin_v3.1`, `longanfengyue_v3.1`, `xunanchuan_v3.1`, `beth_v3.1`, `betty_v3.1`, `cally_v3.1`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.enable_speech_emotion`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `boolean`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Seja para permitir uma expressão emocional aprimorada. Quando ativada, a voz de resposta apresenta variação emocional mais perceptível. Padrão: `true`. Valores válidos: `true` e `false`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.instructions`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Instruções do sistema que definem a função do modelo, o estilo de resposta e as preferências comportamentais para toda a sessão.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.max_history_turns`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Número máximo de turnos históricos de perguntas e respostas permitidos em uma solicitação. Valores válidos: 1 a 50. Padrão: `20`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.tools`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de definições de ferramentas de chamada de função. Depois de configurar esse parâmetro, o modelo decide se chamará uma ferramenta com base na entrada do usuário. Cada definição usa `type` (necessário e fixado para `function`) e um `function` objeto contendo `name` (obrigatório), `description` (opcional) e `parameters` (opcional). Se uma função não tiver argumentos, omita `parameters`.

Exemplo:

    ```json
    [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Queries weather information for a specified city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "City"
              }
            },
            "required": [
              "city"
            ]
          }
        }
      }
    ]
    ```
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo um objeto JSON para detecção de curva. Se omitido, a sessão usa o modo push-to-talk, no qual o áudio é confirmado e a inferência é acionada manualmente. Se definido, o modo de conversação duplex será ativado.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.type`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Tipo VAD. `server_vad` (padrão) detecta limites de fala de recursos acústicos e aciona automaticamente a inferência. `smart_turn` combina sinais acústicos e semânticos; sons sem conteúdo semântico, como sons de preenchimento, não iniciam uma curva nem interrompem a reprodução do modelo.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.threshold`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `float`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sensibilidade do DAV. Este parâmetro se aplica apenas a `server_vad` e não tem efeito `smart_turn`. Valores mais baixos tornam o VAD mais sensível a sons baixos e ruídos de fundo; valores mais altos requerem uma fala mais clara e mais alta. Intervalo válido: `[-1.0, 1.0]`. Padrão: `0.5`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.silence_duration_ms`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Duração mínima do silêncio após a fala, em milissegundos, antes que a resposta do modelo seja acionada. Este parâmetro se aplica apenas a `server_vad` e não tem efeito `smart_turn`. Valores mais baixos reduzem a latência, mas podem ser acionados em breves pausas. Intervalo válido: `[200, 6000]`. Padrão: `800`. Recomendado para conversa: `400` para `800`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.voiceprint_audio_urls`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de URLs de áudio pré-gravados publicamente acessíveis para o locutor alvo. Este parâmetro se aplica apenas a `smart_turn`. Em conversas duplex, ajuda o modelo a focar no alto-falante alvo e ignorar outros alto-falantes e ruídos de fundo. Até cinco URLs são suportados. O áudio deve ser PCM ou WAV de 16 kHz.
  </td>
</tr>

</tbody> </table>

Principais APIs

NativoNui

inicializar

Inicializa uma instância do SDK de conversação por voz. O SDK usa o padrão singleton. Não inicialize-o novamente antes de chamar release.

Este método pode bloquear. Chame-o em um thread que não seja da UI.

Assinatura do método

public initialize(
  callback: INativeNuiCallback,
  parameters: string,
  level: number,
  save_log: boolean = false
): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> callback </td>

  <td>
    `INativeNuiCallback`
  </td>

  <td>
    Uma implementação da interface de retorno de chamada de eventos e dados.
  </td>
</tr>

<tr>
  <td>
    `parameters`
  </td>

  <td>
    `string`
  </td>

  <td>
    Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte [Parâmetros de conexão e controle](#connection-and-control-parameters).
  </td>
</tr>

<tr>
  <td>
    `level`
  </td>

  <td>
    `number`
  </td>

  <td>
    Controla o nível de impressão dos próprios logs do SDK.
  </td>
</tr>

<tr>
  <td>
    `save_log`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Se os logs devem ser salvos localmente. Se definido para `true`, especifique o caminho usando `debug_path` nos [parâmetros de conexão e controle](#connection-and-control-parameters). Você também pode definir o tamanho do arquivo usando `max_log_file_size`.
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

####setParams

Define os parâmetros de conversação por voz no formato JSON. Chame esse método antes de startDialog.

Assinatura do método

public setParams(params: string): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> params </td>

  <td>
    `string`
  </td>

  <td>
    [Parâmetros de conversação por voz](#conversation-parameters).
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

startDialog

Inicia a conversa.

Assinatura do método

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `Constants.VadMode`
  </td>

  <td>
    Modo VAD. Corrigido para `Constants.VadMode.TYPE_P2T`.
  </td>
</tr>

<tr>
  <td>
    `dialog_params`
  </td>

  <td>
    `string`
  </td>

  <td>
    Se `apikey` nos [parâmetros de conexão e controle](#connection-and-control-parameters) é uma [chave de API temporária](/api-reference/more/generate-a-temporary-api-key), atualize-o aqui depois que ele expirar.

Formato JSON:

    ```json
    {
      "apikey": "st-****"
    }
    ```
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

stopDialog

Termina a conversa. Depois de chamar esse método, o servidor retorna o resultado final da conversa e encerra a tarefa.

Assinatura do método

public stopDialog(): number

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

cancelarDialog

Termina a conversa imediatamente. Depois de chamar esse método, a tarefa termina sem esperar que o servidor retorne o resultado final da conversa.

Assinatura do método

public cancelDialog(): number

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

diálogoAção

Envia um comando de ação de conversa durante uma interação para atualizar o comportamento do tempo de execução, como o contexto da conversa.

Assinatura do método

public dialogAction(params: string): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> params </td>

  <td>
    `string`
  </td>

  <td>
    Uma string JSON usada para atualizar o comportamento do tempo de execução, como o contexto da conversa.
  </td>
</tr>

<tr>
  <td>
    `params.type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Definir como `"action"`.
  </td>
</tr>

<tr>
  <td>
    `params.command`
  </td>

  <td>
    `String`
  </td>

  <td>
    Comando de tempo de execução. Valores válidos:<ul><li><code>função\_chamada</code>: atualiza uma solicitação de chamada de função.</li><li><code>jogar\_iniciar</code>: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio foi iniciada.</li><li><code>jogar\_over</code>: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio foi encerrada.</li></ul>
  </td>
</tr>

<tr>
  <td>
    `params.context`
  </td>

  <td>
    `String`
  </td>

  <td>
    Atualização de solicitação de chamada de função. Usado quando `command` é `"function_call"`.
  </td>
</tr>

<tr>
  <td>
    `params.context.type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Tipo de evento. Este parâmetro é necessário quando `command` é `"function_call"`. `conversation.item.create` insere um item de conversa para contexto histórico, texto suplementar ou resultado de ferramenta. Depois de enviar `conversation.item.create`, usar `response.create` para desencadear outra inferência.
  </td>
</tr>

<tr>
  <td>
    `params.context.item`
  </td>

  <td>
    `object`
  </td>

  <td>
    Obrigatório quando `params.context.type` é `conversation.item.create`. O item de conversa a ser criado.
  </td>
</tr>

<tr>
  <td>
    `params.context.response`
  </td>

  <td>
    `object`
  </td>

  <td>
    Opcional quando `params.context.type` é `response.create`. Substitui os padrões de sessão para esta inferência. Se omitido, a configuração da sessão atual será usada.
  </td>
</tr>

</tbody> </table>

context.item parâmetros:

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `String`
  </td>

  <td>
    ID de item de conversa exclusivo opcional. Se omitido, o servidor gera um. Um erro será retornado se o ID especificado já existir.
  </td>
</tr>

<tr>
  <td>
    `type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Tipo de item obrigatório. Valores válidos:<ul><li><code>mensagem</code>: uma mensagem normal.</li><li><code>função\_chamada</code>: uma solicitação de chamada de função. Esse tipo normalmente é gerado pelo servidor. O cliente também pode usá-lo para adicionar contexto histórico.</li><li><code>função\_chamada\_saída</code>: um resultado de execução da ferramenta. Depois de receber um <code>função\_chamada</code>, o cliente executa a ferramenta e usa esse tipo para gravar o resultado.</li></ul>
  </td>
</tr>

<tr>
  <td>
    `role`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `message`. Valores válidos: `system`, `user`e `assistant`.
  </td>
</tr>

<tr>
  <td>
    `content`
  </td>

  <td>
    `array`
  </td>

  <td>
    Obrigatório para `message`. Cada item contém um `type` e o campo de dados associado. `system` suporta `input_text` com `text`; `user` suporta `input_text` com `text` e `input_audio` com codificação Base64 `audio`; `assistant` suporta `output_text` com `text`.
  </td>
</tr>

<tr>
  <td>
    `call_id`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call` e `function_call_output`. O ID exclusivo que associa uma solicitação de chamada de função ao seu resultado.
  </td>
</tr>

<tr>
  <td>
    `name`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call`. O nome da função a ser chamada.
  </td>
</tr>

<tr>
  <td>
    `arguments`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call`. Argumentos de função como uma string JSON.
  </td>
</tr>

<tr>
  <td>
    `output`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call_output`. Resultado da execução da ferramenta como uma string JSON.
  </td>
</tr>

</tbody> </table>

context.response parâmetros:

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> modalities </td>

  <td>
    `array`
  </td>

  <td>
    Modalidades de saída. `["text"]` retorna apenas texto. `["audio", "text"]` (padrão) retorna áudio e texto.
  </td>
</tr>

<tr>
  <td>
    `voice`
  </td>

  <td>
    `string`
  </td>

  <td>
    Substitui a voz TTS para esta inferência.
  </td>
</tr>

</tbody> </table>

Exemplo:

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

atualizaçãoÁudio

Quando audio_update_manually está definido para "true", os dados de gravação não são mais fornecidos por meio de onNuiNeedAudioData. Use este método para enviar ativamente os dados.

Assinatura do método

public updateAudio(data: ArrayBuffer, first_pack: boolean): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `ArrayBuffer`
  </td>

  <td>
    Dados de áudio para enviar (PCM).
  </td>
</tr>

<tr>
  <td>
    `first_pack`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Se este é o primeiro pacote de áudio. O SDK calcula a contagem de bytes de `data.byteLength`.
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

pushReferenceData (corresponde ao updateRefAudio do Android)

Quando audio_update_manually está definido para "true" e o AEC no dispositivo estiver ativado, use este método para enviar o áudio reproduzido pelo player como sinal de referência.

Assinatura do método

public pushReferenceData(data: ArrayBuffer, first_pack: boolean): number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `ArrayBuffer`
  </td>

  <td>
    Dados de áudio para enviar (PCM).
  </td>
</tr>

<tr>
  <td>
    `first_pack`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Se este é o primeiro pacote de áudio. O SDK calcula a contagem de bytes de `data.byteLength`.
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

lançamento

Libera todos os recursos internos do SDK. A instância do SDK fica indisponível após esta chamada. Para usar o SDK novamente, chame initialize para reinicializá-lo.

Assinatura do método

public release(): number

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

Obter versão

Retorna informações sobre a versão atual do SDK.

Assinatura do método

public GetVersion(): string

Valor de retorno

Informações sobre a versão atual do SDK.

INativeNuiCallback: retornos de chamada do ouvinte

onNuiEventCallback: ouça informações do evento

Assinatura do método

onNuiEventCallback: (
  event: Constants.NuiEvent,
  resultCode: number,
  arg2: number,
  kwsResult: KwsResult,
  asrResult: AsrResult
) => void;

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> event </td>

  <td>
    `Constants.NuiEvent`
  </td>

  <td>
    Evento de retorno de chamada.
  </td>
</tr>

<tr>
  <td>
    `resultCode`
  </td>

  <td>
    `number`
  </td>

  <td>
    [Código de erro](/api-reference/preparation/error-messages). Este parâmetro é válido quando `EVENT_ASR_ERROR` ocorre.
  </td>
</tr>

<tr>
  <td>
    `arg2`
  </td>

  <td>
    `number`
  </td>

  <td>
    Parâmetro reservado.
  </td>
</tr>

<tr>
  <td>
    `asrResult`
  </td>

  <td>
    `AsrResult`
  </td>

  <td>
    Resultado do reconhecimento de fala.
  </td>
</tr>

<tr>
  <td>
    `kwsResult`
  </td>

  <td>
    `KwsResult`
  </td>

  <td>
    Resultado de despertar por voz. Você não precisa usar este parâmetro.
  </td>
</tr>

</tbody> </table>

onNuiAudioStateChanged: ouça o estado do áudio

O SDK usa esse retorno de chamada para notificar o aplicativo quando iniciar ou interromper a gravação.

Assinatura do método

onNuiAudioStateChanged: (state: Constants.AudioState) => void

Valores de estado de áudio

<col style={{ width: "75%" }} />

</colgroup>

<thead> <tr> <th> Estado </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> STATE_OPEN </td>

  <td>
    A interação começou. Você pode abrir o dispositivo de gravação e começar a gravar.
  </td>
</tr>

<tr>
  <td>
    `STATE_PAUSE`
  </td>

  <td>
    A interação foi interrompida. Você pode parar de gravar.
  </td>
</tr>

<tr>
  <td>
    `STATE_CLOSE`
  </td>

  <td>
    A instância do SDK foi lançada. Você pode fechar completamente o dispositivo de gravação.
  </td>
</tr>

</tbody> </table>

onNuiAudioRMSChanged: ouça o volume da gravação

Escuta o volume da gravação, que pode ser exibido na IU.

Assinatura do método

onNuiAudioRMSChanged: (val: number) => number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `number`
  </td>

  <td>
    Volume de gravação.
  </td>
</tr>

</tbody> </table>

onNuiNeedAudioData: fornece dados de áudio

Após o início da conversa, esse retorno de chamada é acionado continuamente. Forneça os dados de áudio para processar neste retorno de chamada. Você não precisa usar esse retorno de chamada quando audio_update_manually está definido para "true".

Assinatura do método

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> buffer </td>

  <td>
    `ArrayBuffer`
  </td>

  <td>
    Dados de áudio para fornecer. O SDK usa `buffer.byteLength` como a contagem de bytes solicitada.
  </td>
</tr>

</tbody> </table>

Valor de retorno

O número real de bytes fornecidos.

onNuiAssistEventCallback: receba dados e informações auxiliares

Recebe eventos auxiliares internos do SDK e dados relacionados.

Assinatura do método

onNuiAssistEventCallback?: (
  event: Constants.NuiEvent,
  info: string,
  infoLen: number,
  data: ArrayBuffer
) => void;

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> event </td>

  <td>
    `Constants.NuiEvent`
  </td>

  <td>
    `NuiEvent` evento.
  </td>
</tr>

<tr>
  <td>
    `info`
  </td>

  <td>
    `string`
  </td>

  <td>
    Informações adicionais, geralmente uma string JSON.
  </td>
</tr>

<tr>
  <td>
    `infoLen`
  </td>

  <td>
    `number`
  </td>

  <td>
    Comprimento das informações adicionais.
  </td>
</tr>

<tr>
  <td>
    `data`
  </td>

  <td>
    `ArrayBuffer`
  </td>

  <td>
    Dados binários adicionais, como áudio TTS retornado pelo modelo.
  </td>
</tr>

</tbody> </table>

Nota: Este retorno de chamada é opcional (?) no HarmonyOS. Omita-o se não precisar das informações.

onNuiLogTrackCallback: escuta logs de rastreamento

Recebe logs internos detalhados do SDK para solução de problemas e depuração.

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

`NuiEvent`: tipos de eventos

No HarmonyOS SDK, os tipos de eventos são definidos pelo Constants.NuiEvent enumeração. A tabela a seguir lista os eventos relacionados à conversa por voz em tempo real:

<col style={{ width: "75%" }} />

</colgroup>

<thead> <tr> <th> Evento </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> EVENT_TRANSCRIBER_STARTED </td>

  <td>
    A tarefa foi iniciada com sucesso.
  </td>
</tr>

<tr>
  <td>
    `EVENT_VAD_START`
  </td>

  <td>
    Acionado imediatamente após o início da tarefa. Isto não significa que o início da fala tenha sido detectado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_VAD_END`
  </td>

  <td>
    O final da fala foi detectado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_PARTIAL_RESULT`
  </td>

  <td>
    Um resultado intermediário de reconhecimento de fala.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_RESULT`
  </td>

  <td>
    Um resultado completo de reconhecimento de fala.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_ERROR`
  </td>

  <td>
    Ocorreu um erro durante a conversa de voz.
  </td>
</tr>

<tr>
  <td>
    `EVENT_MIC_ERROR`
  </td>

  <td>
    Disparado quando nenhum dado de áudio é recebido por dois segundos consecutivos.
  </td>
</tr>

<tr>
  <td>
    `EVENT_SENTENCE_START`
  </td>

  <td>
    O início de uma frase foi detectado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_SENTENCE_END`
  </td>

  <td>
    O final de uma frase foi detectado e um resultado de reconhecimento completo foi retornado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_TRANSCRIBER_COMPLETE`
  </td>

  <td>
    A conversa de voz terminou.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AUDIO_TRANSCRIPTION`
  </td>

  <td>
    Um evento incremental de transcrição de texto para saída de áudio. Os segmentos de transcrição são retornados no modo de streaming.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AUDIO_TRANSCRIPTION_COMPLETED`
  </td>

  <td>
    A transcrição para saída de áudio está completa.
  </td>
</tr>

<tr>
  <td>
    `EVENT_OTHER_RESULT`
  </td>

  <td>
    Outras informações de evento, como o resultado de uma chamada de função.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_START`
  </td>

  <td>
    O modelo começou a retornar áudio TTS.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_DATA`
  </td>

  <td>
    Áudio TTS retornado pelo modelo.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_COMPLETE`
  </td>

  <td>
    O modelo terminou de retornar o áudio TTS.
  </td>
</tr>

<tr>
  <td>
    `EVENT_RESULT_TRANSLATED`
  </td>

  <td>
    Um resultado de tradução intermediário.
  </td>
</tr>

<tr>
  <td>
    `EVENT_RESULT_TRANSLATED_END`
  </td>

  <td>
    A saída do resultado da tradução está concluída.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AEC_DATA`
  </td>

  <td>
    Dados de áudio processados pelo AEC.
  </td>
</tr>

</tbody> </table>

Qwen-Audio-3.0-Realtime conversa por voz em tempo real HarmonyOS SDK

Início rápido

Procedimento de chamada

Gerenciamento de dispositivos de áudio

Gravação (AudioCapturer)

Reprodução (AudioRenderer)

Declaração de permissão

Parâmetros de solicitação

Parâmetros de conexão e controle

Parâmetros de conversação por voz

Principais APIs

NativoNui

inicializar

startDialog

stopDialog

cancelarDialog

diálogoAção

atualizaçãoÁudio

pushReferenceData (corresponde ao updateRefAudio do Android)

lançamento

Obter versão

INativeNuiCallback: retornos de chamada do ouvinte

onNuiEventCallback: ouça informações do evento

onNuiAudioStateChanged: ouça o estado do áudio

onNuiAudioRMSChanged: ouça o volume da gravação

onNuiNeedAudioData: fornece dados de áudio

onNuiAssistEventCallback: receba dados e informações auxiliares

onNuiLogTrackCallback: escuta logs de rastreamento

NuiEvent: tipos de eventos

`NuiEvent`: tipos de eventos