Alibaba Cloud Model Studio:Fun-ASR non-real-time speech recognition Java SDK

Este tópico descreve os parâmetros e os detalhes da API do SDK Java para reconhecimento de fala não em tempo real Fun-ASR.

Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Audio specifications.

Pré-requisitos

• Você ativou o service e Obtain an API key. Utilize Configure API key as an environment variable em vez de codificá-la diretamente no seu código para evitar riscos de segurança causados por vazamento de código.

• Install the latest DashScope SDK.

Início rápido

O Core class (Transcription) fornece interfaces para enviar uma tarefa de forma assíncrona, aguardar sincronamente a conclusão da tarefa e consultar o resultado da tarefa de forma assíncrona. Execute o reconhecimento de fala não em tempo real de uma das duas maneiras seguintes:

• Envie uma tarefa de forma assíncrona e aguarde sincronamente sua conclusão: após enviar a tarefa, a thread atual é bloqueada até que a tarefa termine e o resultado do reconhecimento seja retornado.
• Envie uma tarefa de forma assíncrona e consulte o resultado da tarefa de forma assíncrona: após enviar a tarefa, chame a interface de consulta para obter o resultado da tarefa sempre que necessário.

Enviar uma tarefa de forma assíncrona e aguardar sincronamente sua conclusão

1. Configure o Request parameters.

2. Instancie um Core class (Transcription).

3. Chame o método asyncCall do Core class (Transcription) para enviar a tarefa de forma assíncrona.

   Observação

   • O service de transcrição de arquivos processa 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, portanto não pode ser definido com precisão, mas geralmente fica dentro de 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 a URL de download permanecem válidos por 24 horas. Depois que expiram, não é mais possível consultar a tarefa ou baixar o resultado pela URL retornada em uma consulta anterior.

4. Chame o método wait do Core class (Transcription) para aguardar sincronamente a conclusão da tarefa.

   Uma tarefa pode estar no estado PENDING, RUNNING, SUCCEEDED ou FAILED. Enquanto a tarefa estiver no estado PENDING ou RUNNING, a interface wait permanece bloqueada. Quando a tarefa atinge o estado SUCCEEDED ou FAILED, a interface wait desbloqueia e retorna o resultado da tarefa.

   O método wait retorna um Task result (TranscriptionResult).

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ across regions.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // Create the transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                        // If you have not configured the environment variable, replace the following line with your Model Studio API Key: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // This uses fun-asr as an example; change the model name as needed. Model list: https://www.alibabacloud.com/help/zh/model-studio/models
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Block and wait for the task to complete, then get the result
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Print the result
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Enviar uma tarefa de forma assíncrona e consultar o resultado da tarefa de forma assíncrona

1. Configure o Request parameters.

2. Instancie um Core class (Transcription).

3. Chame o método asyncCall do Core class (Transcription) para enviar a tarefa de forma assíncrona.

   Observação

   • O service de transcrição de arquivos processa 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, portanto não pode ser definido com precisão, mas geralmente fica dentro de 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 a URL de download permanecem válidos por 24 horas. Depois que expiram, não é mais possível consultar a tarefa ou baixar o resultado pela URL retornada em uma consulta anterior.

4. Chame o método fetch do Core class (Transcription) em um loop até obter o resultado final da tarefa.

   Quando o status da tarefa for SUCCEEDED ou FAILED, interrompa a sondagem e processe o resultado.

   O método fetch retorna um Task result (TranscriptionResult).

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ across regions.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // Create the transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                        // If you have not configured the environment variable, replace the following line with your Model Studio API Key: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // This uses fun-asr as an example; change the model name as needed. Model list: https://www.alibabacloud.com/help/zh/model-studio/models
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Poll for the task result in a loop until the task finishes
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }
            // Print the result
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Endpoints

Por padrão, o SDK usa o endpoint da região China (Beijing). Para mudar para outra região, modifique Constants.baseHttpApiUrl antes da inicialização.

Nota:

• As API keys diferem entre regiões. Certifique-se de usar a API key correspondente à região de destino.
• A configuração de região é global e afeta as chamadas de API de todos os SDKs DashScope.

Parâmetros de solicitação

Configure os parâmetros de solicitação usando os métodos encadeados de TranscriptionParam.

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .fileUrls(
          Arrays.asList(
                  "{YOUR_AUDIO_URL}"))
  .build();

Map<String, Integer> vocab = new HashMap<>();
    vocab.put("John Smith", 5);
    vocab.put("Jane Doe", 5);

    TranscriptionParam param = TranscriptionParam.builder()
      .model("fun-asr")
      .parameter("vocabulary", vocab)
      .build();

Map<String, Integer> vocab = new HashMap<>();
    vocab.put("John Smith", 5);
    vocab.put("Jane Doe", 5);

    TranscriptionParam param = TranscriptionParam.builder()
      .model("fun-asr")
      .parameters(Collections.singletonMap("vocabulary", vocab))
      .build();

TranscriptionParam param = TranscriptionParam.builder()
      .model("fun-asr")
      .parameter("language_hints", new String[]{"zh"})
      .build();

TranscriptionParam param = TranscriptionParam.builder()
      .model("fun-asr")
      .parameters(Collections.singletonMap("language_hints", new String[]{"zh"}))
      .build();

Resposta

Resultado da tarefa (TranscriptionResult)

O TranscriptionResult encapsula o resultado da tarefa atual.

public String getRequestId()

public String getTaskId()

public TaskStatus getTaskStatus()

public List<TranscriptionTaskResult> getResults()

public JsonObject getOutput()

{
        "task_id":"0795ff8c-b666-4e91-bb8b-xxx",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 16:12:09.109",
        "scheduled_time":"2025-02-13 16:12:09.128",
        "end_time":"2025-02-13 16:12:10.189",
        "results":[
            {
                "file_url":"{YOUR_AUDIO_URL}",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/16%3A12/3baafe5f-d09d-46c6-8b01-724927670edb-1.json?Expires=1739520730&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }

{
              "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
              }
          }

Resultado da subtarefa (TranscriptionTaskResult)

O TranscriptionTaskResult encapsula o resultado de uma subtarefa. Uma subtarefa reconhece um único arquivo de áudio.

public String getFileUrl()

public String getTranscriptionUrl()

public TaskStatus getSubTaskStatus()

public String getMessage()

Descrição do resultado do reconhecimento

O resultado do reconhecimento é salvo como um arquivo JSON.

{
    "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, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}

Os seguintes parâmetros merecem atenção:

Interfaces principais

Classe de parâmetros de consulta de tarefa (TranscriptionQueryParam)

O TranscriptionQueryParam é usado ao aguardar a conclusão de uma tarefa (chamando o método wait de Transcription) ou ao consultar o resultado da tarefa (chamando o método fetch de Transcription).

Crie uma instância de TranscriptionQueryParam através do método estático FromTranscriptionParam.

// Build the transcription request parameters
TranscriptionParam param =
        TranscriptionParam.builder()
                // If you have not set the API key as an environment variable, replace apiKey with your own API key
                //.apiKey("apikey")
                .model("fun-asr")
                .fileUrls(
                        Arrays.asList(
                                "{YOUR_AUDIO_URL}"))
                .build();
try {
    Transcription transcription = new Transcription();
    // Submit the transcription request
    TranscriptionResult result = transcription.asyncCall(param);
    System.out.println("RequestId: " + result.getRequestId());
    TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());

} catch (Exception e) {
    System.out.println("error: " + e);
}

public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)

Classe principal (Transcription)

Importe Transcription com import com.alibaba.dashscope.audio.asr.transcription.*;. Suas interfaces principais são as seguintes:

public TranscriptionResult asyncCall(TranscriptionParam param)

public TranscriptionResult wait(TranscriptionQueryParam queryParam)

public TranscriptionResult fetch(TranscriptionQueryParam queryParam)

Códigos de erro

Se encontrar um erro, consulte Error codes para solução de problemas.

Quando uma tarefa contém várias subtarefas, o status geral da tarefa é marcado como SUCCEEDED desde que pelo menos uma subtarefa tenha sucesso. Verifique o campo subtask_status 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
    }
}

FAQ

Recursos

P: Áudio codificado em Base64 é suportado?

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

P: Como torno um arquivo de áudio disponível em uma URL acessível publicamente?

As etapas típicas são as seguintes. Esta é uma abordagem; o processo exato varia conforme o product de armazenamento. Recomendamos que você upload the audio to Alibaba Cloud OSS:

Ao usar o SDK, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo 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 a expiração. Não utilize em ambiente de produção.
• A API para obtenção de credencial de upload tem limite de 100 QPS e não suporta scale out. Não 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 service 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?

Após o envio de uma tarefa, ela entra no estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do áudio, portanto não pode ser afirmado com exatidão, mas geralmente fica dentro de alguns minutos. Em geral, quanto mais longo o áudio, mais tempo leva.

Solução de problemas

Se o seu código retornar um erro, solucione-o com base nas informações em Error codes.

P: A sondagem nunca retorna um resultado?

Isso pode ser causado por limitação de taxa. Aguarde 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âmetros.

Use a ferramenta ffprobe para obter o container 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