Alibaba Cloud Model Studio:Qwen-Audio-ASR-Streaming HarmonyOS SDK

Conheça os parâmetros, as interfaces, os callbacks e o uso do SDK HarmonyOS para Qwen-Audio-ASR-Streaming.

Início rápido

1. Obtenha uma chave de API. Não incorpore uma chave de longa duração ao código do cliente. Recomenda-se que o servidor do aplicativo obtenha uma chave de API temporária e a envie ao cliente.

2. Baixe o SDK mais recente. Extraia o pacote, copie entry/libs/neonui.har para entry/libs do aplicativo e adicione a dependência em entry/oh-package.json5:

   {
     "dependencies": {
       "neonui": "file:libs/neonui.har"
     }
   }
   

   Para integração com HarmonyOS C++, use as bibliotecas compartilhadas em native/libs e os arquivos de cabeçalho em native/include.

3. Declare as permissões de rede e microfone em module.json5 e solicite a permissão de microfone em tempo de execução. reason_internet e reason_microphone são exemplos de nomes de recursos. Defina suas descrições nos recursos do aplicativo.

   "requestPermissions": [
     {
       "name": "ohos.permission.INTERNET",
       "reason": "$string:reason_internet",
       "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
     },
     {
       "name": "ohos.permission.MICROPHONE",
       "reason": "$string:reason_microphone",
       "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
     }
   ]
   

4. Abra o projeto de exemplo do SDK no DevEco Studio. A página é entry/src/main/ets/pages/dashscope/DashFunAsrSpeechTranscriberPage.ets. Configure uma chave de API e execute o projeto.

Sequência de chamadas

1. Crie uma instância de NativeNui(Constants.ModeType.MODE_DIALOG).
2. Chame initialize para inicializar o SDK e configurar os parâmetros de conexão e controle.
3. Chame setParams para configurar o modelo e os parâmetros de reconhecimento.
4. Chame startDialog para iniciar o reconhecimento.
5. Em onNuiAudioStateChanged, inicie, pause ou feche o dispositivo de gravação conforme o estado do áudio.
6. Forneça continuamente dados gravados em onNuiNeedAudioData. Se o envio ativo estiver habilitado, use updateAudio.
7. Obtenha os resultados de reconhecimento e os estados da tarefa em onNuiEventCallback.
8. Chame stopDialog e aguarde EVENT_TRANSCRIBER_COMPLETE.
9. Quando o reconhecimento não for mais necessário, chame release para liberar os recursos.

Parâmetros da solicitação

Parâmetros de conexão e controle

