Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR gravando Python SDK

Transcrição de arquivo Python

Este tópico descreve os parâmetros e interfaces do Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR SDK Python de reconhecimento de fala não em tempo real.

Guia do usuário: Reconhecimento de fala em tempo não real. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Especificações de áudio.

Pré-requisitos

• Faça login em QwenCloud e criar uma chave de API. Defina a chave API como uma variável de ambiente.

  Para acesso temporário a aplicativos de terceiros, use um token temporário. Os tokens expiram em 60 segundos, limitando o risco de vazamento.

• Instale o SDK DashScope mais recente.

Disponibilidade do modelo

• Idiomas suportados:
  • fun-asr: Chinês (mandarim, cantonês, Wu, Minnan, Hakka, Gan, Xiang e Jin; também suporta sotaques de mandarim das regiões de Zhongyuan, Sudoeste, Jilu, Jianghuai, Lanyin, Jiaoliao, Nordeste, Pequim e Hong Kong-Taiwan - incluindo Henan, Shaanxi, Hubei, Sichuan, Chongqing, Yunnan, Guizhou, Guangdong, Guangxi, Hebei, Tianjin, Shandong, Anhui, Nanjing, Jiangsu, Hangzhou, Gansu e Ningxia), inglês, japonês, coreano, vietnamita, tailandês, indonésio, malaio, filipino, hindi, árabe, francês, alemão, espanhol, português, russo, italiano, holandês, sueco, dinamarquês, finlandês, norueguês, grego, polonês, tcheco, húngaro, romeno, búlgaro, croata e eslovaco.
• Taxas de amostra suportadas: Qualquer
• Formatos de áudio suportados: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv

Limitações

