Skip to main content

Qwen-Audio-ASR-Message iOS SDK

Conheça os parâmetros, as interfaces, os callbacks e o uso do SDK iOS para Qwen-Audio-ASR-Message.

Início rápido

  1. Obter 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.
    • Extraia o pacote ZIP e adicione o arquivo nuisdk.xcframework incluído ao 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 está em DashFunAsrSpeechTranscriberViewController.m. Substitua a chave de API pela sua para testar o recurso.

Sequência de chamadas

  1. Inicialize o SDK.
  2. Configure os parâmetros conforme seu caso de uso: use nui_initialize para os parâmetros de conexão e controle, e nui_set_params para os parâmetros de qualidade do reconhecimento.
  3. Chame nui_dialog_start para iniciar o reconhecimento.
  4. No callback onNuiAudioStateChanged, abra o dispositivo de gravação conforme o estado do áudio.
  5. Forneça continuamente os dados gravados em onNuiNeedAudioData ou chame nui_update_audio_data para enviá-los ativamente.
  6. Em onNuiEventCallback, monitore os eventos e obtenha os resultados de reconhecimento de fala.
  7. Chame nui_dialog_cancel para interromper o reconhecimento e confirme sua conclusão pelo evento EVENT_TRANSCRIBER_COMPLETE.
  8. Quando o reconhecimento não for mais necessário, chame nui_release para liberar os recursos do SDK.

Parâmetros da solicitação

Parâmetros de conexão e controle

Configure esses parâmetros passando uma string JSON no argumento parameters de nui_initialize. Exemplo de parâmetros: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever o código.
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Descrição dos parâmetros
ParâmetroTipoObrigatórioDescrição
urlStringSimEndereço do serviço:
  • wss://dashscope.aliyuncs.com/api-ws/v1/inference
  • China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
Substitua {WorkspaceId} pelo seu ID do Workspace real.
apikeyStringSimAPI key.
service_modeStringSimModo de execução. Fixo em "1" para reconhecimento de fala em tempo real.
device_idStringSimString exclusiva que identifica o usuário final. Você pode usar um ID de usuário do aplicativo ou um identificador de dispositivo gerado no cliente. Esse ID é usado principalmente para rastrear logs e solucionar problemas.
audio_update_manuallyStringNãoDefine se o envio ativo de áudio está habilitado. Padrão: "false". Se definido como "true" e a versão do SDK suportar processamento de áudio no dispositivo, como AEC ou VAD, essas capacidades serão habilitadas por padrão.
workspaceStringNãoO caminho onde os arquivos de recursos no dispositivo são armazenados. Este parâmetro é obrigatório quando audio_update_manually está definido como "true" e uma capacidade de processamento de áudio no dispositivo, como AEC ou VAD, está habilitada.
debug_pathStringNãoCaminho de armazenamento dos logs. Só tem efeito quando save_log é YES em nui_initialize. Nesse caso, o caminho é obrigatório; caso contrário, ocorre um erro. São mantidos no máximo dois arquivos de log locais.
save_wavStringNãoDefine se o áudio de depuração será salvo em debug_path. Padrão: "false". "true" salva o arquivo; "false" não o salva. Só tem efeito quando save_log é true em nui_initialize. Também é necessário definir debug_path.
max_log_file_sizeintNãoTamanho máximo do arquivo de log em bytes. Só tem efeito quando save_log é YES em nui_initialize. Padrão: 104857600 (100 × 1024 × 1024 bytes, ou 100 MiB).
log_track_levelintNãoNível de filtragem dos logs retornados por onNuiLogTrackCallback. Padrão: 2. Valores: 0 (LOG_LEVEL_VERBOSE), 1 (LOG_LEVEL_DEBUG), 2 (LOG_LEVEL_INFO), 3 (LOG_LEVEL_WARNING), 4 (LOG_LEVEL_ERROR), 5 (LOG_LEVEL_NONE, desativado). Um log só é retornado se seu nível for maior ou igual a log_track_level e ao level de nui_initialize. Por exemplo, com 2 (INFO) e 3 (WARNING), só são retornados logs WARNING ou superiores (valor ≥ 3).

Parâmetros de qualidade do reconhecimento

