Skip to main content

SDK HarmonyOS de reconhecimento de fala em tempo real Paraformer

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

O 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.

Início rápido

  1. Obter uma chave de API: Obter e configurar uma chave de API. Por segurança, recomendamos configurar a chave de API como uma variável de ambiente.
    Para conceder acesso temporário a aplicativos ou usuários terceiros, ou para controlar estritamente operações de alto risco, como acessar ou excluir dados sensíveis, use uma chave de API temporária. Uma chave de API temporária é válida por 60 segundos por padrão. Obtenha uma nova após a expiração.
  2. Baixe o SDK e execute o código de exemplo:
    • 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.
    • 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
urlstringSimO endpoint. Isso é fixado em wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Substitua {WorkspaceId} pelo seu ID de workspace real.
apikeystringSimA 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_modestringSimO modo de operação. Para reconhecimento de fala em tempo real, isso é fixado em "1".
device_idstringSimUma 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_pathstringNãoO 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_wavstringNãoEspecifica 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_sizenumberNãoDefine 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_levelnumberNãoControla 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_typeintSimO tipo de serviço de fala. Para reconhecimento de fala em tempo real, isso é fixado em 4.
nls_configobjectSimO 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.modelstringSimO modelo de reconhecimento de fala.
nls_config.sr_formatstringSim

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

  • 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_rateintSimA 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_enabledbooleanNãoEspecifica se devem ser removidas disfluências, como palavras de preenchimento. Valor padrão: false.
nls_config.language_hintsarray[string]NãoEspecifica 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_enabledbooleanNãoEspecifica 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_silenceintNãoO 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_enabledbooleanNãoEspecifica 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_enabledbooleanNãoEspecifica 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.heartbeatbooleanNãoEspecifica 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_enabledbooleanNãoEspecifica 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_idstringNãoO 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.

Interfaces principais

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
callbackINativeNuiCallbackUma implementação da interface de callback de eventos e dados.
parametersstringUma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.
levelnumberControla o nível de log do SDK. Os valores válidos são definidos pela enumeração Constants.LogLevel.
save_logbooleanEspecifica 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
paramsstringOs 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.VadModeO modo VAD. Isso é fixado em Constants.VadMode.TYPE_P2T.
dialog_paramsstringSe 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.NuiEventO evento de callback.
resultCodenumberVálido apenas quando o evento EVENT_ASR_ERROR ocorre.
asrResultAsrResultO resultado do reconhecimento de fala.
kwsResultKwsResultO recurso de despertar por voz. Você não precisa usar este parâmetro.
arg2numberUm 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_OPENA interação começa. Você pode iniciar o dispositivo de gravação.
STATE_PAUSEA interação está pausada. Você pode pausar a gravação.
STATE_CLOSEA 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
valnumberO 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
bufferArrayBufferOs 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_STARTEDA tarefa é iniciada com sucesso.
EVENT_VAD_STARTEste evento é acionado imediatamente após o início da tarefa. Ele não indica que o início da fala foi detectado.
EVENT_VAD_ENDO fim da fala foi detectado.
EVENT_ASR_PARTIAL_RESULTUm resultado intermediário de reconhecimento de fala.
EVENT_ASR_RESULTUm resultado completo de reconhecimento de fala.
EVENT_ASR_ERROROcorre um erro durante o reconhecimento de fala.
EVENT_MIC_ERROREste evento é acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos.
EVENT_SENTENCE_STARTO início de uma frase é detectado.
EVENT_SENTENCE_ENDO fim de uma frase é detectado e um resultado completo de reconhecimento é retornado.
EVENT_TRANSCRIBER_COMPLETEO 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_VERBOSEOs logs mais detalhados.
LOG_LEVEL_DEBUGLogs de depuração.
LOG_LEVEL_INFOLogs informativos (padrão).
LOG_LEVEL_WARNINGLogs de aviso.
LOG_LEVEL_ERRORLogs de erro.
LOG_LEVEL_NONEDesativa 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.
O 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" }
  ]
}