Skip to main content

Reconhecimento de fala não em tempo real (Fun-ASR-Flash) HarmonyOS SDK

O SDK HarmonyOS de reconhecimento de fala não em tempo real Fun-ASR-Flash converte fala em texto.

Para formatos de áudio suportados, limites de tamanho de arquivo, limites de duração e outros requisitos de entrada, consulte Especificações de áudio.

Início rápido

  1. Obtenha uma chave de API: Obter uma chave de API. Por segurança, recomendamos que você configure a chave de API em uma variável de ambiente.
  2. Baixe o SDK e execute o código de exemplo:
    • Baixe o pacote mais recente do SDK.
    • Extraia o arquivo TAR. Obtenha o SDK no formato HAR de neonui e adicione-o às dependências do seu projeto. Para integração com C++, use native/libs e native/include no arquivo TAR para obter as bibliotecas dinâmicas e arquivos de cabeçalho.
    • Abra o projeto no DevEco Studio. O código de exemplo está em DashFunAsrFlashFileTranscriberPage.ets. Substitua a chave de API para testar o recurso.

Procedimento de chamada

Modo síncrono

  1. Inicializar o SDK
  2. Configure os parâmetros com base nos requisitos do seu negócio
  3. Chame startFileTranscriber para enviar uma solicitação de reconhecimento de fala não em tempo real e aguarde o resultado.
  4. Use onFileTransEventCallback para ouvir o evento EVENT_FILE_TRANS_RESULT e obter o resultado final do reconhecimento.
  5. Chame release para 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 do método initializeFileTrans para configurar essas definições. Exemplo de parâmetro: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione parâmetros conforme necessário em seu código:
{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Parâmetros
ParâmetroTipoObrigatórioDescrição
urlstringSimO endpoint de serviço. Defina este parâmetro como wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation. Substitua {WorkspaceId} pelo seu ID do Workspace real.
apikeystringSimA chave de API. Recomendamos o uso de uma chave de API temporária de curta duração e mais segura para reduzir o risco de expor uma chave de longa duração.
service_modestringSimO modo de operação. Para reconhecimento de fala não em tempo real, defina este parâmetro como "1".
device_idstringSimUma string exclusiva que identifica o usuário final. Você pode usar 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_pathstringNãoO caminho para os arquivos de log. Este parâmetro só tem efeito quando você chama initializeFileTrans com save_log definido como true. Nesse caso, você deve especificar o caminho do arquivo de log. Caso contrário, ocorrerá um erro. Até dois arquivos de log são mantidos localmente.
max_log_file_sizenumberNãoO tamanho máximo do arquivo de log em bytes. Este parâmetro só tem efeito quando você chama initializeFileTrans com save_log definido como true. Padrão: 104857600 (100 * 1024 * 1024 bytes, ou 100 MiB).

Parâmetros de reconhecimento

Use setParams para configurar os parâmetros nls_config, ou use startFileTranscriber para configurar todos os parâmetros de reconhecimento. Exemplo de parâmetro: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione parâmetros conforme necessário em seu código:
{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "fun-asr-flash-2026-06-15"
  }
}
Parâmetros
ParâmetroTipoObrigatórioDescrição
apikeystringNãoSe os Parâmetros de conexão e controle apikey usarem uma chave de API temporária, você pode atualizá-la aqui para evitar a expiração.
nls_configobjectSimO objeto de configuração principal de reconhecimento de fala, incluindo o modelo e os parâmetros que controlam o reconhecimento.
nls_config.modelstringSimO nome do modelo.
nls_config.formatstringSimO formato de áudio. Defina este parâmetro para o formato real. Os formatos suportados incluem wav, mp3, opus. Para obter detalhes, consulte Especificações de áudio.
nls_config.sample_ratestringNãoA taxa de amostragem de áudio em Hz. Por exemplo, 16000 indica uma taxa de amostragem de 16 kHz. Para obter detalhes, consulte Especificações de áudio.
nls_config.vocabulary_idstringNãoO ID do vocabulário pré-compilado. Crie um vocabulário com antecedência e passe seu ID durante o reconhecimento para usar suas palavras-chave. Use esta opção quando o vocabulário for conhecido, relativamente estável e reutilizado entre solicitações. Para instruções de uso, consulte Palavras-chave pré-compiladas.
nls_config.language_hintsarray[string]NãoOs códigos de idioma a reconhecer. Se o idioma não for conhecido, omita este parâmetro para que o modelo o detecte automaticamente. Você pode definir até 1 valor. Se definir mais, apenas os 1 primeiros terão efeito.
  • 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