Os arquivos devem estar em URLs públicos (HTTP/HTTPS, como https://your-domain.com/file.mp3). Arquivos locais e codificação Base64 não são suportados.

Passe URLs com o file_urls parâmetro. Até 100 URLs por solicitação.

• Formatos de áudio: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv

  Nem todas as variantes de formato são testadas. Teste seus arquivos para verificar os resultados.

• Taxa de amostragem de áudio: Qualquer

• Tamanho e duração do arquivo: Máximo de 2 GB e 12 horas. Para arquivos maiores, consulte Corte de áudio.

• Processamento em lote: até 100 URLs por solicitação.

• Idiomas: fun-asr suporta chinês e 29 outros idiomas. Consulte Idiomas suportados.

Parâmetros de solicitação

Defina parâmetros de solicitação por meio do async_call método da classe de transcrição.

Se um URL de arquivo de áudio definido como um URL público temporário de OSS estiver inacessível, defina X-DashScope-OssResourceResolve para enable no cabeçalho da solicitação (não recomendado). O SDK não oferece suporte à configuração de cabeçalhos de solicitação. | | manter_dialeto | bool | Não | Apoiado por qwen-audio-3.1-asr-flash-filetrans apenas. O padrão é false, que transcreve dialetos para o chinês padrão. Definir como true para preservar expressões dialetais. Passe como um argumento de palavra-chave com o mesmo nome. Consulte referência da API para obter detalhes. | | vocabulário_id | | Não | O ID de uma lista de hot word pré-compilada. Gere esse ID antecipadamente chamando a API de criação de lista de palavras quentes. Passe o ID durante o reconhecimento para usar as palavras quentes da lista. Adequado para cenários onde o vocabulário é conhecido e relativamente estável, e onde é necessário reutilizar a mesma lista de palavras em solicitações. Para obter detalhes de uso, consulte Hotwords pré-compiladas. | | vocabulário | ditado | Não | Palavras quentes instantâneas. Passados como pares de valores-chave, onde a chave é o texto da palavra quente (string) e o valor é o peso da palavra quente (integer). Nenhuma lista de palavras quentes precisa ser criada com antecedência. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] aumenta a probabilidade de o modelo gerar a palavra à medida que o valor aumenta; um valor de 50 designa uma palavra superquente, o que melhora muito a recuperação, mas o número de palavras superquentes não pode exceder 50. Adequado para otimização de palavra quente temporária em nível de sessão. Quando hotwords instantâneas e pré-compiladas são configuradas juntas, o sistema mescla os dois conjuntos. Se o conjunto mesclado contiver mais de 2.000 hotwords, o sistema selecionará aleatoriamente 2.000 para usar. Para obter detalhes de uso, consulte Hotwords instantâneas. Somente qwen-audio-3.1-asr-flash-filetrans e qwen-audio-3.0-asr-flash-filetrans suporte a hotwords in-line. | | canal_id | lista[int] | Não | O índice das trilhas de áudio a serem reconhecidas em um arquivo de áudio multitrilha. O índice começa em 0. Por exemplo, [0] reconhece a primeira faixa e [0, 1] reconhece a primeira e a segunda faixas ao mesmo tempo. Se você omitir este parâmetro, somente a primeira faixa será processada. Valor padrão: [0]. Cada faixa especificada é cobrada de forma independente. Por exemplo, solicitar [0, 1] para um único arquivo incorre em duas cobranças separadas. | | especial_palavra_filtro | | Não | As palavras sensíveis a serem processadas durante o reconhecimento de fala. Você pode definir um método de tratamento diferente para cada palavra sensível. Para obter detalhes, consulte Filtragem de palavras sensíveis. | | diarização_habilitado | bool | Não | Se deve ativar a diarização do orador. Desativado por padrão. Aplica-se apenas ao áudio mono. O áudio multicanal não suporta diarização de alto-falante. Quando ativado, o resultado do reconhecimento inclui um speaker_id campo que distingue diferentes falantes. Quando a diarização do alto-falante estiver ativada, mantenha a duração do áudio em 2 horas. Caso contrário, o reconhecimento poderá falhar ou expirar. Valor padrão: Falso. Para um exemplo de speaker_id, consulte Resultado do reconhecimento. | | alto-falante_contagem | interno | Não | Entra em vigor somente quando a diarização do alto-falante está habilitada (diarization_enabled está definido para True). Um valor de referência para o número de alto-falantes. O intervalo válido é um número inteiro de 2 a 100 (inclusive). Por padrão, o número de alto-falantes é detectado automaticamente. Se você definir esse valor, ele apenas orientará o algoritmo para gerar a contagem especificada quando possível e não garantirá essa contagem exata. Nenhum valor padrão. | | idioma_dicas | lista[str] | Não | Os códigos de idioma a serem reconhecidos. Se você não conseguir determinar o idioma antecipadamente, deixe-o sem definição e o modelo detectará o idioma automaticamente. Para Qwen-Audio-3.x-ASR-Flash-Filetrans modelos, você pode configurar até 4 valores; quaisquer valores além dos 4 primeiros são ignorados. Para Fun-ASR modelos, você pode definir apenas 1 valor; se você definir vários, apenas o primeiro terá efeito. Consulte Idiomas suportados. | | fala_ruído_limiar | flutuar | Não | Limiar de ruído de fala. |

Exemplo de vocabulário

from dashscope.audio.asr import Transcription
vocab = {"Zhang San": 5, "Li Si": 5}
result = Transcription.async_call(
  model="qwen-audio-3.1-asr-flash-filetrans",
  vocabulary=vocab,
  file_urls=['{YOUR_AUDIO_URL}']
)

Filtro de palavras sensíveis

Por padrão, as palavras no QwenCloud lista de palavras sensíveis são substituídos por asteriscos (*).

Com special_word_filter, você pode:

• Substitua por *: Palavras correspondentes tornam-se asteriscos.
• Filtrar: as palavras correspondentes são removidas.

O valor deve ser uma string JSON:

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

Campos:

• filter_with_signed (objeto, opcional): Palavras a serem substituídas por *.
  • Exemplo: "Ajude-me <u>teste</u> este código" se torna "Ajude-me <u>****</u> este código"
  • word_list: Palavras para substituir.
• filter_with_empty (objeto, opcional): Palavras a serem removidas.
  • Exemplo: "O jogo está prestes a <u>começar</u>?" torna-se "O jogo está prestes a acontecer?"
  • word_list: Palavras a serem removidas.
