Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Paraformer HarmonyOS SDK

Última atualização: Nov 19, 2026

Este guia explica como usar o SDK HarmonyOS de reconhecimento de fala em tempo real Paraformer para converter fala em texto.

ImportanteO Alibaba Cloud Model Studio introduziu um domínio específico de workspace para a região China (Pequim). O domínio oferece desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Substitua {WorkspaceId} pelo seu ID do workspace real. O domínio existente permanece disponível.

Guia do usuário: Para introduções aos modelos e recomendações de seleção, consulte Reconhecimento de fala em tempo real - Fun-ASR e Paraformer.

Pré-requisitos

  1. Obtenha e configure uma chave de API. Não insira chaves de API de longa duração diretamente no código do aplicativo móvel. Recomendamos gerar uma chave de API temporária no servidor do aplicativo e enviá-la ao cliente.

Instalar o SDK

  • Baixe o pacote SDK mais recente.
  • Extraia o pacote TAR. Obtenha o SDK no formato HAR do diretório neonui e adicione-o às dependências do seu projeto. Para integração C++, obtenha as bibliotecas dinâmicas e arquivos de cabeçalho de native/libs e native/include no pacote TAR.

Início rápido

Abra o projeto no DevEco Studio. O código de exemplo está localizado em DashParaformerSpeechTranscriberPage.ets. Substitua a chave de API para testar o recurso.

Etapas de invocação

  1. Inicialize o SDK.
  2. Configure os parâmetros com base nos requisitos do seu negócio: Use o parâmetro parameters de initialize para definir parâmetros de conexão e controle e use setParams para definir parâmetros de efeito de reconhecimento de fala.
  3. Chame startDialog para iniciar o reconhecimento.
  4. No callback onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
  5. No callback onNuiNeedAudioData, forneça continuamente dados de áudio gravados.
  6. No callback onNuiEventCallback, escute eventos e obtenha resultados de reconhecimento de fala.
  7. Chame stopDialog para parar o reconhecimento e ouça o evento EVENT_TRANSCRIBER_COMPLETE para confirmar que o reconhecimento terminou.
  8. Quando o reconhecimento de fala não for mais necessário, chame release para liberar os recursos do SDK.

Parâmetros da solicitação

Parâmetros de conexão e controle

Passe uma string JSON para o parâmetro parameters de initialize para configurar os seguintes parâmetros. Exemplo: A seguinte string JSON é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
  • Descrições dos parâmetros
ParâmetroTipoObrigatórioDescrição
urlstring

Sim

O endpoint. Isso é fixado em wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Substitua {WorkspaceId} pelo seu ID de workspace real.

apikeystring

Sim

A chave de API. Recomendamos usar uma chave de API temporária mais segura, com curto período de validade, para reduzir o risco de vazamento de uma chave de longo prazo.

service_modestring

Sim

O modo de operação. Para reconhecimento de fala em tempo real, isso é fixado em "1".

device_idstring

Sim

Uma string única que identifica o usuário final. Você pode defini-la como um ID de usuário no aplicativo ou um identificador de dispositivo único gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas.

debug_pathstring

Não

O caminho de armazenamento para arquivos de log. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Neste caso, você deve especificar um caminho de arquivo de log. Caso contrário, ocorrerá um erro. No máximo dois arquivos de log são retidos localmente.

save_wavstring

Não

Especifica se deve salvar arquivos de áudio para depuração. Os arquivos de áudio são salvos em debug_path. Valor padrão: "false". Valores válidos: - "true": sim - "false": não. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Você também deve definir debug_path.

max_log_file_sizenumber

Não

Define o tamanho máximo de um arquivo de log em bytes. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Valor padrão: 104857600 (100 * 1024 * 1024 bytes, ou 100 MiB).

log_track_levelnumber

Não

Controla o nível de filtragem do conteúdo de log enviado externamente através do callback onNuiLogTrackCallback. Valor padrão: 2. Valores válidos: - 0: LOG_LEVEL_VERBOSE - 1: LOG_LEVEL_DEBUG - 2: LOG_LEVEL_INFO - 3: LOG_LEVEL_WARNING - 4: LOG_LEVEL_ERROR - 5: LOG_LEVEL_NONE (desabilita este recurso). Nota: log_track_level e level, que é definido através de initialize, determinam juntos quais logs são enviados ao callback. Um nível de log deve ser maior ou igual tanto a log_track_level quanto a level para acionar o callback. Por exemplo, se log_track_level for 2 (INFO) e level for 3 (WARNING), apenas logs no nível WARNING ou superior (valor >=3) acionam o callback.