messagesarray[object]SimA lista de messages. Ela contém o áudio a ser reconhecido e o contexto opcional de conversa para melhorar o reconhecimento.Consulte as descrições a seguir.
parâmetros de messages:
O contexto melhora a precisão do reconhecimento de termos especializados. Para instruções de uso, consulte Aprimoramento de contexto.as mensagens de contexto (tipos input_text e text) são limitadas a cinco cada. Se o limite for excedido, apenas as cinco mensagens mais recentes serão mantidas. O comprimento total do texto de contexto por turno (a soma dos comprimentos dos campos user e assistant text) não deve exceder 400 caracteres. Cada caractere conta como um. Os caracteres excedentes são truncados a partir do final.
Quando o contexto é incluído, as mensagens messages devem seguir uma ordem específica. Organize as mensagens de contexto por turno de conversa. Dentro de cada turno, user (tipo input_text) deve preceder o assistant correspondente (tipo text). A mensagem input_audio user contendo o áudio de entrada deve ser colocada no final de messages.
ParâmetroTipoObrigatórioDescrição
rolestringSimA função da mensagem. Valores válidos:
  • user (obrigatório): uma mensagem do usuário. Quando o tipo é input_audio, representa o áudio a ser reconhecido. Quando o tipo é input_text, representa os resultados de reconhecimento de turnos anteriores ou um vocabulário específico de domínio (contexto opcional).
  • assistant (contexto opcional): Respostas do modelo de linguagem grande de turnos anteriores.
contentarray[object]SimA lista de conteúdo da mensagem. Consulte as descrições a seguir.
parâmetros de content:
ParâmetroTipoObrigatórioDescrição
typestringSimO tipo de conteúdo. Cada solicitação requer pelo menos uma mensagem input_audio . Valores válidos:
  • input_audio (obrigatório): A entrada de áudio a ser reconhecida (o role é user). Você também deve fornecer o objeto input_audio.
  • input_text (contexto opcional): Resultados de reconhecimento da fala do usuário de turnos anteriores ou um vocabulário específico de domínio (o role é user). Você também deve fornecer o campo text.
  • text (contexto opcional): Respostas do modelo de linguagem grande de turnos anteriores (o role é assistant). Você também deve fornecer o campo text.
input_audioobjectNãoObrigatório quando type é input_audio.
input_audio.datastringSimOs dados de áudio a serem reconhecidos. Para formatos de áudio suportados, limites de tamanho de arquivo, limites de duração e outros requisitos de entrada, consulte Especificações de áudio. Os dois métodos de entrada a seguir são suportados:
  • URL do arquivo de áudio: Passe uma URL de arquivo de áudio publicamente acessível.
  • URI de dados Base64: passe o áudio codificado em Base64 como um URI de dados. Concatene o prefixo data:{MIME_TYPE};base64, com os dados de áudio codificados em Base64. Os tipos MIME suportados incluem audio/wav, audio/mp3.Exemplo (URL): https://example.com/audio/sample.wavExemplo (Base64): data:audio/wav;base64,{BASE64_ENCODED_DATA}
textstringNãoObrigatório quando type é input_text, forneça os resultados de reconhecimento da fala do usuário de turnos anteriores ou um vocabulário específico de domínio. Quando type é text, forneça as respostas do modelo de linguagem grande de turnos anteriores. O comprimento do texto é contado em caracteres, com cada caractere contando como um. O comprimento total de todos os campos text das mensagens em cada turno de contexto não deve exceder 400 caracteres. Os caracteres excedentes são truncados a partir do final.

Interfaces principais

NativeNui

initializeFileTrans