Configure esses parâmetros passando uma string JSON no argumento params de nui_set_params. Exemplo de parâmetros: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever o código.
{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-asr-flash-message",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
Descrição dos parâmetros
Parâmetro de nível superiorTipoObrigatórioDescrição
service_typeintSimTipo de serviço de voz. Fixo em 4 para reconhecimento de fala em tempo real.
nls_configobjectSimObjeto principal de configuração do reconhecimento. Contém parâmetros como seleção do modelo e controles de qualidade do reconhecimento.
nls_config.modelstringSimNome do modelo. Defina como qwen-audio-3.1-asr-flash-message.
nls_config.sr_formatstringSimO formato do áudio.Valores válidos:
  • pcm
  • opus
Se você fornecer áudio PCM e definir este parâmetro como opus, o SDK codificará os dados em Opus internamente.
nls_config.sample_rateintSimA taxa de amostragem em Hz. Apenas 16000 é compatível.
nls_config.language_hintsarray[string]NãoO idioma do áudio a reconhecer. Não há valor padrão; se não for definido, o modelo detectará o idioma automaticamente.Você pode definir até 4 valores. Se houver mais, apenas os 4 primeiros serão usados.
  • zh: Chinese
  • en: English
  • ja: Japanese
  • ko: Korean
  • vi: Vietnamese
  • th: Thai
  • id: Indonesian
  • ms: Malay
  • tl: Filipino
  • hi: Hindi
  • ar: Arabic
  • fr: French
  • de: German
  • es: Spanish
  • pt: Portuguese
  • ru: Russian
  • it: Italian
  • nl: Dutch
  • sv: Swedish
  • da: Danish
  • fi: Finnish
  • no: Norwegian
  • el: Greek
  • pl: Polish
  • cs: Czech
  • hu: Hungarian
  • ro: Romanian
  • bg: Bulgarian
  • hr: Croatian
  • sk: Slovak
Este parâmetro se aplica somente aos resultados finais (sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false).
nls_config.keep_dialectbooleanNãoEspecifica se as expressões dialetais devem ser preservadas. Padrão: false. Defina como false para transcrever a fala dialetal em texto em mandarim padrão, ou como true para preservar as expressões dialetais.
Este parâmetro se aplica somente aos resultados finais (sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false).
nls_config.vad_modelstringNãoO modelo VAD. Padrão: far_field_meeting_16k.
  • near_meeting_16k: cenários de campo próximo.
  • far_field_meeting_16k: cenários de campo distante.
nls_config.max_sentence_silenceintNãoLimite de silêncio do VAD para segmentação, em milissegundos. A frase termina quando o silêncio após a fala ultrapassa esse limite. Padrão: 800. Intervalo válido: [200, 6000].
nls_config.heartbeatbooleanNãoSe deve habilitar pacotes de heartbeat.Valor padrão: false.
  • true: Mantém a conexão com o servidor ativa mesmo quando áudio silencioso é enviado continuamente.
  • false (padrão): Mesmo quando áudio silencioso é enviado continuamente, a conexão expira e fecha após um período de tempo.
Áudio silencioso refere-se a conteúdo em um arquivo de áudio ou fluxo de dados que não contém sinal sonoro. Você pode gerar áudio silencioso de várias maneiras, como usando software de edição de áudio como Audacity ou Adobe Audition, ou usando uma ferramenta de linha de comando como FFmpeg.
nls_config.disfluency_removal_enabledbooleanNãoIndica se palavras de preenchimento devem ser removidas e o texto de saída aprimorado. Padrão: false. Defina como true para ativar.
nls_config.intermediate_result_enabledbooleanNãoIndica se resultados intermediários de streaming devem ser retornados. Padrão: false. Defina como true para retorná-los.
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ãoPalavras-chave instantâneas.Passado como pares chave-valor, onde a chave é o texto da palavra-chave (string) e o valor é o peso da palavra-chave (integer). Não é necessário criar uma lista de palavras-chave antecipadamente. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] torna o modelo mais propenso a emitir a palavra à medida que o valor aumenta; um valor de 50 designa uma super palavra-chave, o que melhora muito a recuperação, mas o número de super palavras-chave não pode exceder 50.Adequado para otimização temporária de palavras-chave no nível da sessão.Quando palavras-chave instantâneas e pré-compiladas são configuradas juntas, o sistema mescla ambos os conjuntos. Se o conjunto mesclado contiver mais de 2000 palavras-chave, o sistema selecionará aleatoriamente 2000 para uso. Para detalhes de uso, consulte Palavras-chave instantâneas.
Para modelos e limites aplicáveis a hotwords instantâneas, consulte Hotwords instantâneas.
nls_config.speech_noise_thresholdfloatNãoO limite para distinguir fala de ruído, usado para ajustar a sensibilidade da Detecção de Atividade de Voz (VAD).Valores válidos: [-1.0, 1.0].Descrições dos valores:
  • Quanto mais próximo o valor estiver de -1: O limite de ruído diminui, então o ruído tem maior probabilidade de ser reconhecido como fala, o que pode causar a transcrição de mais ruído.
  • Quanto mais próximo o valor estiver de +1: O limite de ruído aumenta, então a fala tem maior probabilidade de ser erroneamente julgada como ruído, o que pode fazer com que parte da fala seja filtrada.
