Skip to main content

SDK Python

Parâmetros e interfaces do SDK Python para reconhecimento de fala em tempo real do Paraformer.

Este documento aplica-se apenas à região China (Beijing). Para usar os modelos, utilize uma chave de API da região China (Beijing).
O 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.
Para 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-v2paraformer-realtime-8k-v2
CenáriosTransmissões ao vivo, reuniões e cenários semelhantesReconhecimento de áudio de 8 kHz em cenários como atendimento telefônico e correio de voz
Taxa de amostragemQualquer8kHz
IdiomaChinê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êsChinês
Previsão de pontuaçãoSuportado 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 personalizadoConsulte Customize hotwordsConsulte Customize hotwords
Especificar idioma de reconhecimentoEspecifique o idioma usando o parâmetro language_hints.Não suportado
Reconhecimento de emoçãoNão suportado
O reconhecimento de emoção possui as seguintes restrições:
  • Aplica-se apenas ao modelo paraformer-realtime-8k-v2.
  • É necessário desativar a pontuação semântica (controlada pelo request parameter semantic_punctuation_enabled). A pontuação semântica vem desativada por padrão.
  • O resultado do reconhecimento de emoção é exibido apenas quando o método is_sentence_end de RecognitionResult retorna True.
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 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.
image
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.
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.
image
  1. Inicie o reconhecimento de fala em streaming Chame o método recognize do recurso principal (client.audio.asr) para criar a sessão de reconhecimento e vincular os parâmetros de solicitação; entre no contexto with (que chama automaticamente o método start para estabelecer a conexão e enviar a tarefa) para iniciar o reconhecimento de fala em streaming.
  2. Streaming Chame repetidamente o método send_audio_frame da 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.
  3. Encerramento do processamento Chame o método stop da 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 evento task-finished para obter os últimos resultados de reconhecimento e as estatísticas. Os erros da camada WebSocket são lançados como exceções DashScopeError e podem ser capturados com try/except no envio/recebimento.
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

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:

  • paraformer-realtime-v2 suporta qualquer taxa de amostragem.

  • paraformer-realtime-8k-v2 suporta apenas taxa de amostragem de 8000 Hz.

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:

  • true: Filtra palavras de preenchimento

  • false (padrão): Não filtra 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:

  • zh: Chinês

  • en: Inglês

  • ja: Japonês

  • yue: Cantonês

  • ko: Coreano

  • de: Alemão

  • fr: Francês

  • ru: Russo

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.

  • true: Ativa a segmentação semântica e desativa a segmentação VAD (Detecção de Atividade de Voz).

  • false (padrão): Ativa a segmentação VAD (Detecção de Atividade de Voz) e desativa a segmentação semântica.

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 semantic_punctuation_enabled, você pode alternar flexivelmente o método de segmentação do reconhecimento de fala para atender a diferentes cenários.

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 semantic_punctuation_enabled é false (segmentação VAD) e o modelo é v2 ou posterior.

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 semantic_punctuation_enabled é false (segmentação VAD) e o modelo é v2 ou posterior.

punctuation_prediction_enabled

bool

True

Não

Define se deve adicionar pontuação automaticamente nos resultados de reconhecimento:

  • true (padrão): Sim

  • false: Não

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:

  • true: A conexão com o servidor pode ser mantida sem interrupção ao enviar continuamente áudio silencioso.

  • false (padrão): Mesmo ao enviar áudio silencioso continuamente, a conexão atingirá o tempo limite e será encerrada após um período.

    Á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.

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 membroAssinatura do métodoDescrição
recognize
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
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
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
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
def start(self)
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
def send_audio_frame(self, buffer: bytes)
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
def stop(self)
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
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
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
def close(self)
Fecha a sessão de reconhecimento. É chamado automaticamente na saída do contexto with.
request_id / first_package_delay / last_package_delay
rec.request_id
rec.first_package_delay
rec.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.
# 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çãoConteúdo produzidoValor de retornoDescrição
event["header"]["event"] == "task-started"
Evento task-startedNenhumLido internamente por start() e salvo em last_response no retorno do início; não é produzido novamente por events().
def events(self) -> Iterator[Dict]
event: evento dict do servidorIteradorProduz 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.
def results(self) -> Iterator[RecognitionResult]
result: RecognitionResultIteradorProduz apenas frames de resultado de reconhecimento (frames de heartbeat filtrados); a iteração termina após o retorno de todos os resultados de reconhecimento.
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
Exceção DashScopeErrorNenhumLançada na thread de envio/recebimento quando ocorre uma exceção; pode ser capturada com try/except.
event["header"]["event"] == "task-finished"
Evento task-finishedNenhumProduzido 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 membroAssinatura do métodoDescrição
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
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
result.request_id
O request_id da solicitação correspondente ao evento atual.
is_sentence_end
def is_sentence_end(self) -> bool
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:

  • positive: Emoção positiva, como feliz ou satisfeito

  • negative: Emoção negativa, como irritado ou triste

  • neutral: Sem emoção evidente

O reconhecimento de emoção possui as seguintes restrições:

  • Aplica-se apenas ao modelo paraformer-realtime-8k-v2.

  • É necessário desativar a pontuação semântica (controlada pelo request parameter semantic_punctuation_enabled). A pontuação semântica vem desativada por padrão.

  • O resultado do reconhecimento de emoção é exibido apenas quando o método is_sentence_end de RecognitionResult retorna True.

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:

  • Aplica-se apenas ao modelo paraformer-realtime-8k-v2.

  • É necessário desativar a pontuação semântica (controlada pelo request parameter semantic_punctuation_enabled). A pontuação semântica vem desativada por padrão.

  • O resultado do reconhecimento de emoção é exibido apenas quando o método is_sentence_end de RecognitionResult retorna True.

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.