Parâmetros de efeito de reconhecimento de fala

Passe uma string JSON para o parâmetro params de setParams para configurar os seguintes parâmetros. Exemplo: A seguinte string JSON é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
  • Descrições dos parâmetros
Parâmetro de Nível-1TipoObrigatórioDescrição
service_typeint

Sim

O tipo de serviço de fala. Para reconhecimento de fala em tempo real, isso é fixado em 4.

nls_configobject

Sim

O objeto de configuração principal de reconhecimento de fala, que contém parâmetros chave para seleção de modelo e controle de efeito de reconhecimento.

nls_config.modelstring

Sim

O modelo de reconhecimento de fala.

nls_config.sr_formatstring

Sim

O formato do áudio a ser reconhecido. Formatos suportados: pcm, wav e opus.

Importante

  • opus: O áudio de origem deve ser codificado em PCM. O SDK o codifica em OPUS.
  • wav/pcm: O áudio deve ser codificado em PCM.
nls_config.sample_rateint

Sim

A taxa de amostragem do áudio a ser reconhecido, em Hz. Isso varia conforme o modelo: - paraformer-realtime-v2 suporta qualquer taxa de amostragem. - paraformer-realtime-8k-v2 suporta apenas 8000 Hz.

nls_config.disfluency_removal_enabledboolean

Não

Especifica se devem ser removidas disfluências, como palavras de preenchimento. Valor padrão: false.

nls_config.language_hintsarray[string]

Não

Especifica códigos de idioma para o áudio a ser reconhecido. Se o idioma não puder ser determinado antecipadamente, omita este parâmetro e o modelo detectará o idioma automaticamente. Códigos de idioma suportados: - zh: Chinês - en: Inglês - ja: Japonês - yue: Cantonês - ko: Coreano - de: Alemão - fr: Francês - ru: Russo. Este parâmetro tem efeito apenas para modelos que suportam vários idiomas.

nls_config.semantic_punctuation_enabledboolean

Não

Especifica o modo de segmentação de sentenças. Valor padrão: false. Valores válidos: - true: Habilita a segmentação semântica e desabilita a segmentação VAD. - false: Habilita a segmentação VAD e desabilita a segmentação semântica. A segmentação semântica é mais precisa e adequada para transcrição de reuniões. A segmentação VAD (Detecção de Atividade de Voz) tem menor latência e é adequada para interação em tempo real. Este parâmetro tem efeito apenas para modelos v2 e posteriores.

nls_config.max_sentence_silenceint

Não

O limite de silêncio para segmentação de sentenças VAD (Detecção de Atividade de Voz), em milissegundos. Valor padrão: 800. Intervalo válido: [200, 6000]. Quando o silêncio após um segmento excede esse limite, o sistema determina que a sentença terminou. Este parâmetro tem efeito apenas quando semantic_punctuation_enabled é false e o modelo é v2 ou posterior.

nls_config.multi_threshold_mode_enabledboolean

Não

Especifica se deve habilitar o modo de prevenção de segmentos excessivamente longos. Este modo evita que os segmentos VAD se tornem muito longos. Valor padrão: false (desabilitado). Valores válidos: - true: habilita o modo - false: desabilita o modo. Este parâmetro tem efeito apenas quando semantic_punctuation_enabled é false e o modelo é v2 ou posterior.

nls_config.punctuation_prediction_enabledboolean

Não

Especifica se deve adicionar pontuação automaticamente aos resultados de reconhecimento. Valor padrão: true. Valores válidos: - true: sim - false: não. Este parâmetro tem efeito apenas para modelos v2 e posteriores.

nls_config.heartbeatboolean

Não

Especifica se deve manter uma conexão persistente com o servidor. Valor padrão: false. Valores válidos: - true: A conexão permanece ativa enquanto áudio silencioso é enviado continuamente. - false: Mesmo que áudio silencioso seja enviado continuamente, a conexão expira após um período de tempo. O tempo limite é um padrão do lado do servidor e não pode ser configurado no cliente. Este parâmetro tem efeito apenas para modelos v2 e posteriores.