Este é um parâmetro de configuração avançado. Ajustá-lo pode afetar significativamente os resultados do reconhecimento. Recomendações:
  • Teste e verifique minuciosamente os resultados antes de ajustar.
  • Ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0.1).
nls_config.enable_connection_fast_checkBOOLNãoDefine se a verificação rápida de rede está habilitada para informar desconexões o mais cedo possível. Padrão: NO.

APIs principais

NeoNui

nui_initialize

Inicializa a instância do SDK de reconhecimento de fala. O SDK é um singleton. Não o reinicialize antes de chamar nui_release. Method signature
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Descrição dos parâmetros
ParâmetroTipoDescrição
parameterschar*Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.
levelNuiSdkLogLevelNível de impressão para os próprios logs do SDK.
save_logBOOLSe deve salvar logs localmente. Se definido como YES, especifique um caminho com debug_path em Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo com max_log_file_size.
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_set_params

Define os parâmetros de qualidade do reconhecimento em JSON. Chame antes de nui_dialog_start. Method signature
-(NuiResultCode) nui_set_params:(const char *)params;
Descrição dos parâmetros
ParâmetroTipoDescrição
paramschar*Parâmetros de qualidade do reconhecimento.
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_dialog_start

Inicia o reconhecimento. Method signature
-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;
Descrição dos parâmetros
ParâmetroTipoDescrição
vad_modeNuiVadModeModo VAD. Fixado como MODE_P2T.
dialog_paramschar*Se apikey nos parâmetros de conexão e controle for uma chave de API temporária, você poderá atualizá-la aqui quando expirar. Também é possível fornecer contexto para melhorar a precisão por enriquecimento de contexto.O conteúdo está em formato JSON:
{
  "apikey": "st-****",
  "input_context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxxxx",
          "type": "input_text"
        }
      ]
    }
  ]
}
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_dialog_cancel

Encerra o reconhecimento ou cancela imediatamente a interação atual. Method signature
-(NuiResultCode) nui_dialog_cancel:(BOOL)force;
Descrição dos parâmetros
ParâmetroTipoDescrição
forceBOOLDefine se o encerramento será forçado e o resultado final descartado. YES: encerra imediatamente sem esperar o resultado final do servidor. NO: encerra a tarefa, mas espera o resultado completo.
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_dialog_action

Envia uma ação durante a interação para atualizar o contexto de reconhecimento ou outros comportamentos em tempo de execução. Method signature
-(NuiResultCode) nui_dialog_action:(const char *)action_params;
Descrição dos parâmetros
ParâmetroTipoDescrição
action_paramschar*String JSON usada para atualizar o contexto de reconhecimento ou outros comportamentos em tempo de execução.
action_params.typeStringFixo em "action".
action_params.commandStringComando em tempo de execução. context: atualiza imediatamente o enriquecimento de contexto para melhorar a precisão. play_start: ao usar AEC no dispositivo, notifica o player AEC interno de que a reprodução começou. play_over: notifica que a reprodução terminou.
action_params.contextStringQuando command é "context", fornece o enriquecimento de contexto a ser atualizado imediatamente. Exemplo:
{
  "context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxx",
          "type": "input_text"
        }
      ]
    }
  ]
}
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_update_audio_data

Quando audio_update_manually é "true", os dados gravados deixam de ser fornecidos por onNuiNeedAudioData. Use este método para enviá-los ativamente. Method signature
-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;
Descrição dos parâmetros
ParâmetroTipoDescrição
dataconst char *Os dados de áudio a serem enviados.
lengthintO comprimento dos dados de áudio, em bytes.
first_packBOOLVocê não precisa usar este parâmetro.
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_push_reference_data

