Skip to main content

SDK HarmonyOS de reconhecimento de fala não em tempo real Fun-ASR

Este guia explica como usar o SDK HarmonyOS de reconhecimento de fala não em tempo real Fun-ASR para converter fala em texto.

Início rápido

  1. Obter uma chave de API: Obter uma chave de API. Por segurança, recomendamos configurar a chave de API como uma variável de ambiente.
  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 DashFunAsrFileTranscriberPage.ets. Substitua a chave de API para testar o recurso.

Etapas de invocação

Modo síncrono

  1. Inicialize o SDK.
  2. Configure os parâmetros com base nos requisitos do seu negócio.
  3. Chame startFileTranscriber para iniciar uma tarefa de reconhecimento com async_request definido como false.
  4. Na interface onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_RESULT para obter o resultado final do reconhecimento.
  5. Chame release para liberar os recursos do SDK.

Modo assíncrono

  1. Inicialize o SDK.
  2. Configure os parâmetros com base nos requisitos do seu negócio.
  3. Chame startFileTranscriber para iniciar uma tarefa de reconhecimento com async_request definido como true.
  4. Chame queryFileTranscriber para consultar o progresso ou o resultado do reconhecimento.
  5. Na interface onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_QUERY_RESULT para obter o resultado da consulta atual.
  6. Na interface onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_RESULT para obter o resultado final do reconhecimento.
  7. 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 initializeFileTrans 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/v1/services/audio/asr/transcription",
    "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/v1/services/audio/asr/transcription. 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 não 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 só tem efeito se você definir save_log como true ao chamar initializeFileTrans. 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.
max_log_file_sizenumberNãoDefine o tamanho máximo de um arquivo de log em bytes. Este parâmetro só tem efeito 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 seguinte string JSON é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}
Descrições dos parâmetros
ParâmetroTipoObrigatórioDescrição
file_urlsarray[string]SimUma 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. Para requisitos de entrada, como formatos de áudio suportados e limites de tamanho e duração de arquivo, consulte Especificações de áudio. Se um arquivo de áudio estiver armazenado no Alibaba Cloud OSS, a API RESTful suporta uma URL temporária com o prefixo oss://, mas o SDK não.
  • Uma URL temporária é válida por 48 horas e não pode ser usada após expirar. Não use URLs temporárias em ambientes de produção.
  • A interface de credenciais de upload de arquivos é limitada a 100 QPS e não pode ser escalada horizontalmente. Não a utilize em ambientes de produção, cenários de alta concorrência ou testes de estresse.
  • Em ambientes de produção, use armazenamento estável, como Alibaba Cloud OSS, para garantir a disponibilidade de arquivos a longo prazo e evitar limitações de taxa.
