Skip to main content

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

Este guia orienta você pelo SDK iOS de reconhecimento de fala não em tempo real Fun-ASR, para que você possa converter áudio em texto.

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

Início rápido

  1. Obtenha uma chave de API:Obter uma chave de API
  2. Baixe o SDK e execute o código de exemplo:
    • Baixe o pacote mais recente do SDK.
    • Descompacte o pacote ZIP e adicione o nuisdk.framework incluído ao seu projeto.
    • Em Build Phases → Link Binary With Libraries, adicione nuisdk.xcframework.
    • Em General → Frameworks, Libraries, and Embedded Content, defina nuisdk.xcframework como Embed & Sign.
    • Abra o projeto de exemplo no Xcode. O código de exemplo está localizado em DashFunAsrFileTranscriberViewController.m. Substitua a API Key para testar o recurso.

Etapas de chamada

  • Modo síncrono
  • Modo assíncrono
  1. Inicialize o SDK.
  2. Configure os parâmetros relevantes para o seu caso de uso.
  3. Defina async_request como false e chame nui_file_trans_start para enviar uma solicitação de reconhecimento de fala não em tempo real e aguardar o resultado.
  4. No callback onFileTransEventCallback, escute o evento EVENT_FILE_TRANS_RESULT para obter o resultado final do reconhecimento.
  5. Chame nui_release para liberar os recursos do SDK.

Parâmetros de solicitação

Parâmetros de conexão e controle