Quando audio_update_manually é "true" e o AEC no dispositivo está habilitado, use este método para enviar o áudio reproduzido como sinal de referência. Method signature
-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;
Descrição dos parâmetros
ParâmetroTipoDescrição
dataconst char *Os dados de áudio a serem enviados.
lengthintO comprimento dos dados de áudio, em bytes.
first_packBOOLVocê não precisa usar este parâmetro.
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_release

Libera todos os recursos internos do SDK e encerra forçadamente todas as tarefas em execução. A instância fica indisponível. Para reutilizá-la, inicialize-a novamente com nui_initialize. Method signature
-(NuiResultCode) nui_release;
Return value Retorna um código de erro. Consulte a referência de códigos de erro.

nui_get_version

Obtém a versão atual do SDK. Só retorna um valor após a chamada de nui_initialize. Method signature
-(const char*) nui_get_version;
Return value A versão atual do SDK.

nui_get_all_response

Obtém as informações completas do callback do evento atual. Method signature
-(const char*) nui_get_all_response;
Return value As informações completas do evento como uma string JSON.

NeoNuiSdkDelegate: listeners de callback

onNuiEventCallback: receber eventos e resultados de reconhecimento de fala

Method signature
-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;
Descrição dos parâmetros
ParâmetroTipoDescrição
nuiEventNuiCallbackEventEvento de callback.
dialoglongID da sessão. Você não precisa usar este parâmetro.
wuwchar*Despertar por voz. Você não precisa usar este parâmetro.
asr_resultchar*Resultado do reconhecimento de fala.
finishBOOLSe a rodada de reconhecimento atual foi concluída.
codeintCódigo de erro. Válido quando ocorre o evento EVENT_ASR_ERROR. Consulte a referência de códigos de erro.

onNuiAudioStateChanged: monitorar o estado do áudio

O SDK usa este callback para informar quando iniciar ou parar a gravação. Method signature
-(void) onNuiAudioStateChanged:(NuiAudioState)state;
NuiAudioState states
ParâmetroDescrição
STATE_OPENA interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar.
STATE_PAUSEA interação parou. Você pode parar a gravação.
STATE_CLOSEA instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação.

onNuiNeedAudioData: fornecer áudio para reconhecimento

Após o início do reconhecimento, este callback é acionado continuamente. Forneça nele os dados de áudio a reconhecer. Method signature
-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Descrição dos parâmetros
ParâmetroTipoDescrição
audioDatachar*Os dados de áudio a serem fornecidos.
lenintO tamanho dos dados de áudio fornecidos em bytes.

onNuiAssistEventCallback: receber dados e informações auxiliares

Recebe eventos auxiliares e dados relacionados do SDK. Method signature
-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;
Descrição dos parâmetros
ParâmetroTipoDescrição
nuiEventNuiCallbackEventO evento de callback.
infochar*Você não precisa usar este parâmetro.
info_lenintVocê não precisa usar este parâmetro.
bufferchar*Dados auxiliares, como áudio após o processamento AEC.
lenintO comprimento dos dados auxiliares, em bytes.

onNuiLogTrackCallback: receber logs de rastreamento

Este callback recebe os logs internos detalhados do SDK para ajudar a localizar e depurar problemas.
-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent: tipos de evento

EventoDescrição
EVENT_TRANSCRIBER_STARTEDA tarefa foi iniciada com sucesso.
EVENT_VAD_STARTAcionado logo após o início da tarefa. Não significa que o início da fala foi detectado.
EVENT_VAD_ENDO fim da fala foi detectado.
EVENT_ASR_PARTIAL_RESULTUm resultado intermediário de reconhecimento de fala.
EVENT_ASR_ERROROcorreu um erro durante o reconhecimento de fala.
EVENT_MIC_ERRORAcionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos.
EVENT_SENTENCE_ENDO fim de uma frase foi detectado. O resultado completo de reconhecimento da frase é retornado.
EVENT_TRANSCRIBER_COMPLETEO reconhecimento de fala foi concluído.
EVENT_AEC_DATADados de áudio após o cancelamento de eco acústico (AEC).