Este tópico descreve os parâmetros e os detalhes da interface do SDK Java de reconhecimento de fala gravada Paraformer.
Pré-requisitos
Início rápido
A Classe principal (Transcription) fornece interfaces para enviar tarefas de forma assíncrona, aguardar sincronamente a conclusão das tarefas e consultar resultados de tarefas assincronamente. Utilize um dos dois métodos de chamada a seguir para reconhecimento de fala gravada:
- Envio assíncrono + espera síncrona: Após enviar uma tarefa, a thread atual é bloqueada até que a tarefa termine e o resultado do reconhecimento seja obtido.
- Envio assíncrono + consulta assíncrona: Após enviar uma tarefa, consulte o resultado da tarefa a qualquer momento chamando a interface de consulta.
Envio assíncrono + espera síncrona
- Configure os Parâmetros de solicitação.
- Instancie a Classe principal (Transcription).
-
Chame o método
asyncCallda Classe principal (Transcription) para enviar uma tarefa de forma assíncrona.- O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Assim que o processamento começa, o reconhecimento de fala é concluído a uma velocidade centenas de vezes superior ao tempo real. - Após a conclusão de cada tarefa, o resultado do reconhecimento e o link de download da URL são válidos por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.
- O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
-
Chame o método
waitda Classe principal (Transcription) para aguardar sincronamente a conclusão da tarefa. Os status das tarefas incluemPENDING,RUNNING,SUCCEEDEDeFAILED. Quando a tarefa está no estadoPENDINGouRUNNING, a interfacewaitfica bloqueada. Quando a tarefa está no estadoSUCCEEDEDouFAILED, a interfacewaitdeixa de ser bloqueada e retorna o resultado da tarefa. O métodowaitretorna o Resultado da tarefa (TranscriptionResult).
Clique para ver o exemplo completo
Clique para ver o exemplo completo
Envio assíncrono + consulta assíncrona
- Configure os Parâmetros de solicitação.
- Instancie a Classe principal (Transcription).
-
Chame o método
asyncCallda Classe principal (Transcription) para enviar uma tarefa de forma assíncrona.- O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Assim que o processamento começa, o reconhecimento de fala é concluído a uma velocidade centenas de vezes superior ao tempo real. - Após a conclusão de cada tarefa, o resultado do reconhecimento e o link de download da URL são válidos por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.
- O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
-
Chame repetidamente o método
fetchda Classe principal (Transcription) até obter o resultado final da tarefa. Quando o status da tarefa forSUCCEEDEDouFAILED, interrompa a consulta periódica e processe o resultado. O métodofetchretorna o Resultado da tarefa (TranscriptionResult).
Clique para ver o exemplo completo
Clique para ver o exemplo completo
Parâmetros de solicitação
Configure os parâmetros de solicitação pelos métodos encadeados de TranscriptionParam.
Clique para ver o exemplo
Clique para ver o exemplo
| Parâmetro | Tipo | Padrão | Obrigatório | Descrição |
|---|---|---|---|---|
| model | String | Sim | Especifica o nome do modelo Paraformer para transcrição de arquivos de áudio/vídeo. Consulte Modelos suportados. | |
| fileUrls | List<String> | Sim | Lista de URLs dos arquivos de áudio/vídeo para transcrição. Suporta protocolos HTTP/HTTPS. Apenas uma URL é suportada por solicitação.Se os arquivos de áudio estiverem armazenados no OSS da Alibaba Cloud, o SDK não suporta URLs temporárias com o prefixo oss://. | |
| vocabularyId | String | Não | ID mais recente de palavras-chave. Suporta os modelos mais recentes da série v2 com configuração de idioma. As palavras-chave associadas a este ID entram em vigor para este reconhecimento de fala. Desativado por padrão. Para instruções de uso, consulte Palavras-chave personalizadas. | |
| channelId | List<Integer> | [0] | Não | Especifica os índices das faixas de áudio a serem reconhecidas em um arquivo de áudio multifaixa. Os índices começam em 0. Por exemplo, [0] significa reconhecer a primeira faixa, e [0, 1] significa reconhecer simultaneamente a primeira e a segunda faixas. Se este parâmetro for omitido, apenas a primeira faixa será processada por padrão. |
| disfluencyRemovalEnabled | Boolean | false | Não | Filtra palavras de preenchimento. Desativado por padrão. |
| timestampAlignmentEnabled | Boolean | false | Não | Define se o recurso de alinhamento de carimbos de data/hora deve ser ativado. Desativado por padrão. |
| specialWordFilter | String | Não | Especifica palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para diferentes palavras sensíveis.Se este parâmetro não for fornecido, o sistema usa a lógica interna de filtragem de palavras sensíveis, e as palavras correspondentes à lista de palavras sensíveis do Alibaba Cloud Model Studio nos resultados de reconhecimento serão substituídas por * de igual comprimento.Se este parâmetro for fornecido, as seguintes estratégias de processamento de palavras sensíveis podem ser implementadas:
| |
| language_hints | String[] | ["zh", "en"] | Não | Especifica os códigos de idioma da fala a ser reconhecida.Este parâmetro aplica-se apenas ao modelo paraformer-v2.Códigos de idioma suportados:
É necessário definir language_hints pelo método parameter ou pelo método parameters da instância TranscriptionParam: |
| diarizationEnabled | Boolean | false | Não | Diarização automática de falantes. Desativada por padrão.Aplica-se apenas a áudio mono. Áudio multicanal não suporta diarização de falantes.Quando este recurso está ativado, os resultados de reconhecimento incluirão um campo speaker_id para distinguir diferentes falantes.Se a diarização de falantes estiver ativada, recomenda-se que a duração do áudio não exceda 2 horas, caso contrário, o reconhecimento pode falhar ou atingir o tempo limite. speaker_id, consulte Descrição do resultado de reconhecimento. |
| speakerCount | Integer | Não | Um valor de referência para o número de falantes. Valores válidos: inteiros de 2 a 100 (inclusive).Entra em vigor quando a diarização de falantes está ativada (diarizationEnabled definido como true).Por padrão, o sistema determina automaticamente o número de falantes. Se este parâmetro for configurado, ele serve apenas como uma dica para o algoritmo tentar gerar o número especificado de falantes, mas o número exato não é garantido. | |
| apiKey | String | Não | A chave de API. Se a chave de API já estiver configurada em uma variável de ambiente, não é necessário defini-la no código. Caso contrário, defina-a no código. |
Resposta
Resultado da tarefa (TranscriptionResult)
A classe TranscriptionResult encapsula o resultado da tarefa atual.
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
| Nenhum | requestId | Obtém o requestId. | |
| Nenhum | taskId | Obtém o taskId. | |
| Nenhum | TaskStatus, o status da tarefa | Obtém o status da tarefa.TaskStatus é uma classe enum. Você só precisa prestar atenção aos quatro status seguintes: PENDING, RUNNING, SUCCEEDED e FAILED.Quando uma tarefa contém várias subtarefas, desde que qualquer subtarefa tenha sucesso, o status geral da tarefa é marcado como SUCCEEDED. É necessário verificar o campo subtask_status para determinar o resultado de cada subtarefa. | |
| Nenhum | Resultado da subtarefa (TranscriptionTaskResult) | Obtém o Resultado da subtarefa (TranscriptionTaskResult).Cada tarefa reconhece um ou mais arquivos de áudio. Arquivos de áudio diferentes são processados em subtarefas diferentes, portanto, cada tarefa corresponde a uma ou mais subtarefas. | |
| Nenhum | Resultado da tarefa em formato JSON | Obtém o resultado da tarefa.O resultado está em formato JSON. Se você usar a interface getOutput para obter o resultado da tarefa, analise-o manualmente.
Clique para ver o exemplo JSON Exemplo normal code" é o código de erro e "message" é a mensagem de erro. Esses dois campos aparecem apenas em cenários de erro. Use-os para solucionar problemas consultando Códigos de erro. |
Resultado da subtarefa (TranscriptionTaskResult)
A classe TranscriptionTaskResult encapsula o resultado da subtarefa. Uma subtarefa reconhece um único arquivo de áudio.
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
| Nenhum | URL do arquivo de áudio reconhecido | Obtém a URL do arquivo de áudio reconhecido. | |
| Nenhum | URL do resultado de reconhecimento | Obtém a URL do resultado de reconhecimento. Esta URL é válida por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.O resultado de reconhecimento é salvo como um arquivo JSON. Baixe o arquivo pela URL acima ou leia diretamente seu conteúdo por uma solicitação HTTP.Para o significado de cada campo nos dados JSON, consulte Descrição do resultado de reconhecimento. | |
| Nenhum | TaskStatus, o status da subtarefa | Obtém o status da subtarefa.TaskStatus é uma classe enum. Você só precisa prestar atenção aos quatro status seguintes: PENDING, RUNNING, SUCCEEDED e FAILED. | |
| Nenhum | Informações chave durante a execução da tarefa, que podem estar vazias | Obtém informações chave durante a execução da tarefa.Quando uma tarefa falha, verifique este conteúdo para analisar a causa. |
Descrição do resultado de reconhecimento
O resultado de reconhecimento é salvo como um arquivo JSON.
Clique para ver o exemplo de resultado de reconhecimento
Clique para ver o exemplo de resultado de reconhecimento
Parâmetro | Tipo | Descrição |
|---|---|---|
audio_format | string | O formato de áudio do arquivo de origem. |
channels | array[integer] | As informações de índice da faixa de áudio do arquivo de origem. Retorna [0] para áudio mono, [0, 1] para áudio de duas faixas, e assim por diante. |
original_sampling_rate | integer | A taxa de amostragem (Hz) do áudio no arquivo de origem. |
original_duration | integer | A duração original do áudio (ms) do arquivo de origem. |
channel_id | integer | O índice da faixa de áudio do resultado de transcrição, começando em 0. |
content_duration | integer | A duração (ms) do conteúdo identificado como fala na faixa de áudio. O serviço de modelo de reconhecimento de fala Paraformer transcreve e mede apenas o conteúdo identificado como fala na faixa de áudio, faturando de acordo. Conteúdo sem fala não é medido nem faturado. Normalmente, a duração do conteúdo de fala é menor que a duração original do áudio. Como a determinação da existência de conteúdo de fala é feita por um modelo de IA, pode haver algum desvio em relação à situação real. |
transcript | string | O resultado de transcrição de fala no nível de parágrafo. |
sentences | array | O resultado de transcrição de fala no nível de sentença. |
words | array | O resultado de transcrição de fala no nível de palavra. |
begin_time | integer | O carimbo de data/hora inicial (ms). |
end_time | integer | O carimbo de data/hora final (ms). |
text | string | O resultado de transcrição de fala. |
speaker_id | integer | O índice do falante atual, começando em 0, usado para distinguir diferentes falantes. Este campo é exibido nos resultados de reconhecimento apenas quando a diarização de falantes está ativada. |
punctuation | string | A pontuação prevista após a palavra (se houver). |
Interfaces principais
Classe de parâmetros de consulta de tarefa (TranscriptionQueryParam)
Utilize TranscriptionQueryParam ao aguardar a conclusão de uma tarefa (chamando o método Transcription wait) ou ao consultar o resultado da tarefa (chamando o método Transcription fetch).
Crie uma instância de TranscriptionQueryParam pelo método estático FromTranscriptionParam.
Clique para ver o exemplo
Clique para ver o exemplo
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
| Uma instância de TranscriptionQueryParam | Cria uma instância de TranscriptionQueryParam. |
Classe principal (Transcription)
Importe Transcription com "import com.alibaba.dashscope.audio.asr.transcription.*;". Suas interfaces principais são as seguintes:
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
param: Parâmetros de reconhecimento de fala, uma instância de TranscriptionParam | Resultado da tarefa (TranscriptionResult) | Envia uma tarefa de reconhecimento de fala de forma assíncrona. | |
queryParam: Uma instância de TranscriptionQueryParam | Resultado da tarefa (TranscriptionResult) | Bloqueia a thread atual até que a tarefa assíncrona termine (o status da tarefa seja SUCCEEDED ou FAILED). | |
queryParam: Uma instância de TranscriptionQueryParam | Resultado da tarefa (TranscriptionResult) | Consulta o resultado da tarefa atual de forma assíncrona. |
Códigos de erro
Se encontrar erros, consulte Códigos de erro para solução de problemas.
Se o problema persistir, junte-se à comunidade de desenvolvedores para relatar o problema e forneça o Request ID para investigação adicional.
Quando uma tarefa contém várias subtarefas, desde que qualquer subtarefa tenha sucesso, o status geral da tarefa é marcado como SUCCEEDED. Verifique o campo subtask_status para determinar o resultado de cada subtarefa.
Exemplo de resposta de erro:
Mais exemplos
Para mais exemplos, consulte o GitHub.
FAQ
Perguntas sobre recursos
P: Suporta áudio codificado em Base64?
Não. Áudio codificado em Base64 não é suportado. Apenas áudio acessível via URLs publicamente acessíveis é suportado. Fluxos binários e reconhecimento direto de arquivos locais não são suportados.
P: Como fornecer arquivos de áudio como URLs publicamente acessíveis?
Geralmente, siga estas etapas (esta é uma abordagem geral; os detalhes variam conforme o produto de armazenamento. Recomendamos fazer upload do áudio para o Alibaba Cloud OSS):
1. Escolha um método de armazenamento e hospedagem
1. Escolha um método de armazenamento e hospedagem
-
Object Storage Service (recomendado):
- Use o serviço de armazenamento de objetos de um provedor de nuvem (como o Alibaba Cloud OSS) para fazer upload de arquivos de áudio para um bucket e configurá-los para acesso público.
- Vantagens: Alta disponibilidade, suporte a aceleração CDN, gerenciamento fácil.
-
Servidor web:
- Coloque arquivos de áudio em um servidor web que suporte acesso HTTP/HTTPS (como Nginx ou Apache).
- Vantagens: Adequado para pequenos projetos ou testes locais.
-
Content Delivery Network (CDN):
- Hospede arquivos de áudio em uma CDN e acesse-os pela URL fornecida pela CDN.
- Vantagens: Entrega acelerada de arquivos, adequada para cenários de alta concorrência.
2. Faça upload dos arquivos de áudio
2. Faça upload dos arquivos de áudio
-
Object Storage Service:
- Faça login no console do provedor de nuvem e crie um bucket.
- Faça upload dos arquivos de áudio e defina as permissões do arquivo como "leitura pública" ou gere links de acesso temporário.
-
Servidor web:
- Coloque os arquivos de áudio no diretório designado do servidor (como
/var/www/html/audio/). - Garanta que os arquivos sejam acessíveis via HTTP/HTTPS.
- Coloque os arquivos de áudio no diretório designado do servidor (como
3. Gere uma URL publicamente acessível
3. Gere uma URL publicamente acessível
-
Object Storage Service:
- Após o upload, o sistema gera automaticamente uma URL de acesso público (geralmente no formato
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Se precisar de um domínio mais amigável, vincule um domínio personalizado e ative HTTPS.
- Após o upload, o sistema gera automaticamente uma URL de acesso público (geralmente no formato
-
Servidor web:
- A URL de acesso ao arquivo é tipicamente o endereço do servidor mais o caminho do arquivo (como
https://your-domain.com/audio/file.mp3).
- A URL de acesso ao arquivo é tipicamente o endereço do servidor mais o caminho do arquivo (como
-
CDN:
- Após configurar a aceleração CDN, use a URL fornecida pela CDN (como
https://cdn.your-domain.com/audio/file.mp3).
- Após configurar a aceleração CDN, use a URL fornecida pela CDN (como
4. Verifique a acessibilidade da URL
4. Verifique a acessibilidade da URL
- Abra a URL em um navegador e verifique se o arquivo de áudio pode ser reproduzido.
- Use ferramentas (como
curlou Postman) para verificar se a URL retorna uma resposta HTTP correta (código de status 200).
oss:// não são suportadas.
Ao usar a API RESTful, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo oss:// são suportadas:
- A URL temporária é válida por 48 horas e não pode ser usada após expirar. Não a utilize em ambiente de produção.
- A API para obtenção de credencial de upload é limitada a 100 QPS e não suporta scale-out. Não a utilize em ambientes de produção, cenários de alta concorrência ou cenários de teste de estresse.
- Para ambientes de produção, use um serviço de armazenamento estável, como o OSS, para garantir disponibilidade de arquivos a longo prazo e evitar problemas de limitação de taxa.
P: Quanto tempo leva para obter os resultados de reconhecimento?
Após o envio, a tarefa entra em um estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Aguarde pacientemente. Arquivos de áudio mais longos exigem mais tempo de processamento.
Solução de problemas
Se encontrar erros de código, solucione o problema com base nas informações em Códigos de erro.
P: O que fazer se o resultado de reconhecimento e a reprodução de áudio estiverem dessincronizados?
Defina o Parâmetro de solicitação timestampAlignmentEnabled como true para ativar o recurso de alinhamento de carimbos de data/hora, que sincroniza o resultado de reconhecimento com a reprodução de áudio.
P: Não consigo obter resultados após consulta contínua?
Isso pode ocorrer devido à limitação de taxa. Aguarde pacientemente. Se precisar de expansão de capacidade, junte-se à comunidade de desenvolvedores para solicitar.
P: Por que não há resultado de reconhecimento (não consegue reconhecer a fala)?
- Verifique se o áudio atende aos requisitos (formato, taxa de amostragem).
- Se estiver usando o modelo
paraformer-v2, verifique se a configuraçãolanguage_hintsestá correta. - Se nenhuma das opções acima resolver o problema, personalize palavras-chave para melhorar o reconhecimento de palavras específicas.