Este guia explica como usar o SDK do HarmonyOS para reconhecimento de fala não em tempo real do Paraformer para converter fala em texto.
Início rápido
-
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 de terceiros, ou para controlar estritamente operações de alto risco, como acessar ou excluir dados confidenciais, 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.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- 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 com C++, obtenha as bibliotecas dinâmicas e arquivos de cabeçalho denative/libsenative/includeno pacote TAR. - Abra o projeto no DevEco Studio. O código de exemplo está localizado em
DashParaformerFileTranscriberPage.ets. Substitua a chave de API para testar o recurso.
Etapas de invocação
Modo síncrono
- Inicialize o SDK.
- Configure os parâmetros com base nos requisitos do seu negócio.
- Chame
startFileTranscriberpara iniciar uma tarefa de reconhecimento comasync_requestdefinido comofalse. - Na interface
onFileTransEventCallback, escute o eventoEVENT_FILE_TRANS_RESULTpara obter o resultado final do reconhecimento. - Chame
releasepara liberar os recursos do SDK.
Modo assíncrono
- Inicialize o SDK.
- Configure os parâmetros com base nos requisitos do seu negócio.
- Chame
startFileTranscriberpara iniciar uma tarefa de reconhecimento comasync_requestdefinido comotrue. - Chame
queryFileTranscriberpara consultar o progresso ou o resultado do reconhecimento. - Na interface
onFileTransEventCallback, escute o eventoEVENT_FILE_TRANS_QUERY_RESULTpara obter o resultado atual da consulta. - Na interface
onFileTransEventCallback, escute o eventoEVENT_FILE_TRANS_RESULTpara obter o resultado final do reconhecimento. - Chame
releasepara liberar os recursos do SDK.
Parâmetros de solicitação
Parâmetros de conexão e controle
Passe uma string JSON para o parâmetro parameters de initializeFileTrans para configurar os seguintes parâmetros. Exemplo: A string JSON a seguir é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:
- Descrições dos parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | O endpoint. Isso é fixado em wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription. Substitua {WorkspaceId} pelo seu ID de workspace real. |
apikey | string | Sim | A chave de API. Recomendamos usar uma chave de API temporária mais segura com um 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 não em tempo real, isso é fixado em "1". |
device_id | string | Sim | Uma string exclusiva que identifica o usuário final. Você pode defini-la como um ID de usuário no aplicativo ou um identificador de dispositivo exclusivo 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 só entra em vigor se você definir save_log como true ao chamar initializeFileTrans. Nesse 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. |
max_log_file_size | number | Não | Define o tamanho máximo de um arquivo de log em bytes. Este parâmetro só entra em vigor se você definir save_log como true ao chamar initializeFileTrans. Valor padrão: 104857600 (100 * 1024 * 1024 bytes, ou 100 MiB). |
Parâmetros de efeito de reconhecimento de fala
Configure o parâmetro nls_config usando setParams, ou configure todos os parâmetros de efeito de reconhecimento de fala usando startFileTranscriber. Exemplo: A string JSON a seguir é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:
- Descrições dos parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
file_urls | array[string] | Sim | Uma lista de URLs para os arquivos de áudio ou vídeo a serem transcritos. HTTP e HTTPS são suportados. Uma única solicitação suporta apenas 1 URL. Se um arquivo de áudio estiver armazenado no Alibaba Cloud OSS, o SDK não suporta uma URL temporária que use o prefixo - Taxas de amostragem de áudio variam de acordo com o modelo: - paraformer-v2 suporta qualquer taxa de amostragem. - paraformer-8k-v2 suporta apenas 8 kHz. - Tamanho e duração do arquivo de áudio: O arquivo não pode exceder 2 GB, e sua duração não pode exceder 12 horas. Para processar um arquivo que exceda esses limites, pré-processe-o para reduzir o tamanho do arquivo. Para obter as melhores práticas, consulte Pré-processar arquivos de vídeo para melhorar a eficiência da transcrição no reconhecimento de arquivos de áudio. |
async_request | boolean | Não | Especifica se deve usar uma solicitação assíncrona. Valor padrão: false. Valores válidos: - true: solicitação assíncrona - false: solicitação síncrona. |
apikey | string | Não | Se apikey em Parâmetros de conexão e controle for uma chave de API temporária, atualize-a aqui antes que expire. |
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.language_hints | array[string] | Não | Especifica os códigos de idioma para o áudio a ser reconhecido. Este parâmetro se aplica apenas ao paraformer-v2. Valor padrão: ["zh", "en"]. 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. |
nls_config.disfluency_removal_enabled | boolean | Não | Especifica se deve remover disfluências, como palavras de preenchimento. Valor padrão: false. Valores válidos: - true: remove disfluências - false: retém disfluências. |
nls_config.timestamp_alignment_enabled | boolean | Não | Especifica se deve ativar o alinhamento de timestamps. Valor padrão: false. Valores válidos: - true: ativado - false: desativado. |
nls_config.special_word_filter | object | Não | Especifica palavras sensíveis a serem processadas durante o reconhecimento de fala e suporta diferentes métodos de processamento para diferentes palavras. Se este parâmetro for omitido, a lógica de filtragem de palavras sensíveis integrada será ativada. Palavras que correspondem à lista de palavras sensíveis do Alibaba Cloud Model Studio são substituídas pelo mesmo número de caracteres *. Se este parâmetro for especificado, as palavras correspondentes podem ser substituídas por caracteres * ou removidas. O valor é um objeto JSON no seguinte formato: { "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true }. Descrições dos campos JSON: - filter_with_signed: Um objeto opcional que especifica palavras a serem substituídas pelo mesmo número de caracteres *. No exemplo anterior, o resultado para “帮我测试一下这段代码” é “帮我**一下这段代码”. Seu campo word_list é uma matriz de strings a serem substituídas. - filter_with_empty: Um objeto opcional que especifica palavras a serem removidas do resultado. No exemplo anterior, o resultado para “比赛这就要开始了吗?” é “比赛这就要了吗”. Seu campo word_list é uma matriz de strings a serem removidas. - system_reserved_filter: Um booleano opcional. Valor padrão: true. Especifica se as regras integradas de palavras sensíveis devem ser ativadas. Se definido como true, as palavras que correspondem à lista de palavras sensíveis do Alibaba Cloud Model Studio são substituídas pelo mesmo número de caracteres *. |
nls_config.channel_id | array[integer] | Não | Especifica os índices das faixas de áudio a serem reconhecidas em um arquivo de áudio com múltiplas faixas. Os índices começam em 0. Por exemplo, Valor padrão: |
nls_config.diarization_enabled | boolean | Não | Especifica se deve ativar a diarização de falantes. Este recurso está desativado por padrão. Ele se aplica apenas a áudio mono. Áudio multicanal não suporta diarização de falantes. Quando ativado, o resultado do reconhecimento contém Se a diarização de falantes estiver ativada, recomendamos limitar a duração do áudio a 2 horas para evitar falha de reconhecimento ou tempo limite esgotado. Para um exemplo de |
nls_config.speaker_count | integer | Não | Um valor de referência para o número de falantes. Para usar este recurso, defina diarization_enabled como true. Por padrão, o número de falantes é determinado automaticamente. Se este parâmetro for definido, ele apenas orienta o algoritmo a gerar o número especificado e não garante esse número. Intervalo válido: [2, 100]. O mínimo é 2 porque este recurso distingue vários falantes. |
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 se aplica aos modelos v2 e posteriores. Para mais informações, consulte Palavras-chave personalizadas. |
Interfaces principais
NativeNui
initializeFileTrans
Inicializa uma instância do SDK de transcrição de fala. Não inicialize a instância novamente antes de chamar release.
initializeFileTrans e passar um callback INativeFileTransCallback em vez de usar initialize.- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
callback | INativeFileTransCallback | Uma implementação da interface de callback de eventos e dados de transcrição de arquivos. |
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 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 ou atualiza apenas o parâmetro nls_config. Se todos os parâmetros forem fornecidos em startFileTranscriber, você não precisa chamar este método.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | string | O parâmetro nls_config em Parâmetros de efeito de reconhecimento de fala. Parâmetros fora de nls_config não podem ser definidos usando este método. Exemplo: { "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } } |
- Valor de retorno
startFileTranscriber
Inicia o reconhecimento.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | string | Os parâmetros de efeito de reconhecimento de fala. Exemplo: { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } } |
task_id | ArrayBuffer | O buffer do ID da tarefa. O SDK grava uma string de ID de tarefa aleatória gerada internamente neste buffer. O buffer deve ter pelo menos 33 bytes de comprimento. O exemplo usa new ArrayBuffer(64). Após uma chamada bem-sucedida, decodifique o buffer para obter o task_id da tarefa. |
- Valor de retorno
queryFileTranscriber
Consulta o status atual e o resultado de uma tarefa assíncrona. Após uma chamada bem-sucedida, o resultado é retornado pelo evento EVENT_FILE_TRANS_QUERY_RESULT no callback onFileTransEventCallback.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | O ID da tarefa a ser consultada, obtido do buffer gravado por startFileTranscriber. |
- Valor de retorno
cancelFileTranscriber
Cancela imediatamente a tarefa atual.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | O ID da tarefa a ser cancelada. |
- Valor de retorno
release
Libera todos os recursos internos do SDK. Depois que este método é chamado, a instância do SDK fica indisponível. Para usá-la novamente, chame initializeFileTrans para reinicializá-la.
- Assinatura do método
- Valor de retorno
GetVersion
Obtém as informações da versão atual do SDK.
- Assinatura do método
- Valor de retorno
INativeFileTransCallback
Define callbacks para eventos de transcrição de arquivos e resultados de reconhecimento.
onFileTransEventCallback
Escuta eventos de transcrição de arquivos e obtém resultados de reconhecimento de fala.
- Assinatura do método
- 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 EVENT_ASR_ERROR ocorre. |
finish | number | Indica se a tarefa terminou. |
asrResult | AsrResult | O resultado do reconhecimento de fala. |
taskId | string | O ID da tarefa. |
Constants.NuiEvent
Os tipos de eventos do SDK HarmonyOS são definidos pela enumeração Constants.NuiEvent. Os seguintes eventos se aplicam à transcrição de arquivos de áudio:
| Evento | Descrição |
|---|---|
EVENT_FILE_TRANS_CONNECTED | O serviço está conectado. |
EVENT_FILE_TRANS_UPLOADED | O arquivo de áudio a ser reconhecido foi carregado. |
EVENT_FILE_TRANS_QUERY_RESULT | O resultado da consulta da tarefa. |
EVENT_FILE_TRANS_RESULT | O resultado final do reconhecimento. |
EVENT_ASR_ERROR | Ocorre um erro durante o reconhecimento de fala. |
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. |
Baixar o resultado
Os resultados do reconhecimento de fala não em tempo real são gerados de forma assíncrona. A resposta retornada pelo evento EVENT_FILE_TRANS_RESULT contém transcription_url. Baixe o texto de reconhecimento no formato JSON a partir desta URL. A URL tem um período de validade. Baixe o resultado prontamente.