nls_config.inverse_text_normalization_enabledboolean

Não

Especifica se deve habilitar a normalização inversa de texto (ITN). Quando habilitada, numerais chineses são convertidos para numerais arábicos. Valor padrão: true (habilitado). Valores válidos: - true: habilitado - false: desabilitado. Este parâmetro tem efeito apenas para modelos v2 e posteriores.

nls_config.vocabulary_idstring

Não

O ID do vocabulário de palavras-chave, que melhora a precisão do reconhecimento de palavras específicas. Este parâmetro aplica-se a modelos v2 e posteriores. Para mais informações, consulte Palavras-chave personalizadas.

Referência da API

NativeNui

initialize

Inicializa uma instância do SDK de reconhecimento de fala. Não inicialize a instância novamente antes de chamar release.

Esta interface bloqueia a thread chamadora. Chame-a a partir de uma thread que não seja de UI.

  • Assinatura do método
public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number
  • Descrições dos parâmetros
ParâmetroTipoDescrição
callbackINativeNuiCallback

Uma implementação da interface de callback de eventos e dados.

parametersstring

Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.

levelnumber

Controla o nível de log do SDK. Os valores válidos são definidos pela enumeração Constants.LogLevel.

save_logboolean

Especifica se deve salvar logs locais. Se este parâmetro for true, use debug_path em Parâmetros de conexão e controle para especificar um caminho. Você também pode usar max_log_file_size para definir o tamanho do arquivo.

  • Valor de retorno

setParams

Define os parâmetros de efeito de reconhecimento de fala no formato JSON. Chame esta interface antes de startDialog.

  • Assinatura do método
public setParams(params: string): number
  • Descrições dos parâmetros
ParâmetroTipoDescrição
paramsstring

Os parâmetros de efeito de reconhecimento de fala.

  • Valor de retorno

startDialog

Inicia o reconhecimento.

  • Assinatura do método
public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
  • Descrições dos parâmetros
ParâmetroTipoDescrição
vad_modeConstants.VadMode

O modo VAD. Isso é fixado em Constants.VadMode.TYPE_P2T.

dialog_paramsstring

Se a chave de API temporária especificada por apikey em Parâmetros de conexão e controle tiver expirado, atualize-a aqui. O valor está no formato JSON: typescript { "apikey": "st-****" }

  • Valor de retorno

stopDialog

Interrompe o reconhecimento. Após chamar esta interface, o servidor retorna o resultado final do reconhecimento e encerra a tarefa.

  • Assinatura do método
public stopDialog(): number
  • Valor de retorno

cancelDialog

Para o reconhecimento imediatamente sem esperar que o servidor retorne o resultado final do reconhecimento.

  • Assinatura do método
public cancelDialog(): number
  • Valor de retorno

release

Libera todos os recursos internos do SDK. Após a chamada deste método, a instância do SDK torna-se indisponível. Para usá-la novamente, chame initialize para reinicializá-la.

  • Assinatura do método
public release(): number
  • Valor de retorno

GetVersion

Obtém as informações da versão atual do SDK.

  • Assinatura do método
public GetVersion(): string
  • Valor de retorno

As informações da versão atual do SDK.

INativeNuiCallback

Escuta eventos, estados de áudio, alterações de volume e logs durante o reconhecimento de fala em tempo real.

onNuiEventCallback

Escuta eventos de reconhecimento e obtém resultados de reconhecimento de fala.

  • Assinatura do método
onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;
  • Descrições dos parâmetros
ParâmetroTipoDescrição
eventConstants.NuiEvent

O evento de callback.

resultCodenumber

Válido apenas quando o evento EVENT_ASR_ERROR ocorre.

asrResultAsrResult

O resultado do reconhecimento de fala.

kwsResultKwsResult

O recurso de despertar por voz. Você não precisa usar este parâmetro.

arg2number

Um parâmetro reservado.

onNuiAudioStateChanged

O SDK usa este callback para indicar quando a gravação deve começar ou parar.

  • Assinatura do método
onNuiAudioStateChanged: (state: Constants.AudioState) => void
  • Descrições do AudioState
EstadoDescrição
STATE_OPEN

A interação começa. Você pode iniciar o dispositivo de gravação.

STATE_PAUSE

A interação está pausada. Você pode pausar a gravação.

STATE_CLOSE

