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. |
Início rápido
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 da 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. |
Referência da API
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. |