Configure esses parâmetros passando uma string JSON no argumento parameters da interface nui_initialize. Parâmetros de exemplo A seguir está uma string JSON de exemplo. Nem todos os parâmetros estão listados. Adicione os que você precisa ao escrever seu código:
{
    "url": "wss://dashscope.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
urlStringSimEndpoints de serviço:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Substitua {WorkspaceId} pelo seu ID do Workspace real.
apikeyStringSimA chave de API.
service_modeStringSimO modo de execução. Fixado em "1" para reconhecimento de fala não em tempo real.
device_idStringSimUma string exclusiva que identifica o usuário final. Defina-a como um ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas.
debug_pathStringNãoO caminho de armazenamento para o arquivo de log.Este parâmetro só entra em vigor quando save_log é definido como YES ao chamar a interface nui_initialize. Nesse caso, você deve definir o caminho do arquivo de log; caso contrário, um erro será retornado.No máximo dois arquivos de log são mantidos localmente.
max_log_file_sizeintNãoO tamanho máximo do arquivo de log, em bytes.Este parâmetro só entra em vigor quando save_log é definido como YES ao chamar a interface nui_initialize.Valor padrão: 104857600 (100 * 1024 * 1024 bytes, ou seja, 100 MiB).
log_track_levelintNãoControla o nível de filtro do conteúdo de log enviado por meio do callback de log (onFileTransLogTrackCallback).Valor padrão: 2.Valores válidos:
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (desativa este recurso)
Nota: log_track_level e level (definidos por meio da interface nui_initialize) determinam juntos quais logs são finalmente enviados para o callback. O valor do nível de um log deve ser maior ou igual a log_track_level e level antes de ser enviado para o callback. Por exemplo, se log_track_level estiver definido como 2 (INFO) e level estiver definido como 3 (WARNING), apenas logs no nível WARNING ou superior (valor >= 3) serão enviados para o callback.

Parâmetros de efeito de reconhecimento de fala

Configure todos os parâmetros de reconhecimento de fala por meio da interface nui_file_trans_start. Parâmetros de exemplo A seguir está uma string JSON de exemplo. Nem todos os parâmetros estão listados. Adicione os que você precisa ao escrever seu código:
{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}
Descrições dos parâmetros
ParâmetroTipoObrigatórioDescrição
file_urlsarray[string]SimUma lista de URLs dos arquivos de áudio ou vídeo a serem transcritos. HTTP e HTTPS são suportados. Uma única solicitação suporta apenas uma URL. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Especificações de áudio.Se a gravação estiver armazenada no Alibaba Cloud OSS, a API RESTful suporta URLs temporárias com o prefixo oss://, enquanto o SDK não suporta URLs temporárias com o prefixo oss://.
  • Uma URL temporária é válida por 48 horas e não pode ser usada após a expiração. Não a use em produção.
  • A interface de credencial de upload tem limite de taxa de 100 QPS e não pode ser escalada. Não a use em cenários de produção, alta simultaneidade ou teste de carga.
  • Para produção, use armazenamento estável, como o Alibaba Cloud OSS, para manter os arquivos disponíveis a longo prazo e evitar limitações de taxa.
  • Se uma URL de arquivo de áudio definida como uma URL pública temporária do OSS estiver inacessível, defina X-DashScope-OssResourceResolve como enable no cabeçalho da solicitação (não recomendado). O SDK não suporta a configuração de cabeçalhos de solicitação.
async_requestbooleanNãoSe a solicitação de reconhecimento de fala é assíncrona.Valor padrão: false.Valores válidos:
  • true: solicitação assíncrona
  • false: solicitação síncrona
apikeystringNãoSe o apikey em Parâmetros de conexão e controle for uma chave de API temporária, você pode atualizá-la aqui para evitar que expire.
nls_configobjectSimO objeto de configuração principal do reconhecimento de fala. Ele contém parâmetros chave, como seleção de modelo e controles de efeito de reconhecimento.
nls_config.modelstringSimO nome do modelo.
nls_config.special_word_filterobjectNãoAs palavras sensíveis a serem processadas durante o reconhecimento de fala. Você pode definir um método de tratamento diferente para cada palavra sensível. Para obter detalhes, consulte Filtragem de palavras sensíveis.
nls_config.channel_idarray[integer]NãoO índice das faixas de áudio a serem reconhecidas em um arquivo de áudio com várias faixas. O índice começa em 0. Por exemplo, [0] reconhece a primeira faixa, e [0, 1] reconhece a primeira e a segunda faixas ao mesmo tempo. Se você omitir este parâmetro, apenas a primeira faixa será processada.
Cada faixa especificada é cobrada de forma independente. Por exemplo, solicitar [0, 1] para um único arquivo incorre em duas cobranças separadas.
Valor padrão: [0].
nls_config.diarization_enabledbooleanNãoSe deve ativar a diarização de falantes. 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 inclui um campo speaker_id que distingue diferentes falantes.
Quando a diarização de falantes está ativada, mantenha a duração do áudio dentro de 2 horas. Caso contrário, o reconhecimento pode falhar ou atingir o tempo limite.
Valor padrão: false.Para um exemplo de speaker_id, consulte Descrição do resultado do reconhecimento.
nls_config.speaker_countintegerNão
Entra em vigor apenas quando a diarização de falantes está ativada (diarization_enabled está definido como true).
Um valor de referência para o número de falantes. O intervalo válido é um número inteiro de 2 a 100 (inclusivo).Por padrão, o número de falantes é detectado automaticamente. Se você definir este valor, ele apenas orientará o algoritmo a gerar a contagem especificada quando possível, e não garante essa contagem exata.Sem valor padrão.
nls_config.vocabulary_idstringNãoO ID de uma lista de palavras-chave pré-compilada.Gere este ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave na lista.Adequado para cenários onde o vocabulário é conhecido e relativamente estável, e onde você precisa reutilizar a mesma lista de palavras em várias solicitações.Para detalhes de uso, consulte Palavras-chave pré-compiladas.
nls_config.instant_vocabularyobjectNãoHotwords instantâneas. Passe pares de chave-valor em que as chaves são os textos das hotwords (string) e os valores são pesos inteiros (integer). Não é necessário criar uma lista pré-compilada.Para saber como usar, consulte Hotwords instantâneas.
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]NãoOs códigos de idioma a serem reconhecidos. Se você não puder determinar o idioma com antecedência, deixe-o indefinido e o modelo detectará o idioma automaticamente.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

Interfaces principais

NeoNui

nui_initialize

Inicializa a instância do SDK de reconhecimento de fala. O SDK é um singleton. Não o inicialize novamente antes de chamar nui_release. Assinatura do método
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Descrições dos parâmetros
ParâmetroTipoDescrição
parameterschar*Uma string JSON que contém os parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.
levelNuiSdkLogLevelControla o nível de impressão dos próprios logs do SDK.
save_logBOOLSe deve salvar logs localmente. Se definido como YES, você deve especificar um caminho por meio de debug_path em Parâmetros de conexão e controle, e pode definir o tamanho do arquivo por meio de max_log_file_size.