Passe uma string JSON no argumento parameters de initialize.

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "device_id": "my_device_id",
  "service_mode": "1",
  "audio_update_manually": "false"
}

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Sim	Endpoints do serviço: Endpoint público: wss://dashscope.aliyuncs.com/api-ws/v1/inference Endpoint do espaço de trabalho em Pequim: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference Endpoint do espaço de trabalho em Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference Substitua {WorkspaceId} pelo seu ID do espaço de trabalho.
service_mode	string	Sim	Modo de execução. Para reconhecimento em tempo real, defina como "1", correspondente a Constants.ModeFullCloud.
device_id	string	Sim	Um identificador exclusivo de usuário final, como um ID de usuário no aplicativo ou um ID de dispositivo gerado pelo cliente. É usado principalmente para rastreamento de logs e solução de problemas.
apikey	string	Não	Chave de API. Pode ser passada na inicialização. Recomenda-se passar uma chave temporária em dialog_params de startDialog.
audio_update_manually	string	Não	Define se o envio ativo de áudio está habilitado. Padrão: "false". Com "true", chame updateAudio; com "false", o SDK obtém áudio por onNuiNeedAudioData. Se o valor for "true" e o SDK suportar AEC ou VAD no dispositivo, essas capacidades serão habilitadas por padrão.
workspace	string	Não	Diretório de recursos no dispositivo. Obrigatório quando audio_update_manually é "true" e o processamento local, como AEC ou VAD, está habilitado.
debug_path	string	Não	Diretório de logs. Obrigatório quando save_log é true. O SDK mantém no máximo dois arquivos de log.
save_wav	string	Não	Define se o áudio de depuração será salvo. Padrão: "false". Os arquivos são salvos em debug_path. Com "true", também defina debug_path e passe true para save_log em initialize.
save_wav_by_id	string	Não	Quando save_wav está habilitado, define se os arquivos de áudio serão nomeados com task_id para facilitar a busca. Padrão: "false".
max_log_file_size	number	Não	Tamanho máximo de um arquivo de log em bytes. Padrão: 104857600 (100 MiB). Só tem efeito quando save_log é true.
log_track_level	number	Não	Nível de filtragem de onNuiLogTrackCallback. Padrão: 2. Valores: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), 5 (NONE). Um log só é retornado se seu nível for maior ou igual a log_track_level e ao level de initialize. Com 2 e 3, só WARNING e níveis superiores são retornados.
enable_reconnection	string	Não	Define se a reconexão e a retomada da transmissão após interrupção de rede estão habilitadas. Padrão: "false".
aec_params	object	Não	Configurações de AEC no dispositivo. Usadas apenas quando audio_update_manually é "true".
aec_params.enable_aec	boolean	Não	Define se o AEC no dispositivo está habilitado. Habilitado por padrão se a compilação do SDK o suportar.
aec_params.save_audio	boolean	Não	Define se o áudio processado por AEC será salvo. Habilitado por padrão se save_wav estiver habilitado e debug_path definido.
aec_params.enable_aec_data_callback	boolean	Não	Define se os dados processados por AEC serão retornados pelo evento EVENT_AEC_DATA de onNuiAssistEventCallback. Padrão: false.
vad_params	object	Não	Configurações de VAD no dispositivo. Usadas apenas quando audio_update_manually é "true".
vad_params.enable_vad	boolean	Não	Define se o VAD no dispositivo está habilitado. Habilitado por padrão se a compilação do SDK o suportar.
vad_params.save_audio	boolean	Não	Define se o áudio processado por VAD será salvo. Habilitado por padrão se save_wav estiver habilitado e debug_path definido.
audio_config	object	Não	Configurações de captura no modo em que o SDK obtém o áudio. Usadas apenas quando audio_update_manually é "false".
audio_config.mic.enable_volume_calculation	boolean	Não	Define se o volume será calculado e informado. Padrão: true. Desabilite se os callbacks de volume não forem necessários.
audio_config.mic.volume_mode	string	Não	Modo de cálculo do volume. Defina como "dbfs" para calcular o dBFS padrão por 20*log10(rms/32768), com escala total de 0 dB.

Parâmetros de reconhecimento

Passe uma string JSON no argumento params de setParams.

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.0-asr-flash-streaming",
    "sr_format": "opus",
    "sample_rate": 16000
  }
}

