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
- 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
neonuie adicione-o às dependências do seu projeto. Para integração C++, obtenha as bibliotecas dinâmicas e arquivos de cabeçalho denative/libsenative/includeno 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
- Inicialize o SDK.
- Configure os parâmetros com base nos requisitos do seu negócio: Use o parâmetro
parametersde initialize para definir parâmetros de conexão e controle e use setParams para definir parâmetros de efeito de reconhecimento de fala. - Chame startDialog para iniciar o reconhecimento.
- No callback onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
- No callback onNuiNeedAudioData, forneça continuamente dados de áudio gravados.
- No callback onNuiEventCallback, escute eventos e obtenha resultados de reconhecimento de fala.
- Chame stopDialog para parar o reconhecimento e ouça o evento
EVENT_TRANSCRIBER_COMPLETEpara confirmar que o reconhecimento terminou. - 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | O endpoint. Isso é fixado em |
apikey | string | 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_mode | string | Sim | O modo de operação. Para reconhecimento de fala em tempo real, isso é fixado em |
device_id | string | 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_path | string | Não | O caminho de armazenamento para arquivos de log. Este parâmetro tem efeito apenas se você definir |
save_wav | string | Não | Especifica se deve salvar arquivos de áudio para depuração. Os arquivos de áudio são salvos em |
max_log_file_size | number | Não | Define o tamanho máximo de um arquivo de log em bytes. Este parâmetro tem efeito apenas se você definir |
log_track_level | number | Não | Controla o nível de filtragem do conteúdo de log enviado externamente através do 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-1 | Tipo | Obrigatório | Descrição |
|---|---|---|---|
service_type | int | Sim | O tipo de serviço de fala. Para reconhecimento de fala em tempo real, isso é fixado em |
nls_config | object | 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.model | string | Sim | O modelo de reconhecimento de fala. |
nls_config.sr_format | string | Sim | O formato do áudio a ser reconhecido. Formatos suportados: pcm, wav e opus. Importante
|
nls_config.sample_rate | int | 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_enabled | boolean | Não | Especifica se devem ser removidas disfluências, como palavras de preenchimento. Valor padrão: false. |
nls_config.language_hints | array[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_enabled | boolean | 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_silence | int | 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: |
nls_config.multi_threshold_mode_enabled | boolean | 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 |
nls_config.punctuation_prediction_enabled | boolean | 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.heartbeat | boolean | 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_enabled | boolean | 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_id | string | 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âmetro | Tipo | Descrição |
|---|---|---|
callback | INativeNuiCallback | Uma implementação da interface de callback de eventos e dados. |
parameters | string | Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle. |
level | number | Controla o nível de log do SDK. Os valores válidos são definidos pela enumeração Constants.LogLevel. |
save_log | boolean | Especifica se deve salvar logs locais. Se este parâmetro for |
- 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âmetro | Tipo | Descrição |
|---|---|---|
params | string |
- 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âmetro | Tipo | Descrição |
|---|---|---|
vad_mode | Constants.VadMode | O modo VAD. Isso é fixado em |
dialog_params | string | Se a chave de API temporária especificada por |
- 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âmetro | Tipo | Descrição |
|---|---|---|
event | Constants.NuiEvent | O evento de callback. |
resultCode | number | Válido apenas quando o evento |
asrResult | AsrResult | O resultado do reconhecimento de fala. |
kwsResult | KwsResult | O recurso de despertar por voz. Você não precisa usar este parâmetro. |
arg2 | number | 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
| Estado | Descriçã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âmetro | Tipo | Descrição |
|---|---|---|
val | number | O volume dos dados de áudio gravados. O intervalo de saída é geralmente |
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âmetro | Tipo | Descrição |
|---|---|---|
buffer | ArrayBuffer | Os dados de áudio a serem fornecidos. O SDK usa |
- 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:
| Evento | Descriçã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:
| Valor | Descriçã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 callbackonNuiNeedAudioDatapossa recuperá-los conforme necessário. - Evento de estado:
capturer.on('stateChange', (state: audio.AudioState) => void).STATE_RUNNINGindica que a gravação foi iniciada eSTATE_STOPPEDindica que a gravação foi interrompida. - Controle:
start()inicia,stop()para erelease()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" }
]
}