Parâmetros e interfaces do SDK Python para reconhecimento de fala em tempo real do Paraformer.
ImportanteEste documento aplica-se apenas à região China (Beijing). Para usar os modelos, utilize uma chave de API da região China (Beijing).
ImportanteO Alibaba Cloud Model Studio lançou um domínio específico por workspace para a região China (Beijing). O novo domínio dedicado oferece desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Substitua {WorkspaceId} pelo seu Workspace ID real. O domínio existente permanece totalmente funcional.
Guia do usuário: Para introdução aos modelos e recomendações de seleção, consulte Real-time speech recognition - Fun-ASR/Paraformer.
Pré-requisitos
Ative o serviço e Obtain an API key. Configure API key as an environment variable em vez de codificá-la diretamente no código para evitar riscos de segurança causados por vazamento de código.
ObservaçãoPara fornecer acesso temporário a aplicativos ou usuários terceiros, ou para controlar rigorosamente operações de alto risco, como acessar ou excluir dados sensíveis, recomendamos o uso de temporary authentication tokens.
Em comparação com as chaves de API de longo prazo, os tokens de autenticação temporários possuem curto período de validade (60 segundos) e maior segurança. Eles são adequados para cenários de chamada temporária e reduzem efetivamente o risco de vazamento da chave de API.
Uso: No seu código, substitua a chave de API originalmente usada para autenticação pelo token de autenticação temporário obtido.
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, russo Dialetos 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 | 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:
Para obter os resultados da detecção de emoção, recupere a emoção e o nível de confiança da emoção da frase atual nos campos |
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.
Chame o método 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
import os
import dashscope
# A configuração abaixo refere-se à região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
# Reconheça um arquivo de áudio local: recognize_file envia o áudio automaticamente em blocos e conduz a tarefa até o fim
for event in client.audio.asr.recognize_file(
'{YOUR_AUDIO_FILE}',
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# O parâmetro "language_hints" só é suportado pelo modelo paraformer-realtime-v2
parameters={'language_hints': ['zh', 'en']}):
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Resultado do reconhecimento: ', sentence['text'])
O 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 consumindo
events()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
import os
import signal # para tratar eventos de teclado (pressione "Ctrl+C" para encerrar a gravação)
import sys
import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor
# A configuração abaixo refere-se à região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
mic = None
stream = None
# Defina os parâmetros de gravação
sample_rate = 16000 # taxa de amostragem (Hz)
channels = 1 # canal mono
dtype = 'int16' # tipo de dados
format_pcm = 'pcm' # o formato dos dados de áudio
block_size = 3200 # número de quadros por buffer
# Receptor de eventos do reconhecimento de fala em tempo real
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Texto reconhecido: ', sentence['text'])
if sentence.get('sentence_end'):
print(
'Fim da frase, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
def signal_handler(sig, frame):
print('Ctrl+C pressionado, interrompendo o reconhecimento ...')
# Interrompa o reconhecimento
recognition.stop()
print('Reconhecimento interrompido.')
print(
'[Métrica] requestId: {}, atraso do primeiro pacote ms: {}, atraso do último pacote ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
# Force a saída do programa
sys.exit(0)
# função principal
if __name__ == '__main__':
print('Inicializando ...')
signal.signal(signal.SIGINT, signal_handler)
print("Pressione 'Ctrl+C' para interromper a gravação e o reconhecimento...")
# Chame o service de reconhecimento; você pode personalizar os parâmetros de reconhecimento, como model, format,
# sample_rate
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format=format_pcm,
# 'pcm', 'wav', 'opus', 'speex', 'aac' ou 'amr'; consulte os formatos suportados na documentação
sample_rate=sample_rate,
# 8000 ou 16000 são suportados
parameters={'semantic_punctuation_enabled': False},
) as recognition:
# Abra o microfone
mic = pyaudio.PyAudio()
stream = mic.open(format=pyaudio.paInt16,
channels=1,
rate=16000,
input=True)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
# Envie o áudio do microfone até que "Ctrl+C" seja pressionado
while stream:
data = stream.read(3200, exception_on_overflow=False)
recognition.send_audio_frame(data)
recognition.stop()
receiver.result()
finally:
# close deve ser executado dentro do contexto do pool para desbloquear o receptor
recognition.close()
stream.stop_stream()
stream.close()
mic.terminate()
stream = None
mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor
# A configuração abaixo refere-se à região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# Receptor de eventos do reconhecimento de fala em tempo real
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print(get_timestamp() + ' Texto reconhecido: ', sentence['text'])
if sentence.get('sentence_end'):
print(get_timestamp() +
'Fim da frase, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# O parâmetro "language_hints" só é suportado pelo modelo paraformer-realtime-v2
parameters={'language_hints': ['zh', 'en']},
) as recognition:
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
audio_data: bytes = None
f = open("{YOUR_AUDIO_FILE}", 'rb')
if os.path.getsize("{YOUR_AUDIO_FILE}"):
while True:
audio_data = f.read(3200)
if not audio_data:
break
else:
recognition.send_audio_frame(audio_data)
time.sleep(0.1)
else:
raise Exception(
'The supplied file was empty (zero bytes long)')
f.close()
recognition.stop()
receiver.result()
finally:
# close deve ser executado dentro do contexto do pool para desbloquear o receptor
recognition.close()
print(
'[Métrica] requestId: {}, atraso do primeiro pacote ms: {}, atraso do último pacote ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
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 O envio de áudio e o consumo de eventos devem ocorrer de forma concorrente (use em conjunto com |
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 |
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 ( |
stop | | Interrompe o reconhecimento de fala: apenas notifica o servidor de que a entrada terminou. A thread receptora deve continuar consumindo |
events / results | | Itera os eventos do servidor: |
close | | Fecha a sessão de reconhecimento. É chamado automaticamente na saída do contexto |
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 |
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
# Itere os eventos brutos: o texto reconhecido está em payload.output.sentence
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Texto reconhecido: ', sentence['text'])
# Ou itere apenas os frames de resultado de reconhecimento (retorna RecognitionResult, frames de heartbeat filtrados)
def receive_results(rec):
for result in rec.results():
sentence = result.get_sentence()
if sentence and 'text' in sentence:
print('Texto reconhecido: ', sentence['text'])
| Evento/método de iteração | Conteúdo produzido | Valor de retorno | Descrição |
|---|---|---|---|
| Evento | Nenhum | Lido internamente por |
|
| Iterador | Produz eventos quando o servidor responde. O resultado do reconhecimento está em |
|
| 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 | Nenhum | Lançada na thread de envio/recebimento quando ocorre uma exceção; pode ser capturada com try/except. |
| Evento | Nenhum | Produzido por |
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 |
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. |
Mais exemplos
Para mais exemplos, consulte o GitHub.
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.