Parâmetro	Tipo	Obrigatório	Descrição
service_type	number	Sim	Tipo de serviço de voz. Defina como 4, que corresponde a Constants.kServiceTypeSpeechTranscriber.
nls_config	object	Sim	Objeto de configuração do reconhecimento.
nls_config.model	string	Sim	Nome do modelo.
nls_config.sr_format	string	Sim	Formato de áudio: pcm ou opus. Com opus, o aplicativo continua fornecendo dados PCM, e o SDK os codifica em Opus.
nls_config.sample_rate	number	Sim	Taxa de amostragem em Hz. Qualquer taxa é aceita, exceto 8000 Hz com AEC ou VAD no dispositivo ativado.
nls_config.max_sentence_silence	number	Não	Limite de silêncio do VAD em milissegundos. O enunciado termina quando o silêncio após a fala ultrapassa esse limite. Padrão: 800. Intervalo válido: [200, 6000].
nls_config.multi_threshold_mode_enabled	boolean	Não	Indica se o modo de múltiplos limites deve ser ativado. Padrão: false. Evita segmentos VAD excessivamente longos.
nls_config.heartbeat	boolean	Não	Indica se os pacotes heartbeat devem ser ativados. Padrão: false. Quando ativados, o envio contínuo de áudio silencioso pode manter a conexão. Caso contrário, ela expira após algum tempo. Áudio silencioso não contém sinal audível no arquivo ou fluxo de áudio.
nls_config.vocabulary_id	string	Não	ID de uma lista de palavras-chave pré-compilada. Crie a lista antecipadamente. Use para vocabulário conhecido e relativamente estável reutilizado entre solicitações. Consulte Palavras-chave pré-compiladas.
nls_config.instant_vocabulary	object	Não	Palavras-chave por solicitação. As chaves são palavras e os valores são pesos inteiros. Não é necessário criar uma lista previamente, o que é adequado à otimização temporária por sessão. Pesos válidos: [1, 5] ou 50. Em [1, 5], um peso maior favorece a palavra. São permitidas até 50 super palavras-chave com peso 50. Quando há palavras-chave pré-compiladas e por solicitação, os conjuntos são mesclados. Se houver mais de 2000 entradas, 2000 serão escolhidas aleatoriamente. Consulte Palavras-chave por solicitação.
nls_config.language_hints	string[]	Não	Idiomas do áudio. Sem padrão; se omitido, o modelo detecta o idioma. São usados no máximo os quatro primeiros valores. Para os códigos de idioma, consulte o guia de reconhecimento de fala em tempo real.
nls_config.speech_noise_threshold	number	Não	Limite de fala/ruído do VAD. Intervalo válido: [-1.0, 1.0]. Próximo de -1, mais ruído pode ser reconhecido e transcrito como fala. Próximo de 1, mais fala pode ser filtrada como ruído. Esta configuração avançada pode afetar significativamente o reconhecimento. Teste com cuidado e ajuste em incrementos de 0,1.
nls_config.special_word_filter	object	Não	Configurações de filtragem de palavras sensíveis. Consulte Filtragem de palavras sensíveis.
nls_config.enable_connection_fast_check	boolean	Não	Indica se a detecção rápida de interrupções de rede deve ser ativada. Padrão: false.

APIs

NativeNui

Importe o SDK:

import { AsrResult, Constants, INativeNuiCallback, KwsResult, NativeNui } from 'neonui';

Criar uma instância

constructor(mode_type: Constants.ModeType, flag?: string)

Parâmetro	Tipo	Descrição
mode_type	Constants.ModeType	Modo do SDK: MODE_DIALOG para diálogo ou reconhecimento, MODE_TTS para síntese de fala ou MODE_STREAM_INPUT_TTS para síntese com entrada em streaming. Use MODE_DIALOG para reconhecimento em tempo real.
flag	string	Identificador opcional da instância para distinguir os logs.

initialize

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

Inicializa o SDK. Este método pode bloquear. Não o chame na thread da interface.

Parâmetro	Tipo	Descrição
callback	INativeNuiCallback	Callback de eventos e dados.
parameters	string	String JSON com parâmetros de conexão e controle.
level	number	Nível de log do SDK: LOG_LEVEL_VERBOSE (0), LOG_LEVEL_DEBUG (1), LOG_LEVEL_INFO (2), LOG_LEVEL_WARNING (3), LOG_LEVEL_ERROR (4) ou LOG_LEVEL_NONE (5).
save_log	boolean	Indica se logs locais devem ser salvos. Padrão: false. Se true, defina debug_path em parameters. Você também pode definir max_log_file_size.

setParams

setParams(params: string): number

Define os parâmetros de reconhecimento antes de startDialog. params é uma string JSON que contém esses parâmetros.

startDialog

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

Inicia o reconhecimento.