nui_set_params

Use esta interface para definir ou atualizar o parâmetro nls_config de forma independente. Se você fornecer todos os parâmetros de uma vez em nui_file_trans_start, não precisará chamar este método. Assinatura do método
-(NuiResultCode) nui_set_params:(const char *)params;
Descrições dos parâmetros
ParâmetroTipoDescrição
paramschar*O parâmetro nls_config em Parâmetros de efeito de reconhecimento de fala. Parâmetros diferentes de nls_config não podem ser definidos por meio deste método.Exemplo:
{
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}

nui_file_trans_start

Inicia o reconhecimento. Assinatura do método
-(NuiResultCode) nui_file_trans_start:(const char *)params
                               taskId:(char *)task_id;
Descrições dos parâmetros
ParâmetroTipoDescrição
paramschar*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_idchar*O ID da tarefa. O SDK gera uma string aleatória internamente e retorna o task_id quando esta interface é chamada com sucesso.

nui_file_trans_query

Use esta interface para consultar ativamente o status e o resultado atuais de uma tarefa assíncrona. Após uma chamada bem-sucedida, o resultado é retornado por meio do evento EVENT_FILE_TRANS_QUERY_RESULT no callback onFileTransEventCallback.
Obtenha o task_id passado para este método a partir do evento EVENT_FILE_TRANS_UPLOADED.
Assinatura do método
-(NuiResultCode) nui_file_trans_query:(const char *)task_id;
Descrições dos parâmetros
ParâmetroTipoDescrição
task_idchar*O ID da tarefa a ser consultada, obtido a partir do evento EVENT_FILE_TRANS_UPLOADED.

nui_file_trans_cancel

Cancela a tarefa atual imediatamente. Assinatura do método
-(NuiResultCode) nui_file_trans_cancel:(const char *)task_id;
Descrições dos parâmetros
ParâmetroTipoDescrição
task_idchar*O ID da tarefa a ser cancelada, obtido a partir do evento EVENT_FILE_TRANS_UPLOADED.

nui_release

Libera todos os recursos internos do SDK e encerra forçosamente todas as tarefas em andamento. Depois de chamar este método, a instância do SDK fica indisponível. Para usá-la novamente, você deve chamar nui_initialize novamente para inicializá-la. Assinatura do método
-(NuiResultCode) nui_release;

nui_get_version

Obtém as informações da versão atual do SDK. Assinatura do método
-(const char*) nui_get_version;
Valor de retorno As informações da versão atual do SDK.

NeoNuiSdkDelegate: monitorar callbacks

onFileTransEventCallback: monitorar eventos e resultados de reconhecimento de fala

Assinatura do método
-(void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                       asrResult:(const char *)asr_result
                          taskId:(const char *)task_id
                        ifFinish:(BOOL)finish
                         retCode:(int)code;
Descrições dos parâmetros
ParâmetroTipoDescrição
nuiEventNuiCallbackEventO evento de callback.
asr_resultchar*O resultado do reconhecimento de fala.
task_idchar*O ID da tarefa.
finishBOOLIndica se esta rodada de reconhecimento foi concluída.
codeintVálido apenas quando o evento EVENT_ASR_ERROR ocorre.

onFileTransLogTrackCallback: monitorar logs de rastreamento

Use este callback para receber logs internos detalhados do SDK para solução de problemas e depuração.
-(void)onFileTransLogTrackCallback:(NuiSdkLogLevel)level
                        logMessage:(const char *)log;

NuiCallbackEvent: tipos de evento

EventoDescrição
EVENT_FILE_TRANS_CONNECTEDConectado ao serviço com sucesso.
EVENT_FILE_TRANS_UPLOADEDO arquivo de áudio a ser reconhecido foi carregado com sucesso. Agora você pode obter o task_id da tarefa atual.
EVENT_FILE_TRANS_QUERY_RESULTO resultado da tarefa de consulta.
EVENT_FILE_TRANS_RESULTO resultado final do reconhecimento.
EVENT_ASR_ERROROcorreu um erro durante o reconhecimento de fala.