• system_reserved_filter (booleano, opcional, padrão: verdadeiro): habilita a filtragem do sistema. Quando verdadeiro, as palavras no QwenCloud lista de palavras sensíveis são substituídos por *.

Idiomas suportados

Códigos de idioma por modelo:

• qwen-audio-3.0-asr-flash-filetrans, fun-asr:
  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • ko: Coreano
  • vi: vietnamita
  • th: Tailandês
  • id: Indonésio
  • ms: malaio
  • tl: Filipino
  • hi: Hindi
  • ar: Árabe
  • fr: francês
  • de: Alemão
  • es: Espanhol
  • pt: Português
  • ru: Russo
  • it: Italiano
  • nl: Holandês
  • sv: Sueco
  • da: dinamarquês
  • fi: Finlandês
  • no: Norueguês
  • el: Grego
  • pl: Polonês
  • cs: Tcheco
  • hu: Húngaro
  • ro: romeno
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco

Resposta

TranscriçãoResposta

TranscriptionResponse envolve as informações básicas da tarefa (task_id e task_status) e o resultado da tarefa (o conteúdo do output atributo, consulte TranscriptionOutput).

Clique para ver uma amostra TranscriçãoResponse structure

PENDING status

  ```json
  {
    "status_code": 200,
    "request_id": "251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code": null,
    "message": "",
    "output": {
      "task_id": "7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
      "task_status": "PENDING",
      "submit_time": "2025-02-13 16:55:08.573",
      "scheduled_time": "2025-02-13 16:55:08.592",
      "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 0,
        "FAILED": 0
      }
    },
    "usage": null
  }
  ```

RUNNING status

  ```json
  {
    "status_code": 200,
    "request_id": "d9d530f1-853c-9848-a5f1-f5de59086ff7",
    "code": null,
    "message": "",
    "output": {
      "task_id": "6351feef-9694-45d2-9d32-63454f2ffb8d",
      "task_status": "RUNNING",
      "submit_time": "2025-02-13 17:31:20.681",
      "scheduled_time": "2025-02-13 17:31:20.703",
      "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 1,
        "FAILED": 0
      }
    },
    "usage": null
  }
  ```

SUCCEEDED status

  ```json
  {
    "status_code": 200,
    "request_id": "16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code": null,
    "message": "",
    "output": {
      "task_id": "6351feef-9694-45d2-9d32-63454f2ffb8d",
      "task_status": "SUCCEEDED",
      "submit_time": "2025-02-13 17:31:20.681",
      "scheduled_time": "2025-02-13 17:31:20.703",
      "end_time": "2025-02-13 17:31:21.867",
      "results": [
        {
          "file_url": "{YOUR_AUDIO_URL}",
          "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/...",
          "subtask_status": "SUCCEEDED"
        },
        {
          "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
          "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/...",
          "subtask_status": "SUCCEEDED"
        }
      ],
      "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 2,
        "FAILED": 0
      }
    },
    "usage": {
      "duration": 9
    }
  }
  ```

FAILED status

  ```json
  {
    "status_code": 200,
    "request_id": "16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code": null,
    "message": "",
    "output": {
      "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
      "task_status": "SUCCEEDED",
      "submit_time": "2024-12-16 16:30:59.170",
      "scheduled_time": "2024-12-16 16:30:59.204",
      "end_time": "2024-12-16 16:31:02.375",
      "results": [
        {
          "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
          "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
          "subtask_status": "SUCCEEDED"
        },
        {
          "file_url": "{YOUR_AUDIO_URL}",
          "code": "InvalidFile.DownloadFailed",
          "message": "The audio file cannot be downloaded.",
          "subtask_status": "FAILED"
        }
      ],
      "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 1,
        "FAILED": 1
      }
    },
    "usage": {
      "duration": 9
    }
  }
  ```

Parâmetros principais:

TranscriçãoSaída

TranscriptionOutput corresponde ao output atributo do TranscriptionResponse e representa o resultado da tarefa atual.

Clique para ver uma amostra Transcrição Estrutura de saída

PENDING status

  ```json
  {
    "task_id": "f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status": "PENDING",
    "submit_time": "2025-02-13 17:59:27.754",
    "scheduled_time": "2025-02-13 17:59:27.789",
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 0,
      "FAILED": 0
    }
  }
  ```