Parâmetro	Tipo	Descrição
vad_mode	Constants.VadMode	Modo VAD. Use Constants.VadMode.TYPE_P2T para reconhecimento de fala em tempo real.
dialog_params	string	String JSON para atualizar uma chave de API temporária expirada ou fornecer contexto de entrada em input_context.

Example:

{
  "apikey": "st-****",
  "input_context": [
    { "role": "user", "content": [{ "type": "input_text", "text": "Example context" }] }
  ]
}

stopDialog

stopDialog(): number

Notifica o servidor para concluir o reconhecimento e retornar o resultado final. A tarefa termina ao receber EVENT_TRANSCRIBER_COMPLETE.

cancelDialog

cancelDialog(): number

Encerra imediatamente o reconhecimento sem esperar o resultado final do servidor.

dialogAction

dialogAction(action_params: string): number

Envia uma ação em tempo de execução para informar ao AEC no dispositivo o estado da reprodução.

Parâmetro	Tipo	Descrição
action_params	string	String JSON que contém a ação.
action_params.type	string	Defina como "action".
action_params.command	string	play_start：Quando o AEC no dispositivo é usado, informa ao SDK que o player começou a reproduzir áudio. play_over：Quando o AEC no dispositivo é usado, informa ao SDK que o player terminou de reproduzir áudio.

updateAudio

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

Quando audio_update_manually é "true", envia ativamente os dados gravados por este método, em vez de preencher onNuiNeedAudioData.

Parâmetro	Tipo	Descrição
data	ArrayBuffer	Dados de áudio a reconhecer.
first_pack	boolean	Indica se este é o primeiro pacote de áudio. Use true para o primeiro e false para os seguintes.

pushReferenceData

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

Quando audio_update_manually é "true" e o AEC no dispositivo está habilitado, envia o áudio reproduzido como sinal de referência AEC.

Parâmetro	Tipo	Descrição
data	ArrayBuffer	Dados de áudio de referência.
first_pack	boolean	Indica se este é o primeiro pacote de áudio. Use true para o primeiro e false para os seguintes.

release

release(): number

Libera todos os recursos internos do SDK. A instância não pode ser usada depois. Para reutilizá-la, chame primeiro initialize.

GetVersion

GetVersion(): string

Retorna a versão atual do SDK.

refreshApikey

refreshApikey(apikey: string, url: string = ''): string

Atualiza uma chave de API e retorna um token temporário de autenticação. Faz uma chamada de rede síncrona; não o chame na thread da interface.

Parâmetro	Tipo	Descrição
apikey	string	Chave de API existente.
url	string	Endpoint opcional de autenticação. Padrão: string vazia, que usa o endpoint padrão.

INativeNuiCallback

onNuiEventCallback

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

Recebe eventos e resultados de reconhecimento.

Parâmetro	Tipo	Descrição
event	Constants.NuiEvent	Evento de callback.
resultCode	number	Válido apenas quando ocorre o evento EVENT_ASR_ERROR.
arg2	number	Reserved.
kwsResult	KwsResult	Resultado da palavra de ativação. Ignore este campo no reconhecimento de fala em tempo real.
asrResult	AsrResult	Resultado do reconhecimento. allResponse contém a resposta JSON completa do servidor. Obtenha o ID da tarefa em header.task_id e o texto em payload.output.sentence.text.

Events:

Evento	Descrição
EVENT_TRANSCRIBER_STARTED	A tarefa foi iniciada. header.task_id em asrResult.allResponse contém o ID da tarefa. Registre-o para solução de problemas.
EVENT_VAD_START	Acionado após o início da tarefa. Não indica a detecção do início da fala.
EVENT_VAD_END	O fim da fala foi detectado.
EVENT_SENTENCE_START	O início de um enunciado foi detectado.
EVENT_ASR_PARTIAL_RESULT	Um resultado intermediário de reconhecimento está disponível.
EVENT_SENTENCE_END	O fim de um enunciado foi detectado, e seu resultado completo está disponível.
EVENT_ASR_WARN	Ocorreu um aviso não fatal durante o reconhecimento, como uma interrupção de rede com reconexão ativada.
EVENT_ASR_ERROR	Ocorreu um erro durante o reconhecimento. resultCode contém o código de erro.
EVENT_MIC_ERROR	Nenhum dado de áudio foi recebido por dois segundos consecutivos. Verifique o código de gravação, as permissões ou se outro aplicativo está usando o gravador.
EVENT_TRANSCRIBER_COMPLETE	O reconhecimento foi concluído.
EVENT_AEC_DATA	Dados de áudio processados pelo AEC, retornados por onNuiAssistEventCallback.

onNuiAudioStateChanged

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

O SDK usa este callback para informar ao aplicativo quando iniciar ou parar a gravação.

State	Descrição
STATE_OPEN	A interação foi iniciada. O dispositivo de gravação pode ser aberto.
STATE_PAUSE	A interação foi interrompida. A gravação pode ser interrompida.
STATE_CLOSE	A instância do SDK foi liberada. O dispositivo de gravação pode ser completamente fechado.

No HarmonyOS, AudioCapturer é criado de forma assíncrona. Crie o gravador durante a inicialização. Ao receber STATE_CLOSE, pare a gravação, mas mantenha a instância para reutilização. Libere-a no fluxo unificado release. Isso evita que um gravador em recriação ignore uma chamada imediata a start quando chegar o próximo STATE_OPEN.

onNuiNeedAudioData

onNuiNeedAudioData: (buffer: ArrayBuffer) => number;

Chamado continuamente quando o SDK obtém áudio. Preencha buffer.byteLength bytes, normalmente 20 ms de PCM mono de 16 bits, e retorne o número de bytes escritos. Um valor ≤ 0 indica erro ou ausência de dados.

onNuiAudioRMSChanged

onNuiAudioRMSChanged: (val: number) => number;

Informa o volume atual para atualizar a interface. Quando audio_config.mic.volume_mode é "dbfs", val varia de -160 a 0. A implementação do callback pode retornar 0.

onNuiAssistEventCallback

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

Callback opcional para eventos e dados auxiliares internos do SDK. Omita-o se essas informações não forem necessárias.

Parâmetro	Tipo	Descrição
event	Constants.NuiEvent	Evento auxiliar.
info	string	Informações adicionais, geralmente uma string JSON.
infoLen	number	Comprimento das informações adicionais.
data	ArrayBuffer	Dados auxiliares, como áudio processado pelo AEC.

onNuiLogTrackCallback

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

Recebe os logs de rastreamento do SDK. Os níveis retornados dependem de log_track_level e do argumento level de initialize.

Objetos de resultado

AsrResult

Property	Tipo	Descrição
finish	boolean	Indica se o resultado atual é final.
resultCode	number	Código de status do resultado.
asrResult	string	Texto reconhecido. Para EVENT_ASR_ERROR, este campo contém a mensagem de erro.
allResponse	string	Resposta completa do servidor como string JSON, incluindo o ID da tarefa e o texto do enunciado.

KwsResult

Property	Tipo	Descrição
type	Constants.WuwType	Tipo de palavra de ativação. Ignore este campo no reconhecimento em tempo real.
kws	string	Palavra de ativação. Ignore este campo no reconhecimento em tempo real.

Constantes e enumerações

Nome	Descrição
Constants.ModeType	Modos do SDK: MODE_DIALOG, MODE_TTS e MODE_STREAM_INPUT_TTS.
Constants.VadMode	Modo VAD. O reconhecimento em tempo real usa TYPE_P2T, no qual o usuário chama stopDialog para encerrar o reconhecimento.
Constants.AudioState	Estados de áudio: STATE_OPEN, STATE_PAUSE e STATE_CLOSE.
Constants.LogLevel	Níveis de log de LOG_LEVEL_VERBOSE (0) a LOG_LEVEL_NONE (5).
Constants.NuiResultCode	Códigos de erro do SDK, como SUCCESS (0), ILLEGAL_PARAM (240002), NECESSARY_PARAM_LACK (240004) e SDK_NOT_INIT (240011).
Constants.kServiceTypeSpeechTranscriber	Valor de service_type para reconhecimento em tempo real: 4.
Constants.ModeFullCloud	Modo totalmente em nuvem. O valor de service_mode é "1".

