Este guia explica como usar o SDK HarmonyOS de reconhecimento de fala não em tempo real Qwen-Audio-ASR-Filetrans para converter fala em texto.
Início rápido
- 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.
- 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
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. - 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
- 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 da consulta atual. - Na interface
onFileTransEventCallback, escute o eventoEVENT_FILE_TRANS_RESULTpara obter o resultado final do reconhecimento. - Chame
releasepara 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:
| 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 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 ú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 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_size | number | Não | Define 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:
| 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. 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.- 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_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 nome do modelo. |
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. Para mais informações, consulte Filtragem de palavras sensíveis. |
nls_config.channel_id | array[integer] | Não | Especifica 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.Valor padrão: [0]. |
nls_config.diarization_enabled | boolean | Não | Especifica 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. speaker_id, consulte Descrições do resultado de reconhecimento. |
nls_config.speaker_count | integer | Não | 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_id | string | Não | O 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_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á automaticamente o idioma. Você pode definir até 4 valores. Se definir mais, apenas os 4 primeiros serão usados.
Clique para ver os códigos de idioma suportados
|
nls_config.parameters | object | Não | Configura 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.| 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. |
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
| 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":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } } |
startFileTranscriber
Inicia o reconhecimento.
Assinatura do método
| 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":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } } |
task_id | ArrayBuffer | O 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | O ID da tarefa a ser consultada, obtido do buffer escrito por startFileTranscriber. |
cancelFileTranscriber
Cancela imediatamente a tarefa atual.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | O 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
GetVersion
Obtém as informações da versão atual do SDK.
Assinatura do método
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
| 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 aplicam-se à 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 em formato JSON desta URL. A URL possui um período de validade. Baixe o resultado prontamente.