A interação para. Você pode parar completamente o dispositivo de gravação.

onNuiAudioRMSChanged

Monitora o volume dos dados de áudio gravados para exibição na UI.

  • Assinatura do método
onNuiAudioRMSChanged: (val: number) => number
  • Descrições dos parâmetros
ParâmetroTipoDescrição
valnumber

O volume dos dados de áudio gravados. O intervalo de saída é geralmente [-160, 0].

onNuiNeedAudioData

Após o início do reconhecimento, este callback é acionado continuamente. Forneça os dados de áudio a serem reconhecidos no callback.

  • Assinatura do método
onNuiNeedAudioData: (buffer: ArrayBuffer) => number
  • Descrições dos parâmetros
ParâmetroTipoDescrição
bufferArrayBuffer

Os dados de áudio a serem fornecidos. O SDK usa buffer.byteLength como o número solicitado de bytes.

  • Valor de retorno

O número real de bytes fornecidos. Um valor de retorno de <=0 indica um erro ou ausência de dados.

onNuiLogTrackCallback

Este callback recebe logs internos detalhados do SDK para solução de problemas e depuração.

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

Constants.NuiEvent

Os tipos de eventos do SDK HarmonyOS são definidos pela enumeração Constants.NuiEvent. Os seguintes eventos se aplicam ao reconhecimento de fala em tempo real:

EventoDescrição
EVENT_TRANSCRIBER_STARTED

A tarefa é iniciada com sucesso.

EVENT_VAD_START

Este evento é acionado imediatamente após o início da tarefa. Ele não indica que o início da fala foi detectado.

EVENT_VAD_END

O fim da fala foi detectado.

EVENT_ASR_PARTIAL_RESULT

Um resultado intermediário de reconhecimento de fala.

EVENT_ASR_RESULT

Um resultado completo de reconhecimento de fala.

EVENT_ASR_ERROR

Ocorre um erro durante o reconhecimento de fala.

EVENT_MIC_ERROR

Este evento é acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos.

EVENT_SENTENCE_START

O início de uma frase é detectado.

EVENT_SENTENCE_END

O fim de uma frase é detectado e um resultado completo de reconhecimento é retornado.

EVENT_TRANSCRIBER_COMPLETE

O reconhecimento de fala termina.

Tipos auxiliares

Constants.LogLevel

Os valores de enumeração para o parâmetro level são os seguintes:

ValorDescrição
LOG_LEVEL_VERBOSE

Os logs mais detalhados.

LOG_LEVEL_DEBUG

Logs de depuração.

LOG_LEVEL_INFO

Logs informativos (padrão).

LOG_LEVEL_WARNING

Logs de aviso.

LOG_LEVEL_ERROR

Logs de erro.

LOG_LEVEL_NONE

Desativa o registro de logs.

Gerenciamento de dispositivos de áudio

Diferente do Android, que usa AudioRecord, o HarmonyOS usa AudioCapturer de @kit.AudioKit para capturar áudio. O exemplo do produto encapsula essa lógica na classe utilitária AudioRecorder.ets, que você pode reutilizar diretamente.

  • Criação: audio.createAudioCapturer(capturerOptions) cria o captador assincronamente com uma taxa de amostragem fixa de 16 kHz, profundidade de bits de 16 e um canal (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
  • Evento de dados: capturer.on('readData', (buffer: ArrayBuffer) => void) obtém continuamente dados de áudio gravados. Armazene os dados em buffer em uma fila para que o callback onNuiNeedAudioData possa recuperá-los conforme necessário.
  • Evento de estado: capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING indica que a gravação foi iniciada e STATE_STOPPED indica que a gravação foi interrompida.
  • Controle: start() inicia, stop() para e release() libera o captador.

ObservaçãoO HarmonyOS cria AudioCapturer assincronamente. Chame start() somente após a conclusão da criação. Portanto, não crie e inicie imediatamente um gravador quando STATE_OPEN ocorrer. Crie-o primeiro e depois chame start() no callback STATE_OPEN. O exemplo cria o gravador durante doInit e o inicia durante onNuiAudioStateChanged. Quando STATE_CLOSE ocorrer, pare o gravador, mas mantenha a instância para reutilização. Libere-a em release.

Declaração de permissão

Declare a permissão de microfone em module.json5 para usar a gravação:

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