Utilisez le SDK Python Paraformer pour transcrire des fichiers audio et vidéo via l'API DashScope.
Prérequis
Premiers pas
La ressource principale (client.audio.asr) prend en charge deux approches de transcription :
- Soumission asynchrone + attente synchrone : soumettez une tâche et bloquez l'exécution jusqu'à son achèvement et au retour du résultat.
- Soumission asynchrone + interrogation asynchrone : soumettez une tâche et interrogez les résultats à tout moment.
Soumission asynchrone + attente synchrone
-
Appelez la ressource principale (
client.audio.asr) (jobs.create/transcribe) et définissez les paramètres de requête.- Le service de transcription de fichiers traite les tâches soumises via l'API selon le principe du meilleur effort. Après soumission, une tâche passe à l'état en file d'attente (
PENDING). La durée d'attente dépend de la longueur de la file et de la durée du fichier ; elle ne peut être estimée avec précision, mais se termine généralement en quelques minutes. Une fois le traitement lancé, la reconnaissance vocale s'effectue à une vitesse plusieurs centaines de fois supérieure au temps réel. - Une fois chaque tâche terminée, le résultat de reconnaissance et le lien de téléchargement URL restent valides pendant 24 heures. Passé ce délai, il n'est plus possible d'interroger la tâche ni de télécharger les résultats via l'URL précédemment fournie.
- Le service de transcription de fichiers traite les tâches soumises via l'API selon le principe du meilleur effort. Après soumission, une tâche passe à l'état en file d'attente (
-
Appelez la ressource principale (
client.audio.asr) (jobs.wait, outranscribeen une étape) pour attendre de manière synchrone la fin de la tâche. États de la tâche :PENDING,RUNNING,SUCCEEDED,FAILED. L'appel àwaitbloque l'exécution durant les étatsPENDINGouRUNNING. Lorsque la tâche atteint l'étatSUCCEEDEDouFAILED,waitretourne le résultat.jobs.waitrenvoie leJoben état final (structure : voir Réponse).
Cliquez pour afficher l'exemple complet
Cliquez pour afficher l'exemple complet
Soumission asynchrone + interrogation asynchrone
-
Appelez la ressource principale (
client.audio.asr) (jobs.create/transcribe) et définissez les paramètres de requête.- Le service de transcription de fichiers traite les tâches soumises via l'API selon le principe du meilleur effort. Après soumission, une tâche passe à l'état en file d'attente (
PENDING). La durée d'attente dépend de la longueur de la file et de la durée du fichier ; elle ne peut être estimée avec précision, mais se termine généralement en quelques minutes. Une fois le traitement lancé, la reconnaissance vocale s'effectue à une vitesse plusieurs centaines de fois supérieure au temps réel. - Une fois chaque tâche terminée, le résultat de reconnaissance et le lien de téléchargement URL restent valides pendant 24 heures. Passé ce délai, il n'est plus possible d'interroger la tâche ni de télécharger les résultats via l'URL précédemment fournie.
- Le service de transcription de fichiers traite les tâches soumises via l'API selon le principe du meilleur effort. Après soumission, une tâche passe à l'état en file d'attente (
-
Interrogez régulièrement la ressource principale (
client.audio.asr) (jobs.fetch) jusqu'à l'achèvement de la tâche. Cessez l'interrogation lorsque l'état estSUCCEEDEDouFAILEDet traitez le résultat.jobs.fetchrenvoie unJob(structure : voir Réponse).
Cliquez pour afficher l'exemple complet
Cliquez pour afficher l'exemple complet
Paramètres de requête
Transmettez ces paramètres via les méthodes jobs.create/transcribe de la ressource principale (client.audio.asr).
| Paramètre | Type | Valeur par défaut | Obligatoire | Description |
|---|---|---|---|---|
| model | str | Oui | Nom du modèle pour la transcription de fichiers audio et vidéo Paraformer. Modèles pris en charge. | |
| file_urls | list[str] | Oui | Liste d'URL pour la transcription de fichiers audio et vidéo. Les protocoles HTTP et HTTPS sont pris en charge. Une seule requête accepte uniquement 1 URL.Si les fichiers audio sont stockés dans Alibaba Cloud OSS, le SDK ne prend pas en charge les URL temporaires avec le préfixe oss://. | |
| vocabulary_id | str | Non | ID du vocabulaire personnalisé. Pris en charge pour les modèles de la série v2 ; nécessite la configuration de la langue. Désactivé par défaut. Vocabulaires personnalisés. | |
| channel_id | list[int] | [0] | Non | Spécifie les index des pistes audio à reconnaître dans un fichier audio multipiste. Les index commencent à 0. Par exemple, [0] signifie la reconnaissance de la première piste, et [0, 1] signifie la reconnaissance simultanée des première et deuxième pistes. Si ce paramètre est omis, seule la première piste est traitée par défaut. |
| disfluency_removal_enabled | bool | False | Non | Filtre les mots de remplissage. Désactivé par défaut. |
| timestamp_alignment_enabled | bool | False | Non | Active l'alignement des horodatages. Désactivé par défaut. |
| special_word_filter | str | Non | Spécifie les mots sensibles à traiter lors de la reconnaissance vocale et permet de définir différentes méthodes de traitement pour différents mots sensibles.Si ce paramètre n'est pas fourni, le système utilise la logique de filtrage des mots sensibles intégrée, et les mots correspondant à la liste des mots sensibles d'Alibaba Cloud Model Studio dans les résultats de reconnaissance seront remplacés par des * de longueur égale.Si ce paramètre est fourni, les stratégies de traitement des mots sensibles suivantes peuvent être mises en œuvre :
| |
| language_hints | list[str] | ["zh", "en"] | Non | Spécifie les codes de langue de la parole à reconnaître.Ce paramètre s'applique uniquement au modèle paraformer-v2.Codes de langue pris en charge :
|
| diarization_enabled | bool | False | Non | Diarisation automatique des locuteurs. Désactivée par défaut.Applicable uniquement à l'audio mono. L'audio multicanal ne prend pas en charge la diarisation des locuteurs.Lorsque cette fonctionnalité est activée, les résultats de reconnaissance incluent un champ speaker_id pour distinguer les différents locuteurs.Si la diarisation des locuteurs est activée, nous recommandons que la durée audio ne dépasse pas 2 heures, faute de quoi la reconnaissance risque d'échouer ou d'expirer. speaker_id, consultez la section Description des résultats de reconnaissance. |
| speaker_count | int | Non | Nombre de locuteurs de référence. Entier compris entre 2 et 100.Prend effet uniquement lorsque diarization_enabled est vrai.Déterminé automatiquement par défaut. La définition de ce paramètre guide l'algorithme mais ne garantit pas le nombre exact. |
Réponse
Job
Un objet Job contient les informations de base de la tâche (task_id et status) et le résultat de l'exécution (results, voir résultats de reconnaissance des sous-tâches, task_metrics, usage). Le Job renvoyé par jobs.create après la soumission de la tâche ne contient que task_id et status ; le Job renvoyé par jobs.fetch, jobs.wait (et transcribe en une étape) contient le résultat de l'exécution de la tâche.
Cliquez pour voir des exemples de structure Job
Cliquez pour voir des exemples de structure Job
Job renvoyé par jobs.create est le suivant (la tâche est à l'état PENDING après la soumission) :Job renvoyé par jobs.fetch, jobs.wait (et transcribe en une étape) est le suivant :Paramètre | Description |
|---|---|
request_id | L'ID généré par le système pour identifier cet appel. |
task_id | L'ID de la tâche. |
status | L'état de la tâche. Les quatre états sont Lorsqu'une tâche contient plusieurs sous-tâches, si une sous-tâche réussit, l'état de toute la tâche est marqué |
results | Les résultats de reconnaissance des sous-tâches. Chaque élément contient |
subtask_status | L'état de la sous-tâche. Les quatre états sont |
file_url | L'URL du fichier audio à reconnaître. |
transcription_url | L'URL correspondant au résultat de reconnaissance audio. Le résultat de reconnaissance est enregistré dans un fichier JSON. Téléchargez le fichier depuis l'URL de |
usage | Les informations de facturation, dont |
DashScopeError. Vous pouvez obtenir le code d'erreur, le code de statut HTTP, le message d'erreur et l'ID de requête via e.code/e.status_code/e.message/e.request_id. L'échec d'une sous-tâche ne lève pas d'exception ; consultez plutôt subtask_status, code et message dans results.
results (résultats de reconnaissance des sous-tâches)
Le tableau results contient le résultat de reconnaissance des sous-tâches de chaque fichier audio du Job. Chaque élément contient file_url, transcription_url et subtask_status ; en cas d'échec d'une sous-tâche, il contient aussi code et message.
Cliquez pour voir des exemples de structure results
Cliquez pour voir des exemples de structure results
- État SUCCEEDED
- État FAILED
Paramètre | Description |
|---|---|
code | Le code d'erreur. À utiliser avec le champ |
message | Le message d'erreur. À utiliser avec le champ |
subtask_status | L'état de la sous-tâche. Les quatre états sont |
file_url | L'URL du fichier audio à reconnaître. |
transcription_url | L'URL correspondant au résultat de reconnaissance audio. Le résultat de reconnaissance est enregistré dans un fichier JSON. Téléchargez le fichier depuis |
Description des résultats de reconnaissance
Le résultat de reconnaissance est enregistré dans un fichier JSON.
Cliquez pour afficher un exemple de résultat de reconnaissance
Cliquez pour afficher un exemple de résultat de reconnaissance
Paramètre | Type | Description |
|---|---|---|
audio_format | string | Format audio du fichier source. |
channels | array[integer] | Informations sur l'index des pistes audio du fichier source. Retourne [0] pour l'audio mono, [0, 1] pour l'audio à deux pistes, etc. |
original_sampling_rate | integer | Taux d'échantillonnage (Hz) de l'audio dans le fichier source. |
original_duration | integer | Durée audio originale (ms) du fichier source. |
channel_id | integer | Index de la piste audio du résultat de transcription, commençant à 0. |
content_duration | integer | Durée (ms) du contenu identifié comme parole dans la piste audio. Le service de modèle de reconnaissance vocale Paraformer transcrit et mesure uniquement le contenu identifié comme parole dans la piste audio, et facture en conséquence. Le contenu non vocal n'est ni mesuré ni facturé. Généralement, la durée du contenu vocal est inférieure à la durée audio originale. Étant donné que la détermination de la présence de contenu vocal est effectuée par un modèle d'IA, il peut exister un certain écart par rapport à la réalité. |
transcript | string | Résultat de transcription vocale au niveau du paragraphe. |
sentences | array | Résultat de transcription vocale au niveau de la phrase. |
words | array | Résultat de transcription vocale au niveau du mot. |
begin_time | integer | Horodatage de début (ms). |
end_time | integer | Horodatage de fin (ms). |
text | string | Résultat de transcription vocale. |
speaker_id | integer | Index du locuteur actuel, commençant à 0, utilisé pour distinguer les différents locuteurs. Ce champ s'affiche uniquement dans les résultats de reconnaissance lorsque la diarisation des locuteurs est activée. |
punctuation | string | Ponctuation prédite après le mot (le cas échéant). |
Interfaces clés
Ressource principale (client.audio.asr)
La reconnaissance vocale hors temps réel est montée sur la ressource client.audio.asr : client.audio.asr.transcribe effectue la soumission et l'attente en une étape, ou client.audio.asr.jobs permet un contrôle étape par étape.
| Méthode membre | Signature de la méthode | Description |
|---|---|---|
| transcribe | Soumet une tâche de reconnaissance de fichier audio et bloque le thread courant jusqu'à la fin de la tâche (état SUCCEEDED ou FAILED).Cette méthode renvoie un Job ; lisez les résultats de transcription dans job.results (chaque élément contient transcription_url). | |
| jobs.create | Soumet de manière asynchrone une tâche de reconnaissance vocale.Cette méthode renvoie un Job (job.task_id/job.status). | |
| jobs.wait | Bloque le thread courant jusqu'à la fin de la tâche asynchrone (interrogation avec temporisation exponentielle, budget total par défaut de 24 heures).Cette méthode renvoie le Job en état final. | |
| jobs.fetch | Interroge de manière asynchrone le résultat d'exécution de la tâche en cours.Cette méthode renvoie un Job. |
Codes d'erreur
En cas d'erreur, 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. Vérifiez le champ subtask_status pour déterminer le résultat de chaque sous-tâche.
Exemple de réponse d'erreur :
Plus d'exemples
Découvrez davantage d'exemples sur GitHub.
FAQ
Fonctionnalités
Q : L'audio encodé en Base64 est-il pris en charge ?
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 ?
Suivez généralement ces étapes (cette procédure fournit 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) :
1. Choisir une méthode de stockage et d'hébergement
1. Choisir une méthode de stockage et d'hébergement
-
Object Storage Service (recommandé) :
- Utilisez le service de stockage objet d'un fournisseur cloud (tel que Alibaba Cloud OSS) pour télécharger des fichiers audio dans un bucket et les configurer en accès public.
- Avantages : haute disponibilité, prise en charge de l'accélération CDN, gestion simplifiée.
-
Serveur Web :
- Placez les fichiers audio sur un serveur Web prenant en charge l'accès HTTP/HTTPS (tel que Nginx ou Apache).
- Avantages : adapté aux petits projets ou aux tests locaux.
-
Content Delivery Network (CDN) :
- Hébergez les fichiers audio sur un CDN et accédez-y via l'URL fournie par le CDN.
- Avantages : diffusion accélérée des fichiers, adapté aux scénarios à forte concurrence.
2. Télécharger les fichiers audio
2. Télécharger les fichiers audio
-
Object Storage Service :
- Connectez-vous à la console du fournisseur cloud et créez un bucket.
- Téléchargez les fichiers audio et définissez les permissions de fichier sur « lecture publique » ou générez des liens d'accès temporaires.
-
Serveur Web :
- Placez les fichiers audio dans le répertoire désigné du serveur (tel que
/var/www/html/audio/). - Assurez-vous que les fichiers sont accessibles via HTTP/HTTPS.
- Placez les fichiers audio dans le répertoire désigné du serveur (tel que
3. Générer une URL accessible publiquement
3. Générer une URL accessible publiquement
-
Object Storage Service :
- Après le téléchargement, le système génère automatiquement une URL d'accès public (généralement au format
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Si vous avez besoin d'un domaine plus convivial, vous pouvez lier un domaine personnalisé et activer HTTPS.
- Après le téléchargement, le système génère automatiquement une URL d'accès public (généralement au format
-
Serveur Web :
- L'URL d'accès au fichier correspond généralement à l'adresse du serveur suivie du chemin du fichier (telle que
https://your-domain.com/audio/file.mp3).
- L'URL d'accès au fichier correspond généralement à l'adresse du serveur suivie du chemin du fichier (telle que
-
CDN :
- Après avoir configuré l'accélération CDN, utilisez l'URL fournie par le CDN (telle que
https://cdn.your-domain.com/audio/file.mp3).
- Après avoir configuré l'accélération CDN, utilisez l'URL fournie par le CDN (telle que
4. Vérifier l'accessibilité de l'URL
4. Vérifier l'accessibilité de l'URL
- Ouvrez l'URL dans un navigateur et vérifiez si le fichier audio peut être lu.
- Utilisez des outils (tels que
curlou Postman) pour vérifier si l'URL retourne une réponse HTTP correcte (code d'état 200).
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 pour 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 scénarios de test 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 en file d'attente (PENDING). La durée d'attente dépend de la longueur de la file et de la durée du fichier ; elle ne peut être estimée avec précision, mais se termine généralement en quelques minutes. Veuillez patienter. Les fichiers audio plus longs nécessitent un temps de traitement plus important.
Dépannage
Pour les erreurs de code, consultez la section 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 pour activer la calibration des horodatages, ce qui synchronise les résultats de reconnaissance avec la lecture vocale.
Q : Que faire si la tâche retourne une erreur InvalidFile.DownloadFailed ?
Vérifiez si l'URL du fichier contient des espaces ou d'autres caractères non ASCII (tels que des caractères chinois). Si le nom du fichier comprend des espaces (par exemple, my audio recording.mp4), remplacez chaque espace par %20 pour encoder l'URL du nom de fichier avant de le transmettre au paramètre file_urls.
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, taux d'échantillonnage).
- Si vous utilisez le modèle
paraformer-v2, vérifiez si le paramètrelanguage_hintsest correct. - Si aucune des solutions ci-dessus ne résout le problème, personnalisez des mots clés pour améliorer la reconnaissance de mots spécifiques.