Este tópico descreve os parâmetros e as interfaces do Python SDK para o modelo de reconhecimento de fala em tempo real Fun-ASR-Realtime.
Pré-requisitos
Ative o service e Obtain an API key. Para evitar riscos de segurança causados por vazamento de código, Configure API key as an environment variable em vez de codificá-la diretamente no código.
Início rápido
O recurso principal (client.audio.asr) fornece interfaces para chamadas sem streaming e com streaming bidirecional. Escolha o método de chamada adequado às 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. Ideal para processar áudio pré-gravado. - Chamada com streaming bidirecional (sessão
recognize): reconhece um fluxo de áudio diretamente e gera resultados em tempo real. O fluxo pode vir de um dispositivo externo, como microfone, ou ser lido de um arquivo local. Recomendado para cenários que exigem feedback imediato.
Chamada sem streaming
Envie uma única tarefa de reconhecimento de fala em tempo real e obtenha o resultado sincronamente ao passar um arquivo local.
Chame o método recognize_file do recurso principal (client.audio.asr) para vincular os parâmetros da solicitação, passar o caminho do arquivo local e iterar os eventos do servidor para obter o resultado do reconhecimento.
import os
import dashscope
# A API Key difere entre as regiões Singapura e Beijing. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# 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"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 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='fun-asr-realtime',
format='wav',
sample_rate=16000):
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'])
Chamada com streaming bidirecional
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados continuamente iterando os 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 da 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. -
Transmita o áudio.
Chame o método
send_audio_frameda sessão em loop para enviar o fluxo de áudio binário ao servidor em segmentos. O fluxo é lido de um arquivo local ou de um dispositivo, como microfone.O envio e o recebimento devem ocorrer de forma concorrente: a thread receptora itera os eventos do servidor por meio do método
events()da sessão, que retorna os resultados de reconhecimento ao cliente em tempo real.Envie cerca de 100 ms de áudio por quadro e mantenha cada quadro entre 1 KB e 16 KB.
-
Encerre a tarefa.
Chame o método
stopda sessão para encerrar o reconhecimento de fala.Esse 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.
import os
import signal # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys
import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor
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__':
# A API Key difere entre as regiões Singapura e Beijing. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# 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"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Chame o service de reconhecimento; você pode personalizar os parâmetros de reconhecimento, como model, format,
# sample_rate
with client.audio.asr.recognize(
model='fun-asr-realtime',
format=format_pcm,
# 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'; consulte os formatos suportados na documentação
sample_rate=sample_rate,
# suporta 8000, 16000
) 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 API Key difere entre as regiões Singapura e Beijing. Obtenha uma API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# 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"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
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='fun-asr-realtime',
format='wav',
sample_rate=16000,
) 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}"):
# Leia todos os dados do arquivo para o buffer de uma só vez
file_buffer = f.read()
f.close()
print("Iniciar reconhecimento")
# Envie 3200 bytes do buffer por vez
buffer_size = len(file_buffer)
offset = 0
chunk_size = 3200
while offset < buffer_size:
# Calcule o tamanho do bloco de dados a enviar desta vez
remaining_bytes = buffer_size - offset
current_chunk_size = min(chunk_size, remaining_bytes)
# Extraia o bloco de dados atual do buffer
audio_data = file_buffer[offset:offset + current_chunk_size]
# Envie o quadro de dados de áudio
recognition.send_audio_frame(audio_data)
# Atualize o offset
offset += current_chunk_size
# Adicione um atraso para simular a transmissão em tempo real
time.sleep(0.1)
recognition.stop()
receiver.result()
else:
raise Exception(
'The supplied file was empty (zero bytes long)')
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,
))
Parâmetros da solicitação
Defina os parâmetros da solicitação por meio dos métodos recognize/recognize_file do recurso principal (client.audio.asr): model, format, sample_rate e vocabulary_id são parâmetros nomeados; os demais parâmetros (como max_sentence_silence e language_hints) são passados por meio do dicionário parameters.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
sample_rate | int | Sim | Taxa de amostragem, em Hz. Valores válidos: modelos de 8 kHz aceitam apenas 8000 Hz; outros modelos aceitam qualquer taxa de amostragem. |
format | str | Sim | Formato do áudio. Valores válidos:
Importanteopus/speex: devem usar encapsulamento Ogg. wav: deve usar codificação PCM. amr: apenas o tipo AMR-NB é aceito. |
vocabulary_id | str | Não | ID de uma lista de palavras-chave pré-compilada. Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista. Indicado para cenários em que o vocabulário é conhecido e relativamente estável e quando você precisa reutilizar a mesma lista de palavras entre solicitações. Para detalhes de uso, consulte Precompiled hotwords. |
max_sentence_silence | int | Não | Limiar de silêncio VAD para segmentação, em ms. Quando o silêncio após um segmento de fala excede esse limiar, o sistema determina que a frase terminou. Valor padrão: 1300. Valores válidos: [200, 6000]. |
multi_threshold_mode_enabled | bool | Não | Define se o modo de múltiplos limiares deve ser ativado. Quando ativado, impede que a segmentação VAD produza segmentos excessivamente longos. Padrão: False. |
punctuation_prediction_enabled | bool | Não | Define se a pontuação deve ser adicionada automaticamente aos resultados de reconhecimento:
|
heartbeat | bool | Não | Define se os pacotes de heartbeat devem ser ativados. Padrão: False.
Á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 formas, como usando software de edição de áudio como Audacity ou Adobe Audition, ou ferramentas de linha de comando como FFmpeg. Este campo requer a versão 2.0.1 ou posterior do SDK. |
language_hints | list[str] | Não | Idioma do áudio a ser reconhecido. Não há valor padrão; se não definido, o modelo detecta o idioma automaticamente. Você pode definir 1 valor. Se definir mais, somente o primeiro terá efeito. Clique em para visualizar os códigos de idioma aceitos
|
speech_noise_threshold | float | Não | Limiar 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:
Este é um parâmetro de configuração avançada. Ajustá-lo pode afetar significativamente os resultados de reconhecimento. Recomendações:
|
special_word_filter | str | Não | Especifica as palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para cada uma. Para detalhes, consulte Sensitive word filtering. |
Passe os seguintes parâmetros por meio do argumento nomeado input dos métodos recognize/recognize_file.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
input | dict | Não | Objeto de entrada usado para passar o contexto da conversa. O aprimoramento de contexto melhora a precisão do reconhecimento para termos específicos de domínio. Para uso, consulte Melhorar a precisão do reconhecimento. ImportanteOs modelos O dict deve incluir uma chave
ImportanteLimites: mensagens de contexto dos tipos ImportanteAo passar o contexto, as mensagens em ObservaçãoEste campo requer a versão 2.0.1 ou posterior do SDK. Passe-o por meio do parâmetro |
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 |
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 áudio. Mantenha cada quadro de áudio enviado nem muito grande nem muito pequeno: cerca de 100 ms por quadro, entre 1 KB e 16 KB. Os resultados de reconhecimento são obtidos iterando |
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 Resultado de reconhecimento (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 / last_response | | Obtém o request_id, o atraso do primeiro pacote (a latência desde o envio do primeiro pacote de áudio até o recebimento do primeiro resultado de reconhecimento) e o atraso do último pacote (o tempo desde o envio do comando stop até o recebimento do último resultado de reconhecimento), usados após a conclusão da tarefa; last_response é a última mensagem bruta lida com sucesso, útil para recuperar erros de task-failed. 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-chave de processo e dados 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 lidar com as informações e dados retornados pelo servidor.
# 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 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: resultado de reconhecimento (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 um erro; 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(). |
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 em chamadas com streaming bidirecional quanto 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 suas informações de timestamp. Este método retorna Dict[str, Any] (informações de uma única frase). Para detalhes, consulte Sentence (Sentence). |
request_id | | O request_id da solicitação correspondente ao evento atual. |
is_sentence_end | | Determina se a frase atual terminou. Este método verifica se o campo |
Informações da frase (Sentence)
Os membros da classe Sentence são os seguintes:
| Parâmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Tempo de início da frase, em ms. |
end_time | int | Tempo de término da frase, em ms. |
text | str | Texto reconhecido. |
words | Uma lista de Word-level timestamp information (Word) | Informações de timestamp no nível da palavra. |
Informações de timestamp no nível da palavra (Word)
Os membros da classe Word são os seguintes:
| Parâmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Tempo de início da palavra, em ms. |
end_time | int | Tempo 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.
FAQ
Recursos
P: Como mantenho a conexão ativa durante longos períodos de silêncio?
Defina o parâmetro de solicitação heartbeat como true e continue enviando áudio silencioso para o servidor.
Áudio silencioso é o conteúdo em um arquivo de áudio ou fluxo 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 ferramentas de linha de comando como FFmpeg.
P: Como converto áudio para um formato aceito?
Use o FFmpeg. Para mais usos, consulte o site oficial do FFmpeg.
# Basic conversion command (all-purpose template)
# -i, purpose: input file path, example value: audio.wav
# -c:a, purpose: audio codec, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar, purpose: sample rate, example values: 44100 (CD), 48000, 16000
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext
# For example: WAV to MP3 (keep the original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# For example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# For example: M4A to AAC (extract or convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac # Extract directly without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac # Re-encode to improve quality
# For example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus
P: Como reconheço um arquivo local (gravação)?
Existem duas maneiras de reconhecer um arquivo local:
-
Passe o caminho do arquivo local diretamente: esta forma retorna o resultado completo somente após o término do reconhecimento, portanto não é adequada para cenários que precisam de feedback imediato.
Consulte Chamada sem streaming e passe o caminho do arquivo para o método
recognize_filepara reconhecer a gravação diretamente. -
Converta o arquivo local em um fluxo binário para reconhecimento: esta forma reconhece o arquivo enquanto transmite os resultados em fluxo, sendo adequada para cenários que precisam de feedback imediato.
Consulte Chamada com streaming bidirecional e envie o fluxo binário para o servidor para reconhecimento através do método
send_audio_frameda sessão de reconhecimento.
Solução de problemas
P: Por que a fala não é reconhecida (nenhum resultado de reconhecimento)?
-
Verifique se o formato de áudio (
format) e a taxa de amostragem (sampleRate/sample_rate) nos parâmetros da solicitação estão corretos e atendem às restrições de parâmetros. Erros comuns incluem:- O arquivo de áudio tem extensão .wav, mas na verdade está no formato MP3, enquanto o parâmetro de solicitação
formatestá definido como mp3 (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).
Use a ferramenta ffprobe para obter o container, codec, taxa de amostragem, canais e outras informações do áudio:
- O arquivo de áudio tem extensão .wav, mas na verdade está no formato MP3, enquanto o parâmetro de solicitação
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
- Se nenhuma das verificações acima revelar um problema, adicione palavras-chave personalizadas para melhorar o reconhecimento de termos específicos.