Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime SDK HarmonyOS

Aprenda sobre a integração do HarmonyOS SDK, parâmetros de solicitação, APIs, retornos de chamada e código de amostra para reconhecimento de fala em tempo real.

Guia do usuário: Para descrições de modelos e orientações de seleção, consulte Fala para texto.

Início rápido

1. Obtenha uma chave API. Não codifique uma chave de API de longa duração em um aplicativo cliente. Recomendamos que seu servidor de aplicativos obtenha uma chave de API temporária e envie para o cliente.
2. Baixe o pacote SDK mais recente. Extraia o pacote, copie entry/libs/neonui.har para o entry/libs diretório do seu aplicativo e adicione a dependência ao entry/oh-package.json5:

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

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

3. Declare permissões de rede e microfone no aplicativo module.json5 arquivo e solicite permissão de microfone em tempo de execução. reason_internet e reason_microphone são exemplos de nomes de recursos. Defina as descrições correspondentes nos recursos do seu 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 amostra do pacote SDK no DevEco Studio. A página de exemplo é entry/src/main/ets/pages/dashscope/DashFunAsrSpeechTranscriberPage.ets. Configure uma chave de API e execute o projeto.

Sequência de chamada

1. Crie um NativeNui(Constants.ModeType.MODE_DIALOG) instância.
2. Chame inicializar para inicializar o SDK e configurar 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 com base no estado do áudio.
6. Forneça continuamente dados de gravação em onNuiNeedAudioData. Se o envio de áudio ativo estiver ativado, chame updateAudio em vez disso.
7. Recupere resultados de reconhecimento e estados de tarefas em onNuiEventCallback.
8. Chame stopDialog e espere EVENT_TRANSCRIBER_COMPLETE.
9. Quando o reconhecimento não for mais necessário, ligue para release para liberar recursos.

Parâmetros de solicitação

Parâmetros de conexão e controle

Passe uma string JSON no parameters argumento de inicializar.

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

Parâmetros de reconhecimento

Passe uma string JSON no params argumento de setParams.

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

APIs

NativoNui

Importe o SDK:

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

Crie uma instância

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

inicializar

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

Inicializa o SDK. Este método pode bloquear. Não chame isso no thread da UI.

O método retorna um código de erro.

####setParams

setParams(params: string): number

Define parâmetros de reconhecimento antes startDialog. params é uma string JSON que contém os parâmetros de reconhecimento. O método retorna um código de erro.

startDialog

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

Inicia o reconhecimento.

Exemplo:

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

O método retorna um código de erro.

stopDialog

stopDialog(): number

Notifica o servidor para finalizar o reconhecimento e retornar o resultado final. A tarefa termina quando EVENT_TRANSCRIBER_COMPLETE é recebido. O método retorna um código de erro.

cancelarDialog

cancelDialog(): number

Encerra imediatamente o reconhecimento sem esperar pelo resultado final do servidor. O método retorna um código de erro.

diálogoAção

dialogAction(action_params: string): number

Envia uma ação de tempo de execução para atualizar o contexto de reconhecimento ou notificar o AEC sobre alterações no estado de reprodução.

Exemplo para atualização do contexto:

{
  "type": "action",
  "command": "context",
  "context": [
    {
      "role": "user",
      "content": [
        { "text": "Example context", "type": "input_text" }
      ]
    }
  ]
}

O método retorna um código de erro.

atualizaçãoÁudio

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

Quando audio_update_manually é "true", envia ativamente os dados de gravação por meio deste método em vez de preencher onNuiNeedAudioData.

O método retorna um código de erro.

pushReferenceData

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

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

O método retorna um código de erro.

lançamento

release(): number

Libera todos os recursos internos do SDK. A instância não pode ser usada após esta chamada. Para usá-lo novamente, ligue initialize primeiro. O método retorna um código de erro.

Obter versão

GetVersion(): string

Retorna a versão atual do SDK.

atualizarApikey

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

Atualiza uma chave de API e retorna um token de autenticação temporário. Este método executa uma chamada de rede síncrona. Não chame isso no thread da UI.

INativeNuiCallback

onNuiEventCallback

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

Recebe eventos e resultados de reconhecimento.

Eventos:

onNuiAudioStateChanged

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

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

No HarmonyOS, AudioCapturer é criado de forma assíncrona. Crie a instância do gravador durante a inicialização. Quando STATE_CLOSE for recebido, pare a gravação, mas guarde a instância para reutilização. Libere-o no unificado release fluxo. Isto evita que um gravador recriado ignore uma resposta imediata. start ligue quando for o próximo STATE_OPEN evento chega.

onNuiNeedAudioData

onNuiNeedAudioData: (buffer: ArrayBuffer) => number;

Chamado continuamente quando o SDK extrai áudio. Preencher buffer.byteLength bytes, normalmente 20 ms de PCM mono de 16 bits, e retorna o número de bytes gravados. Um valor menor ou igual a 0 indica um erro ou nenhum dado disponível.

onNuiAudioRMSChanged

onNuiAudioRMSChanged: (val: number) => number;

Informa o volume de áudio atual para atualizações da IU. Quando audio_config.mic.volume_mode é "dbfs", val varia de -160 para 0. A implementação de retorno de chamada pode retornar 0.

onNuiAssistEventCallback

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

Retorno de chamada opcional para eventos e dados auxiliares internos do SDK. Omita esse retorno de chamada se as informações não forem necessárias.

onNuiLogTrackCallback

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

Recebe logs de rastreamento do SDK. Os níveis retornados são determinados por ambos log_track_level e o level argumento de initialize.

Objetos de resultado

####AsrResult

####KwsResult

Constantes e enumerações

Código de exemplo

O código a seguir mostra o fluxo principal do SDK. Para tratamento completo de permissão, fila de gravação e análise de resposta, consulte DashFunAsrSpeechTranscriberPage.ets no pacote 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://maas.qwencloudapi.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.

Usar AudioCapturer de @kit.AudioKit para gravação. O áudio deve ser PCM mono de 16 bits com uma 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();