Inicialize a instância do SDK de reconhecimento de fala.
Ao contrário do reconhecimento de fala em tempo real, a transcrição não em tempo real (arquivo gravado) requer initializeFileTrans com um callback INativeFileTransCallback em vez de initialize.
Este método bloqueia. Chame-o 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
Parâmetros
ParâmetroTipoDescrição
callbackINativeFileTransCallbackA implementação da interface de callback de eventos e dados de transcrição de arquivo.
parametersstringUma string JSON contendo parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.
levelnumberO nível de log do SDK. Use um valor da enumeração .
save_logbooleanSe deve salvar logs localmente. Se definido como true, use os Parâmetros de conexão e controle para definir debug_path para especificar o caminho e use max_log_file_size para definir o tamanho do arquivo.

setParams

Use este método para definir ou atualizar nls_config separadamente. Você não precisa chamar este método se todos os parâmetros forem fornecidos em startFileTranscriber em uma única chamada. Assinatura do método
public setParams(params: string): number
Parâmetros
ParâmetroTipoDescrição
paramsstringParâmetros de reconhecimento nos parâmetros nls_config; parâmetros fora de nls_config não podem ser definidos com este método.

startFileTranscriber

Iniciar o reconhecimento. Assinatura do método
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
Parâmetros
ParâmetroTipoDescrição
paramsstringParâmetros de reconhecimento.Exemplo:
{
 "apikey": "st-****",
 "messages": [
 {
 "content": [
 {
 "input_audio": {
 "data": "{YOUR_AUDIO_URL}"
 },
 "type": "input_audio"
 }
 ],
 "role": "user"
 }
 ],
 "nls_config": {
 "format": "mp3",
 "model": "fun-asr-flash-2026-06-15"
 }
}
task_idArrayBufferO buffer de ID da tarefa. O SDK grava uma string de ID de tarefa aleatória gerada internamente neste buffer. Seu comprimento em bytes deve ser >= 33 bytes (o exemplo usa new ArrayBuffer(64)). Após uma chamada bem-sucedida, decodifique o buffer para obter o task_id da tarefa.

queryFileTranscriber

Use este método para consultar o status atual e o resultado de uma tarefa assíncrona. Após uma chamada bem-sucedida, o resultado é retornado por meio do evento EVENT_FILE_TRANS_QUERY_RESULT do callback onFileTransEventCallback. Assinatura do método
public queryFileTranscriber(task_id: string): number
Parâmetros
ParâmetroTipoDescrição
task_idstringO ID da tarefa a ser consultada (gravado no buffer por startFileTranscriber ).

cancelFileTranscriber

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

release

Libere todos os recursos internos do SDK. Após esta chamada, a instância do SDK fica indisponível. Para usá-la novamente, chame initializeFileTrans para inicializá-la novamente. Assinatura do método
public release(): number

GetVersion

Obter a versão atual do SDK. Assinatura do método
public GetVersion(): string
Valor de retorno A versão atual do SDK.

INativeFileTransCallback: Callbacks

onFileTransEventCallback: Ouça eventos e resultados de reconhecimento

Assinatura do método
onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;
Parâmetros
ParâmetroTipoDescrição
eventConstants.NuiEventO evento de callback.
resultCodenumberVálido apenas quando o evento EVENT_ASR_ERROR ocorre.
finishnumberSe a tarefa foi concluída.
asrResultAsrResultO resultado do reconhecimento de fala.
taskIdstringO ID da tarefa.

onFileTransLogTrackCallback: Ouça logs de rastreamento

Este callback recebe logs internos detalhados do SDK para solução de problemas e depuração. Para usar este callback, baixe o pacote do SDK do HarmonyOS com data de 20260908 ou posterior.
onFileTransLogTrackCallback?: (level: Constants.LogLevel, log: string) => void;

Tipos de evento

No SDK do HarmonyOS, os tipos de evento são definidos pela enumeração Constants.NuiEvent . Os seguintes eventos estão relacionados à transcrição de arquivos gravados:
EventoDescrição
EVENT_FILE_TRANS_CONNECTEDConectado com sucesso ao serviço.
EVENT_FILE_TRANS_UPLOADEDO arquivo de áudio foi carregado com sucesso.
EVENT_FILE_TRANS_QUERY_RESULTO resultado da consulta da tarefa.
EVENT_FILE_TRANS_RESULTO resultado final do reconhecimento.
EVENT_ASR_ERROROcorreu um erro durante o reconhecimento de fala.