- Se uma URL pública temporária do OSS não puder ser acessada, defina o cabeçalho de solicitação X-DashScope-OssResourceResolve como enable. Este método não é recomendado. O SDK não suporta a configuração de cabeçalhos de solicitação.
async_requestbooleanNãoEspecifica 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.
apikeystringNãoSe apikey em Parâmetros de conexão e controle for uma chave de API temporária, atualize-a aqui antes que expire.
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 nome do modelo.
nls_config.special_word_filterobjectNãoEspecifica palavras sensíveis a serem processadas durante o reconhecimento de fala e suporta diferentes métodos de processamento para diferentes palavras. Para mais informações, consulte Filtragem de palavras sensíveis.
nls_config.channel_idarray[integer]NãoEspecifica os índices das faixas de áudio a serem reconhecidas em um arquivo de áudio multifaixa. Os índices começam em 0. Por exemplo, [0] reconhece a primeira faixa, e [0, 1] reconhece a primeira e a segunda faixas. Se omitido, a primeira faixa é processada.
Cada faixa especificada é cobrada separadamente. Por exemplo, [0, 1] para um arquivo incorre em duas cobranças separadas.
Valor padrão: [0].
nls_config.diarization_enabledbooleanNãoEspecifica se deve ativar a diarização de falantes. Este recurso está desativado por padrão. Aplica-se apenas a áudio mono. Áudio multicanal não suporta diarização de falantes. Quando ativado, o resultado do reconhecimento contém speaker_id para distinguir os falantes.
Se a diarização de falantes estiver ativada, recomendamos limitar a duração do áudio a 2 horas para evitar falha no reconhecimento ou tempo limite.
Valor padrão: false. Para um exemplo de speaker_id, consulte Descrições do resultado de reconhecimento.
nls_config.speaker_countintegerNão
Este parâmetro só tem efeito quando a diarização de falantes é ativada definindo diarization_enabled como true.
Fornece um valor de referência para o número de falantes. Os valores válidos são inteiros de 2 a 100. Por padrão, o número de falantes é determinado automaticamente. Se este parâmetro for definido, ele apenas orienta o algoritmo a produzir o número especificado, sem garantir esse número. Sem valor padrão.
nls_config.vocabulary_idstringNãoO ID da lista de palavras-chave pré-compiladas. Crie uma lista de palavras-chave primeiro e passe seu ID durante o reconhecimento para usar as palavras-chave da lista. Isso é adequado quando o vocabulário é conhecido e relativamente estável, e o mesmo vocabulário precisa ser reutilizado entre solicitações. Para mais informações, consulte Palavras-chave pré-compiladas.
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á automaticamente o idioma. Você pode definir até 1 valor. Se definir mais, apenas os 1 primeiros serão usados.
  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • ko: Coreano
  • vi: Vietnamita
  • th: Tailandês
  • id: Indonésio
  • ms: Malaio
  • tl: Filipino
  • hi: Hindi
  • ar: Árabe
  • fr: Francês
  • de: Alemão
  • es: Espanhol
  • pt: Português
  • ru: Russo
  • it: Italiano
  • nl: Holandês
  • sv: Sueco
  • da: Dinamarquês
  • fi: Finlandês
  • no: Norueguês
  • el: Grego
  • pl: Polonês
  • cs: Tcheco
  • hu: Húngaro
  • ro: Romeno
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco
nls_config.parametersobjectNãoConfigura parâmetros adicionais como um objeto JSON.

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.
Diferentemente do reconhecimento de fala em tempo real, a transcrição de arquivos de áudio não em tempo real deve usar initializeFileTrans e passar um callback INativeFileTransCallback em vez de usar initialize.
Esta interface bloqueia a thread chamadora. Chame-a a partir de uma thread que não seja de UI. Assinatura do método
public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number
Descrições dos parâmetros
ParâmetroTipoDescrição
callbackINativeFileTransCallbackUma implementação da interface de callback de eventos e dados de transcrição de arquivos.
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.

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
public setParams(params: string): number
Descrições dos parâmetros
ParâmetroTipoDescrição
paramsstringO 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":"fun-asr", "diarization_enabled": false } }

startFileTranscriber

Inicia o reconhecimento. Assinatura do método
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
Descrições dos parâmetros
ParâmetroTipoDescrição
paramsstringOs parâmetros de efeito de reconhecimento de fala. Exemplo: { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"fun-asr", "diarization_enabled": false } }
task_idArrayBufferO buffer de 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.

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
public queryFileTranscriber(task_id: string): number
Descrições dos parâmetros
ParâmetroTipoDescrição
task_idstringO ID da tarefa a ser consultada, obtido do buffer escrito por startFileTranscriber.

cancelFileTranscriber

Cancela imediatamente a tarefa atual. Assinatura do método
public cancelFileTranscriber(task_id: string): number
Descrições dos parâmetros
ParâmetroTipoDescrição
task_idstringO ID da tarefa a ser cancelada.

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 initializeFileTrans para reinicializá-la. Assinatura do método
public release(): number

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.

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
onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;
Descrições dos parâmetros
ParâmetroTipoDescrição
eventConstants.NuiEventO evento de callback.
resultCodenumberVálido apenas quando o evento EVENT_ASR_ERROR ocorre.
finishnumberIndica se a tarefa terminou.
asrResultAsrResultO resultado do reconhecimento de fala.
taskIdstringO ID da tarefa.

Constants.NuiEvent

Os tipos de eventos do SDK HarmonyOS são definidos pela enumeração Constants.NuiEvent. Os seguintes eventos aplicam-se à transcrição de arquivos de áudio:
EventoDescrição
EVENT_FILE_TRANS_CONNECTEDO serviço está conectado.
EVENT_FILE_TRANS_UPLOADEDO arquivo de áudio a ser reconhecido foi carregado.
EVENT_FILE_TRANS_QUERY_RESULTO resultado da consulta da tarefa.
EVENT_FILE_TRANS_RESULTO resultado final do reconhecimento.
EVENT_ASR_ERROROcorre 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:
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.

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 em formato JSON desta URL. A URL possui um período de validade. Baixe o resultado prontamente.