Conheça os parâmetros, as interfaces, os callbacks e o uso do SDK iOS para Qwen-Audio-ASR-Message.
Início rápido
- Obter uma chave de API: Obter uma chave de API
-
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.xcframeworkincluído ao projeto. - Em Build Phases → Link Binary With Libraries, adicione
nuisdk.xcframework. - Em General → Frameworks, Libraries, and Embedded Content, defina
nuisdk.xcframeworkcomo 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
- Inicialize o SDK.
- Configure os parâmetros conforme seu caso de uso: use
nui_initializepara os parâmetros de conexão e controle, enui_set_paramspara os parâmetros de qualidade do reconhecimento. - Chame
nui_dialog_startpara iniciar o reconhecimento. - No callback
onNuiAudioStateChanged, abra o dispositivo de gravação conforme o estado do áudio. - Forneça continuamente os dados gravados em
onNuiNeedAudioDataou chamenui_update_audio_datapara enviá-los ativamente. - Em
onNuiEventCallback, monitore os eventos e obtenha os resultados de reconhecimento de fala. - Chame
nui_dialog_cancelpara interromper o reconhecimento e confirme sua conclusão pelo eventoEVENT_TRANSCRIBER_COMPLETE. - Quando o reconhecimento não for mais necessário, chame
nui_releasepara 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.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | String | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | String | Sim | API key. |
service_mode | String | Sim | Modo de execução. Fixo em "1" para reconhecimento de fala em tempo real. |
device_id | String | Sim | String 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_manually | String | Não | Define 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. |
workspace | String | Não | O 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_path | String | Não | Caminho 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_wav | String | Não | Define 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_size | int | Não | Tamanho 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_level | int | Não | Ní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.
| Parâmetro de nível superior | Tipo | Obrigatório | Descrição |
|---|---|---|---|
service_type | int | Sim | Tipo de serviço de voz. Fixo em 4 para reconhecimento de fala em tempo real. |
nls_config | object | Sim | Objeto principal de configuração do reconhecimento. Contém parâmetros como seleção do modelo e controles de qualidade do reconhecimento. |
nls_config.model | string | Sim | Nome do modelo. Defina como qwen-audio-3.1-asr-flash-message. |
nls_config.sr_format | string | Sim | O formato do áudio.Valores válidos:
|
nls_config.sample_rate | int | Sim | A taxa de amostragem em Hz. Apenas 16000 é compatível. |
nls_config.language_hints | array[string] | Não | O 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.
Click to view the supported language codes
sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false). |
nls_config.keep_dialect | boolean | Não | Especifica 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_model | string | Não | O modelo VAD. Padrão: far_field_meeting_16k.
|
nls_config.max_sentence_silence | int | Não | Limite 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.heartbeat | boolean | Não | Se deve habilitar pacotes de heartbeat.Valor padrão: false.
|
nls_config.disfluency_removal_enabled | boolean | Não | Indica 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_enabled | boolean | Não | Indica se resultados intermediários de streaming devem ser retornados. Padrão: false. Defina como true para retorná-los. |
nls_config.vocabulary_id | string | Não | O 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_vocabulary | object | Não | Palavras-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. |
nls_config.speech_noise_threshold | float | Não | O 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:
|
nls_config.enable_connection_fast_check | BOOL | Não | Define 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
parameters | char* | 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 | NuiSdkLogLevel | Nível de impressão para os próprios logs do SDK. |
save_log | BOOL | Se 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. |
nui_set_params
Define os parâmetros de qualidade do reconhecimento em JSON. Chame antes de nui_dialog_start.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | char* | Parâmetros de qualidade do reconhecimento. |
nui_dialog_start
Inicia o reconhecimento.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
vad_mode | NuiVadMode | Modo VAD. Fixado como MODE_P2T. |
dialog_params | char* | 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: |
nui_dialog_cancel
Encerra o reconhecimento ou cancela imediatamente a interação atual.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
force | BOOL | Define 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. |
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
action_params | char* | String JSON usada para atualizar o contexto de reconhecimento ou outros comportamentos em tempo de execução. |
action_params.type | String | Fixo em "action". |
action_params.command | String | Comando 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.context | String | Quando command é "context", fornece o enriquecimento de contexto a ser atualizado imediatamente. Exemplo: |
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | const char * | Os dados de áudio a serem enviados. |
length | int | O comprimento dos dados de áudio, em bytes. |
first_pack | BOOL | Você não precisa usar este parâmetro. |
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | const char * | Os dados de áudio a serem enviados. |
length | int | O comprimento dos dados de áudio, em bytes. |
first_pack | BOOL | Você não precisa usar este parâmetro. |
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
nui_get_version
Obtém a versão atual do SDK. Só retorna um valor após a chamada de nui_initialize.
Method signature
nui_get_all_response
Obtém as informações completas do callback do evento atual.
Method signature
NeoNuiSdkDelegate: listeners de callback
onNuiEventCallback: receber eventos e resultados de reconhecimento de fala
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
nuiEvent | NuiCallbackEvent | Evento de callback. |
dialog | long | ID da sessão. Você não precisa usar este parâmetro. |
wuw | char* | Despertar por voz. Você não precisa usar este parâmetro. |
asr_result | char* | Resultado do reconhecimento de fala. |
finish | BOOL | Se a rodada de reconhecimento atual foi concluída. |
code | int | Có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
| Parâmetro | Descrição |
|---|---|
STATE_OPEN | A interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar. |
STATE_PAUSE | A interação parou. Você pode parar a gravação. |
STATE_CLOSE | A 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
audioData | char* | Os dados de áudio a serem fornecidos. |
len | int | O 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
nuiEvent | NuiCallbackEvent | O evento de callback. |
info | char* | Você não precisa usar este parâmetro. |
info_len | int | Você não precisa usar este parâmetro. |
buffer | char* | Dados auxiliares, como áudio após o processamento AEC. |
len | int | O 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.
NuiCallbackEvent: tipos de evento
| Evento | Descrição |
|---|---|
EVENT_TRANSCRIBER_STARTED | A tarefa foi iniciada com sucesso. |
EVENT_VAD_START | Acionado logo após o início da tarefa. Não significa que o início da fala foi detectado. |
EVENT_VAD_END | O fim da fala foi detectado. |
EVENT_ASR_PARTIAL_RESULT | Um resultado intermediário de reconhecimento de fala. |
| EVENT_ASR_ERROR | Ocorreu um erro durante o reconhecimento de fala. |
EVENT_MIC_ERROR | Acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos. |
EVENT_SENTENCE_END | O fim de uma frase foi detectado. O resultado completo de reconhecimento da frase é retornado. |
EVENT_TRANSCRIBER_COMPLETE | O reconhecimento de fala foi concluído. |
EVENT_AEC_DATA | Dados de áudio após o cancelamento de eco acústico (AEC). |