Parâmetros e interfaces do SDK Python para reconhecimento de fala em tempo real do Paraformer.
Pré-requisitos
Lista de modelos
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| Cenários | Transmissões ao vivo, reuniões e cenários semelhantes | Reconhecimento de áudio de 8 kHz em cenários como atendimento telefônico e correio de voz |
| Taxa de amostragem | Qualquer | 8kHz |
| Idioma | Chinês (incluindo mandarim e vários dialetos), inglês, japonês, coreano, alemão, francês, russoDialetos chineses suportados: Xangai, Wu, Minnan, Nordeste, Gansu, Guizhou, Henan, Hubei, Hunan, Jiangxi, Ningxia, Shanxi, Shaanxi, Shandong, Sichuan, Tianjin, Yunnan, Cantonês | Chinês |
| Previsão de pontuação | Suportado por padrão. Nenhuma configuração necessária. | Suportado por padrão. Nenhuma configuração necessária. |
| Normalização Inversa de Texto (ITN) | Suportado por padrão. Nenhuma configuração necessária. | Suportado por padrão. Nenhuma configuração necessária. |
| Vocabulário personalizado | Consulte Customize hotwords | Consulte Customize hotwords |
| Especificar idioma de reconhecimento | Especifique o idioma usando o parâmetro language_hints. | Não suportado |
| Reconhecimento de emoção | Não suportado |
Clique para ver o uso O reconhecimento de emoção possui as seguintes restrições:
emo_tag e emo_confidence do single-sentence information (Sentence), respectivamente. |
Primeiros passos
O recurso principal (client.audio.asr) fornece interfaces para chamadas sem streaming e com streaming bidirecional. Selecione o método apropriado conforme suas necessidades:
- Chamada sem streaming (
recognize_file): reconhece um arquivo local. O SDK envia o áudio automaticamente em blocos e conduz a tarefa até o fim. Adequado para processamento de áudio pré-gravado. - Chamada com streaming bidirecional: reconhece um fluxo de áudio diretamente e gera resultados em tempo real. O fluxo pode vir de um dispositivo externo, como um microfone, ou ser lido de um arquivo local. Ideal para cenários que exigem feedback imediato.
Chamada sem streaming
Este método envia uma tarefa de transcrição de fala em tempo real para um arquivo local. O processo bloqueia a execução até que o resultado completo da transcrição seja retornado.
recognize_file do recurso principal (client.audio.asr) para vincular os parâmetros da solicitação e passar o caminho do arquivo local, iterando os eventos do servidor para obter o RecognitionResult.
Clique para ver o exemplo completo
Clique para ver o exemplo completo
recognize_file produz eventos do servidor (Dict[str, Any]) um a um: o tipo do evento está em event['header']['event'] e o texto reconhecido está em event['payload']['output']['sentence'] (sentence_end igual a true indica que a frase terminou; begin_time / end_time são carimbos de data/hora e words contém os carimbos por palavra — consulte Frase (Sentence)). Eventos de heartbeat e de texto vazio continuam sendo produzidos e podem ser ignorados conforme necessário.Em uma sessão com streaming bidirecional, além de events(), você também pode usar results() para iterar apenas os frames de resultado de reconhecimento (retorna objetos tipados RecognitionResult, com frames de heartbeat já filtrados); consulte a descrição do método get_sentence.Chamada com streaming bidirecional
Este método envia uma tarefa de transcrição de fala em tempo real e retorna resultados de reconhecimento em tempo real por meio da iteração de eventos.
-
Inicie o reconhecimento de fala em streaming
Chame o método
recognizedo recurso principal (client.audio.asr) para criar a sessão de reconhecimento e vincular os parâmetros de solicitação; entre no contextowith(que chama automaticamente o métodostartpara estabelecer a conexão e enviar a tarefa) para iniciar o reconhecimento de fala em streaming. -
Streaming
Chame repetidamente o método
send_audio_frameda sessão para enviar o fluxo de áudio binário de um arquivo local ou dispositivo (como um microfone) ao servidor em segmentos. O envio e o recebimento devem ocorrer de forma concorrente: a thread receptora itera os eventos do servidor por meio da iteração de eventos (events()/results()), que retorna os resultados de reconhecimento ao cliente em tempo real. Recomenda-se que a duração de cada segmento de áudio enviado seja de aproximadamente 100 milissegundos, com tamanho de dados entre 1 KB e 16 KB. -
Encerramento do processamento
Chame o método
stopda sessão para interromper o reconhecimento de fala. Este método apenas notifica o servidor de que a entrada terminou; a thread receptora deve continuar consumindoevents()até o eventotask-finishedpara obter os últimos resultados de reconhecimento e as estatísticas. Os erros da camada WebSocket são lançados como exceçõesDashScopeErrore podem ser capturados com try/except no envio/recebimento.
Clique para ver o exemplo completo
Clique para ver o exemplo completo
Chamadas concorrentes
No Python, devido ao Global Interpreter Lock (GIL), apenas uma thread pode executar código Python por vez (embora algumas bibliotecas focadas em desempenho possam remover essa limitação). Para aproveitar melhor os recursos computacionais de um computador multicore, recomendamos o uso de multiprocessing ou concurrent.futures.ProcessPoolExecutor. O multithreading pode aumentar significativamente a latência das chamadas do SDK sob alta concorrência.
Parâmetros de solicitação
Os parâmetros de solicitação são definidos nos métodos recognize/recognize_file do recurso principal (client.audio.asr): model, format, sample_rate, vocabulary_id e disfluency_removal_enabled são parâmetros nomeados; os demais parâmetros (como language_hints e semantic_punctuation_enabled) são passados por meio do dicionário parameters.
Parâmetro | Tipo | Padrão | Obrigatório | Descrição |
|---|---|---|---|---|
model | str | - | Sim | Modelo usado para reconhecimento de fala em tempo real. Para mais informações, consulte Model List. |
sample_rate | int | - | Sim | Define a taxa de amostragem (em Hz) do áudio a ser reconhecido. Varia conforme o modelo:
|
format | str | - | Sim | Define o formato de áudio a ser reconhecido. Formatos de áudio suportados: pcm, wav, mp3, opus, speex, aac, amr. opus/speex: Deve usar encapsulamento Ogg. wav: Deve ser codificado em PCM. amr: Apenas o tipo AMR-NB é suportado. |
vocabulary_id | str | - | Não | Define o ID de palavras-chave. Se não definido, as palavras-chave não terão efeito. Use este campo para definir o ID de palavras-chave para modelos v2 e posteriores. Na sessão atual de reconhecimento de fala, as informações de palavras-chave correspondentes a este ID serão aplicadas. Para uso detalhado, consulte Custom hotwords. |
disfluency_removal_enabled | bool | False | Não | Define se deve filtrar palavras de preenchimento:
|
language_hints | list[str] | ["zh", "en"] | Não | Define os códigos de idioma para reconhecimento. Se não for possível determinar o idioma antecipadamente, deixe este campo indefinido e o modelo detectará automaticamente o idioma. Códigos de idioma suportados atualmente:
Este parâmetro aplica-se apenas a modelos multilíngues. Para mais informações, consulte Model list. |
semantic_punctuation_enabled | bool | False | Não | Define se deve ativar a segmentação semântica. Desativado por padrão.
A segmentação semântica oferece maior precisão e é adequada para cenários de transcrição de reuniões. A segmentação VAD (Detecção de Atividade de Voz) tem menor latência e é adequada para cenários interativos. Ao ajustar o parâmetro Este parâmetro só tem efeito quando o modelo é v2 ou posterior. |
max_sentence_silence | int | 800 | Não | Define o limiar de duração de silêncio (em ms) para segmentação VAD (Detecção de Atividade de Voz). Quando a duração do silêncio após um segmento de fala excede esse limiar, o sistema determina que a frase terminou. O intervalo do parâmetro é de 200 ms a 6000 ms, com valor padrão de 800 ms. Este parâmetro só tem efeito quando o parâmetro |
multi_threshold_mode_enabled | bool | False | Não | Quando esta opção está ativada (true), impede que a segmentação VAD corte frases excessivamente longas. Desativado por padrão. Este parâmetro só tem efeito quando o parâmetro |
punctuation_prediction_enabled | bool | True | Não | Define se deve adicionar pontuação automaticamente nos resultados de reconhecimento:
Este parâmetro só tem efeito quando o modelo é v2 ou posterior. |
heartbeat | bool | False | Não | Quando for necessário manter uma conexão longa com o servidor, use esta opção para controlar o comportamento:
Este parâmetro só tem efeito quando o modelo é v2 ou posterior. Este campo foi introduzido no SDK 1.23.1 e já está incluído na versão 2.0.1 ou posterior. |
inverse_text_normalization_enabled | bool | True | Não | Define se deve ativar a ITN (Normalização Inversa de Texto). Ativado por padrão (true). Quando ativado, numerais chineses são convertidos para numerais arábicos. Este parâmetro só tem efeito quando o modelo é v2 ou posterior. |
Interfaces principais
Recurso principal (client.audio.asr)
O reconhecimento de fala em tempo real é montado no recurso client.audio.asr: recognize cria uma sessão de reconhecimento com streaming bidirecional (Recognition) e recognize_file faz o reconhecimento de um arquivo local em uma única chamada.
| Método membro | Assinatura do método | Descrição |
|---|---|---|
| recognize | Cria uma sessão de reconhecimento com streaming bidirecional. A entrada no contexto with chama automaticamente start para estabelecer a conexão e enviar a tarefa.O envio de áudio e o consumo de eventos devem ocorrer de forma concorrente (use em conjunto com send_audio_frame, events()/results() e stop). | |
| recognize_file | Chamada sem streaming baseada em arquivo local: envia o áudio automaticamente em blocos e conduz a tarefa até o fim, produzindo os eventos do servidor um a um. Este método requer permissão de leitura no arquivo. | |
| start | Inicia o reconhecimento de fala: estabelece a conexão, envia a tarefa e aguarda task-started. É chamado automaticamente na entrada do contexto with; o áudio só pode ser enviado após um início bem-sucedido. | |
| send_audio_frame | Envia um fluxo de áudio. O fluxo de áudio enviado a cada vez não deve ser muito grande nem muito pequeno. Recomenda-se que cada pacote de áudio tenha duração de cerca de 100 ms e tamanho entre 1 KB e 16 KB.Os resultados de reconhecimento são obtidos por meio da iteração de eventos (events()/results()). | |
| stop | Interrompe o reconhecimento de fala: apenas notifica o servidor de que a entrada terminou. A thread receptora deve continuar consumindo events() até o evento task-finished. | |
| events / results | Itera os eventos do servidor: events() produz eventos dict brutos (o texto reconhecido está em payload.output.sentence); results() produz apenas os frames de resultado de reconhecimento, retornando objetos tipados RecognitionResult (frames de heartbeat já filtrados). | |
| close | Fecha a sessão de reconhecimento. É chamado automaticamente na saída do contexto with. | |
| request_id / first_package_delay / last_package_delay | Obtém o request_id, o atraso do primeiro pacote (a latência entre o envio do primeiro pacote de áudio e o recebimento do primeiro pacote de resultado de reconhecimento) e o atraso do último pacote (o tempo decorrido entre o envio da instrução stop e o recebimento do último pacote de resultado de reconhecimento). Use após a conclusão da tarefa; continuam legíveis após o fechamento da sessão. |
Iteração de eventos (events()/results())
Durante uma chamada com streaming bidirecional, o servidor retorna informações e dados importantes do processo ao cliente por meio de eventos. Itere os events() da sessão (eventos dict brutos) ou results() (frames tipados de resultado de reconhecimento) na thread receptora, para processar as informações e dados retornados.
Clique para ver o exemplo
Clique para ver o exemplo
| Evento/método de iteração | Conteúdo produzido | Valor de retorno | Descrição |
|---|---|---|---|
Evento task-started | Nenhum | Lido internamente por start() e salvo em last_response no retorno do início; não é produzido novamente por events(). | |
event: evento dict do servidor | Iterador | Produz eventos quando o servidor responde. O resultado do reconhecimento está em payload.output.sentence, que pode ser um evento de heartbeat ou de texto vazio, que o aplicativo pode ignorar conforme necessário. Consuma em uma única thread receptora; não crie múltiplos leitores concorrentes. | |
result: RecognitionResult | Iterador | Produz apenas frames de resultado de reconhecimento (frames de heartbeat filtrados); a iteração termina após o retorno de todos os resultados de reconhecimento. | |
Exceção DashScopeError | Nenhum | Lançada na thread de envio/recebimento quando ocorre uma exceção; pode ser capturada com try/except. | |
Evento task-finished | Nenhum | Produzido por events() quando o servidor conclui todo o reconhecimento; a iteração termina em seguida. Este evento deve continuar sendo lido após o envio de stop(). |
Resultados da resposta
Resultado de reconhecimento (RecognitionResult)
RecognitionResult representa um frame de resultado de reconhecimento produzido pela iteração de results() da sessão (utilizável tanto na chamada com streaming bidirecional quanto na chamada sem streaming; events() produz eventos dict brutos — use results() se precisar dessa visão tipada).
| Método membro | Assinatura do método | Descrição |
|---|---|---|
| get_sentence | Obtém a frase reconhecida atual e informações de carimbo de data/hora. Este método retorna um tipo Dict[str, Any] (informações de uma única frase).Para mais informações, consulte Sentence. | |
| request_id | O request_id da solicitação correspondente ao evento atual. | |
| is_sentence_end | Determina se a frase atual terminou (retorna True quando a frase contém end_time). |
Frase (Sentence)
Os membros da classe Sentence são os seguintes:
Parâmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Hora de início da frase, em ms. |
end_time | int | Hora de término da frase, em ms. |
text | str | Texto reconhecido. |
words | Uma lista de Informações de carimbo de data/hora por palavra (Word) | Informações de carimbo de data/hora por palavra. |
emo_tag | str | Emoção da frase atual:
O reconhecimento de emoção possui as seguintes restrições:
|
emo_confidence | float | Nível de confiança da emoção reconhecida para a frase atual. O valor varia de 0,0 a 1,0. Um valor maior indica maior nível de confiança. O reconhecimento de emoção possui as seguintes restrições:
|
Informações de carimbo de data/hora por palavra (Word)
Os membros da classe Word são os seguintes:
Parâmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Hora de início da palavra, em ms. |
end_time | int | Hora de término da palavra, em ms. |
text | str | A palavra. |
punctuation | str | A pontuação. |
Códigos de erro
Se encontrar erros, consulte Error codes para solução de problemas.
Se o problema persistir, junte-se à comunidade de desenvolvedores para relatar seu problema e forneça o Request ID para investigação adicional.
Mais exemplos
Para mais exemplos, consulte o GitHub.
FAQ
Recursos
P: Como manter uma conexão longa com o servidor durante silêncio prolongado?
Defina o parâmetro de solicitação heartbeat como true e envie continuamente áudio silencioso ao servidor.
Áudio silencioso refere-se a arquivos de áudio ou fluxos de dados que não contêm sinal sonoro. Áudio silencioso pode ser gerado por vários métodos, como softwares de edição de áudio (Audacity ou Adobe Audition) ou ferramentas de linha de comando como FFmpeg.
P: Como converter áudio para um formato suportado?
Utilize a ferramenta FFmpeg. Para mais informações de uso, consulte o site oficial do FFmpeg.
P: Há suporte para visualizar o intervalo de tempo de cada frase?
Sim. Os resultados do reconhecimento de fala incluem os carimbos de data/hora de início e fim de cada frase, que podem ser usados para determinar o intervalo de tempo de cada frase.
P: Como reconheço um arquivo local (arquivo de áudio gravado)?
Existem duas maneiras de reconhecer um arquivo local:
-
Passar diretamente o caminho do arquivo local: Este método retorna o resultado completo do reconhecimento após o arquivo ser totalmente processado. Não é adequado para cenários que exigem feedback imediato.
Passe o caminho do arquivo para o método
recognize_filepara reconhecer diretamente o arquivo de áudio. Para mais informações, consulte Chamada sem streaming. -
Converter o arquivo local em um fluxo binário para reconhecimento: Este método retorna resultados de reconhecimento como um fluxo enquanto o arquivo está sendo processado. É adequado para cenários que exigem feedback imediato.
Use o método
send_audio_frameda sessão de reconhecimento para enviar um fluxo binário ao servidor para reconhecimento. Para mais informações, consulte Chamada com streaming bidirecional.
Solução de problemas
P: O que causa falha no reconhecimento de fala (sem resultados de reconhecimento)?
-
Verifique se o formato de áudio (
format) e a taxa de amostragem (sampleRate/sample_rate) nos parâmetros de solicitação estão definidos corretamente e cumprem as restrições de parâmetros. Veja abaixo exemplos comuns de erros:- A extensão do arquivo de áudio é .wav, mas o formato real é MP3, e o parâmetro de solicitação
formatestá definido comowav(configuração incorreta de parâmetro). - A taxa de amostragem do áudio é 3600 Hz, mas o parâmetro de solicitação
sampleRate/sample_rateestá definido como 48000 (configuração incorreta de parâmetro).
- A extensão do arquivo de áudio é .wav, mas o formato real é MP3, e o parâmetro de solicitação
-
Ao usar o modelo
paraformer-realtime-v2, verifique se o idioma definido emlanguage_hintscorresponde ao idioma real do áudio. Por exemplo: O áudio está realmente em chinês, maslanguage_hintsestá definido comoen(inglês). - Se todas as verificações acima forem aprovadas, utilize palavras-chave personalizadas para melhorar a precisão do reconhecimento de palavras específicas.
Q: Como corrigir a ausência de resultados de reconhecimento causada por um parâmetro de formato de áudio incorreto?
format é obrigatório e deve corresponder ao formato real do áudio. Por exemplo, para um arquivo de áudio em formato MP3 com a extensão .wav, defina format='mp3'.
-
Verifique o formato real do áudio: Use
ffprobepara consultar o contêiner, o codec, a taxa de amostragem e os canais do áudio. -
Defina os parâmetros da solicitação: Defina
formatcomo o formato real do áudio. Definasample_ratecomo a taxa de amostragem real e verifique se ela atende aos requisitos do modelo utilizado. -
Converta o formato do áudio se necessário: Se precisar de áudio WAV, use o comando a seguir para gerar um arquivo WAV com codificação PCM, taxa de amostragem de 16 kHz e um canal.
Após a conversão, defina
format='wav'esample_rate=16000.