RUNNING status

  ```json
  {
    "task_id": "f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status": "RUNNING",
    "submit_time": "2025-02-13 17:59:27.754",
    "scheduled_time": "2025-02-13 17:59:27.789",
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 0,
      "FAILED": 0
    }
  }
  ```

SUCCEEDED status

  ```json
  {
    "task_id": "f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status": "SUCCEEDED",
    "submit_time": "2025-02-13 17:59:27.754",
    "scheduled_time": "2025-02-13 17:59:27.789",
    "end_time": "2025-02-13 17:59:28.828",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/...",
        "subtask_status": "SUCCEEDED"
      },
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/...",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
    }
  }
  ```

FAILED status

  `code` é o código de erro e `message` é a mensagem de erro. Esses dois campos aparecem apenas quando ocorre uma exceção. Use-os juntos e consulte [Códigos de erro](#error-codes) para solucionar o problema.

  ```json
  {
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
        "subtask_status": "SUCCEEDED"
      },
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "code": "InvalidFile.DownloadFailed",
        "message": "The audio file cannot be downloaded.",
        "subtask_status": "FAILED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 1,
      "FAILED": 1
    }
  }
  ```

Parâmetros principais:

Resultado de reconhecimento

O resultado do reconhecimento é salvo como um arquivo JSON.

Clique para ver o exemplo do resultado do reconhecimento.

{
  "file_url": "{YOUR_AUDIO_URL}",
  "properties": {
    "audio_format": "pcm_s16le",
    "channels": [
      0
    ],
    "original_sampling_rate": 16000,
    "original_duration_in_milliseconds": 3834
  },
  "transcripts": [
    {
      "channel_id": 0,
      "content_duration_in_milliseconds": 3720,
      "text": "Hello world, this is Alibaba Speech Lab.",
      "sentences": [
        {
          "begin_time": 100,
          "end_time": 3820,
          "text": "Hello world, this is Alibaba Speech Lab.",
          "sentence_id": 1,
          "speaker_id": 0,
          "words": [
            {
              "begin_time": 100,
              "end_time": 596,
              "text": "Hello ",
              "punctuation": ""
            },
            {
              "begin_time": 596,
              "end_time": 844,
              "text": "world",
              "punctuation": ", "
            }
          ]
        }
      ]
    }
  ]
}

`speaker_id` aparece somente quando a diarização do alto-falante está habilitada.

Os seguintes parâmetros são dignos de nota:

Classe de transcrição

Importar Transcription com from dashscope.audio.asr import Transcription.

Códigos de erro

Se você encontrar um erro, consulte Códigos de erro para solucionar problemas.

Quando uma tarefa contém várias subtarefas, o status geral da tarefa é marcado como SUCCEEDED contanto que pelo menos uma subtarefa seja bem-sucedida. Verifique o subtask_status campo para determinar o resultado de cada subtarefa.

Exemplo de resposta de erro:

{
  "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
  "task_status": "SUCCEEDED",
  "submit_time": "2024-12-16 16:30:59.170",
  "scheduled_time": "2024-12-16 16:30:59.204",
  "end_time": "2024-12-16 16:31:02.375",
  "results": [
    {
      "file_url": "{YOUR_AUDIO_URL}",
      "code": "InvalidFile.DownloadFailed",
      "message": "The audio file cannot be downloaded.",
      "subtask_status": "FAILED"
    }
  ],
  "task_metrics": {
    "TOTAL": 1,
    "SUCCEEDED": 0,
    "FAILED": 1
  }
}

Perguntas frequentes

Recursos

P: O áudio codificado em Base64 é compatível?

O áudio codificado em Base64 não é compatível. Somente o áudio em uma URL acessível publicamente pode ser reconhecido. Fluxos binários e arquivos locais não podem ser reconhecidos diretamente.

P: Como faço para disponibilizar um arquivo de áudio em um URL acessível publicamente?

As etapas típicas são as seguintes. Esta é uma abordagem; o processo exato varia de acordo com o produto de armazenamento. Recomendamos que você carregue o áudio no Alibaba Cloud OSS:

1. Escolha um método de armazenamento e hospedagem.

Por exemplo:

• Serviço de armazenamento de objetos (recomendado):
  • Use um serviço de armazenamento de objetos de um provedor de nuvem (como Alibaba Cloud OSS) para carregar o arquivo de áudio em um bucket e configurá-lo para acesso público.
  • Vantagens: alta disponibilidade, suporte à aceleração CDN e fácil gerenciamento.
• Servidor web:
  • Coloque o arquivo de áudio em um servidor web que suporte acesso HTTP/HTTPS (como Nginx ou Apache).
  • Vantagens: adequado para pequenos projetos ou testes locais.
• Rede de entrega de conteúdo (CDN):
  • Hospede o arquivo de áudio em uma CDN e acesse-o através da URL fornecida pela CDN.
  • Vantagens: acelera a entrega de arquivos e se adapta a cenários de alta simultaneidade.

2. Envie o arquivo de áudio

Faça upload do áudio de acordo com o método de armazenamento ou hospedagem que você escolheu. Por exemplo:

• Serviço de armazenamento de objetos:
  • Faça login no console do provedor de nuvem e crie um bucket.
  • Faça upload do arquivo de áudio e defina sua permissão para leitura pública ou gere um link de acesso temporário.
• Servidor web:
  • Coloque o arquivo de áudio em um diretório designado no servidor (como /var/www/html/audio/).
  • Certifique-se de que o arquivo esteja acessível por HTTP/HTTPS.

3. Gere uma URL acessível publicamente

Por exemplo:

• Serviço de armazenamento de objetos:
  • Após o upload do arquivo, o sistema gera automaticamente uma URL de acesso público (normalmente no formato https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
  • Para um nome de domínio mais amigável, vincule um domínio personalizado e habilite HTTPS.
• Servidor web:
  • A URL de acesso geralmente é o endereço do servidor mais o caminho do arquivo (como https://your-domain.com/audio/file.mp3). -CDN:
  • Depois de configurar a aceleração do CDN, use a URL fornecida pelo CDN (como https://cdn.your-domain.com/audio/file.mp3).

4. Verifique se a URL funciona.

Certifique-se de que o URL gerado esteja acessível pela rede pública. Por exemplo:

• Abra o URL em um navegador e verifique se o arquivo de áudio é reproduzido.
• Use uma ferramenta (como curl ou Postman) para verificar se o URL retorna a resposta HTTP correta (código de status 200).

Ao usar o SDK, se os arquivos de áudio forem armazenados no Alibaba Cloud OSS, URLs temporários com o oss:// prefixo não são suportados.

Ao usar a API RESTful, se os arquivos de áudio forem armazenados no Alibaba Cloud OSS, URLs temporários com o oss:// prefixo são suportados:

• O URL temporário é válido por 48 horas e não pode ser usado após expirar. Não use em um ambiente de produção.
• A API para obter uma credencial de upload é limitada a 100 QPS e não oferece suporte à expansão. Não use-o em ambientes de produção, cenários de alta simultaneidade ou cenários de testes de estresse.
• Para ambientes de produção, use um serviço de armazenamento estável, como OSS, para garantir a disponibilidade de arquivos a longo prazo e evitar problemas de limitação de taxa.

P: Quanto tempo leva para obter o resultado do reconhecimento?

Depois que uma tarefa é enviada, ela entra no estado de fila (PENDENTE). O tempo de espera depende do comprimento da fila e da duração do áudio, por isso não pode ser declarado com exatidão, mas geralmente leva alguns minutos. Em geral, quanto mais longo o áudio, mais tempo demora.

Solução de problemas

Se você encontrar um erro de código, solucione o problema com base nas informações em Códigos de erro.

P: A pesquisa nunca retorna um resultado?

Isso pode ser causado por estrangulamento. Espere um momento e tente novamente.

P: Por que a fala não pode ser reconhecida (sem resultado de reconhecimento)?

Verifique se o formato de áudio e a taxa de amostragem estão corretos e atendem às restrições de parâmetro.

Use o ffprobe ferramenta para obter o contêiner de áudio, codec, taxa de amostragem, canais e outros detalhes:

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx