SDK HarmonyOS de reconhecimento de fala não em tempo real Qwen-Audio-ASR-Filetrans SDK_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

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

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

Modo assíncrono

Inicialize o SDK.
Configure os parâmetros com base nos requisitos do seu negócio.
Chame startFileTranscriber para iniciar uma tarefa de reconhecimento com async_request definido como true.
Chame queryFileTranscriber para consultar o progresso ou o resultado do reconhecimento.
Na interface onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_QUERY_RESULT para obter o resultado da consulta atual.
Na interface onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_RESULT para obter o resultado final do reconhecimento.
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â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:

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

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. 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. Importante 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_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. ImportanteCada faixa especificada é cobrada separadamente. Por exemplo, `[0, 1]` para um arquivo incorre em duas cobranças separadas. 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. ObservaçãoSe 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_count`	`integer`	Não	ImportanteEste 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_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 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.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.

ObservaçãoDiferentemente 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â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

public setParams(params: string): number

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":"qwen-audio-3.0-asr-flash-filetrans", "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â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

public queryFileTranscriber(task_id: string): number

Descrições dos parâmetros

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

public cancelFileTranscriber(task_id: string): number

Descrições dos parâmetros

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

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