Alibaba Cloud Model Studio:API HTTP de reconnaissance vocale non temps réel Paraformer

Paramètres et détails de l'API HTTP pour la reconnaissance vocale non temps réel Paraformer.

Guide d'utilisation :Reconnaissance vocale non temps réel

Le service fournit une interface de soumission de tâche ainsi qu'une interface d'interrogation de tâche. En règle générale, appelez l'interface de soumission pour envoyer une tâche de reconnaissance, puis interrogez régulièrement l'interface d'état jusqu'à ce que la tâche soit terminée.

Prérequis

Vous avez activé le service et obtenu une clé API. Configurez la clé API comme variable d'environnement plutôt que de la coder en dur dans votre code afin d'éviter les risques de sécurité liés à une fuite de code.

Interface de soumission de tâche

Informations de base

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

Authorization: Bearer {api-key} // Remplacez {api-key} par votre clé API.
Content-Type: application/json
X-DashScope-Async: enable // N'omettez pas cet en-tête de requête. Sinon, la tâche ne pourra pas être soumise.

{
    "model":"paraformer-v2", // Nom du modèle. Ce paramètre est obligatoire.
    "input":{
        "file_urls":[
            "{YOUR_AUDIO_URL}"
        ] // Fichier à reconnaître. Ce paramètre est obligatoire.
    },
    "parameters":{
        "channel_id":[
            0
        ], // Index de la piste audio. Paramètre facultatif.
        "disfluency_removal_enabled":false, // Activation du filtrage des mots de remplissage. Paramètre facultatif.
        "timestamp_alignment_enabled": false, // Active la fonctionnalité d'alignement temporel. Paramètre facultatif.
        "special_word_filter": "xxx", // Mots sensibles. Paramètre facultatif.
        "language_hints":[ // Applicable uniquement au modèle paraformer-v2. N'utilisez pas ce champ pour d'autres modèles.
            "zh",
            "en"
        ],
        "diarization_enabled":false, // Active la diarisation automatique des locuteurs. Paramètre facultatif.
        "speaker_count": 2 // Nombre de référence de locuteurs. Paramètre facultatif.
    }
}

Paramètres de requête

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{"model":"paraformer-v2","input":{"file_urls":["{YOUR_AUDIO_URL}"]},"parameters":{"channel_id":[0]}}'

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

Paramètres de réponse

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

Interface d'interrogation de tâche

Informations de base

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Authorization: Bearer {api-key} // Remplacez {api-key} par votre clé API.

Paramètres de requête

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Paramètres de réponse

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

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

Description des résultats de reconnaissance

Le résultat de la reconnaissance est enregistré dans un fichier 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 the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is only displayed 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 omitted here
                    ]
                }
            ]
        }
    ]
}

Les principaux paramètres sont les suivants :

Exemple complet

Utilisez les bibliothèques HTTP intégrées pour mettre en œuvre les requêtes de soumission et d'interrogation de tâches. Soumettez d'abord la tâche de reconnaissance, puis effectuez des interrogations répétées jusqu'à son achèvement.

Le code suivant fournit un exemple en Python :

import requests
import json
import time

api_key = "your-dashscope-api-key"  # Replace this with your API key.
file_urls = [
    "{YOUR_AUDIO_URL}",
]
language_hints = ["zh", "en"]

# Submit file transcription task with list of file URLs to transcribe.
def submit_task(apikey, file_urls) -> str:

    headers = {
        "Authorization": f"Bearer {apikey}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable",
    }
    data = {
        "model": "paraformer-v2",
        "input": {"file_urls": file_urls},
        "parameters": {
            "channel_id": [0],
            "language_hints": language_hints
        },
    }
    # The URL of the recorded file transcription service.
    service_url = (
        "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"
    )
    response = requests.post(
        service_url, headers=headers, data=json.dumps(data)
    )

    # Print the response content.
    if response.status_code == 200:
        return response.json()["output"]["task_id"]
    else:
        print("task failed!")
        print(response.json())
        return None

# Recursively query the task status until the task is successful.
def wait_for_complete(task_id):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable",
    }

    pending = True
    while pending:
        # The URL of the task status query service.
        service_url = f"https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}"
        response = requests.get(
            service_url, headers=headers
        )
        if response.status_code == 200:
            status = response.json()['output']['task_status']
            if status == 'SUCCEEDED':
                print("task succeeded!")
                pending = False
                return response.json()['output']['results']
            elif status == 'RUNNING' or status == 'PENDING':
                pass
            else:
                print("task failed!")
                pending = False
        else:
            print("query failed!")
            pending = False
        print(response.json())
        time.sleep(0.1)

task_id = submit_task(apikey=api_key, file_urls=file_urls)
print("task_id: ", task_id)
result = wait_for_complete(task_id)
print("transcription result: ", result)

Codes d'erreur

Si vous rencontrez des erreurs, consultez la section Codes d'erreur pour le dépannage.

Si le problème persiste, rejoignez la communauté des développeurs pour signaler le problème et fournir l'ID de requête pour une investigation plus approfondie.

Lorsqu'une tâche contient plusieurs sous-tâches, tant qu'une sous-tâche réussit, l'état global de la tâche est marqué comme SUCCEEDED. Vous devez vérifier le champ subtask_status pour déterminer le résultat de chaque sous-tâche.

Exemple de réponse d'erreur :

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

Plus d'exemples

Pour plus d'exemples, consultez notre référentiel GitHub.

FAQ

Fonctionnalités

Q : Le service prend-il en charge l'audio encodé en Base64 ?

Non. L'audio encodé en Base64 n'est pas pris en charge. Seul l'audio accessible via des URL publiques est accepté. Les flux binaires et la reconnaissance directe de fichiers locaux ne sont pas pris en charge.

Q : Comment fournir des fichiers audio sous forme d'URL accessibles publiquement ?

En général, suivez ces étapes (il s'agit d'une approche générale ; les spécificités varient selon le produit de stockage. Nous recommandons de télécharger l'audio sur Alibaba Cloud OSS) :

Lors de l'utilisation du SDK, si les fichiers audio sont stockés dans Alibaba Cloud OSS, les URL temporaires avec le préfixe oss:// ne sont pas prises en charge.

Lors de l'utilisation de l'API RESTful, si les fichiers audio sont stockés dans Alibaba Cloud OSS, les URL temporaires avec le préfixe oss:// sont prises en charge :

• L'URL temporaire est valide pendant 48 heures et ne peut plus être utilisée après expiration. Ne l'utilisez pas dans un environnement de production.
• L'API permettant d'obtenir un identifiant de téléchargement est limitée à 100 QPS et ne prend pas en charge la mise à l'échelle horizontale. Ne l'utilisez pas dans des environnements de production, des scénarios à forte concurrence ou des tests de charge.
• Pour les environnements de production, utilisez un service de stockage stable tel que OSS afin de garantir la disponibilité à long terme des fichiers et d'éviter les problèmes de limitation de débit.

Q : Combien de temps faut-il pour obtenir les résultats de reconnaissance ?

Après soumission, la tâche passe à l'état de file d'attente (PENDING). Le temps d'attente dépend de la longueur de la file et de la durée du fichier ; il ne peut pas être estimé avec précision, mais se termine généralement en quelques minutes. Veuillez patienter. Les fichiers audio plus longs nécessitent plus de temps de traitement.

Dépannage

Si vous rencontrez une erreur, reportez-vous aux informations dans Codes d'erreur.

Q : Que faire si les résultats de reconnaissance ne sont pas synchronisés avec la lecture audio ?

Définissez le paramètre de requête timestamp_alignment_enabled sur true. Cela synchronise les résultats de reconnaissance avec la lecture audio.

Q : Que faire si j'obtiens une erreur InvalidFile.DownloadFailed après avoir soumis une tâche ?

Vérifiez si l'URL du fichier contient des espaces, des caractères chinois ou d'autres caractères spéciaux. Si le nom du fichier comprend des espaces (par exemple, « Enregistrement Réunion T1 2024.mp4 »), encodez le nom du fichier en URL en remplaçant les espaces par %20 avant de le transmettre au paramètre file_urls.

Q : Que faire si l'URL d'accès public temporaire d'un fichier audio OSS est inaccessible ?

Définissez X-DashScope-OssResourceResolve sur enable dans les en-têtes.

Non recommandé.

Le SDK Java et le SDK Python de reconnaissance vocale non temps réel Paraformer ne prennent pas en charge la configuration des en-têtes.

Q : Impossible d'obtenir des résultats après une interrogation continue ?

Cela peut être dû à une limitation de débit. Veuillez patienter. Si vous avez besoin d'une extension de capacité, rejoignez la communauté des développeurs pour en faire la demande.

Q : Pourquoi n'y a-t-il aucun résultat de reconnaissance (impossible de reconnaître la parole) ?

• Vérifiez si l'audio répond aux exigences (format, fréquence d'échantillonnage).
• Si vous utilisez le modèle paraformer-v2, vérifiez si le paramètre language_hints est correct.
• Si aucune des solutions ci-dessus ne résout le problème, vous pouvez personnaliser des mots-clés pour améliorer la reconnaissance de termes spécifiques.

Autres questions

Pour plus de questions, consultez la FAQ sur GitHub.