Exemplo de código

O código a seguir mostra o fluxo principal do SDK. Para tratamento completo de permissões, fila de gravação e análise de respostas, consulte DashFunAsrSpeechTranscriberPage.ets no SDK.

import { AsrResult, Constants, INativeNuiCallback, KwsResult, NativeNui } from 'neonui';

const callback: INativeNuiCallback = {
  onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
    kwsResult: KwsResult, asrResult: AsrResult): void => {
    if (event == Constants.NuiEvent.EVENT_ASR_PARTIAL_RESULT
      || event == Constants.NuiEvent.EVENT_SENTENCE_END) {
      // Parse payload.output.sentence.text from asrResult.allResponse.
    } else if (event == Constants.NuiEvent.EVENT_TRANSCRIBER_COMPLETE) {
      // Recognition is complete.
    } else if (event == Constants.NuiEvent.EVENT_ASR_ERROR) {
      // resultCode contains the error code.
    }
  },
  onNuiAudioStateChanged: (state: Constants.AudioState): void => {
    // Control AudioCapturer for STATE_OPEN, STATE_PAUSE, and STATE_CLOSE.
  },
  onNuiNeedAudioData: (buffer: ArrayBuffer): number => {
    // Copy recording data to buffer and return the number of bytes written.
    return 0;
  },
  onNuiAudioRMSChanged: (val: number): number => 0,
  onNuiLogTrackCallback: (level: Constants.LogLevel, log: string): void => {}
};

const nuiInstance = new NativeNui(Constants.ModeType.MODE_DIALOG);

const initParams: Record<string, Object> = {};
initParams['url'] = 'wss://dashscope.aliyuncs.com/api-ws/v1/inference';
initParams['device_id'] = 'my_device_id';
initParams['service_mode'] = Constants.ModeFullCloud;
initParams['audio_update_manually'] = 'false';

const initResult = nuiInstance.initialize(
  callback,
  JSON.stringify(initParams),
  Constants.LogLevel.LOG_LEVEL_DEBUG,
  false
);

if (initResult == Constants.NuiResultCode.SUCCESS) {
  const nlsConfig: Record<string, Object> = {
    'model': 'qwen-audio-3.0-asr-flash-streaming',
    'sr_format': 'opus',
    'sample_rate': 16000
  };
  const params: Record<string, Object> = {
    'service_type': Constants.kServiceTypeSpeechTranscriber,
    'nls_config': nlsConfig
  };
  nuiInstance.setParams(JSON.stringify(params));

  const dialogParams: Record<string, Object> = { 'apikey': 'st-****' };
  nuiInstance.startDialog(Constants.VadMode.TYPE_P2T, JSON.stringify(dialogParams));
}

// Stop recognition when the user finishes recording, and wait for EVENT_TRANSCRIBER_COMPLETE.
function stopRecognition(): void {
  nuiInstance.stopDialog();
}
// Call nuiInstance.release() from the EVENT_TRANSCRIBER_COMPLETE handler.

Use AudioCapturer de @kit.AudioKit para gravar. O áudio deve ser PCM mono de 16 bits, com taxa de amostragem suportada pelo modelo selecionado.

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

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

const capturer = await audio.createAudioCapturer(options);
capturer.on('readData', (buffer: ArrayBuffer): void => {
  // Pull mode: enqueue data for onNuiNeedAudioData.
  // Push mode: call nuiInstance.updateAudio(buffer, firstPack).
});
await capturer.start();